Re: [Xen-devel] [PATCH DOCDAY] introduce an xl man page in pod format

[Ian Campbell <Ian.Campbell@xxxxxxxxxx>]

On Tue, 2011-11-08 at 17:50 +0000, Stefano Stabellini wrote:
> On Wed, 2 Nov 2011, Ian Campbell wrote:
> > On Tue, 2011-11-01 at 14:45 -0400, Ian Jackson wrote:
> > > Stefano Stabellini writes ("[Xen-devel] [PATCH DOCDAY] introduce an xl 
> > > man page in pod format"):
> > > > This is the initial version of an xl man page, based on the old xm man
> > > > page.
> > > 
> > > Thanks.  I have applied this.  There were various suggestions for
> > > improvements in the thread, but I think this manpage is better than
> > > nothing so it should go in ASAP.  Further improvents are indeed
> > > welcome and should come as patches against this.
> > 
> > Sure. Stefano, are you going to address the review or shall I do it?
> 
> I am going to address the review.

Great.

> However I am not so sure about splitting the man page, after all using /
> to search through it has worked very well in the past 40 years. Are you
> sure you haven't been drinking the kool-aid? ;)

By that rationale we only need one manpage for all of POSIX and another
for SysV and we are done ;-)

Long manpages documenting lots of commands don't scale that well, have
you ever tried to use e.g. bash-builtins(7) or perlfunc(1) to find the
documentation for a particular function? They are basically unusable,
even with search, because they glom everything into a single page. The
xl one is reasonably short right now but I expect it will grow as it
gets flesh out, we add more examples etc etc.

As well as keeping each individual doc shorter (which I think makes them
more manageable, less intimidating and easier on the reader etc)
splitting things up also means that each command can be documented in
the more traditional style, i.e. with its own SYNOPSYS, DESCRIPTION,
OPTIONS, RETURNS, EXAMPLES, SEE ALSO etc. If you merge them altogether
then this becomes cumbersome.

xl happens to be a single binary but in reality it is implementing
multiple commands, in some sense those commands are even unrelated (e.g.
what has vcpu pinning really got to do with migration?). It could just
as well been implemented that way too (e.g. the xl-<subcommand> form)
and then we would naturally have had separate pages.

Ian.


_______________________________________________
Xen-devel mailing list
Xen-devel@xxxxxxxxxxxxxxxxxxx
http://lists.xensource.com/xen-devel