BuildingDocumentation

Differences between revisions 1 and 27 (spanning 26 versions)
⇤ ← Revision 1 as of 2005-05-28 20:11:18 →
Size: 1796
Editor: adsl-213-190-44-43
Comment: imported from the old wiki
← Revision 27 as of 2013-04-14 23:42:21 → ⇥
Size: 4883
Editor: dsmythies
Comment: seems to also need gnome-common
Deletions are marked like this. Additions are marked like this.
Line 1: Line 1:
= DocteamBuildingDocumentation = #title Building the System Documentation
Line 3: Line 3:
The makefile found in the root of the Subversion repository trunk directory can be used to transform the Docbook XML documents into presentational formats. As of this writing the only presentational format is HTML. We expect to add PDF shortly. <<Include(DocumentationTeam/SystemDocumentation/MenuBar)>>
Line 5: Line 5:
To use the makefile you will need to install GNU make (you'll find it in the 'make' package). Documentation which is written in Docbook XML can be quite easily converted into other formats. This page deals with converting to HTML and PDF.
Line 7: Line 7:
Other build dependencies for most of the documentation are the packages 'docbook-xsl' and 'xsltproc'. = Building HTML Documentation =
Line 9: Line 9:
To transform a document using make:  1. Set up a copy of the docteam bzr branch as described on [[DocumentationTeam/SystemDocumentation/Repository|Repository page]]. Choose the appropriate branch for the version of Ubuntu documentation you wish to build.
 1. Install at least the following packages: [[apt:make|make]], [[apt:gettext|gettext]], [[apt:docbook-xsl|docbook-xsl]], [[apt:yelp-tools|yelp-tools]], [[apt:gnome-common|gnome-common]], and [[apt:yelp-xsl|yelp-xsl]].
 1. Type:
Line 11: Line 13:
 1. Make trunk/ your present working directory
 2. Run the command {{{
make [targetname]		 {{{
./autogen.sh
cd html
make all
Line 16: Line 19:
If your build is very slow trying to download things from the Internet, try running make as: {{{
XML_CATALOG_FILES=/usr/share/xml/docbook/schema/dtd/4.3/catalog.xml make [targetname]
}}}		 This command will build HTML versions of all the documents available.
Line 20: Line 21:
== Make Targets == The command uses docbook-xsl templates to customise the output of the html. The majority of the templates used are supplied by the docbook-xsl package, but some custom templates are used to create the Ubuntu theme. These custom templates can be found in the libs/ directory of the branch and are called by the Makefile. For more information about docbook-xsl, please see the [[http://www.sagehill.net/docbookxsl/|Docbook XSL: The Complete Guide]].
Line 22: Line 23:
The makefile provides the following targets: There are a number of other make targets which you can use to build specific or miscellaneous documents. Read through the Makefile to discover what these are.
Line 24: Line 25:
 all:: builds all documents
 ug:: build the User's Guide (UserGuide) (outputs to trunk/build/userguide/)
 qg:: builds the Quick Guide (QuickGuide) (outputs to trunk/build/quickguide/)
 faq:: builds the Frequently Asked Questions ([FAQGuide]) (outputs to trunk/build/faqguide/)
 ag:: builds the Administrators Guide (AdminGuide) (outputs to trunk/build/adminguide/)
 abt:: builds the About Ubuntu page (AboutUbuntuPage) (outputs to trunk/build/about-ubuntu/home/)
 rn:: builds the Release Notes (outputs to trunk/build/release-notes/)
 status:: builds the Project Status Reports (outputs to trunk/build/reports/)
 dist:: builds documents and prepares a source tarball (outputs to trunk/ubuntu-docs/)
 clean:: removes any mess made during the builds		 You will see a lot of warnings like the following, which can be safely ignored:
 {{{No localization exists for "c" or "". Using default "en".}}}
Line 35: Line 28:
Example make command and target: Since Ubuntu 7.04, the Ubuntu system documentation has split into several categories, many of which link between them using an internal Gnome/KDE linking system. When the documents are converted into HTML, this results in a lot of links being broken. For this reason we use a script called {{{fix-urls.sh}}} to correct the broken internal links. This script is run automatically as part of the {{{make all}}} command described above.
Line 37: Line 30:
{{{
 make ug
}}}		 In case you are building kubuntu-docs on Ubuntu system, you will also need to install [[apt:khelpcenter4|khelpcenter4]] package at step 2 above (It would have already been installed on a Kubuntu system).
Line 41: Line 32:
To view any of these documents just open index.html found in the relevant build directory. = Updating help.ubuntu.com =

The static pages on [[https://help.ubuntu.com|help.ubuntu.com]] (as opposed to the [[https://help.ubuntu.com/community|community wiki]]) are kept updated by pushing the HTML documents built to a [[https://code.launchpad.net/~ubuntu-core-doc/ubuntu-doc/help.ubuntu.com|specific bzr branch]] on Launchpad.

The contents of the help.ubuntu.com bzr branch are generally identical to the output of the {{{make all}}} command described in the previous section, subject to the following exceptions:
 * A custom index.html page is used which is not part of the build process. The index.html page which is produced by the build process is discarded.
 * A copy of the [[https://launchpad.net/ubuntu/+source/installation-guide|Ubuntu installation guide]] is added to the build process together with a custom index.html page. See the {{{install}}} target in the Makefile for information about how this is done.
 * The PDF version of the serverguide should be built separately. See below for instructions.
 * The root index for the website should be manually updated to add or remove links to each release as they are added or removed from the site.

The help.ubuntu.com website is automatically pulled regularly from the bzr branch. If this doesn't work, please contact the Canonical Sysadmins after waiting a reasonable period (e.g. 24 hours).

'''Note:''' the HTML documentation on help.ubuntu.com should always reflect the documentation as it appears in the applicable version of Ubuntu. Changes to the help.ubuntu.com branch should not be made without the StableReleaseUpdates procedure first being followed and an equivalent change being made to the mainline bzr branch for the Ubuntu version concerned.

= Building Translated HTML =

If building translated copies of the documentation, you will need to adjust the Makefile and substitute your language code for the {{{LN}}} variable defined near the top of the Makefile.

You may also wish to modify the header and footer details. These can be found in the {{{libs/ubuntu-banner.xsl}}} file.

= Building PDF =

To build PDF, we currently use a tool called [[http://xmlgraphics.apache.org/fop/|Apache Fop]].

Currently, the only document which we build a PDF version of is the Ubuntu Server Guide. To build a PDF version of the Server Guide, [[apt:fop|install the fop package]] and run the following command from an ubuntu-doc branch:
 {{{make serverguide-pdf}}}

If you are interested in building other documents, read the {{{serverguide-pdf}}} target in the Makefile for more information.

----
CategoryDocteam

Documentation which is written in Docbook XML can be quite easily converted into other formats. This page deals with converting to HTML and PDF.

Building HTML Documentation

  1. Set up a copy of the docteam bzr branch as described on Repository page. Choose the appropriate branch for the version of Ubuntu documentation you wish to build.

  2. Install at least the following packages: make, gettext, docbook-xsl, yelp-tools, gnome-common, and yelp-xsl.

  3. Type: 

./autogen.sh
cd html
make all

This command will build HTML versions of all the documents available.

The command uses docbook-xsl templates to customise the output of the html. The majority of the templates used are supplied by the docbook-xsl package, but some custom templates are used to create the Ubuntu theme. These custom templates can be found in the libs/ directory of the branch and are called by the Makefile. For more information about docbook-xsl, please see the Docbook XSL: The Complete Guide.

There are a number of other make targets which you can use to build specific or miscellaneous documents. Read through the Makefile to discover what these are.

You will see a lot of warnings like the following, which can be safely ignored:

  • No localization exists for "c" or "". Using default "en".

Since Ubuntu 7.04, the Ubuntu system documentation has split into several categories, many of which link between them using an internal Gnome/KDE linking system. When the documents are converted into HTML, this results in a lot of links being broken. For this reason we use a script called fix-urls.sh to correct the broken internal links. This script is run automatically as part of the make all command described above.

In case you are building kubuntu-docs on Ubuntu system, you will also need to install khelpcenter4 package at step 2 above (It would have already been installed on a Kubuntu system).

Updating help.ubuntu.com

The static pages on help.ubuntu.com (as opposed to the community wiki) are kept updated by pushing the HTML documents built to a specific bzr branch on Launchpad.

The contents of the help.ubuntu.com bzr branch are generally identical to the output of the make all command described in the previous section, subject to the following exceptions:

  • A custom index.html page is used which is not part of the build process. The index.html page which is produced by the build process is discarded.

  • A copy of the Ubuntu installation guide is added to the build process together with a custom index.html page. See the install target in the Makefile for information about how this is done.

  • The PDF version of the serverguide should be built separately. See below for instructions.
  • The root index for the website should be manually updated to add or remove links to each release as they are added or removed from the site.

The help.ubuntu.com website is automatically pulled regularly from the bzr branch. If this doesn't work, please contact the Canonical Sysadmins after waiting a reasonable period (e.g. 24 hours).

Note: the HTML documentation on help.ubuntu.com should always reflect the documentation as it appears in the applicable version of Ubuntu. Changes to the help.ubuntu.com branch should not be made without the StableReleaseUpdates procedure first being followed and an equivalent change being made to the mainline bzr branch for the Ubuntu version concerned.

Building Translated HTML

If building translated copies of the documentation, you will need to adjust the Makefile and substitute your language code for the LN variable defined near the top of the Makefile.

You may also wish to modify the header and footer details. These can be found in the libs/ubuntu-banner.xsl file.

Building PDF

To build PDF, we currently use a tool called Apache Fop.

Currently, the only document which we build a PDF version of is the Ubuntu Server Guide. To build a PDF version of the Server Guide, install the fop package and run the following command from an ubuntu-doc branch:

  • make serverguide-pdf

If you are interested in building other documents, read the serverguide-pdf target in the Makefile for more information.

CategoryDocteam

DocumentationTeam/SystemDocumentation/BuildingDocumentation (last edited 2020-04-23 19:58:36 by dsmythies)