BuildingDocumentation
|
Size: 2392
Comment: converted to 1.6 markup
|
Size: 3310
Comment: updating for svn->bzr change and adding section on updating help.ubuntu.com
|
| Deletions are marked like this. | Additions are marked like this. |
| Line 1: | Line 1: |
| ## page was renamed from DocteamBuildingDocumentation = Building Documentation Yourself = |
Documentation which is written in Docbook XML can be quite easily converted into other formats. This page deals with converting to HTML. If you are interested in converting to PDF format, see [[/PDF]]. |
| Line 4: | Line 3: |
| Documentation which is written in Docbook XML can be quite easily converted into other formats. This page deals with converting to HTML. If you are interested in converting to PDF format, see [[/PDF]] | = Building HTML Documentation = |
| Line 6: | Line 5: |
| 1. Set up a copy of the docteam svn repository as described on [[DocumentationTeam/Repository|Repository page]]. If you want the latest documents, get the svn trunk. If you want to build documents for existing Ubuntu releases, get the appropriate svn branch as described on that page. 1. Install at least the following packages: {{{make}}} & {{{docbook-xsl}}}. 1. Open a terminal and change to the appropriate directory ({{{ubuntu-doc/ubuntu}}}, {{{ubuntu-doc/edubuntu}}}, {{{ubuntu-doc/kubuntu}}} or {{{ubuntu-doc/generic}}}). |
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]] and [[apt:docbook-xsl|docbook-xsl]]. |
| Line 16: | Line 14: |
| '''Note:''' Previews of all docteam work in progress are also available on http://docteam.ubuntu.com | 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 18: | Line 17: |
| '''Note:''' You will see a lot of warnings like the following, which can be safely ignored: | 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 20: | Line 19: |
| {{{No localization exists for "c" or "". Using default "en".}}} | = Updating help.ubuntu.com = |
| Line 22: | Line 21: |
| '''Note:''' The above process describes how to build the documents in English. If you wish to build translated versions of the documentation, you will need to edit the Makefile manually and replace each instance of {{{C/}}} with the appropriate language code. If you need help with this, you should [[DocumentationTeam/Contact|contact]] the Documentation team. | 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. |
| Line 24: | Line 23: |
| = Note for Ubuntu 7.04 (Feisty Fawn) = | 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. |
| Line 26: | Line 27: |
| 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 [[https://docteam.ubuntu.com/repos/branches/feisty/ubuntu/fix-urls.sh|script]] named {{{fix-urls.sh}}} to correct the broken internal links. | The [[https://launchpad.net/~canonical-sysadmins|Canonical Sysadmins]] are responsible for updating help.ubuntu.com from the bzr branch. It is intended that the updates will be pulled automatically in the future. |
| Line 28: | Line 29: |
| If building translated copies of the documentation, you will need to adjust the script and replace each instance of {{{C/}}} with the relevant language code. |
'''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. |
Documentation which is written in Docbook XML can be quite easily converted into other formats. This page deals with converting to HTML. If you are interested in converting to PDF format, see /PDF.
Building HTML Documentation
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.
Install at least the following packages: make and docbook-xsl.
Type:
make all
This command will build HTML versions of all the documents available.
Generally 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.
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 Canonical Sysadmins are responsible for updating help.ubuntu.com from the bzr branch. It is intended that the updates will be pulled automatically in the future.
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.
DocumentationTeam/SystemDocumentation/BuildingDocumentation (last edited 2020-04-23 19:58:36 by dsmythies)