Re: [Xen-users] Push for Better Documentation

[Nico Kadel-Garcia <nkadel@xxxxxxxxx>]

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