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

[Grant McWilliams <grantmasterflash@xxxxxxxxx>]

On Tue, Sep 25, 2012 at 9:01 AM, Ian Campbell <Ian.Campbell@xxxxxxxxxx> wrote:

That may all be true. But I was talking about about the docs which Grant
has produced, which he said were in asciidoc.

> > 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.
> >
> I wouldn't want to create a barrier for Grant's students (or other
> people that want to contribute). Remember that most are not developers
> but users of XCP. ÂEmbedding the documentation into the code would mean:
> a) existing document source code would need to be refactored
> b) it would create a psychological barrier to contribute
> c) possibly unnecessary process
>
> Keeping the documentation separate (either in a separate repo, or
> directory in an existing repo) is probably the easiest and quickest way
> to get this project off the ground quickly.

In which case I would suggest a directory of the existing xen-api repo
and not a completely separate one.

I agree a directory within xen-api would be great.Â

Â

BTW, I wasn't suggesting that people contributing docs needed to become
code contributors too. Only the inverse which is that people changing
the code should be expect to simultaneously update any docs relevant to
their change. Obviously it is also fine to improve the docs without
changing the code.

Ian.

The way I see it is we can create documentation for the xe help command

in source code the way it's done now (I'm guessing) and export that to man pages or we can go the other way around.

The way I'd envisioned this is we create the ALL documentation in asciidoc which gets transformed into Docbook. From Docbook

we can use XSLT to make anything we want including Admin Guide, manpages and xe help. We can export only the sections we need and in the format weÂneed so for xe help we could include only NAME, SYNOPSIS and DESCRIPTION whereas for manpages we'd include allÂsections etc... I'd need to know more about how the current xe help is created to know if we could transform to that. This way

it keeps theÂdocumentation people writing in a publishing system they know and the coders could either jump over to xen-api github

and update the docs when needed or they could ping the people maintaining them.

This is all theory of course.

Grant McWilliams

_______________________________________________
Xen-devel mailing list
Xen-devel@xxxxxxxxxxxxx
http://lists.xen.org/xen-devel