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

Re: [Xen-users] Push for Better Documentation

  • To: Dylan Martin <dmartin@xxxxxxxxxxxx>
  • 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
  • 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=
  • List-id: Xen user discussion <xen-users.lists.xensource.com>

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

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



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