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

[Anil Madhavapeddy <anil@xxxxxxxxxx>]

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?
Manually keeping the zillion commands in sync will be quite the ongoing 
effort.

-anil


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