BuildingDocumentation
|
Size: 5074
Comment: Updated make targets for current trunk settings & includes edubuntu and xubuntu
|
← Revision 41 as of 2020-04-23 19:58:36 ⇥
Size: 5322
Comment: add link to more detailed installation guide procedure
|
| Deletions are marked like this. | Additions are marked like this. |
| Line 1: | Line 1: |
| ## page was renamed from DocteamBuildingDocumentation = Building Documentation Yourself = |
#title Building the System Documentation |
| Line 4: | Line 3: |
| Docteam documents are built with GNU {{{make}}}. | <<Include(DocumentationTeam/MenuBar)>> <<Include(DocumentationTeam/MeetingBanner)>> |
| Line 6: | Line 6: |
| If you set up your svn repository according to /Repository, then the makefiles required for building the Ubuntu, Kubuntu and Edubuntu docs are in {{{ubuntu-doc/ubuntu}}}, {{{ubuntu-doc/edubuntu}}} and {{{ubuntu-doc/kubuntu}}} respectively. The makefiles required for building generic docs are in {{{ubuntu-doc/generic}}}. | Documentation which is written in Mallard and Docbook XML can be quite easily converted into other formats. This page deals with converting to HTML and PDF. |
| Line 8: | Line 8: |
| To build the docs, open a terminal and change to the appropriate directory ({{{ubuntu-doc/ubuntu}}}, {{{ubuntu-doc/edubuntu}}}, {{{ubuntu-doc/kubuntu}}} or {{{ubuntu-doc/generic}}}). The [#TargetList tables] below show which commands to use to build a specific document or group of documents. You will need to have following packages installed: {{{make}}} & {{{docbook-xsl}}}. | = Building HTML Documentation = |
| Line 10: | Line 10: |
| '''Note:''' These documents are all available on DocteamProjects. | 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. If this is not the first time you have done a build with this branch you must do a {{{ make clean }}} from within the ubuntu-help sub-directory first. 1. Install at least the following packages: make gettext gnome-doc-utils docbook-xsl yelp-tools gnome-common yelp-xsl 1. Type: {{{ ./autogen.sh }}} 1. If more than just english html is desired, then the other languages .page file need to be built first. Type: {{{ cd ubuntu-help make cd .. }}} 1. Now generate the HTML. Type: {{{ cd html make }}} |
| Line 12: | Line 21: |
| '''Note:''' You will see a lot of warnings like the following: | This command will build HTML versions of all the documents available and place them in the html/build directory. |
| Line 14: | Line 23: |
| {{{No localization exists for "c" or "". Using default "en".}}} | The command uses the various language .page files to create the html. |
| Line 16: | Line 25: |
| It is owing to document language setting. In the document, it is mentioned as "&EnglishAmerican;". This variable is defined in {{{ubuntu-doc/libs/global.ent}}} file. If you are worried about this error, you can edit the document and set it as "en". Anyhow, you need not worry about this warning; it does not affect the output. | 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 18: | Line 27: |
| [[Anchor(TargetList)]] Document Set: * [#u Ubuntu] * [#k Kubuntu] * [#e Edubuntu] * [#x Xubuntu] * [#g Generic] |
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 26: | Line 30: |
| '''Note:''' These {{{make}}} targets are documented according to the current state of the {{{Makefiles}}} (in trunk). | 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}}} command described above. |
| Line 28: | Line 32: |
| [[Anchor(u)]] == Ubuntu Documents == From inside the {{{ubuntu-doc/ubuntu}}} directory: |
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 32: | Line 34: |
| ||<#f0f5fa>'''Command'''||<#f0f5fa>'''Document/Result'''||<#f0f5fa>'''Output File Location/Target Location'''|| ||'''make all'''||''builds all targets below''||{{{../build/ubuntu}}}|| ||'''make clean'''||''cleans out build target directory''||{{{../build/ubuntu/}}}|| ||'''make au'''||About Ubuntu||{{{../build/ubuntu/about-ubuntu/C/index.html}}}|| ||'''make rn'''||Release Notes||{{{../build/ubuntu/release-notes/C/index.html}}}|| ||'''make dg'''||Ubuntu Desktop Guide||{{{../build/ubuntu/desktopguide/C/index.html}}}|| ||'''make server'''||Ubuntu Server Guide||{{{../build/serverguide/C/index.html}}}|| ||'''make package'''||Ubuntu Packaging Guide||{{../build/ubuntu/packagingguide/C/index.html}}}|| |
= Updating help.ubuntu.com = |
| Line 41: | Line 36: |
| [[Anchor(k)]] == Kubuntu Documents == From inside the {{{ubuntu-doc/kubuntu}}} directory: |
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/help.ubuntu.com/help.ubuntu.com|specific bzr branch]] on Launchpad. |
| Line 45: | Line 38: |
| ||<#f0f5fa>'''Command'''||<#f0f5fa>'''Document/Result'''||<#f0f5fa>'''Output File Location/Target Location'''|| ||'''make all'''||''builds all targets below''||{{{../build/kubuntu}}}|| ||'''make clean'''||''cleans out build target directory''||{{{../build/kubuntu/}}}|| ||'''make about'''||About Kubuntu||{{{../build/kubuntu/about-kubuntu/C/index.html}}}|| ||'''make desktop'''||Kubuntu Desktop Guide||{{{../build/kubuntu/desktopguide/C/index.html}}}|| ||'''make release-notes'''||Release Notes||{{{../build/kubuntu/release-notes/C/index.html}}}|| ||'''make server'''||Ubuntu Server Guide||{{{../build/kubuntu/serverguide/C/index.html}}}|| ||'''make package'''||Ubuntu Packaging Guide||{{../build/kubuntu/packagingguide/C/index.html}}}|| ||'''make adept-guide'''|| || || ||'''make adept-updater'''|| || || ||'''make addremoveprograms'''|| || || |
The contents of the help.ubuntu.com bzr branch are generally identical to the output of the {{{make}}} commands for all languages described in the previous section, subject to the following exceptions: * The various languages are combined into one sub-directory, differentiated with the language code added to the end of the file name. The web server automatically delivers the correct language content based on the users language settings. To create the required structure, in html/ubuntu-docs, type (from the html sub-directory): {{{ make install }}} * A custom index.html page is used which is not part of the build process. * 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. [[DocumentationTeam/SystemDocumentation/UbuntuInstallationGuide|The detailed procedure]]. * 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. |
| Line 57: | Line 48: |
| [[Anchor(e)]] == Edubuntu == From inside the {{{ubuntu-doc/edubuntu}}} directory: |
The help.ubuntu.com website is automatically pulled once per day from the bzr branch. If this doesn't work, please contact the Canonical Sysadmins after waiting a reasonable period (e.g. at least 24 hours). |
| Line 61: | Line 50: |
| ||<#f0f5fa>'''Command'''||<#f0f5fa>'''Document/Result'''||<#f0f5fa>'''Output File Location/Target Location'''|| ||'''make all'''||''builds all targets below''||{{{../build/edubuntu}}}|| ||'''make ae'''||About Edubuntu||{{{../build/edubuntu/about-edubuntu/C/index.html}}}|| ||'''make rn'''||Release Notes||{{{../build/edubuntu/edubuntu-releasenotes/C/index.html}}}|| ||'''make hb'''||Edubuntu Hand Book||{{{../build/edubuntu/handbook/C/index.html}}}|| ||'''make esa'''||Edubuntu School Advocacy||{{{../build/edubuntu/school-advocacy/C/index.html}}}|| |
'''Note:''' the HTML documentation on help.ubuntu.com should always reflect the documentation as it appears in the applicable version of Ubuntu. For Desktop help, changes to the help.ubuntu.com branch should not be made without the StableReleaseUpdates (SRU) procedure first being followed and an equivalent change being made to the mainline bzr branch for the package version of the project and for the Ubuntu version concerned. The Serverguide is not released as a package and therefore does not require SRU procedures. |
| Line 68: | Line 52: |
| [[Anchor(x)]] == Xubuntu Documents == From inside the {{{ubuntu-doc/xubuntu}}} directory: |
= Building Translated HTML (for DocBook source code) = |
| Line 72: | Line 54: |
| ||<#f0f5fa>'''Command'''||<#f0f5fa>'''Document/Result'''||<#f0f5fa>'''Output File Location/Target Location'''|| ||'''make all'''||''builds desktopguide''||{{{../build/xubuntu}}}|| ||'''make clean'''||''cleans out build target directory''||{{{../build/xubuntu/}}}|| ||'''make desktopguide'''||Xubuntu Desktop Guide||{{{../build/xubuntu/desktopguide/C/index.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. |
| Line 77: | Line 56: |
| [[Anchor(g)]] == Generic Documents == From inside the {{{ubuntu-doc/generic}}} directory: |
You may also wish to modify the header and footer details. These can be found in the {{{libs/ubuntu-banner.xsl}}} file. |
| Line 81: | Line 58: |
| ||<#f0f5fa>'''Command'''||<#f0f5fa>'''Document/Result'''||<#f0f5fa>'''Output File Location/Target Location'''|| ||'''make sg'''||Style Guide||{{{../build/ubuntu/styleguide/C/index.html}}}|| ||'''make sg-pdf'''||Style Guide (PDF)||{{{../build/ubuntu/pdf/C/serverguide.pdf}}}|| ||'''make server'''||Server Guide||{{{../build/serverguide/C/index.html}}}|| ||'''make package'''||Packaging Guide||{{{../build/ubuntu/packagingguide/C/index.html}}}|| |
= 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. |
Inclusion deadlines for Impish – String Freeze: September 16, 2021 / Non-language packs: September 30, 2021 |
Documentation which is written in Mallard and Docbook XML can be quite easily converted into other formats. This page deals with converting to HTML and 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. If this is not the first time you have done a build with this branch you must do a make clean from within the ubuntu-help sub-directory first.
- Install at least the following packages: make gettext gnome-doc-utils docbook-xsl yelp-tools gnome-common yelp-xsl
Type: ./autogen.sh
If more than just english html is desired, then the other languages .page file need to be built first. Type:
cd ubuntu-help make cd ..
Now generate the HTML. Type:
cd html make
This command will build HTML versions of all the documents available and place them in the html/build directory.
The command uses the various language .page files to create the html.
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 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 commands for all languages described in the previous section, subject to the following exceptions:
- The various languages are combined into one sub-directory, differentiated with the language code added to the end of the file name. The web server automatically delivers the correct language content based on the users language settings. To create the required structure, in html/ubuntu-docs, type (from the html sub-directory):
make install
- A custom index.html page is used which is not part of the build process.
A copy of the Ubuntu installation guide is added to the build process together with a custom index.html page. The detailed procedure.
- 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 once per day from the bzr branch. If this doesn't work, please contact the Canonical Sysadmins after waiting a reasonable period (e.g. at least 24 hours).
Note: the HTML documentation on help.ubuntu.com should always reflect the documentation as it appears in the applicable version of Ubuntu. For Desktop help, changes to the help.ubuntu.com branch should not be made without the StableReleaseUpdates (SRU) procedure first being followed and an equivalent change being made to the mainline bzr branch for the package version of the project and for the Ubuntu version concerned. The Serverguide is not released as a package and therefore does not require SRU procedures.
Building Translated HTML (for DocBook source code)
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.
DocumentationTeam/SystemDocumentation/BuildingDocumentation (last edited 2020-04-23 19:58:36 by dsmythies)