WARNING - OLD ARCHIVES

This is an archived copy of the Xen.org mailing list, which we have preserved to ensure that existing links to archives are not broken. The live archive, which contains the latest emails, can be found at http://lists.xen.org/
   
 
 
Xen 
 
Home Products Support Community News
 
   
 

xen-users

Re: [Xen-users] Push for Better Documentation

To: Dylan Martin <dmartin@xxxxxxxxxxxx>
Subject: Re: [Xen-users] Push for Better Documentation
From: Nico Kadel-Garcia <nkadel@xxxxxxxxx>
Date: Wed, 18 Jul 2007 23:00:19 +0100
Cc: Xen Users <xen-users@xxxxxxxxxxxxxxxxxxx>
Delivery-date: Wed, 18 Jul 2007 14:58:00 -0700
Dkim-signature: a=rsa-sha1; c=relaxed/relaxed; d=gmail.com; s=beta; h=domainkey-signature:received:received:message-id:date:from:user-agent:mime-version:to:cc:subject:references:in-reply-to:content-type:content-transfer-encoding; b=Xya5VnFgvpOQZA+FSKAB5u/naFOg+4xu1DEQmyovEXUWn8x8cuTjv5DLEev0eczfn5O6o/fUpX3mcD2yejwbmDurH6D4wEBBY7I3umyk2ZImHn+oTYpjsAbk3VzrTgRY7bzS+VKDe/jXUdVk6EGSWISWNljUsPE+7QZqSGHASHo=
Domainkey-signature: a=rsa-sha1; c=nofws; d=gmail.com; s=beta; h=received:message-id:date:from:user-agent:mime-version:to:cc:subject:references:in-reply-to:content-type:content-transfer-encoding; b=jV9SQ26+c3VJ90Se7Fv9yU5MiviWdXPqgwlEN/M1SCkcNW9B/PZNTAoGCRFb+yfS7idooEAmEefV9wUtSwLH6QW+yH2KUw3PckDEEZ8u6CuA/NHirerSnXh3zvPDVkEyVqGf/mfN7K1UjLH/e41QsF68tJs+v2gIbToXNvGnAkM=
Envelope-to: www-data@xxxxxxxxxxxxxxxxxx
In-reply-to: <20070718214422.GN30252@xxxxxxxxxxxx>
List-help: <mailto:xen-users-request@lists.xensource.com?subject=help>
List-id: Xen user discussion <xen-users.lists.xensource.com>
List-post: <mailto:xen-users@lists.xensource.com>
List-subscribe: <http://lists.xensource.com/cgi-bin/mailman/listinfo/xen-users>, <mailto:xen-users-request@lists.xensource.com?subject=subscribe>
List-unsubscribe: <http://lists.xensource.com/cgi-bin/mailman/listinfo/xen-users>, <mailto:xen-users-request@lists.xensource.com?subject=unsubscribe>
References: <20070710011615.GA25845@xxxxxxxxxxxx> <03ce01c7c2ff$15d4b8e0$6d58a8c0@xxxxxxxxxxxxxxxxxxxxxxxxx> <20070711003248.GA2640@xxxxxxxxxxxx> <04d601c7c3a4$d2d4e910$6d58a8c0@xxxxxxxxxxxxxxxxxxxxxxxxx> <20070718202540.GK30252@xxxxxxxxxxxx> <ce6304780707181356p681e182fh7e5af632ec165691@xxxxxxxxxxxxxx> <20070718214422.GN30252@xxxxxxxxxxxx>
Sender: xen-users-bounces@xxxxxxxxxxxxxxxxxxx
User-agent: Thunderbird 1.5.0.12 (Windows/20070509)
Dylan Martin wrote:
   I'm sorry, but please look again. A number of documents  from the tarball
   are in *LaTeX*.  It converts the LaTeX documentation into podfiles and
   turns those into man pages, using /usr/bin/latex, /usr/bin/dot,
   /usr/bin/ps2pdf, and a variety of other undocumented requirements to
   rebuild the documentation from their original format.

If you're only interested in man pages, you only need to worry about
the pod stuff.  The longer docs, like the user guide or the xen-api
doc might be in other formats.  To convert pod to pdf you first
convert it to latex, so that's part of what you're seeing.

It looks like the make file only uses tools it finds.  For instance,
it won't build the python-dev-docs if it doesn't find doxygen.
I get "make docs" casting errors, and failing. This makes modifying the .spec file to build RPM's rather awkward. The RHEL and Fedora Core bundles do a better job of this, I'm afraid.

So, if you want to edit the man pages, you can do so without worrying
about latex or anything else.
OK, the xenapi documents, for example, seem to be in LaTeX format.

   Inconsistent document format is a long-standing problem of a lot of
   projects.

Yes.  I totally agree about this.  It's a total pain that they're not
all written in pod or docbook or some other single format.  You can
always convert between formats, but you should have one canonical
format for your project.
Especially when hte LaTeX stuff throws errors, which seem to still produce a printable page, but wind up hanging at a LaTeX debugging console.....

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

<Prev in Thread] Current Thread [Next in Thread>