GDP Status Report
This is the status of the Gentoo Documentation Project. It will be posted
regularly, but not with a static frequency. All questions can be posted to
email@example.com or to
The Gentoo Documentation Project, from now on abbreviated to GDP, has its own
project page (just like almost all other Gentoo projects). You can find it at
This status mail will briefly discuss the following tasks, objectives and/or
projects related to the GDP:
The GDP is working on a Gentoo Handbook. At this point, a draft version for
"Installing Gentoo" is ready and being reviewed at this moment. You can find
this draft (which will probably be the official location, albeit this has not
been decided yet) at
We still have to make sure that:
licensing information is inbedded inside the seperate handbook chapters
- all architectures have been correctly represented in the handbook
all references are correct and are using relative paths to other Gentoo
the handbook is fool-proof (as far as this is possible without having to
draw stuff :)
If all goes well the reviewing should be finished before saturday. At that
point translation teams can start with translating the handbook. Also, all
changes to the handbook must be according to the documentation policy.
I hope to have the handbook (well, the "Installing Gentoo" chapter) online and
official at the 6th of november.
Several users have been asking for our Gentoo Documentation in PDF format. We
have been investigating possible resolutions, and found that XSL:FO (the
standard way to format XML-content) is the best way as it can be generated
on-the-fly (theoretically) at the server-level.
We have succesfully created a guide2pdf.xsl file that transforms the GuideXML
format to XSL:FO. Although there are still some quirks it is almost
production-ready. It is however *only* meant for the Gentoo Guides (a
book2pdf.xsl will be created when guide2pdf.xsl is working flawlessly).
However, some setbacks have been found. The two ways (PassiveTex.pm in AxKit,
and FOP with Cocoon) have their problems:
PassiveTex doesn't seem to work (pdfxmltex, which is used by
PassiveTex.pm, doesn't want to "compile" the XSL:FO we generate)
Cocoon isn't installed on our webnodes, and is therefor an
infrastructure-request. I haven't got it to work personally on my laptop.
Using FOP manually ("fop gentoo-x86-install.fo gentoo-x86-install.pdf") works
A third way is to have a dynamic script ran on the webservers that converts
the guides to PDF. This has to be checked yet (resourceconsumption, security
aspects, disk usage etc.).
Since previous week we have a Coding Style for the internal GuideXML
sourcecode. All new documentation must adhere to this style so that
intermediate diffs are easy to comprehend and all editors (ppl) can configure
their editor (tool) to use a consistent layout.
If all goes well, most documentation should be "converted" in mid-november.
More information on the Coding Style is available in the XML Guide at
I have held a small discussion on firstname.lastname@example.org regarding off-project
documentation (i.e. documentation specifically created by other Gentoo
projects). From this small discussion I believe that most ppl agree that this
documentation should also be listed on the documentation index page
I will propose a small guideline for such documentation shortly, namely that:
- Only documentation licensed under cc-by-sa is accepted
If the documentation is user-oriented (i.e. non Gentoo development), then
the guide is to be placed in doc/
If the documentation is developer-oriented, then the guide stays in its
proj/ site. Linking occurs at a special section in the documentation index
(which will make clear to other languages that this documentation is and
will only be available in English).
This latter is because developer-oriented documentation doesn't need to be
translated (we should only focus at user-documentation) and the translation
teams don't have access to proj/<language>.
Some translation leads have scripts that inform them about the progress their
translation team(s) make. I have thought about implementing such a page as
dynamical page (dyn/), but I now believe it is more up to the translation
leads (and the translation project lead) to use their own script(s) or means
Interested translation leads can ofcourse use the existing scripts (from
Xavier Neys, Tiemo Kieft or Lars Weiler) for their own language (this is even
Several users want to have the Gentoo Documentation offline available. The
major request is for an ebuild that provides the Gentoo Documentation.
However, such an ebuild would require *very* frequent updates as the Gentoo
Documentation is updated almost on a daily basis.
A better approach would be to have a script or program that fetches the
documentation from the webservers and parses it locally. This could even
include the PDF-support if the webservers don't provide one.
Information about this will be discussed on email@example.com