[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

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

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.


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-api mailing list



Lists.xenproject.org is hosted with RackSpace, monitoring our
servers 24x7x365 and backed by RackSpace's Fanatical Support®.