Re: [Xen-API] [Xen-devel] Proposal - Add xe manpages to xen-org

[Ian Campbell <Ian.Campbell@xxxxxxxxxx>]

On Tue, 2012-09-25 at 15:19 +0100, Anil Madhavapeddy wrote:
> On 25 Sep 2012, at 04:22, Ian Campbell <Ian.Campbell@xxxxxxxxxx> wrote:
> 
> > On Mon, 2012-09-24 at 16:21 +0100, Lars Kurth wrote:
> >> On 24/09/2012 16:06, Grant McWilliams wrote:
> >>> Xen Community,
> >>> 
> >>>    I have a team of people frantically creating manpages for the xe 
> >>> command and all of it's 361 subcommands. The initial source 
> >>> documentation is in asciidoc but also saved as Docbook. From docbook 
> >>> we transform to epub, html, manpage and pdf. This is currently being 
> >>> hosted in a subversion server at a Seattle area college and we'd like 
> >>> to move it to the xen-org github so it's public, can be reviewed, 
> >>> commented on and contributed too.
> > 
> > IME the best way to ensure that documentation remains current as the
> > code base changes is to check it in next to the code in the same repo.
> > 
> > This requires a little bit of discipline from the maintainers, to
> > remember to request appropriate docs updates when code patches require
> > them, but has been pretty effective e.g. for the xen-unstable code base.
> 
> While xe man-pages are sorely needed, wouldn't it be better to autogenerate
> it from the existing xe/xapi help by converting it to groff/asciidoc?

According to the original mail it is in asciidoc already, so maybe this
is already the case?

I agree that actually in the source is even better than next to the
source, if it's an option...

> Manually keeping the zillion commands in sync will be quite the ongoing 
> effort.

Someone still needs to write/update the text regardless of where it
lives, but that's as much a code review thing as anything else.

Ian.


_______________________________________________
Xen-api mailing list
Xen-api@xxxxxxxxxxxxx
http://lists.xen.org/cgi-bin/mailman/listinfo/xen-api