From e49b2d81d9ca61cc123b509095046cca5f9f578e Mon Sep 17 00:00:00 2001 From: Gabor Pali Date: Wed, 29 Apr 2009 18:51:54 +0000 Subject: [PATCH] Add a subsection on using the documentation ports. Co-authored by: keramida Reviewed by: rene, manolis, trhodes, gabor, Ben Kaduk [1], keramida [1] minimarmot (at) gmail (dot) com --- .../books/handbook/cutting-edge/chapter.sgml | 232 +++++++++++++++++- 1 file changed, 231 insertions(+), 1 deletion(-) diff --git a/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.sgml b/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.sgml index bf09ab0468..7352dd49ed 100644 --- a/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.sgml +++ b/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.sgml @@ -80,7 +80,7 @@ How to keep your documentation up to date with - CVSup. @@ -959,6 +959,236 @@ DOCSUPFILE?= /usr/share/examples/cvsup/doc-supfile &prompt.root; make FORMATS='html html-split' install clean + + + + + Marc + Fonvieille + Based on the work of + + + + + Using Documentation Ports + + Updating and Upgrading + + + documentation package + Updating and Upgrading + + + In the previous section, we have presented a method for + updating the &os; documentation from sources. Sources based on + updates may not be feasible or practical for all &os; systems + though. Building the documentation sources requires a fairly + large collection of tools and utilities, the + documentation toolchain, a certain level of + familiarity with CVS and source + checkouts from a repository, and a few manual steps to build the + checked out sources. In this section, we describe an + alternative way of updating the installed copies of the &os; + documentation; one that uses the Ports Collection and makes + it possible to: + + + + Download and install pre-built snaphots of the + documentation, without having to locally build anything + (eliminating this way the need for an installation of the + entire documentation toolchain). + + + + Download the documentation sources and build them + through the ports framework (making the checkout and build + steps a bit eaiser). + + + + These two methods of updating the &os; documentation are + supported by a set of documentation ports, + updated by the &a.doceng; on a monthly basis. These are listed + in the &os; Ports Collection, under the virtual category + named docs. + + + Building and Installing Documentation Ports + + The documentation ports use the ports building framework + to make documentation builds easier. They automate the + process of checking out the documentation source, running + &man.make.1; with the appropriate environment settings and + command-line options, and they make the installation or + deinstallation of documentation as easy as the installation of + any other &os; port or package. + + + As an extra feature, when the documentation ports are + built locally, they record a dependency to the + documentation toolchain ports, so the + latter is automatically installed too. + + + Organization of the documentation ports is as follows: + + + + There is a master port, misc/freebsd-doc-en, where the + documentation port files can be found. It is the base of + all documentation ports. By default, it builds the + English documentation only. + + + + There is an all in one port, misc/freebsd-doc-all, and it + builds and installs all documentation in all available + languages. + + + + Finally, there is a slave port for + each translation, e.g.: misc/freebsd-doc-hu for the + Hungarian-language documents. All of them depend on the + master port and install the translated documentation of + the respective language. + + + + To install a documentation port from source, issue the + following commands (as root): + + &prompt.root; cd /usr/ports/misc/freebsd-doc-en +&prompt.root; make install clean + + This will build and install the English documentation in + split HTML format (the same as used on ) in the /usr/local/share/doc/freebsd + directory. + + + Common Knobs and Options + + There are many options for modifying the default + behavior of the documentation ports. The following is just + a short list: + + + + WITH_HTML + + + Allows the build of the HTML format: a single HTML + file per document. The formatted documentation is + saved to a file called + article.html, or + book.html, as appropriate, plus + images. + + + + + WITH_PDF + + + Allows the build of the &adobe; Portable Document + Format, for use with &adobe; &acrobat.reader;, + Ghostscript or other PDF + readers. The formatted documentation is saved to a + file called article.pdf or + book.pdf, as appropriate. + + + + + DOCBASE + + + Where to install the documentation. It defaults + to /usr/local/share/doc/freebsd. + + + Notice that the default target directory + differs from the directory used by the + CVSup method. This is + because we are installing a port, and ports are + usually installed under the /usr/local directory. + This can overriden, by adding the + PREFIX variable. + + + + + + Here is a brief example on how to use the variables + mentioned above to install the Hungarian documentation in + Portable Document Format: + + &prompt.root; cd /usr/ports/misc/freebsd-doc-hu +&prompt.root; make -DWITH_PDF DOCBASE=share/doc/freebsd/hu install clean + + + + + Using Documentation Packages + + Building the documentation ports from source, as described + in the previous section, requires a local installation of the + documentation toolchain and a bit of disk space for the build + of the ports. When resources are not available to install the + documentation toolchain, or because the build from sources + would take too much disk space), it is still possible to + install pre-built snapshots of the documentation ports. + + The &a.doceng; prepares monthly snapshots of the &os; + documentation packages. These binary packages can be used + with any of the bundled package tools, like &man.pkg.add.1;, + &man.pkg.delete.1;, and so on. + + + When binary packages are used, the &os; documentation + will be installed in all available + formats for the given language. + + + For example, the following command will install the latest + pre-built package of the Hungarian documentation: + + &prompt.root; pkg_add -r hu-freebsd-doc + + + Packages have the following name format that differs + from the corresponding port's name: + lang-freebsd-doc. + Here lang is the short format of + the language code, i.e. hu for + Hungarian, or zh_cn for Simplified + Chinese. + + + + + Updating Documentation Ports + + To update a previously installed documentation port, any + tool suitable for updating ports is sufficient. For example, + the following command updates the installed Hungarian + documentation via the ports-mgmt/portupgrade tool by + using packages only: + + &prompt.root; portupgrade -PP hu-freebsd-doc + + +