GDP Status Report

1.  Status Reports

Preliminaries

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 gentoo-doc@gentoo.org or to me personally.

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 http://www.gentoo.org/proj/en/gdp.

Content

This status mail will briefly discuss the following tasks, objectives and/or projects related to the GDP:

• Gentoo Handbook
• PDF Documentation
• Coding Style
• Off-project Documentation
• Translation Metadata
• Downloadable Documentation

2.  Gentoo Handbook

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 http://www.gentoo.org/doc/en/handbook/handbook.xml.

We still have to make sure that:

• licensing information is inbedded inside the seperate handbook chapters (as comments)
• all architectures have been correctly represented in the handbook
• all references are correct and are using relative paths to other Gentoo documentation
• 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.

3.  PDF Documentation

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 (see http://emu.gentoo.org/~swift/gentoo-x86-install.pdf).

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.).

4.  Coding Style

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 http://www.gentoo.org/doc/en/xml-guide.xml

5.  Off-project Documentation

I have held a small discussion on gentoo-dev@gentoo.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 (http://www.gentoo.org/doc/en/index.xml).

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>.

6.  Translation Metadata

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 internally.

Interested translation leads can ofcourse use the existing scripts (from Xavier Neys, Tiemo Kieft or Lars Weiler) for their own language (this is even recommended).

7.  Downloadable Documentation

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 gentoo-doc@gentoo.org