diff options
| author | Warren Block <wblock@FreeBSD.org> | 2015-10-31 20:45:54 +0000 |
|---|---|---|
| committer | Warren Block <wblock@FreeBSD.org> | 2015-10-31 20:45:54 +0000 |
| commit | 4f25f34ddde1b52238574033851c042a23d251e4 (patch) | |
| tree | f6aef6e298e28d5cb7851fe409625539f7f73872 /nl_NL.ISO8859-1/books/fdp-primer | |
| parent | 6457f53b95a8cb3477f9bc6c862acec13493845e (diff) | |
| download | doc-4f25f34ddde1b52238574033851c042a23d251e4.tar.gz doc-4f25f34ddde1b52238574033851c042a23d251e4.zip | |
Remove unnecessary files.
Notes
Notes:
svn path=/head/; revision=47716
Diffstat (limited to 'nl_NL.ISO8859-1/books/fdp-primer')
18 files changed, 0 insertions, 8987 deletions
diff --git a/nl_NL.ISO8859-1/books/fdp-primer/chapters.ent b/nl_NL.ISO8859-1/books/fdp-primer/chapters.ent deleted file mode 100644 index 55c9cdcf53..0000000000 --- a/nl_NL.ISO8859-1/books/fdp-primer/chapters.ent +++ /dev/null @@ -1,29 +0,0 @@ -<?xml version="1.0" encoding="iso-8859-1"?> -<!-- - Creates entities for each chapter in the Documentation Project Primer. - Each entity is named chap.foo, where foo is the value of the id - attribute on that chapter, and corresponds to the name of the - directory in which that chapter's .xml file is stored. - - Chapters should be listed in the order in which they are referenced. - - $FreeBSD$ ---> - -<!ENTITY chap.overview SYSTEM "overview/chapter.xml"> -<!ENTITY chap.tools SYSTEM "tools/chapter.xml"> -<!ENTITY chap.working-copy SYSTEM "working-copy/chapter.xml"> -<!ENTITY chap.structure SYSTEM "structure/chapter.xml"> -<!ENTITY chap.doc-build SYSTEM "doc-build/chapter.xml"> -<!ENTITY chap.the-website SYSTEM "the-website/chapter.xml"> -<!ENTITY chap.xml-primer SYSTEM "xml-primer/chapter.xml"> -<!ENTITY chap.xhtml-markup SYSTEM "xhtml-markup/chapter.xml"> -<!ENTITY chap.docbook-markup SYSTEM "docbook-markup/chapter.xml"> -<!ENTITY chap.stylesheets SYSTEM "stylesheets/chapter.xml"> -<!ENTITY chap.translations SYSTEM "translations/chapter.xml"> -<!ENTITY chap.po-translations SYSTEM "po-translations/chapter.xml"> -<!ENTITY chap.writing-style SYSTEM "writing-style/chapter.xml"> -<!ENTITY chap.editor-config SYSTEM "editor-config/chapter.xml"> -<!ENTITY chap.see-also SYSTEM "see-also/chapter.xml"> - -<!ENTITY app.examples SYSTEM "examples/appendix.xml"> diff --git a/nl_NL.ISO8859-1/books/fdp-primer/doc-build/chapter.xml b/nl_NL.ISO8859-1/books/fdp-primer/doc-build/chapter.xml deleted file mode 100644 index d2ef3545dd..0000000000 --- a/nl_NL.ISO8859-1/books/fdp-primer/doc-build/chapter.xml +++ /dev/null @@ -1,529 +0,0 @@ -<?xml version="1.0" encoding="iso-8859-1"?> -<!-- Copyright (c) 1999 Neil Blakey-Milner, All rights reserved. - - Redistribution and use in source (SGML DocBook) and 'compiled' forms - (SGML HTML, PDF, PostScript, RTF and so forth) with or without - modification, are permitted provided that the following conditions - are met: - - 1. Redistributions of source code (SGML DocBook) must retain the above - copyright notice, this list of conditions and the following - disclaimer as the first lines of this file unmodified. - - 2. Redistributions in compiled form (transformed to other DTDs, - converted to PDF, PostScript, RTF and other formats) must reproduce - the above copyright notice, this list of conditions and the - following disclaimer in the documentation and/or other materials - provided with the distribution. - - THIS DOCUMENTATION IS PROVIDED BY THE AUTHOR "AS IS" AND ANY EXPRESS OR - IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES - OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE - DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT, - INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES - (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR - SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) - HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, - STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN - ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE - POSSIBILITY OF SUCH DAMAGE. - - $FreeBSD$ ---> -<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="doc-build"> - <title>The Documentation Build Process</title> - - <para>This chapter covers organization of the documentation build - process and how &man.make.1; is used to control it.</para> - - <sect1 xml:id="doc-build-rendering"> - <title>Rendering DocBook into Output</title> - - <para>Different types of output can be produced from a single - DocBook source file. The type of output desired is set with the - <varname>FORMATS</varname> variable. A list of known formats is - stored in <varname>KNOWN_FORMATS</varname>:</para> - - <screen xml:id="doc-build-rendering-known-formats">&prompt.user; <userinput>cd ~/doc/en_US.ISO8859-1/books/handbook</userinput> -&prompt.user; <userinput>make -V KNOWN_FORMATS</userinput></screen> - - <table xml:id="doc-build-rendering-common-formats" frame="none"> - <title>Common Output Formats</title> - - <tgroup cols="3"> - <thead> - <row> - <entry><varname>FORMATS</varname> Value</entry> - <entry>File Type</entry> - <entry>Description</entry> - </row> - </thead> - - <tbody> - <row> - <entry><literal>html</literal></entry> - <entry><acronym>HTML</acronym>, one file</entry> - <entry>A single <filename>book.html</filename> or - <filename>article.html</filename>.</entry> - </row> - - <row> - <entry><literal>html-split</literal></entry> - <entry><acronym>HTML</acronym>, multiple files</entry> - <entry>Multiple <acronym>HTML</acronym> files, one for - each chapter or section, for use on a typical web - site.</entry> - </row> - - <row> - <entry><literal>pdf</literal></entry> - <entry><acronym>PDF</acronym></entry> - <entry>Portable Document Format</entry> - </row> - </tbody> - </tgroup> - </table> - - <para>The default output format can vary by document, but is - usually <literal>html-split</literal>. Other formats are chosen - by setting <varname>FORMATS</varname> to a specific value. - Multiple output formats can be created at a single time by - setting <varname>FORMATS</varname> to a list of formats.</para> - - <example xml:id="doc-build-formats-example-html"> - <title>Build a Single HTML Output File</title> - - <screen>&prompt.user; <userinput>cd ~/doc/en_US.ISO8859-1/books/handbook</userinput> -&prompt.user; <userinput>make FORMATS=html</userinput></screen> - </example> - - <example xml:id="doc-build-formats-example-html-split-pdf"> - <title>Build HTML-Split and <acronym>PDF</acronym> Output - Files</title> - - <screen>&prompt.user; <userinput>cd ~/doc/en_US.ISO8859-1/books/handbook</userinput> -&prompt.user; <userinput>make FORMATS="html-split pdf"</userinput></screen> - </example> - </sect1> - - <sect1 xml:id="doc-build-toolset"> - <title>The &os; Documentation Build Toolset</title> - - <para>These are the tools used to build and install the - <acronym>FDP</acronym> documentation.</para> - - <itemizedlist> - <listitem> - <para>The primary build tool is &man.make.1;, specifically - <application>Berkeley Make</application>.</para> - </listitem> - - <listitem> - <para>Package building is handled by &os;'s - &man.pkg.create.1;.</para> - </listitem> - - <listitem> - <para>&man.gzip.1; is used to create compressed versions of - the document. &man.bzip2.1; archives are also supported. - &man.tar.1; is used for package building.</para> - </listitem> - - <listitem> - <para>&man.install.1; is used to install the - documentation.</para> - </listitem> - </itemizedlist> - </sect1> - - <sect1 xml:id="doc-build-makefiles"> - - <title>Understanding <filename>Makefile</filename>s in the - Documentation Tree</title> - - <para>There are three main types of <filename>Makefile</filename>s - in the &os; Documentation Project tree.</para> - - <itemizedlist> - <listitem> - <para><link linkend="sub-make">Subdirectory - <filename>Makefile</filename>s</link> simply pass - commands to those directories below them.</para> - </listitem> - - <listitem> - <para><link linkend="doc-make">Documentation - <filename>Makefile</filename>s</link> describe the - document(s) that should be produced from this - directory.</para> - </listitem> - - <listitem> - <para><link linkend="make-includes"><application>Make</application> - includes</link> are the glue that perform the document - production, and are usually of the form - <filename>doc.<replaceable>xxx</replaceable>.mk</filename>.</para> - </listitem> - </itemizedlist> - - <sect2 xml:id="sub-make"> - <title>Subdirectory <filename>Makefile</filename>s</title> - - <para>These <filename>Makefile</filename>s usually take the form - of:</para> - - <programlisting>SUBDIR =articles -SUBDIR+=books - -COMPAT_SYMLINK = en - -DOC_PREFIX?= ${.CURDIR}/.. -.include "${DOC_PREFIX}/share/mk/doc.project.mk"</programlisting> - - <para>The first four non-empty lines define the &man.make.1; - variables <varname>SUBDIR</varname>, - <varname>COMPAT_SYMLINK</varname>, and - <varname>DOC_PREFIX</varname>.</para> - - <para>The <varname>SUBDIR</varname> statement and - <varname>COMPAT_SYMLINK</varname> statement show how to - assign a value to a variable, overriding any previous - value.</para> - - <para>The second <varname>SUBDIR</varname> statement shows how a - value is appended to the current value of a variable. The - <varname>SUBDIR</varname> variable is now <literal>articles - books</literal>.</para> - - <para>The <varname>DOC_PREFIX</varname> assignment shows how a - value is assigned to the variable, but only if it is not - already defined. This is useful if - <varname>DOC_PREFIX</varname> is not where this - <filename>Makefile</filename> thinks it is - the user can - override this and provide the correct value.</para> - - <para>What does it all mean? <varname>SUBDIR</varname> - mentions which subdirectories below this one the build process - should pass any work on to.</para> - - <para><varname>COMPAT_SYMLINK</varname> is specific to - compatibility symlinks (amazingly enough) for languages to - their official encoding (<filename>doc/en</filename> would - point to <filename>en_US.ISO-8859-1</filename>).</para> - - <para><varname>DOC_PREFIX</varname> is the path to the root of - the &os; Document Project tree. This is not always that easy - to find, and is also easily overridden, to allow for - flexibility. <varname>.CURDIR</varname> is a &man.make.1; - builtin variable with the path to the current - directory.</para> - - <para>The final line includes the &os; Documentation Project's - project-wide &man.make.1; system file - <filename>doc.project.mk</filename> which is the glue which - converts these variables into build instructions.</para> - </sect2> - - <sect2 xml:id="doc-make"> - <title>Documentation <filename>Makefile</filename>s</title> - - <para>These <filename>Makefile</filename>s set &man.make.1; - variables that describe how to build the documentation - contained in that directory.</para> - - <para>Here is an example:</para> - - <programlisting>MAINTAINER=nik@FreeBSD.org - -DOC?= book - -FORMATS?= html-split html - -INSTALL_COMPRESSED?= gz -INSTALL_ONLY_COMPRESSED?= - -# SGML content -SRCS= book.xml - -DOC_PREFIX?= ${.CURDIR}/../../.. - -.include "$(DOC_PREFIX)/share/mk/docproj.docbook.mk"</programlisting> - - <para>The <varname>MAINTAINER</varname> variable allows - committers to claim ownership of a document in the &os; - Documentation Project, and take responsibility for maintaining - it.</para> - - <para><varname>DOC</varname> is the name (sans the - <filename>.xml</filename> extension) of the main document - created by this directory. <varname>SRCS</varname> lists all - the individual files that make up the document. This should - also include important files in which a change should result - in a rebuild.</para> - - <para><varname>FORMATS</varname> indicates the default formats - that should be built for this document. - <varname>INSTALL_COMPRESSED</varname> is the default list of - compression techniques that should be used in the document - build. <varname>INSTALL_ONLY_COMPRESS</varname>, empty by - default, should be non-empty if only compressed documents are - desired in the build.</para> - - <para>The <varname>DOC_PREFIX</varname> and include statements - should be familiar already.</para> - </sect2> - </sect1> - - <sect1 xml:id="make-includes"> - <title>&os; Documentation Project - <application>Make</application> Includes</title> - - <para>&man.make.1; includes are best explained by inspection of - the code. Here are the system include files:</para> - - <itemizedlist> - <listitem> - <para><filename>doc.project.mk</filename> is the main project - include file, which includes all the following include - files, as necessary.</para> - </listitem> - - <listitem> - <para><filename>doc.subdir.mk</filename> handles traversing of - the document tree during the build and install - processes.</para> - </listitem> - - <listitem> - <para><filename>doc.install.mk</filename> provides variables - that affect ownership and installation of documents.</para> - </listitem> - - <listitem> - <para><filename>doc.docbook.mk</filename> is included if - <varname>DOCFORMAT</varname> is <literal>docbook</literal> - and <varname>DOC</varname> is set.</para> - </listitem> - </itemizedlist> - - <sect2> - <title><filename>doc.project.mk</filename></title> - - <para>By inspection:</para> - - <programlisting>DOCFORMAT?= docbook -MAINTAINER?= doc@FreeBSD.org - -PREFIX?= /usr/local -PRI_LANG?= en_US.ISO8859-1 - -.if defined(DOC) -.if ${DOCFORMAT} == "docbook" -.include "doc.docbook.mk" -.endif -.endif - -.include "doc.subdir.mk" -.include "doc.install.mk"</programlisting> - - <sect3> - - <title>Variables</title> - - <para><varname>DOCFORMAT</varname> and - <varname>MAINTAINER</varname> are assigned default values, - if these are not set by the document make file.</para> - - <para><varname>PREFIX</varname> is the prefix under which the - <link linkend="tools">documentation building tools</link> - are installed. For normal package and port installation, - this is <filename>/usr/local</filename>.</para> - - <para><varname>PRI_LANG</varname> should be set to whatever - language and encoding is natural amongst users these - documents are being built for. US English is the - default.</para> - - <note> - <para><varname>PRI_LANG</varname> does not affect which - documents can, or even will, be built. Its main use is - creating links to commonly referenced documents into the - &os; documentation install root.</para> - </note> - </sect3> - - <sect3> - <title>Conditionals</title> - - <para>The <literal>.if defined(DOC)</literal> line is an - example of a &man.make.1; conditional which, like in other - programs, defines behavior if some condition is true or if - it is false. <literal>defined</literal> is a function which - returns whether the variable given is defined or not.</para> - - <para><literal>.if ${DOCFORMAT} == "docbook"</literal>, next, - tests whether the <varname>DOCFORMAT</varname> variable is - <literal>"docbook"</literal>, and in this case, includes - <filename>doc.docbook.mk</filename>.</para> - - <para>The two <literal>.endif</literal>s close the two above - conditionals, marking the end of their application.</para> - </sect3> - </sect2> - - <sect2> - <title><filename>doc.subdir.mk</filename></title> - - <para>This file is too long to explain in detail. These notes - describe the most important features.</para> - - <sect3> - <title>Variables</title> - - <itemizedlist> - <listitem> - <para><varname>SUBDIR</varname> is a list of - subdirectories that the build process should go further - down into.</para> - </listitem> - - <listitem> - <para><varname>ROOT_SYMLINKS</varname> is the name of - directories that should be linked to the document - install root from their actual locations, if the current - language is the primary language (specified by - <varname>PRI_LANG</varname>).</para> - </listitem> - - <listitem> - <para><varname>COMPAT_SYMLINK</varname> is described in - the - <link linkend="sub-make">Subdirectory Makefile</link> - section.</para> - </listitem> - </itemizedlist> - </sect3> - - <sect3> - <title>Targets and Macros</title> - - <para>Dependencies are described by - <literal><replaceable>target</replaceable>: - <replaceable>dependency1 dependency2 - ...</replaceable></literal> tuples, where to build - <literal>target</literal>, the given - dependencies must be built first.</para> - - <para>After that descriptive tuple, instructions on how to - build the target may be given, if the conversion process - between the target and its dependencies are not previously - defined, or if this particular conversion is not the same as - the default conversion method.</para> - - <para>A special dependency <literal>.USE</literal> defines - the equivalent of a macro.</para> - - <programlisting>_SUBDIRUSE: .USE -.for entry in ${SUBDIR} - @${ECHO} "===> ${DIRPRFX}${entry}" - @(cd ${.CURDIR}/${entry} && \ - ${MAKE} ${.TARGET:S/realpackage/package/:S/realinstall/install/} DIRPRFX=${DIRPRFX}${entry}/ ) -.endfor</programlisting> - - <para>In the above, <buildtarget>_SUBDIRUSE</buildtarget> is now - a macro which will execute the given commands when it is - listed as a dependency.</para> - - <para>What sets this macro apart from other targets? - Basically, it is executed <emphasis>after</emphasis> the - instructions given in the build procedure it is listed as a - dependency to, and it does not adjust - <varname>.TARGET</varname>, which is the variable which - contains the name of the target currently being - built.</para> - - <programlisting>clean: _SUBDIRUSE - rm -f ${CLEANFILES}</programlisting> - - <para>In the above, <buildtarget>clean</buildtarget> will use - the <buildtarget>_SUBDIRUSE</buildtarget> macro after it has - executed the instruction - <command>rm -f ${CLEANFILES}</command>. In effect, this - causes <buildtarget>clean</buildtarget> to go further and - further down the directory tree, deleting built files as it - goes <emphasis>down</emphasis>, not on the way back - up.</para> - - <sect4> - <title>Provided Targets</title> - - <itemizedlist> - <listitem> - <para><buildtarget>install</buildtarget> and - <buildtarget>package</buildtarget> both go down the - directory tree calling the real versions of themselves - in the subdirectories - (<buildtarget>realinstall</buildtarget> and - <buildtarget>realpackage</buildtarget> - respectively).</para> - </listitem> - - <listitem> - <para><buildtarget>clean</buildtarget> removes files - created by the build process (and goes down the - directory tree too). - <buildtarget>cleandir</buildtarget> does the same, and - also removes the object directory, if any.</para> - </listitem> - </itemizedlist> - </sect4> - </sect3> - - <sect3> - <title>More on Conditionals</title> - - <itemizedlist> - <listitem> - <para><literal>exists</literal> is another condition - function which returns true if the given file - exists.</para> - </listitem> - - <listitem> - <para><literal>empty</literal> returns true if the given - variable is empty.</para> - </listitem> - - <listitem> - <para><literal>target</literal> returns true if the given - target does not already exist.</para> - </listitem> - </itemizedlist> - </sect3> - - <sect3> - <title>Looping Constructs in <command>make - (.for)</command></title> - - <para><literal>.for</literal> provides a way to repeat a set - of instructions for each space-separated element in a - variable. It does this by assigning a variable to contain - the current element in the list being examined.</para> - - <programlisting>_SUBDIRUSE: .USE -.for entry in ${SUBDIR} - @${ECHO} "===> ${DIRPRFX}${entry}" - @(cd ${.CURDIR}/${entry} && \ - ${MAKE} ${.TARGET:S/realpackage/package/:S/realinstall/install/} DIRPRFX=${DIRPRFX}${entry}/ ) -.endfor</programlisting> - - <para>In the above, if <varname>SUBDIR</varname> is empty, no - action is taken; if it has one or more elements, the - instructions between <literal>.for</literal> and - <literal>.endfor</literal> would repeat for every element, - with <varname>entry</varname> being replaced with the value - of the current element.</para> - </sect3> - </sect2> - </sect1> -</chapter> diff --git a/nl_NL.ISO8859-1/books/fdp-primer/docbook-markup/chapter.xml b/nl_NL.ISO8859-1/books/fdp-primer/docbook-markup/chapter.xml deleted file mode 100644 index 94bcb542d2..0000000000 --- a/nl_NL.ISO8859-1/books/fdp-primer/docbook-markup/chapter.xml +++ /dev/null @@ -1,2744 +0,0 @@ -<?xml version="1.0" encoding="iso-8859-1"?> -<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved. - - Redistribution and use in source (SGML DocBook) and 'compiled' forms - (SGML HTML, PDF, PostScript, RTF and so forth) with or without - modification, are permitted provided that the following conditions - are met: - - 1. Redistributions of source code (SGML DocBook) must retain the above - copyright notice, this list of conditions and the following - disclaimer as the first lines of this file unmodified. - - 2. Redistributions in compiled form (transformed to other DTDs, - converted to PDF, PostScript, RTF and other formats) must reproduce - the above copyright notice, this list of conditions and the - following disclaimer in the documentation and/or other materials - provided with the distribution. - - THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR - IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES - OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE - DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT, - INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES - (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR - SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) - HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, - STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN - ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE - POSSIBILITY OF SUCH DAMAGE. - - $FreeBSD$ ---> - -<chapter xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" - xml:id="docbook-markup"> - - <title>DocBook Markup</title> - - <sect1 xml:id="docbook-markup-introduction"> - <title>Introduction</title> - - <para>This chapter is an introduction to DocBook as it is used for - &os; documentation. DocBook is a large and complex markup - system, but the subset described here covers the parts that are - most widely used for &os; documentation. While a moderate - subset is covered, it is impossible to anticipate every - situation. Please post questions that this document does - not answer to the &a.doc;.</para> - - <para>DocBook was originally developed by HaL Computer Systems and - O'Reilly & Associates to be a Document Type Definition - (<acronym>DTD</acronym>) for writing technical documentation - <footnote><para>A short history can be found under <link - xlink:href="http://www.oasis-open.org/docbook/intro.shtml#d0e41">http://www.oasis-open.org/docbook/intro.shtml#d0e41</link>.</para></footnote>. - Since 1998 it is maintained by the <link - xlink:href="http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=docbook"> - DocBook Technical Committee</link>. As such, and unlike - LinuxDoc and <acronym>XHTML</acronym>, DocBook is very heavily - oriented towards markup that describes <emphasis>what</emphasis> - something is, rather than describing <emphasis>how</emphasis> it - should be presented.</para> - - <para>The DocBook <acronym>DTD</acronym> is available from the - Ports Collection in the - <package>textproc/docbook-xml</package> - port. It is automatically installed as part of the - <package>textproc/docproj</package> - port.</para> - - <note> - <title>Formal Versus Informal</title> - - <para>Some elements may exist in two forms, - <emphasis>formal</emphasis> and <emphasis>informal</emphasis>. - Typically, the formal version of the element will consist of a - title followed by the informal version of the element. The - informal version will not have a title.</para> - </note> - - <note> - <title>Inline Versus Block</title> - - <para>In the remainder of this document, when describing - elements, <emphasis>inline</emphasis> means that the element - can occur within a block element, and does not cause a line - break. A <emphasis>block</emphasis> element, by comparison, - will cause a line break (and other processing) when it is - encountered.</para> - </note> - </sect1> - - <sect1 xml:id="docbook-markup-freebsd-extensions"> - <title>&os; Extensions</title> - - <para>The &os; Documentation Project has extended the DocBook - <acronym>DTD</acronym> with additional elements and entities. - These additions serve to make some of the markup easier or more - precise.</para> - - <para>Throughout the rest of this document, the term - <quote>DocBook</quote> is used to mean the &os;-extended - DocBook <acronym>DTD</acronym>.</para> - - <note> - <para>Most of these extensions are not unique to &os;, it was - just felt that they were useful enhancements for this - particular project. Should anyone from any of the other *nix - camps (NetBSD, OpenBSD, Linux, …) be interested in - collaborating on a standard DocBook extension set, please - contact &a.doceng;.</para> - </note> - - <sect2 xml:id="docbook-markup-freebsd-extensions-elements"> - <title>&os; Elements</title> - - <para>The additional &os; elements are not (currently) in the - Ports Collection. They are stored in the &os; Subversion - tree, as <link - xlink:href="http://svnweb.FreeBSD.org/doc/head/share/xml/freebsd.dtd">head/share/xml/freebsd.dtd</link>.</para> - - <para>&os;-specific elements used in the examples below are - clearly marked.</para> - </sect2> - - <sect2 xml:id="docbook-markup-freebsd-extensions-entities"> - <title>&os; Entities</title> - - <para>This table shows some of the most useful entities - available in the <acronym>FDP</acronym>. For a complete list, - see the <filename>*.ent</filename> files in - <filename>doc/share/xml</filename>.</para> - - <informaltable frame="none" pgwide="1"> - <tgroup cols="3"> - <colspec colname="entity"/> - <colspec colname="expandsto"/> - <colspec colname="notes"/> - <thead> - <row> - <entry></entry> - <entry></entry> - <entry></entry> - </row> - </thead> - - <tbody valign="top"> - <row> - <entry namest="entity" nameend="notes"><emphasis>&os; - Name Entities</emphasis></entry> - </row> - - <row> - <entry><literal>&os;</literal></entry> - <entry><literal>&os;</literal></entry> - <entry/> - </row> - - <row> - <entry><literal>&os.stable;</literal></entry> - <entry><literal>&os.stable;</literal></entry> - <entry/> - </row> - - <row> - <entry><literal>&os.current;</literal></entry> - <entry><literal>&os.current;</literal></entry> - <entry/> - </row> - - <row> - <entry/> - <entry/> - <entry/> - </row> - - <row> - <entry namest="entity" nameend="notes">Manual Page - Entities</entry> - </row> - - <row> - <entry><literal>&man.ls.1;</literal></entry> - <entry>&man.ls.1;</entry> - <entry>Usage: <literal>&man.ls.1; is the manual page - for - <command>ls</command>.</literal></entry> - </row> - - <row> - <entry><literal>&man.cp.1;</literal></entry> - <entry>&man.cp.1;</entry> - <entry>Usage: <literal>The manual page for - <command>cp</command> is - &man.cp.1;.</literal></entry> - </row> - - <row> - <entry><literal>&man.<replaceable>command</replaceable>.<replaceable>sectionnumber</replaceable>;</literal></entry> - <entry><emphasis>link to - <replaceable>command</replaceable> manual page in - section - <replaceable>sectionnumber</replaceable></emphasis></entry> - <entry>Entities are defined for all the - <link xlink:href="&url.base;/cgi/man.cgi">&os; manual - pages</link>.</entry> - </row> - - <row> - <entry/> - <entry/> - <entry/> - </row> - - <row> - <entry namest="entity" nameend="notes">&os; Mailing List - Entities</entry> - </row> - - <row> - <entry><literal>&a.doc;</literal></entry> - <entry><literal>&a.doc;</literal></entry> - <entry>Usage: <literal>A link to the - &a.doc;.</literal></entry> - </row> - - <row> - <entry><literal>&a.questions;</literal></entry> - <entry><literal>&a.questions;</literal></entry> - <entry>Usage: <literal>A link to the - &a.questions;.</literal></entry> - </row> - - <row> - <entry><literal>&a.<replaceable>listname</replaceable>;</literal></entry> - <entry><emphasis>link to - <replaceable>listname</replaceable></emphasis></entry> - <entry>Entities are defined for all the <link - xlink:href="&url.books.handbook;/eresources.html#eresources-mail">&os; - mailing lists</link>.</entry> - </row> - - <row> - <entry/> - <entry/> - <entry/> - </row> - - <row> - <entry namest="entity" nameend="notes">&os; Document - Link Entities</entry> - </row> - - <row> - <entry><literal>&url.books.handbook;</literal></entry> - <entry><literal>&url.books.handbook;</literal></entry> - <entry>Usage: <literal>A link to the <link - xlink:href="&url.books.handbook;/advanced-networking.html">Advanced - Networking</link> chapter of the - Handbook.</literal></entry> - </row> - - <row> - <entry><literal>&url.books.<replaceable>bookname</replaceable>;</literal></entry> - <entry><emphasis>relative path to - <replaceable>bookname</replaceable></emphasis></entry> - <entry>Entities are defined for all the <link - xlink:href="&url.doc.langbase;/books/">&os; - books</link>.</entry> - </row> - - <row> - <entry><literal>&url.articles.committers-guide;</literal></entry> - <entry><literal>&url.articles.committers-guide;</literal></entry> - <entry>Usage: <literal>A link to the <link - xlink:href="&url.articles.committers-guide;">Committer's - Guide</link> - article.</literal></entry> - </row> - - <row> - <entry><literal>&url.articles.<replaceable>articlename</replaceable>;</literal></entry> - <entry><emphasis>relative path to - <replaceable>articlename</replaceable></emphasis></entry> - <entry>Entities are defined for all the <link - xlink:href="&url.doc.langbase;/articles/">&os; - articles</link>.</entry> - </row> - - <row> - <entry/> - <entry/> - <entry/> - </row> - - <row> - <entry namest="entity" nameend="notes">Other Operating - System Name Entities</entry> - </row> - - <row> - <entry><literal>&linux;</literal></entry> - <entry>&linux;</entry> - <entry>The &linux; operating system.</entry> - </row> - - <row> - <entry><literal>&unix;</literal></entry> - <entry>&unix;</entry> - <entry>The &unix; operating system.</entry> - </row> - - <row> - <entry><literal>&windows;</literal></entry> - <entry>&windows;</entry> - <entry>The &windows; operating system.</entry> - </row> - - <row> - <entry/> - <entry/> - <entry/> - </row> - - <row> - <entry namest="entity" nameend="notes">Miscellaneous - Entities</entry> - </row> - - <row> - <entry><literal>&prompt.root;</literal></entry> - <entry>&prompt.root;</entry> - <entry>The <systemitem - class="username">root</systemitem> user - prompt.</entry> - </row> - - <row> - <entry><literal>&prompt.user;</literal></entry> - <entry>&prompt.user;</entry> - <entry>A prompt for an unprivileged user.</entry> - </row> - - <row> - <entry><literal>&postscript;</literal></entry> - <entry>&postscript;</entry> - <entry>The - &postscript; programming language.</entry> - </row> - - <row> - <entry><literal>&tex;</literal></entry> - <entry>&tex;</entry> - <entry>The - &tex; typesetting language.</entry> - </row> - - <row> - <entry><literal>&xorg;</literal></entry> - <entry>&xorg;</entry> - <entry>The &xorg; open source X - Window System.</entry> - </row> - </tbody> - </tgroup> - </informaltable> - </sect2> - </sect1> - - <sect1 xml:id="docbook-markup-fpi"> - <title>Formal Public Identifier (FPI)</title> - - <para>In compliance with the DocBook guidelines for writing - <acronym>FPI</acronym>s for DocBook customizations, the - <acronym>FPI</acronym> for the &os; extended DocBook - <acronym>DTD</acronym> is:</para> - - <programlisting>PUBLIC "-//FreeBSD//DTD DocBook V4.2-Based Extension//EN"</programlisting> - </sect1> - - <sect1 xml:id="docbook-markup-document-structure"> - <title>Document Structure</title> - - <para>DocBook allows structuring documentation in several ways. - The &os; Documentation Project uses two primary types of DocBook - document: the book and the article.</para> - - <para>Books are organized into <tag>chapter</tag>s. - This is a mandatory requirement. There may be - <tag>part</tag>s between the book and the chapter to - provide another layer of organization. For example, the - Handbook is arranged in this way.</para> - - <para>A chapter may (or may not) contain one or more sections. - These are indicated with the <tag>sect1</tag> element. - If a section contains another section then use the - <tag>sect2</tag> element, and so on, up to - <tag>sect5</tag>.</para> - - <para>Chapters and sections contain the remainder of the - content.</para> - - <para>An article is simpler than a book, and does not use - chapters. Instead, the content of an article is organized into - one or more sections, using the same <tag>sect1</tag> - (and <tag>sect2</tag> and so on) elements that are used - in books.</para> - - <para>The nature of the document being written should be used to - determine whether it is best marked up as a book or an article. - Articles are well suited to information that does not need to be - broken down into several chapters, and that is, relatively - speaking, quite short, at up to 20-25 pages of content. Books - are best suited to information that can be broken up into - several chapters, possibly with appendices and similar content - as well.</para> - - <para>The <link xlink:href="&url.base;/docs.html">&os; - tutorials</link> are all marked up as articles, while this - document, the <link - xlink:href="&url.books.faq;/index.html">FAQ</link>, - and the <link - xlink:href="&url.books.handbook;/index.html">Handbook</link> are all marked up as books, for - example.</para> - - <sect2 xml:id="docbook-markup-starting-a-book"> - <title>Starting a Book</title> - - <para>The content of a book is contained within the - <tag>book</tag> element. As well as containing - structural markup, this element can contain elements that - include additional information about the book. This is either - meta-information, used for reference purposes, or additional - content used to produce a title page.</para> - - <para>This additional information is contained within - <tag>info</tag>.</para> - - <example> - <title>Boilerplate <tag>book</tag> with - <tag>info</tag></title> - - <!-- Cannot put this in a marked section because of the - replaceable elements --> - - <programlisting><tag class="starttag">book</tag> - <tag class="starttag">info</tag> - <tag class="starttag">title</tag><replaceable>Your Title Here</replaceable><tag class="endtag">title</tag> - - <tag class="starttag">author</tag> - <tag class="starttag">personname</tag> - <tag class="starttag">firstname</tag><replaceable>Your first name</replaceable><tag class="endtag">firstname</tag> - <tag class="starttag">surname</tag><replaceable>Your surname</replaceable><tag class="endtag">surname</tag> - <tag class="endtag">personname</tag> - - <tag class="starttag">affiliation</tag> - <tag class="starttag">address</tag> - <tag class="starttag">email</tag><replaceable>Your email address</replaceable><tag class="endtag">email</tag> - <tag class="endtag">address</tag> - <tag class="endtag">affiliation</tag> - <tag class="endtag">author</tag> - - <tag class="starttag">copyright</tag> - <tag class="starttag">year</tag><replaceable>1998</replaceable><tag class="endtag">year</tag> - <tag class="starttag">holder role="mailto:<replaceable>your email address</replaceable>"</tag><replaceable>Your name</replaceable><tag class="endtag">holder</tag> - <tag class="endtag">copyright</tag> - - <tag class="starttag">releaseinfo</tag>$&os;$<tag class="endtag">releaseinfo</tag> - - <tag class="starttag">abstract</tag> - <tag class="starttag">para</tag><replaceable>Include an abstract of the book's contents here.</replaceable><tag class="endtag">para</tag> - <tag class="endtag">abstract</tag> - <tag class="endtag">info</tag> - - … - -<tag class="endtag">book</tag></programlisting> - </example> - </sect2> - - <sect2 xml:id="docbook-markup-starting-an-article"> - <title>Starting an Article</title> - - <para>The content of the article is contained within the - <tag>article</tag> element. As well as containing - structural markup, this element can contain elements that - include additional information about the article. This is - either meta-information, used for reference purposes, or - additional content used to produce a title page.</para> - - <para>This additional information is contained within - <tag>info</tag>.</para> - - <example> - <title>Boilerplate <tag>article</tag> with - <tag>info</tag></title> - - <!-- Cannot put this in a marked section because of the - replaceable elements --> - - <programlisting><tag class="starttag">article</tag> - <tag class="starttag">info</tag> - <tag class="starttag">title</tag><replaceable>Your title here</replaceable><tag class="endtag">title</tag> - - <tag class="starttag">author</tag> - <tag class="starttag">personname</tag> - <tag class="starttag">firstname</tag><replaceable>Your first name</replaceable><tag class="endtag">firstname</tag> - <tag class="starttag">surname</tag><replaceable>Your surname</replaceable><tag class="endtag">surname</tag> - <tag class="endtag">personname</tag> - - <tag class="starttag">affiliation</tag> - <tag class="starttag">address</tag> - <tag class="starttag">email</tag><replaceable>Your email address</replaceable><tag class="endtag">email</tag><tag class="endtag">address</tag> - <tag class="endtag">address</tag> - <tag class="endtag">affiliation</tag> - <tag class="endtag">author</tag> - - <tag class="starttag">copyright</tag> - <tag class="starttag">year</tag><replaceable>1998</replaceable><tag class="endtag">year</tag> - <tag class="starttag">holder role="mailto:<replaceable>your email address</replaceable>"</tag><replaceable>Your name</replaceable><tag class="endtag">holder</tag> - <tag class="endtag">copyright</tag> - - <tag class="starttag">releaseinfo</tag>$&os;$<tag class="endtag">releaseinfo</tag> - - <tag class="starttag">abstract</tag> - <tag class="starttag">para</tag><replaceable>Include an abstract of the article's contents here.</replaceable><tag class="endtag">para</tag> - <tag class="endtag">abstract</tag> - <tag class="endtag">info</tag> - - … - -<tag class="endtag">article</tag></programlisting> - </example> - </sect2> - - <sect2 xml:id="docbook-markup-indicating-chapters"> - <title>Indicating Chapters</title> - - <para>Use <tag>chapter</tag> to mark up your chapters. - Each chapter has a mandatory <tag>title</tag>. - Articles do not contain chapters, they are reserved for - books.</para> - - <example> - <title>A Simple Chapter</title> - - <programlisting><tag class="starttag">chapter</tag> - <tag class="starttag">title</tag>The Chapter's Title<tag class="endtag">title</tag> - - ... -<tag class="endtag">chapter</tag></programlisting> - </example> - - <para>A chapter cannot be empty; it must contain elements in - addition to <tag>title</tag>. If you need to - include an empty chapter then just use an empty - paragraph.</para> - - <example> - <title>Empty Chapters</title> - - <programlisting><tag class="starttag">chapter</tag> - <tag class="starttag">title</tag>This is An Empty Chapter<tag class="endtag">title</tag> - - <tag class="starttag">para</tag><tag class="endtag">para</tag> -<tag class="endtag">chapter</tag></programlisting> - </example> - </sect2> - - <sect2 xml:id="docbook-markup-sections-below-chapters"> - <title>Sections Below Chapters</title> - - <para>In books, chapters may (but do not need to) be broken up - into sections, subsections, and so on. In articles, sections - are the main structural element, and each article must contain - at least one section. Use the - <tag>sect<replaceable>n</replaceable></tag> element. - The <replaceable>n</replaceable> indicates the section number, - which identifies the section level.</para> - - <para>The first - <tag>sect<replaceable>n</replaceable></tag> is - <tag>sect1</tag>. You can have one or more of these - in a chapter. They can contain one or more - <tag>sect2</tag> elements, and so on, down to - <tag>sect5</tag>.</para> - - <example> - <title>Sections in Chapters</title> - - <programlisting><tag class="starttag">chapter</tag> - <tag class="starttag">title</tag>A Sample Chapter<tag class="endtag">title</tag> - - <tag class="starttag">para</tag>Some text in the chapter.<tag class="endtag">para</tag> - - <tag class="starttag">sect1</tag> - <tag class="starttag">title</tag>First Section<tag class="endtag">title</tag> - - … - <tag class="endtag">sect1</tag> - - <tag class="starttag">sect1</tag> - <tag class="starttag">title</tag>Second Section<tag class="endtag">title</tag> - - <tag class="starttag">sect2</tag> - <tag class="starttag">title</tag>First Sub-Section<tag class="endtag">title</tag> - - <tag class="starttag">sect3</tag> - <tag class="starttag">title</tag>First Sub-Sub-Section<tag class="endtag">title</tag> - - … - <tag class="endtag">sect3</tag> - <tag class="endtag">sect2</tag> - - <tag class="starttag">sect2</tag> - <tag class="starttag">title</tag>Second Sub-Section (1.2.2)<tag class="endtag">title</tag> - - … - <tag class="endtag">sect2</tag> - <tag class="endtag">sect1</tag> -<tag class="endtag">chapter</tag></programlisting> - </example> - - <note> - <para>Section numbers are automatically generated and - prepended to titles when the document is rendered to an - output format. The generated section numbers and titles - from the example above will be:</para> - - <itemizedlist> - <listitem> - <para>1.1. First Section</para> - </listitem> - - <listitem> - <para>1.2. Second Section</para> - </listitem> - - <listitem> - <para>1.2.1. First Sub-Section</para> - </listitem> - - <listitem> - <para>1.2.1.1. First Sub-Sub-Section</para> - </listitem> - - <listitem> - <para>1.2.2. Second Sub-Section</para> - </listitem> - </itemizedlist> - </note> - </sect2> - - <sect2 xml:id="docbook-markup-subdividing-part"> - <title>Subdividing Using <tag>part</tag> - Elements</title> - - <para><tag>part</tag>s introduce another level of - organization between <tag>book</tag> and - <tag>chapter</tag> with one or more - <tag>part</tag>s. This cannot be done in an - <tag>article</tag>.</para> - - <programlisting><tag class="starttag">part</tag> - <tag class="starttag">title</tag>Introduction<tag class="endtag">title</tag> - - <tag class="starttag">chapter</tag> - <tag class="starttag">title</tag>Overview<tag class="endtag">title</tag> - - ... - <tag class="endtag">chapter</tag> - - <tag class="starttag">chapter</tag> - <tag class="starttag">title</tag>What is FreeBSD?<tag class="endtag">title</tag> - - ... - <tag class="endtag">chapter</tag> - - <tag class="starttag">chapter</tag> - <tag class="starttag">title</tag>History<tag class="endtag">title</tag> - - ... - <tag class="endtag">chapter</tag> -<tag class="endtag">part</tag></programlisting> - </sect2> - </sect1> - - <sect1 xml:id="docbook-markup-block-elements"> - <title>Block Elements</title> - - <sect2 xml:id="docbook-markup-paragraphs"> - <title>Paragraphs</title> - - <para>DocBook supports three types of paragraphs: - <tag>formalpara</tag>, <tag>para</tag>, and - <tag>simpara</tag>.</para> - - <para>Almost all paragraphs in &os; documentation use - <tag>para</tag>. <tag>formalpara</tag> - includes a <tag>title</tag> element, and - <tag>simpara</tag> disallows some elements from - within <tag>para</tag>. Stick with - <tag>para</tag>.</para> - - <example> - <title><tag>para</tag> Example</title> - - <para>Usage:</para> - - <programlisting><tag class="starttag">para</tag>This is a paragraph. It can contain just about any - other element.<tag class="endtag">para</tag></programlisting> - - <para>Appearance:</para> - - <para>This is a paragraph. It can contain just about any - other element.</para> - </example> - </sect2> - - <sect2 xml:id="docbook-markup-block-quotations"> - <title>Block Quotations</title> - - <para>A block quotation is an extended quotation from another - document that should not appear within the current paragraph. - These are rarely needed.</para> - - <para>Blockquotes can optionally contain a title and an - attribution (or they can be left untitled and - unattributed).</para> - - <example> - <title><tag>blockquote</tag> Example</title> - - <para>Usage:</para> - - <programlisting><tag class="starttag">para</tag>A small excerpt from the US Constitution:<tag class="endtag">para</tag> - -<tag class="starttag">blockquote</tag> - <tag class="starttag">title</tag>Preamble to the Constitution of the United States<tag class="endtag">title</tag> - - <tag class="starttag">attribution</tag>Copied from a web site somewhere<tag class="endtag">attribution</tag> - - <tag class="starttag">para</tag>We the People of the United States, in Order to form a more - perfect Union, establish Justice, insure domestic Tranquility, - provide for the common defence, promote the general Welfare, and - secure the Blessings of Liberty to ourselves and our Posterity, do - ordain and establish this Constitution for the United States of - America.<tag class="endtag">para</tag> -<tag class="endtag">blockquote</tag></programlisting> - - <para>Appearance:</para> - - <para>A small excerpt from the US Constitution:</para> - - <blockquote> - <title>Preamble to the Constitution of the United - States</title> - - <attribution>Copied from a web site - somewhere</attribution> - - <para>We the People of the United States, in Order to form - a more perfect Union, establish Justice, insure domestic - Tranquility, provide for the common defence, promote the - general Welfare, and secure the Blessings of Liberty to - ourselves and our Posterity, do ordain and establish - this Constitution for the United States of - America.</para> - </blockquote> - </example> - </sect2> - - <sect2 xml:id="docbook-markup-tips-notes"> - <title>Tips, Notes, Warnings, Cautions, and Important - Information</title> - - <para>Extra information may need to be separated from - the main body of the text. Typically this is - <quote>meta</quote> information of which the user should be - aware.</para> - - <para>Several types of admonitions are available: - <tag>tip</tag>, <tag>note</tag>, - <tag>warning</tag>, <tag>caution</tag>, and - <tag>important</tag>.</para> - - <para>Which admonition to choose depends on the situation. - The DocBook - documentation suggests:</para> - - <itemizedlist> - <listitem> - <para>Note is for information that should be heeded by - all readers.</para> - </listitem> - - <listitem> - <para>Important is a variation on Note.</para> - </listitem> - - <listitem> - <para>Caution is for information regarding possible data - loss or software damage.</para> - </listitem> - - <listitem> - <para>Warning is for information regarding possible - hardware damage or injury to life or limb.</para> - </listitem> - </itemizedlist> - - <example> - <title><tag>tip</tag> and <tag>important</tag> Example</title> - - <para>Usage:</para> - - <programlisting><tag class="starttag">tip</tag> - <tag class="starttag">para</tag>&os; may reduce stress.<tag class="endtag">para</tag> -<tag class="endtag">tip</tag> - -<tag class="starttag">important</tag> - <tag class="starttag">para</tag>Please use admonitions sparingly. Too many admonitions - are visually jarring and can have the opposite of the - intended effect.<tag class="endtag">para</tag> -<tag class="endtag">important</tag></programlisting> - </example> - - <para>Appearance:</para> - <!-- Need to do this outside of the example --> - <tip> - <para>&os; may reduce stress.</para> - </tip> - - <important> - <para>Please use admonitions sparingly. Too many admonitions - are visually jarring and can have the opposite of the - intended effect.</para> - </important> - </sect2> - - <sect2 xml:id="docbook-markup-example"> - <title>Examples</title> - - <para>Examples can be shown with <tag>example</tag>.</para> - - <example> - <title><tag>example</tag> Source</title> - - <para>Usage:</para> - - <programlisting><tag class="starttag">example</tag> - <tag class="starttag">para</tag>Empty files can be created easily:<tag class="endtag">para</tag> - - <tag class="starttag">screen</tag>&prompt.user; <tag class="starttag">userinput</tag>touch file1 file2 file3<tag class="endtag">userinput</tag><tag class="endtag">screen</tag> -<tag class="endtag">example</tag></programlisting> - </example> - - <!-- Need to do this outside of the example --> - <para>Appearance:</para> - - <example> - <title>Rendered <tag>example</tag></title> - - <para>Empty files can be created easily:</para> - - <screen>&prompt.user; <userinput>touch file1 file2 file3</userinput></screen> - </example> - </sect2> - - <sect2 xml:id="docbook-markup-lists-and-procedures"> - <title>Lists and Procedures</title> - - <para>Information often needs to be presented as lists, or as a - number of steps that must be carried out in order to - accomplish a particular goal.</para> - - <para>To do this, use <tag>itemizedlist</tag>, - <tag>orderedlist</tag>, <tag>variablelist</tag>, or - <tag>procedure</tag>. There are other types of list - elements in DocBook, but we will not cover them here.</para> - - <para><tag>itemizedlist</tag> and - <tag>orderedlist</tag> are similar to their - counterparts in <acronym>HTML</acronym>, <tag>ul</tag> - and <tag>ol</tag>. Each one consists of one or more - <tag>listitem</tag> elements, and each - <tag>listitem</tag> contains one or more block - elements. The <tag>listitem</tag> elements are - analogous to <acronym>HTML</acronym>'s <tag>li</tag> - tags. However, unlike HTML, they are required.</para> - - <example> - <title><tag>itemizedlist</tag> and - <tag>orderedlist</tag> Example</title> - - <para>Usage:</para> - - <programlisting><tag class="starttag">itemizedlist</tag> - <tag class="starttag">listitem</tag> - <tag class="starttag">para</tag>This is the first itemized item.<tag class="endtag">para</tag> - <tag class="endtag">listitem</tag> - - <tag class="starttag">listitem</tag> - <tag class="starttag">para</tag>This is the second itemized item.<tag class="endtag">para</tag> - <tag class="endtag">listitem</tag> -<tag class="endtag">itemizedlist</tag> - -<tag class="starttag">orderedlist</tag> - <tag class="starttag">listitem</tag> - <tag class="starttag">para</tag>This is the first ordered item.<tag class="endtag">para</tag> - <tag class="endtag">listitem</tag> - - <tag class="starttag">listitem</tag> - <tag class="starttag">para</tag>This is the second ordered item.<tag class="endtag">para</tag> - <tag class="endtag">listitem</tag> -<tag class="endtag">orderedlist</tag></programlisting> - - <para>Appearance:</para> - - <itemizedlist> - <listitem> - <para>This is the first itemized item.</para> - </listitem> - - <listitem> - <para>This is the second itemized item.</para> - </listitem> - </itemizedlist> - - <orderedlist> - <listitem> - <para>This is the first ordered item.</para> - </listitem> - - <listitem> - <para>This is the second ordered item.</para> - </listitem> - </orderedlist> - </example> - - <para xml:id="docbook-markup-varlist">An alternate and often - useful way of presenting information is the - <tag>variablelist</tag>. These are lists where each entry has - a term and a description. They are well suited for many types - of descriptions, and present information in a form that is - often easier for the reader than sections and - subsections.</para> - - <para>A <tag>variablelist</tag> has a <tag>title</tag>, and then - pairs of <tag>term</tag> and <tag>listitem</tag> - entries.</para> - - <example xml:id="docbook-markup-variablelist-example"> - <title><tag>variablelist</tag> Example</title> - - <para>Usage:</para> - - <programlisting><tag class="starttag">variablelist</tag> - <tag class="starttag">varlistentry</tag> - <tag class="starttag">term</tag>Parallel<tag class="endtag">term</tag> - - <tag class="starttag">listitem</tag> - <tag class="starttag">para</tag>In parallel communications, groups of bits arrive - at the same time over multiple communications - channels.<tag class="endtag">para</tag> - <tag class="endtag">listitem</tag> - <tag class="endtag">varlistentry</tag> - - <tag class="starttag">varlistentry</tag> - <tag class="starttag">term</tag>Serial<tag class="endtag">term</tag> - - <tag class="starttag">listitem</tag> - <tag class="starttag">para</tag>In serial communications, bits arrive one at a - time over a single communications - channel.<tag class="endtag">para</tag> - <tag class="endtag">listitem</tag> - <tag class="endtag">varlistentry</tag> -<tag class="endtag">variablelist</tag></programlisting> - - <para>Appearance:</para> - - <variablelist> - <varlistentry> - <term>Parallel</term> - - <listitem> - <para>In parallel communications, groups of bits arrive - at the same time over multiple communications - channels.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Serial</term> - - <listitem> - <para>In serial communications, bits arrive one at a - time over a single communications channel.</para> - </listitem> - </varlistentry> - </variablelist> - </example> - - <para>A <tag>procedure</tag> shows a series of - <tag>step</tag>s, which may in turn - consist of more <tag>step</tag>s or - <tag>substep</tag>s. Each <tag>step</tag> - contains block elements and may include an optional title.</para> - - <para>Sometimes, steps are not sequential, but present a choice: - do <emphasis>this</emphasis> or do <emphasis>that</emphasis>, - but not both. For these alternative choices, use - <tag>stepalternatives</tag>.</para> - - <example> - <title><tag>procedure</tag> Example</title> - - <para>Usage:</para> - - <programlisting><tag class="starttag">procedure</tag> - <tag class="starttag">step</tag> - <tag class="starttag">para</tag>Do this.<tag class="endtag">para</tag> - <tag class="endtag">step</tag> - - <tag class="starttag">step</tag> - <tag class="starttag">para</tag>Then do this.<tag class="endtag">para</tag> - <tag class="endtag">step</tag> - - <tag class="starttag">step</tag> - <tag class="starttag">para</tag>And now do this.<tag class="endtag">para</tag> - <tag class="endtag">step</tag> - - <tag class="starttag">step</tag> - <tag class="starttag">para</tag>Finally, do one of these.<tag class="endtag">para</tag> - - <tag class="starttag">stepalternatives</tag> - <tag class="starttag">step</tag> - <tag class="starttag">para</tag>Go left.<tag class="endtag">para</tag> - <tag class="endtag">step</tag> - - <tag class="starttag">step</tag> - <tag class="starttag">para</tag>Go right.<tag class="endtag">para</tag> - <tag class="endtag">step</tag> - <tag class="endtag">stepalternatives</tag> - <tag class="endtag">step</tag> -<tag class="endtag">procedure</tag></programlisting> - - <para>Appearance:</para> - - <procedure> - <step> - <para>Do this.</para> - </step> - - <step> - <para>Then do this.</para> - </step> - - <step> - <para>And now do this.</para> - </step> - - <step> - <para>Finally, do one of these:</para> - - <stepalternatives> - <step> - <para>Go left.</para> - </step> - - <step> - <para>Go right.</para> - </step> - </stepalternatives> - </step> - </procedure> - </example> - </sect2> - - <sect2 xml:id="docbook-markup-showing-file-samples"> - <title>Showing File Samples</title> - - <para>Fragments of a file (or perhaps a complete file) are shown - by wrapping them in the <tag>programlisting</tag> - element.</para> - - <para>White space and line breaks within - <tag>programlisting</tag> <emphasis>are</emphasis> - significant. In particular, this means that the opening tag - should appear on the same line as the first line of the - output, and the closing tag should appear on the same line - as the last line of the output, otherwise spurious blank - lines may be included.</para> - - <example> - <title><tag>programlisting</tag> Example</title> - - <para>Usage:</para> - - <programlisting><tag class="starttag">para</tag>When finished, the program will look like - this:<tag class="endtag">para</tag> - -<tag class="starttag">programlisting</tag>#include &lt;stdio.h&gt; - -int -main(void) -{ - printf("hello, world\n"); -}<tag class="endtag">programlisting</tag></programlisting> - - <para>Notice how the angle brackets in the - <literal>#include</literal> line need to be referenced by - their entities instead of being included literally.</para> - - <para>Appearance:</para> - - <para>When finished, the program will look like this:</para> - - <programlisting>#include <stdio.h> - -int -main(void) -{ - printf("hello, world\n"); -}</programlisting> - </example> - </sect2> - - <sect2 xml:id="docbook-markup-callouts"> - <title>Callouts</title> - - <para>A callout is a visual marker for referring to a - piece of text or specific position within an - example.</para> - - <para>Callouts are marked with the <tag>co</tag> - element. Each element must have a unique - <literal>id</literal> assigned to it. After the example, - include a <tag>calloutlist</tag> that describes each - callout.</para> - - <example> - <title><tag>co</tag> and - <tag>calloutlist</tag> Example</title> - - <programlisting><tag class="starttag">para</tag>When finished, the program will look like - this:<tag class="endtag">para</tag> - -<tag class="starttag">programlisting</tag>#include &lt;stdio.h&gt; <tag class="emptytag">co xml:id="co-ex-include"</tag> - -int <tag class="emptytag">co xml:id="co-ex-return"</tag> -main(void) -{ - printf("hello, world\n"); <tag class="emptytag">co xml:id="co-ex-printf"</tag> -}<tag class="endtag">programlisting</tag> - -<tag class="starttag">calloutlist</tag> - <tag class="starttag">callout arearefs="co-ex-include"</tag> - <tag class="starttag">para</tag>Includes the standard IO header file.<tag class="endtag">para</tag> - <tag class="endtag">callout</tag> - - <tag class="starttag">callout arearefs="co-ex-return"</tag> - <tag class="starttag">para</tag>Specifies that <tag class="starttag">function</tag>main()<tag class="endtag">function</tag> returns an - int.<tag class="endtag">para</tag> - <tag class="endtag">callout</tag> - - <tag class="starttag">callout arearefs="co-ex-printf"</tag> - <tag class="starttag">para</tag>The <tag class="starttag">function</tag>printf()<tag class="endtag">function</tag> call that writes - <tag class="starttag">literal</tag>hello, world<tag class="endtag">literal</tag> to standard output.<tag class="endtag">para</tag> - <tag class="endtag">callout</tag> -<tag class="endtag">calloutlist</tag></programlisting> - - <para>Appearance:</para> - - <para>When finished, the program will look like this:</para> - - <programlisting>#include <stdio.h> <co xml:id="co-ex-include"/> - -int <co xml:id="co-ex-return"/> -main(void) -{ - printf("hello, world\n"); <co xml:id="co-ex-printf"/> -}</programlisting> - - <calloutlist> - <callout arearefs="co-ex-include"> - <para>Includes the standard IO header file.</para> - </callout> - - <callout arearefs="co-ex-return"> - <para>Specifies that <function>main()</function> returns - an int.</para> - </callout> - - <callout arearefs="co-ex-printf"> - <para>The <function>printf()</function> call that writes - <literal>hello, world</literal> to standard - output.</para> - </callout> - </calloutlist> - </example> - </sect2> - - <sect2 xml:id="docbook-markup-tables"> - <title>Tables</title> - - <para>Unlike <acronym>HTML</acronym>, DocBook does not need - tables for layout purposes, as the stylesheet handles those - issues. Instead, just use tables for marking up tabular - data.</para> - - <para>In general terms (and see the DocBook documentation for - more detail) a table (which can be either formal or informal) - consists of a <tag>table</tag> element. This contains - at least one <tag>tgroup</tag> element, which - specifies (as an attribute) the number of columns in this - table group. Within the tablegroup there is one - <tag>thead</tag> element, which contains elements for - the table headings (column headings), and one - <tag>tbody</tag> which contains the body of the - table.</para> - - <para>Both <tag>tgroup</tag> and - <tag>thead</tag> contain <tag>row</tag> - elements, which in turn contain <tag>entry</tag> - elements. Each <tag>entry</tag> element specifies - one cell in the table.</para> - - <example> - <title><tag>informaltable</tag> Example</title> - - <para>Usage:</para> - - <programlisting><tag class="starttag">informaltable pgwide="1"</tag> - <tag class="starttag">tgroup cols="2"</tag> - <tag class="starttag">thead</tag> - <tag class="starttag">row</tag> - <tag class="starttag">entry</tag>This is Column Head 1<tag class="endtag">entry</tag> - <tag class="starttag">entry</tag>This is Column Head 2<tag class="endtag">entry</tag> - <tag class="endtag">row</tag> - <tag class="endtag">thead</tag> - - <tag class="starttag">tbody</tag> - <tag class="starttag">row</tag> - <tag class="starttag">entry</tag>Row 1, column 1<tag class="endtag">entry</tag> - <tag class="starttag">entry</tag>Row 1, column 2<tag class="endtag">entry</tag> - <tag class="endtag">row</tag> - - <tag class="starttag">row</tag> - <tag class="starttag">entry</tag>Row 2, column 1<tag class="endtag">entry</tag> - <tag class="starttag">entry</tag>Row 2, column 2<tag class="endtag">entry</tag> - <tag class="endtag">row</tag> - <tag class="endtag">tbody</tag> - <tag class="endtag">tgroup</tag> -<tag class="endtag">informaltable</tag></programlisting> - - <para>Appearance:</para> - - <informaltable pgwide="1"> - <tgroup cols="2"> - <thead> - <row> - <entry>This is Column Head 1</entry> - <entry>This is Column Head 2</entry> - </row> - </thead> - - <tbody> - <row> - <entry>Row 1, column 1</entry> - <entry>Row 1, column 2</entry> - </row> - - <row> - <entry>Row 2, column 1</entry> - <entry>Row 2, column 2</entry> - </row> - </tbody> - </tgroup> - </informaltable> - </example> - - <para>Always use the <literal>pgwide</literal> attribute with - a value of <literal>1</literal> with the - <tag>informaltable</tag> element. A bug in Internet - Explorer can cause the table to render incorrectly if this - is omitted.</para> - - <para>Table borders can be suppressed by setting the - <literal>frame</literal> attribute to <literal>none</literal> - in the <tag>informaltable</tag> element. For example, - <literal>informaltable frame="none"</literal>.</para> - - <example> - <title>Table with <literal>frame="none"</literal> Example</title> - - <para>Appearance:</para> - - <informaltable frame="none" pgwide="1"> - <tgroup cols="2"> - <thead> - <row> - <entry>This is Column Head 1</entry> - <entry>This is Column Head 2</entry> - </row> - </thead> - - <tbody> - <row> - <entry>Row 1, column 1</entry> - <entry>Row 1, column 2</entry> - </row> - - <row> - <entry>Row 2, column 1</entry> - <entry>Row 2, column 2</entry> - </row> - </tbody> - </tgroup> - </informaltable> - </example> - </sect2> - - <sect2 xml:id="docbook-markup-examples"> - <title>Examples for the User to Follow</title> - - <para>Examples for the user to follow are often necessary. - Typically, these will consist of dialogs with the computer; - the user types in a command, the user gets a response back, - the user types another command, and so on.</para> - - <para>A number of distinct elements and entities come into - play here.</para> - - <variablelist> - <varlistentry> - <term><tag>screen</tag></term> - - <listitem> - <para>Everything the user sees in this example will be - on the computer screen, so the next element is - <tag>screen</tag>.</para> - - <para>Within <tag>screen</tag>, white space is - significant.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><tag>prompt</tag>, - <literal>&prompt.root;</literal> and - <literal>&prompt.user;</literal></term> - - <listitem> - <para>Some of the things the user will be seeing on the - screen are prompts from the computer (either from the - operating system, command shell, or application). These - should be marked up using - <tag>prompt</tag>.</para> - - <para>As a special case, the two shell prompts for the - normal user and the root user have been provided as - entities. To indicate the user is at a shell prompt, - use one of <literal>&prompt.root;</literal> and - <literal>&prompt.user;</literal> as necessary. They - do not need to be inside - <tag>prompt</tag>.</para> - - <note> - <para><literal>&prompt.root;</literal> and - <literal>&prompt.user;</literal> are &os; - extensions to DocBook, and are not part of the - original <acronym>DTD</acronym>.</para> - </note> - </listitem> - </varlistentry> - - <varlistentry> - <term><tag>userinput</tag></term> - - <listitem> - <para>When displaying text that the user should type in, - wrap it in <tag>userinput</tag> tags. It will - be displayed differently than system output text.</para> - </listitem> - </varlistentry> - </variablelist> - - <example> - <title><tag>screen</tag>, <tag>prompt</tag>, - and <tag>userinput</tag> Example</title> - - <para>Usage:</para> - - <programlisting><tag class="starttag">screen</tag>&prompt.user; <tag class="starttag">userinput</tag>ls -1<tag class="endtag">userinput</tag> -foo1 -foo2 -foo3 -&prompt.user; <tag class="starttag">userinput</tag>ls -1 | grep foo2<tag class="endtag">userinput</tag> -foo2 -&prompt.user; <tag class="starttag">userinput</tag>su<tag class="endtag">userinput</tag> -<tag class="starttag">prompt</tag>Password: <tag class="endtag">prompt</tag> -&prompt.root; <tag class="starttag">userinput</tag>cat foo2<tag class="endtag">userinput</tag> -This is the file called 'foo2'<tag class="endtag">screen</tag></programlisting> - - <para>Appearance:</para> - - <screen>&prompt.user; <userinput>ls -1</userinput> -foo1 -foo2 -foo3 -&prompt.user; <userinput>ls -1 | grep foo2</userinput> -foo2 -&prompt.user; <userinput>su</userinput> -<prompt>Password: </prompt> -&prompt.root; <userinput>cat foo2</userinput> -This is the file called 'foo2'</screen> - </example> - - <note> - <para>Even though we are displaying the contents of the file - <filename>foo2</filename>, it is <emphasis>not</emphasis> - marked up as <tag>programlisting</tag>. Reserve - <tag>programlisting</tag> for showing fragments of - files outside the context of user actions.</para> - </note> - </sect2> - </sect1> - - <sect1 xml:id="docbook-markup-inline-elements"> - <title>In-line Elements</title> - - <sect2 xml:id="docbook-markup-inline-emphasizing"> - <title>Emphasizing Information</title> - - <para>To emphasize a particular word or phrase, use - <tag>emphasis</tag>. This may be presented as - italic, or bold, or might be spoken differently with a - text-to-speech system.</para> - - <para>There is no way to change the presentation of the - emphasis within the document, no equivalent of - <acronym>HTML</acronym>'s <tag>b</tag> and - <tag>i</tag>. If the information being presented is - important, then consider presenting it in - <tag>important</tag> rather than - <tag>emphasis</tag>.</para> - - <example> - <title><tag>emphasis</tag> Example</title> - - <para>Usage:</para> - - <programlisting><tag class="starttag">para</tag>&os; is without doubt <tag class="starttag">emphasis</tag>the<tag class="endtag">emphasis</tag> - premiere &unix;-like operating system for the Intel - architecture.<tag class="endtag">para</tag></programlisting> - - <para>Appearance:</para> - - <para>&os; is without doubt <emphasis>the</emphasis> - premiere &unix;-like operating system for the Intel - architecture.</para> - </example> - </sect2> - - <sect2 xml:id="docbook-markup-acronyms"> - <title>Acronyms</title> - - <para>Many computer terms are <emphasis>acronyms</emphasis>, - words formed from the first letter of each word in a - phrase. Acronyms are marked up into - <tag>acronym</tag> elements. It is helpful to the - reader when an acronym is defined on the first use, as shown - in the example below.</para> - - <example> - <title><tag>acronym</tag> Example</title> - - <para>Usage:</para> - - <programlisting><tag class="starttag">para</tag>Request For Comments (<tag class="starttag">acronym</tag>RFC<tag class="endtag">acronym</tag>) 1149 - defined the use of avian carriers for transmission of - Internet Protocol (<tag class="starttag">acronym</tag>IP<tag class="endtag">acronym</tag>) data. The - quantity of <tag class="starttag">acronym</tag>IP<tag class="endtag">acronym</tag> data currently - transmitted in that manner is unknown.<tag class="endtag">para</tag></programlisting> - - <para>Appearance:</para> - - <para>Request For Comments (<acronym>RFC</acronym>) 1149 - defined the use of avian carriers for transmission of - Internet Protocol (<acronym>IP</acronym>) data. The - quantity of <acronym>IP</acronym> data currently - transmitted in that manner is unknown.</para> - </example> - </sect2> - - <sect2 xml:id="docbook-markup-quotations"> - <title>Quotations</title> - - <para>To quote text from another document or source, or to - denote a phrase that is used figuratively, use - <tag>quote</tag>. Most of the markup tags available - for normal text are also available from within a - <tag>quote</tag>.</para> - - <example> - <title><tag>quote</tag> Example</title> - - <para>Usage:</para> - - <programlisting><tag class="starttag">para</tag>However, make sure that the search does not go beyond the - <tag class="starttag">quote</tag>boundary between local and public administration<tag class="endtag">quote</tag>, - as <tag class="starttag">acronym</tag>RFC<tag class="endtag">acronym</tag> 1535 calls it.<tag class="endtag">para</tag></programlisting> - - <para>Appearance:</para> - - <para>However, make sure that the search does not go beyond - the <quote>boundary between local and public - administration</quote>, as <acronym>RFC</acronym> 1535 - calls it.</para> - </example> - </sect2> - - <sect2 xml:id="docbook-markup-keys"> - <title>Keys, Mouse Buttons, and Combinations</title> - - <para>To refer to a specific key on the keyboard, use - <tag>keycap</tag>. To refer to a mouse button, use - <tag>mousebutton</tag>. And to refer to - combinations of key presses or mouse clicks, wrap them all - in <tag>keycombo</tag>.</para> - - <para><tag>keycombo</tag> has an attribute called - <literal>action</literal>, which may be one of - <literal>click</literal>, <literal>double-click</literal>, - <literal>other</literal>, <literal>press</literal>, - <literal>seq</literal>, or <literal>simul</literal>. The - last two values denote whether the keys or buttons should be - pressed in sequence, or simultaneously.</para> - - <para>The stylesheets automatically add any connecting - symbols, such as <literal>+</literal>, between the key - names, when wrapped in <tag>keycombo</tag>.</para> - - <example> - <title>Keys, Mouse Buttons, and Combinations Example</title> - - <para>Usage:</para> - - <programlisting><tag class="starttag">para</tag>To switch to the second virtual terminal, press - <tag class="starttag">keycombo action="simul"</tag><tag class="starttag">keycap</tag>Alt<tag class="endtag">keycap</tag> - <tag class="starttag">keycap</tag>F1<tag class="endtag">keycap</tag><tag class="endtag">keycombo</tag>.<tag class="endtag">para</tag> - -<tag class="starttag">para</tag>To exit <tag class="starttag">command</tag>vi<tag class="endtag">command</tag> without saving changes, type - <tag class="starttag">keycombo action="seq"</tag><tag class="starttag">keycap</tag>Esc<tag class="endtag">keycap</tag><tag class="starttag">keycap</tag>:<tag class="endtag">keycap</tag> - <tag class="starttag">keycap</tag>q<tag class="endtag">keycap</tag><tag class="starttag">keycap</tag>!<tag class="endtag">keycap</tag><tag class="endtag">keycombo</tag>.<tag class="endtag">para</tag> - -<tag class="starttag">para</tag>My window manager is configured so that - <tag class="starttag">keycombo action="simul"</tag><tag class="starttag">keycap</tag>Alt<tag class="endtag">keycap</tag> - <tag class="starttag">mousebutton</tag>right<tag class="endtag">mousebutton</tag> - <tag class="endtag">keycombo</tag> mouse button is used to move windows.<tag class="endtag">para</tag></programlisting> - - <para>Appearance:</para> - - <para>To switch to the second virtual terminal, press - <keycombo action="simul"><keycap>Alt</keycap> - <keycap>F1</keycap></keycombo>.</para> - - <para>To exit <command>vi</command> without saving changes, - type <keycombo action="seq"> - <keycap>Esc</keycap> - <keycap>:</keycap> - <keycap>q</keycap> - <keycap>!</keycap></keycombo>.</para> - - <para>My window manager is configured so that - <keycombo action="simul"> - <keycap>Alt</keycap> - <mousebutton>right</mousebutton></keycombo> mouse button - is used to move windows.</para> - </example> - </sect2> - - <sect2 xml:id="docbook-markup-applications"> - <title>Applications, Commands, Options, and Cites</title> - - <para>Both applications and commands are frequently referred to - when writing documentation. The distinction between them is - that an application is the name of a program or suite of - programs that fulfill a particular task. A command is the - filename of a program that the user can type and run at a - command line.</para> - - <para>It is often necessary to show some of the options that a - command might take.</para> - - <para>Finally, it is often useful to list a command with its - manual section number, in the <quote>command(number)</quote> - format so common in Unix manuals.</para> - - <para>Mark up application names with - <tag>application</tag>.</para> - - <para>To list a command with its manual section - number (which should be most of the time) the DocBook - element is <tag>citerefentry</tag>. This will - contain a further two elements, - <tag>refentrytitle</tag> and - <tag>manvolnum</tag>. The content of - <tag>refentrytitle</tag> is the name of the command, - and the content of <tag>manvolnum</tag> is the - manual page section.</para> - - <para>This can be cumbersome to write, and so a series of - <link linkend="xml-primer-general-entities">general - entities</link> have been created to make this easier. - Each entity takes the form - <literal>&man.<replaceable>manual-page</replaceable>.<replaceable>manual-section</replaceable>;</literal>.</para> - - <para>The file that contains these entities is in - <filename>doc/share/xml/man-refs.ent</filename>, and can be - referred to using this <acronym>FPI</acronym>:</para> - - <programlisting>PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"</programlisting> - - <para>Therefore, the introduction to &os; documentation will - usually include this:</para> - - <programlisting><!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [ - -<!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"> -%man; - -… - -]></programlisting> - - <para>Use <tag>command</tag> to include a command - name <quote>in-line</quote> but present it as something the - user should type.</para> - - <para>Use <tag>option</tag> to mark up the options - which will be passed to a command.</para> - - <para>When referring to the same command multiple times in - close proximity, it is preferred to use the - <literal>&man.<replaceable>command</replaceable>.<replaceable>section</replaceable>;</literal> - notation to markup the first reference and use - <tag>command</tag> to markup subsequent references. - This makes the generated output, especially - <acronym>HTML</acronym>, appear visually better.</para> - - <example> - <title>Applications, Commands, and Options Example</title> - - <para>Usage:</para> - - <programlisting><tag class="starttag">para</tag><tag class="starttag">application</tag>Sendmail<tag class="endtag">application</tag> is the most - widely used Unix mail application.<tag class="starttag">para</tag> - -<tag class="starttag">para</tag><tag class="starttag">application</tag>Sendmail<tag class="endtag">application</tag> includes the - <tag class="starttag">citerefentry</tag> - <tag class="starttag">refentrytitle</tag>sendmail<tag class="endtag">refentrytitle</tag> - <tag class="starttag">manvolnum</tag>8<tag class="endtag">manvolnum</tag> - <tag class="endtag">citerefentry</tag>, &man.mailq.1;, and &man.newaliases.1; - programs.<tag class="endtag">para</tag> - -<tag class="starttag">para</tag>One of the command line parameters to <tag class="starttag">citerefentry</tag> - <tag class="starttag">refentrytitle</tag>sendmail<tag class="endtag">refentrytitle</tag> - <tag class="starttag">manvolnum</tag>8<tag class="endtag">manvolnum</tag> - <tag class="endtag">citerefentry</tag>, <tag class="starttag">option</tag>-bp<tag class="endtag">option</tag>, will display the current - status of messages in the mail queue. Check this on the command - line by running <tag class="starttag">command</tag>sendmail -bp<tag class="endtag">command</tag>.<tag class="endtag">para</tag></programlisting> - - <para>Appearance:</para> - - <para><application>Sendmail</application> is the most widely - used Unix mail application.</para> - - <para><application>Sendmail</application> includes the - <citerefentry> - <refentrytitle>sendmail</refentrytitle> - <manvolnum>8</manvolnum> - </citerefentry>, &man.mailq.1;, and &man.newaliases.1; - programs.</para> - - <para>One of the command line parameters to - <citerefentry> - <refentrytitle>sendmail</refentrytitle> - <manvolnum>8</manvolnum> - </citerefentry>, <option>-bp</option>, will display the - current status of messages in the mail queue. Check this - on the command line by running - <command>sendmail -bp</command>.</para> - </example> - - <note> - <para>Notice how the - <literal>&man.<replaceable>command</replaceable>.<replaceable>section</replaceable>;</literal> - notation is easier to follow.</para> - </note> - </sect2> - - <sect2 xml:id="docbook-markup-files"> - <title>Files, Directories, Extensions, Device Names</title> - - <para>To refer to the name of a file, a directory, a file - extension, or a device name, use <tag>filename</tag>.</para> - - <example> - <title><tag>filename</tag> Example</title> - - <para>Usage:</para> - - <programlisting><tag class="starttag">para</tag>The source for the Handbook in English is found in - <tag class="starttag">filename</tag>/usr/doc/en_US.ISO8859-1/books/handbook/<tag class="endtag">filename</tag>. - The main file is called <tag class="starttag">filename</tag>book.xml<tag class="endtag">filename</tag>. - There is also a <tag class="starttag">filename</tag>Makefile<tag class="endtag">filename</tag> and a - number of files with a <tag class="starttag">filename</tag>.ent<tag class="endtag">filename</tag> extension.<tag class="endtag">para</tag> - -<tag class="starttag">para</tag><tag class="starttag">filename</tag>kbd0<tag class="endtag">filename</tag> is the first keyboard detected - by the system, and appears in - <tag class="starttag">filename</tag>/dev<tag class="endtag">filename</tag>.<tag class="endtag">para</tag></programlisting> - - <para>Appearance:</para> - - <para>The source for the Handbook in English is found in - <filename>/usr/doc/en_US.ISO8859-1/books/handbook/</filename>. - The main file is called <filename>book.xml</filename>. - There is also a <filename>Makefile</filename> and a number - of files with a <filename>.ent</filename> extension.</para> - - <para><filename>kbd0</filename> is the first keyboard detected - by the system, and appears in - <filename>/dev</filename>.</para> - </example> - </sect2> - - <sect2 xml:id="docbook-markup-name-of-ports"> - <title>The Name of Ports</title> - - <note> - <title>&os; Extension</title> - - <para>These elements are part of the &os; extension to - DocBook, and do not exist in the original DocBook - <acronym>DTD</acronym>.</para> - </note> - - <para>To include the name of a program from the &os; - Ports Collection in the document, use the <tag>package</tag> - tag. Since the Ports Collection can be installed in any - number of locations, only include the category and the port - name; do not include <filename>/usr/ports</filename>.</para> - - <para>By default, <tag>package</tag> refers to a binary package. - To refer to a port that will be built from source, set the - <literal>role</literal> attribute to - <literal>port</literal>.</para> - - <example> - <title><tag>package</tag> Example</title> - - <para>Usage:</para> - - <programlisting><tag class="starttag">para</tag>Install the <tag class="starttag">package</tag>net/wireshark<tag class="endtag">package</tag> binary - package to view network traffic.<tag class="endtag">para</tag> - -<tag class="starttag">para</tag><tag class="starttag">package role="port"</tag>net/wireshark<tag class="endtag">package</tag> can also be - built and installed from the Ports Collection.<tag class="endtag">para</tag></programlisting> - - <para>Appearance:</para> - - <para>Install the <package>net/wireshark</package> binary - package to view network traffic.</para> - - <para><package role="port">net/wireshark</package> can also be - built and installed from the Ports Collection.</para> - </example> - </sect2> - - <sect2 xml:id="docbook-markup-hosts"> - <title>Hosts, Domains, IP Addresses, User Names, Group Names, - and Other System Items</title> - - <note> - <title>&os; Extension</title> - - <para>These elements are part of the &os; extension to - DocBook, and do not exist in the original DocBook - <acronym>DTD</acronym>.</para> - </note> - - <para>Information for <quote>system items</quote> is marked up - with <tag>systemitem</tag>. The <literal>class</literal> - attribute is used to identify the particular type of - information shown.</para> - - <variablelist> - <varlistentry> - <term><literal>class="domainname"</literal></term> - - <listitem> - <para>The text is a domain name, such as - <literal>FreeBSD.org</literal> or - <literal>ngo.org.uk</literal>. There is no hostname - component.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>class="etheraddress"</literal></term> - - <listitem> - <para>The text is an Ethernet <acronym>MAC</acronym> - address, expressed as a series of 2 digit hexadecimal - numbers separated by colons.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>class="fqdomainname"</literal></term> - - <listitem> - <para>The text is a Fully Qualified Domain Name, with - both hostname and domain name parts.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>class="ipaddress"</literal></term> - - <listitem> - <para>The text is an <acronym>IP</acronym> address, - probably expressed as a dotted quad.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>class="netmask"</literal></term> - - <listitem> - <para>The text is a network mask, which might be - expressed as a dotted quad, a hexadecimal string, or as - a <literal>/</literal> followed by a number - (<acronym>CIDR</acronym> notation).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>class="systemname"</literal></term> - - <listitem> - <para>With <literal>class="systemname"</literal> - the marked up information is the simple hostname, such - as <literal>freefall</literal> or - <literal>wcarchive</literal>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>class="username"</literal></term> - - <listitem> - <para>The text is a username, like - <literal>root</literal>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>class="groupname"</literal></term> - - <listitem> - <para>The text is a groupname, like - <literal>wheel</literal>.</para> - </listitem> - </varlistentry> - </variablelist> - - <example> - <title><tag>systemitem</tag> and Classes Example</title> - - <para>Usage:</para> - - <programlisting><tag class="starttag">para</tag>The local machine can always be referred to by the - name <tag class="starttag">systemitem class="systemname"</tag>localhost<tag class="endtag">systemitem</tag>, which will have the IP - address <tag class="starttag">systemitem class="ipaddress"</tag>127.0.0.1<tag class="endtag">systemitem</tag>.<tag class="endtag">para</tag> - -<tag class="starttag">para</tag>The <tag class="starttag">systemitem class="domainname"</tag>FreeBSD.org<tag class="endtag">systemitem</tag> - domain contains a number of different hosts, including - <tag class="starttag">systemitem class="fqdomainname"</tag>freefall.FreeBSD.org<tag class="endtag">systemitem</tag> and - <tag class="starttag">systemitem class="fqdomainname"</tag>bento.FreeBSD.org<tag class="endtag">systemitem</tag>.<tag class="endtag">para</tag> - -<tag class="starttag">para</tag>When adding an <tag class="starttag">acronym</tag>IP<tag class="endtag">acronym</tag> alias to an - interface (using <tag class="starttag">command</tag>ifconfig<tag class="endtag">command</tag>) - <tag class="starttag">emphasis</tag>always<tag class="endtag">emphasis</tag> use a netmask of - <tag class="starttag">systemitem class="netmask"</tag>255.255.255.255<tag class="endtag">systemitem</tag> (which can - also be expressed as - <tag class="starttag">systemitem class="netmask"</tag>0xffffffff<tag class="endtag">systemitem</tag>).<tag class="endtag">para</tag> - -<tag class="starttag">para</tag>The <tag class="starttag">acronym</tag>MAC<tag class="endtag">acronym</tag> address uniquely identifies - every network card in existence. A typical - <tag class="starttag">acronym</tag>MAC<tag class="endtag">acronym</tag> address looks like - <tag class="starttag">systemitem class="etheraddress"</tag>08:00:20:87:ef:d0<tag class="endtag">systemitem</tag>.<tag class="endtag">para</tag> - -<tag class="starttag">para</tag>To carry out most system administration functions - requires logging in as <tag class="starttag">systemitem class="username"</tag>root<tag class="endtag">systemitem</tag>.<tag class="endtag">para</tag></programlisting> - - <para>Appearance:</para> - - <para>The local machine can always be referred to by the name - <systemitem>localhost</systemitem>, which will have the IP - address - <systemitem class="ipaddress">127.0.0.1</systemitem>.</para> - - <para>The - <systemitem class="fqdomainname">FreeBSD.org</systemitem> - domain contains a number of different hosts, including - <systemitem - class="fqdomainname">freefall.FreeBSD.org</systemitem> and - <systemitem - class="fqdomainname">bento.FreeBSD.org</systemitem>.</para> - - <para>When adding an <acronym>IP</acronym> alias to an - interface (using <command>ifconfig</command>) - <emphasis>always</emphasis> use a netmask of - <systemitem class="netmask">255.255.255.255</systemitem> - (which can also be expressed as - <systemitem class="netmask">0xffffffff</systemitem>).</para> - - <para>The <acronym>MAC</acronym> address uniquely identifies - every network card in existence. A typical - <acronym>MAC</acronym> address looks like <systemitem - class="etheraddress">08:00:20:87:ef:d0</systemitem>.</para> - - <para>To carry out most system administration functions - requires logging in as - <systemitem class="username">root</systemitem>.</para> - </example> - </sect2> - - <sect2 xml:id="docbook-markup-uri"> - <title>Uniform Resource Identifiers - (<acronym>URI</acronym>s)</title> - - <para>Occasionally it is useful to show a - Uniform Resource Identifier (<acronym>URI</acronym>) without - making it an active hyperlink. The <tag>uri</tag> element - makes this possible:</para> - - <example> - <title><tag>uri</tag> Example</title> - - <para>Usage:</para> - - <programlisting><tag class="starttag">para</tag>This <acronym>URL</acronym> shows only as text: - <tag class="starttag">uri</tag>https://www.FreeBSD.org<tag class="endtag">uri</tag>. It does not - create a link.<tag class="endtag">para</tag></programlisting> - - <para>Appearance:</para> - - <para>This <acronym>URL</acronym> shows only as text: - <uri>https://www.FreeBSD.org</uri>. It does not - create a link.</para> - </example> - - <para>To create links, see - <xref linkend="docbook-markup-links"/>.</para> - </sect2> - - <sect2 xml:id="docbook-markup-email-addresses"> - <title>Email Addresses</title> - - <para>Email addresses are marked up as <tag>email</tag> - elements. In the <acronym>HTML</acronym> output format, the - wrapped text becomes a hyperlink to the email address. Other - output formats that support hyperlinks may also make the email - address into a link.</para> - - <example> - <title><tag>email</tag> with a Hyperlink Example</title> - - <para>Usage:</para> - - <programlisting><tag class="starttag">para</tag>An email address that does not actually exist, like - <tag class="starttag">email</tag>notreal@example.com<tag class="endtag">email</tag>, can be used as an - example.<tag class="endtag">para</tag></programlisting> - - <para>Appearance:</para> - - <para>An email address that does not actually exist, like - <email>notreal@example.com</email>, can be used as an - example.</para> - </example> - - <para>A &os;-specific extension allows setting the - <literal>role</literal> attribute to <literal>nolink</literal> - to prevent the creation of the hyperlink to the email - address.</para> - - <example> - <title><tag>email</tag> Without a Hyperlink Example</title> - - <para>Usage:</para> - - <programlisting><tag class="starttag">para</tag>Sometimes a link to an email address like - <tag class="starttag">email role="nolink"</tag>notreal@example.com<tag class="endtag">email</tag> is not - desired.<tag class="endtag">para</tag></programlisting> - - <para>Appearance:</para> - - <para>Sometimes a link to an email address like - <email role="nolink">notreal@example.com</email> is not - desired.</para> - </example> - </sect2> - - <sect2 xml:id="docbook-markup-describing-makefiles"> - <title>Describing <filename>Makefile</filename>s</title> - - <note> - <title>&os; Extension</title> - - <para>These elements are part of the &os; extension to - DocBook, and do not exist in the original DocBook - <acronym>DTD</acronym>.</para> - </note> - - <para>Two elements exist to describe parts of - <filename>Makefile</filename>s, <tag>buildtarget</tag> - and <tag>varname</tag>.</para> - - <para><tag>buildtarget</tag> identifies a build target - exported by a <filename>Makefile</filename> that can be - given as a parameter to <command>make</command>. - <tag>varname</tag> identifies a variable that can be - set (in the environment, on the command line with - <command>make</command>, or within the - <filename>Makefile</filename>) to influence the - process.</para> - - <example> - <title><tag>buildtarget</tag> and - <tag>varname</tag> Example</title> - - <para>Usage:</para> - - <programlisting><tag class="starttag">para</tag>Two common targets in a <tag class="starttag">filename</tag>Makefile<tag class="endtag">filename</tag> - are <tag class="starttag">buildtarget</tag>all<tag class="endtag">buildtarget</tag> and - <tag class="starttag">buildtarget</tag>clean<tag class="endtag">buildtarget</tag>.<tag class="endtag">para</tag> - -<tag class="starttag">para</tag>Typically, invoking <tag class="starttag">buildtarget</tag>all<tag class="endtag">buildtarget</tag> will - rebuild the application, and invoking - <tag class="starttag">buildtarget</tag>clean<tag class="endtag">buildtarget</tag> will remove the temporary - files (<tag class="starttag">filename</tag>.o<tag class="endtag">filename</tag> for example) created by the - build process.<tag class="endtag">para</tag> - -<tag class="starttag">para</tag><tag class="starttag">buildtarget</tag>clean<tag class="endtag">buildtarget</tag> may be controlled by a - number of variables, including <tag class="starttag">varname</tag>CLOBBER<tag class="endtag">varname</tag> - and <tag class="starttag">varname</tag>RECURSE<tag class="endtag">varname</tag>.<tag class="endtag">para</tag></programlisting> - - <para>Appearance:</para> - - <para>Two common targets in a <filename>Makefile</filename> - are <buildtarget>all</buildtarget> and - <buildtarget>clean</buildtarget>.</para> - - <para>Typically, invoking <buildtarget>all</buildtarget> will - rebuild the application, and invoking - <buildtarget>clean</buildtarget> will remove the temporary - files (<filename>.o</filename> for example) created by the - build process.</para> - - <para><buildtarget>clean</buildtarget> may be controlled by a - number of variables, including <varname>CLOBBER</varname> - and <varname>RECURSE</varname>.</para> - </example> - </sect2> - - <sect2 xml:id="docbook-markup-literal-text"> - <title>Literal Text</title> - - <para>Literal text, or text which should be entered verbatim, is - often needed in documentation. This is text that is excerpted - from another file, or which should be copied exactly as shown - from the documentation into another file.</para> - - <para>Some of the time, <tag>programlisting</tag> will - be sufficient to denote this text. But - <tag>programlisting</tag> is not always appropriate, - particularly when you want to include a portion of a file - <quote>in-line</quote> with the rest of the - paragraph.</para> - - <para>On these occasions, use - <tag>literal</tag>.</para> - - <example> - <title><tag>literal</tag> Example</title> - - <para>Usage:</para> - - <programlisting><tag class="starttag">para</tag>The <tag class="starttag">literal</tag>maxusers 10<tag class="endtag">literal</tag> line in the kernel - configuration file determines the size of many system tables, and is - a rough guide to how many simultaneous logins the system will - support.<tag class="endtag">para</tag></programlisting> - - <para>Appearance:</para> - - <para>The <literal>maxusers 10</literal> line in the kernel - configuration file determines the size of many system - tables, and is a rough guide to how many simultaneous - logins the system will support.</para> - </example> - </sect2> - - <sect2 xml:id="docbook-markup-replaceable"> - <title>Showing Items That the User <emphasis>Must</emphasis> - Fill In</title> - - <para>There will often be times when the user is shown - what to do, or referred to a file or command line, but - cannot simply copy the example provided. Instead, they - must supply some information themselves.</para> - - <para><tag>replaceable</tag> is designed for this - eventuality. Use it <emphasis>inside</emphasis> other - elements to indicate parts of that element's content that - the user must replace.</para> - - <example> - <title><tag>replaceable</tag> Example</title> - - <para>Usage:</para> - - <programlisting><tag class="starttag">screen</tag>&prompt.user; <tag class="starttag">userinput</tag>man <tag class="starttag">replaceable</tag>command<tag class="endtag">replaceable</tag><tag class="endtag">userinput</tag><tag class="endtag">screen</tag></programlisting> - - <para>Appearance:</para> - - <informalexample> - <screen>&prompt.user; <userinput>man <replaceable>command</replaceable></userinput></screen> - </informalexample> - - <para><tag>replaceable</tag> can be used in many - different elements, including <tag>literal</tag>. - This example also shows that <tag>replaceable</tag> - should only be wrapped around the content that the user - <emphasis>is</emphasis> meant to provide. The other content - should be left alone.</para> - - <para>Usage:</para> - - <programlisting><tag class="starttag">para</tag>The <tag class="starttag">literal</tag>maxusers <tag class="starttag">replaceable</tag>n<tag class="endtag">replaceable</tag><tag class="endtag">literal</tag> - line in the kernel configuration file determines the size of many system - tables, and is a rough guide to how many simultaneous logins the system will - support.<tag class="endtag">para</tag> - -<tag class="starttag">para</tag>For a desktop workstation, <tag class="starttag">literal</tag>32<tag class="endtag">literal</tag> is a good value - for <tag class="starttag">replaceable</tag>n<tag class="endtag">replaceable</tag>.<tag class="endtag">para</tag></programlisting> - - <para>Appearance:</para> - - <para>The - <literal>maxusers <replaceable>n</replaceable></literal> - line in the kernel configuration file determines the size - of many system tables, and is a rough guide to how many - simultaneous logins the system will support.</para> - - <para>For a desktop workstation, <literal>32</literal> is a - good value for <replaceable>n</replaceable>.</para> - </example> - </sect2> - - <sect2 xml:id="docbook-markup-gui-buttons"> - <title>Showing <acronym>GUI</acronym> Buttons</title> - - <para>Buttons presented by a graphical user interface are marked - with <tag>guibutton</tag>. To make the text look more - like a graphical button, brackets and non-breaking spaces are - added surrounding the text.</para> - - <example> - <title><tag>guibutton</tag> Example</title> - - <para>Usage:</para> - - <programlisting><tag class="starttag">para</tag>Edit the file, then click - <tag class="starttag">guibutton</tag>[&nbsp;Save&nbsp;]<tag class="endtag">guibutton</tag> to save the - changes.<tag class="endtag">para</tag></programlisting> - - <para>Appearance:</para> - - <para>Edit the file, then click - <guibutton>[ Save ]</guibutton> to save the - changes.</para> - </example> - </sect2> - - <sect2 xml:id="docbook-markup-system-errors"> - <title>Quoting System Errors</title> - - <para>System errors generated by &os; are marked with - <tag>errorname</tag>. This indicates the exact error - that appears.</para> - - <example> - <title><tag>errorname</tag> Example</title> - - <para>Usage:</para> - - <programlisting><tag class="starttag">screen</tag><tag class="starttag">errorname</tag>Panic: cannot mount root<tag class="endtag">errorname</tag><tag class="endtag">screen</tag></programlisting> - - <para>Appearance:</para> - - <informalexample> - <screen><errorname>Panic: cannot mount root</errorname></screen> - </informalexample> - </example> - </sect2> - </sect1> - - <sect1 xml:id="docbook-markup-images"> - <title>Images</title> - - <important> - <para>Image support in the documentation is somewhat - experimental. The mechanisms described here are unlikely to - change, but that is not guaranteed.</para> - - <para>To provide conversion between different image formats, the - <package>graphics/ImageMagick</package> - port must be installed. This port is not included in the - <package>textproc/docproj</package> meta - port, and must be installed separately.</para> - - <para>A good example of the use of images is the - <filename>doc/en_US.ISO8859-1/articles/vm-design/</filename> - document. Examine the files in that directory to see how - these elements are used together. Build different output - formats to see how the format determines what images are shown - in the rendered document.</para> - </important> - - <sect2 xml:id="docbook-markup-image-formats"> - <title>Image Formats</title> - - <para>The following image formats are currently supported. An - image file will automatically be converted to bitmap or vector - image depending on the output document format.</para> - - <para>These are the <emphasis>only</emphasis> formats in which - images should be committed to the documentation - repository.</para> - - <variablelist> - <varlistentry> - <term><acronym>EPS</acronym> (Encapsulated - Postscript)</term> - - <listitem> - <para>Images that are primarily vector based, such as - network diagrams, time lines, and similar, should be in - this format. These images have a - <filename>.eps</filename> extension.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><acronym>PNG</acronym> (Portable Network - Graphic)</term> - - <listitem> - <para>For bitmaps, such as screen captures, use this - format. These images have the <filename>.png</filename> - extension.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><acronym>PIC</acronym> (PIC graphics language)</term> - - <listitem> - <para><acronym>PIC</acronym> is a language for drawing - simple vector-based figures used in the &man.pic.1; - utility. These images have the - <filename>.pic</filename> extension.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><acronym>SCR</acronym> (SCReen capture)</term> - - <listitem> - <para>This format is specific to screenshots of console - output. The following command generates an SCR file - <filename>shot.scr</filename> from video buffer of - <filename>/dev/ttyv0</filename>:</para> - - <screen>&prompt.root; <userinput><command>vidcontrol -p</command> < <filename><replaceable>/dev/ttyv0</replaceable></filename> > <filename><replaceable>shot.scr</replaceable></filename></userinput></screen> - - <para>This is preferable to <acronym>PNG</acronym> format - for screenshots because the <acronym>SCR</acronym> file - contains plain text of the command lines so that it can - be converted to a <acronym>PNG</acronym> image or a - plain text depending on the output document - format.</para> - </listitem> - </varlistentry> - </variablelist> - - <para>Use the appropriate format for each image. Documentation - will often have a mix of <acronym>EPS</acronym> and - <acronym>PNG</acronym> images. The - <filename>Makefile</filename>s ensure that the correct format - image is chosen depending on the output format used. - <emphasis>Do not commit the same image to the repository in - two different formats</emphasis>.</para> - - <important> - <para>The Documentation Project may eventually switch to using - the <acronym>SVG</acronym> (Scalable Vector Graphic) format - for vector images. However, the current state of - <acronym>SVG</acronym> capable editing tools makes this - impractical.</para> - </important> - </sect2> - - <sect2 xml:id="docbook-markup-image-file-locations"> - <title>Image File Locations</title> - - <para>Image files can be stored in one of several locations, - depending on the document and image:</para> - - <itemizedlist> - <listitem> - <para>In the same directory as the document itself, usually - done for articles and small books that keep all their - files in a single directory.</para> - </listitem> - - <listitem> - <para>In a subdirectory of the main document. Typically - done when a large book uses separate subdirectories to - organize individual chapters.</para> - - <para>When images are stored in a subdirectory of the - main document directory, the subdirectory name must be - included in their paths in the - <filename>Makefile</filename> and the - <tag>imagedata</tag> element.</para> - </listitem> - - <listitem> - <para>In a subdirectory of - <filename>doc/share/images</filename> named after the - document. For example, images for the Handbook are stored - in <filename>doc/share/images/books/handbook</filename>. - Images that work for multiple translations are stored in - this upper level of the documentation file tree. - Generally, these are images that can be used unchanged in - non-English translations of the document.</para> - </listitem> - </itemizedlist> - </sect2> - - <sect2 xml:id="docbook-markup-image-markup"> - <title>Image Markup</title> - - <para>Images are included as part of a <tag>mediaobject</tag>. - The <tag>mediaobject</tag> can contain other, more specific - objects. We are concerned with two, the - <tag>imageobject</tag> and the <tag>textobject</tag>.</para> - - <para>Include one <tag>imageobject</tag>, and two - <tag>textobject</tag> elements. The <tag>imageobject</tag> - will point to the name of the image file without the - extension. The <tag>textobject</tag> elements contain - information that will be presented to the user as well as, or - instead of, the image itself.</para> - - <para>Text elements are shown to the reader in several - situations. When the document is viewed in - <acronym>HTML</acronym>, text elements are shown while the - image is loading, or if the mouse pointer is hovered over the - image, or if a text-only browser is being used. In formats - like plain text where graphics are not possible, the text - elements are shown instead of the graphical ones.</para> - - <para>This example shows how to include an image called - <filename>fig1.png</filename> in a document. The image is a - rectangle with an A inside it:</para> - - <programlisting><tag class="starttag">mediaobject</tag> - <tag class="starttag">imageobject</tag> - <tag class="starttag">imagedata fileref="fig1"</tag> <co xml:id="co-image-ext"/> - <tag class="endtag">imageobject</tag> - - <tag class="starttag">textobject</tag> - <tag class="starttag">literallayout class="monospaced"</tag>+---------------+ <co xml:id="co-image-literal"/> -| A | -+---------------+<tag class="endtag">literallayout</tag> - <tag class="endtag">textobject</tag> - - <tag class="starttag">textobject</tag> - <tag class="starttag">phrase</tag>A picture<tag class="endtag">phrase</tag> <co xml:id="co-image-phrase"/> - <tag class="endtag">textobject</tag> -<tag class="endtag">mediaobject</tag></programlisting> - - <calloutlist> - <callout arearefs="co-image-ext"> - <para>Include an <tag>imagedata</tag> element - inside the <tag>imageobject</tag> element. The - <literal>fileref</literal> attribute should contain the - filename of the image to include, without the extension. - The stylesheets will work out which extension should be - added to the filename automatically.</para> - </callout> - - <callout arearefs="co-image-literal"> - - <para>The first <tag>textobject</tag> contains a - <tag>literallayout</tag> element, where the - <literal>class</literal> attribute is set to - <literal>monospaced</literal>. This is an opportunity to - demonstrate <acronym>ASCII</acronym> art skills. This - content will be used if the document is converted to plain - text.</para> - - <para>Notice how the first and last lines of the content - of the <tag>literallayout</tag> element butt up - next to the element's tags. This ensures no extraneous - white space is included.</para> - </callout> - - <callout arearefs="co-image-phrase"> - <para>The second <tag>textobject</tag> contains a - single <tag>phrase</tag> element. The contents of - this phrase will become the <literal>alt</literal> - attribute for the image when this document is converted to - <acronym>HTML</acronym>.</para> - </callout> - </calloutlist> - </sect2> - - <sect2 xml:id="docbook-markup-image-makefile-entries"> - <title>Image <filename>Makefile</filename> Entries</title> - - <para>Images must be listed in the <filename>Makefile</filename> - in the <varname>IMAGES</varname> variable. This variable must - contain the names of all the <emphasis>source</emphasis> - images. For example, if there are three figures, - <filename>fig1.eps</filename>, <filename>fig2.png</filename>, - <filename>fig3.png</filename>, then the - <filename>Makefile</filename> should have lines like this in - it.</para> - - <programlisting>… -IMAGES= fig1.eps fig2.png fig3.png -…</programlisting> - - <para>or</para> - - <programlisting>… -IMAGES= fig1.eps -IMAGES+= fig2.png -IMAGES+= fig3.png -…</programlisting> - - <para>Again, the <filename>Makefile</filename> will work out the - complete list of images it needs to build the source document, - you only need to list the image files <emphasis>you</emphasis> - provided.</para> - </sect2> - - <sect2 xml:id="docbook-markup-images-in-subdirectories"> - <title>Images and Chapters in Subdirectories</title> - - <para>Be careful when separating documentation into smaller - files in different directories (see <xref - linkend="xml-primer-include-using-gen-entities"/>).</para> - - <para>Suppose there is a book with three chapters, and the - chapters are stored in their own directories, called - <filename>chapter1/chapter.xml</filename>, - <filename>chapter2/chapter.xml</filename>, and - <filename>chapter3/chapter.xml</filename>. If each chapter - has images associated with it, place those images in each - chapter's subdirectory (<filename>chapter1/</filename>, - <filename>chapter2/</filename>, and - <filename>chapter3/</filename>).</para> - - <para>However, doing this requires including the directory - names in the <varname>IMAGES</varname> variable in the - <filename>Makefile</filename>, <emphasis>and</emphasis> - including the directory name in the <tag>imagedata</tag> - element in the document.</para> - - <para>For example, if the book has - <filename>chapter1/fig1.png</filename>, then - <filename>chapter1/chapter.xml</filename> should - contain:</para> - - <programlisting><tag class="starttag">mediaobject</tag> - <tag class="starttag">imageobject</tag> - <tag class="emptytag">imagedata fileref="chapter1/fig1"</tag> <co xml:id="co-image-dir"/> - <tag class="endtag">imageobject</tag> - - … - -<tag class="endtag">mediaobject</tag></programlisting> - - <calloutlist> - <callout arearefs="co-image-dir"> - <para>The directory name must be included in the - <literal>fileref</literal> attribute.</para> - </callout> - </calloutlist> - - <para>The <filename>Makefile</filename> must contain:</para> - - <programlisting>… -IMAGES= chapter1/fig1.png -…</programlisting> - </sect2> - </sect1> - - <sect1 xml:id="docbook-markup-links"> - <title>Links</title> - - <note> - <para>Links are also in-line elements. To show a - <acronym>URI</acronym> without creating a link, see - <xref linkend="docbook-markup-uri"/>.</para> - </note> - - <sect2 xml:id="docbook-markup-links-ids"> - <title><literal>xml:id</literal> Attributes</title> - - <para>Most DocBook elements accept an <literal>xml:id</literal> - attribute to give that part of the document a unique name. - The <literal>xml:id</literal> can be used as a target for a - crossreference or link.</para> - - <para>Any portion of the document that will be a link target - must have an <literal>xml:id</literal> attribute. Assigning - an <literal>xml:id</literal> to all chapters and sections, - even if there are no current plans to link to them, is a good - idea. These <literal>xml:id</literal>s can be used as unique - reference points by anyone referring to the - <acronym>HTML</acronym> version of the document.</para> - - <example> - <title><literal>xml:id</literal> on Chapters and - Sections Example</title> - - <programlisting><tag class="starttag">chapter xml:id="introduction"</tag> - <tag class="starttag">title</tag>Introduction<tag class="endtag">title</tag> - - <tag class="starttag">para</tag>This is the introduction. It contains a subsection, - which is identified as well.<tag class="endtag">para</tag> - - <tag class="starttag">sect1 xml:id="introduction-moredetails"</tag> - <tag class="starttag">title</tag>More Details<tag class="endtag">title</tag> - - <tag class="starttag">para</tag>This is a subsection.<tag class="endtag">para</tag> - <tag class="endtag">sect1</tag> -<tag class="endtag">chapter</tag></programlisting> - </example> - - <para>Use descriptive values for <literal>xml:id</literal> - names. The values must be unique within the entire document, - not just in a single file. In the example, the subsection - <literal>xml:id</literal> is constructed by appending text to - the chapter <literal>xml:id</literal>. This ensures that the - <literal>xml:id</literal>s are unique. It also helps both - reader and anyone editing the document to see where the link - is located within the document, similar to a directory path to - a file.</para> - </sect2> - - <sect2 xml:id="docbook-markup-links-crossreferences"> - <title>Crossreferences with <literal>xref</literal></title> - - <para><tag>xref</tag> provides the reader with a link to jump to - another section of the document. The target - <literal>xml:id</literal> is specified in the - <literal>linkend</literal> attribute, and <tag>xref</tag> - generates the link text automatically.</para> - - <example> - <title><tag>xref</tag> Example</title> - - <para>Assume that this fragment appears somewhere in a - document that includes the <literal>xml:id</literal> - example shown above:</para> - - <programlisting><tag class="starttag">para</tag>More information can be found - in <tag class="emptytag">xref linkend="introduction"</tag>.<tag class="endtag">para</tag> - -<tag class="starttag">para</tag>More specific information can be found - in <tag class="emptytag">xref linkend="introduction-moredetails"</tag>.<tag class="endtag">para</tag></programlisting> - - <para>The link text will be generated automatically, looking - like (<emphasis>emphasized</emphasis> text indicates the - link text):</para> - - <blockquote> - <para>More information can be found in <emphasis>Chapter - 1, Introduction</emphasis>.</para> - - <para>More specific information can be found in - <emphasis>Section 1.1, - <quote>More Details</quote></emphasis>.</para> - </blockquote> - </example> - - <para>The link text is generated automatically from the chapter - and section number and <literal>title</literal> - elements.</para> - </sect2> - - <sect2 xml:id="docbook-markup-links-to-web-documents"> - <title>Linking to Other Documents on the - Web</title> - - <para>The link element described here allows the writer to - define the link text. When link text is used, it is very important to be descriptive - to give the reader an idea of where the link goes. - Remember that DocBook can be rendered to multiple - types of media. The reader might be looking at a printed book - or other form of media where there are no links. If the link - text is not descriptive enough, the reader might not be able to - locate the linked section.</para> - - <para>The <literal>xlink:href</literal> attribute - is the <acronym>URL</acronym> of the page, - and the content of the element is the text that - will be displayed for the user to activate.</para> - - <para>In many situations, it is preferable to show the actual - <acronym>URL</acronym> rather than text. This can be done by - leaving out the element text entirely.</para> - - <example> - <title><tag>link</tag> to a &os; Documentation Web - Page Example</title> - - <para>Link to the book or article <acronym>URL</acronym> - entity. To link to a specific chapter in a book, add a - slash and the chapter file name, followed by an optional - anchor within the chapter. For articles, link to the - article <acronym>URL</acronym> entity, followed by an - optional anchor within the article. - <acronym>URL</acronym> entities can be found in - <filename>doc/share/xml/urls.ent</filename>.</para> - - <para>Usage for &os; book links:</para> - - <programlisting><tag class="starttag">para</tag>Read the <tag class="starttag">link - xlink:href="&url.books.handbook;/svn.html#svn-intro"</tag>SVN - introduction<tag class="endtag">link</tag>, then pick the nearest mirror from - the list of <tag class="starttag">link - xlink:href="&url.books.handbook;/svn.html#svn-mirrors"</tag>Subversion - mirror sites<tag class="endtag">link</tag>.<tag class="endtag">para</tag></programlisting> - - <para>Appearance:</para> - - <para>Read the <link - xlink:href="&url.books.handbook;/svn.html#svn-intro">SVN - introduction</link>, then pick the nearest mirror from - the list of <link - xlink:href="&url.books.handbook;/svn.html#svn-mirrors">Subversion - mirror sites</link>.</para> - - <para>Usage for &os; article links:</para> - - <programlisting><tag class="starttag">para</tag>Read this - <tag class="starttag">link xlink:href="&url.articles.bsdl-gpl;"</tag>article - about the BSD license<tag class="endtag">link</tag>, or just the - <tag class="starttag">link xlink:href="&url.articles.bsdl-gpl;#intro"</tag>introduction<tag class="endtag">link</tag>.<tag class="endtag">para</tag></programlisting> - - <para>Appearance:</para> - - <para>Read this - <link xlink:href="&url.articles.bsdl-gpl;">article - about the BSD license</link>, or just the <link - xlink:href="&url.articles.bsdl-gpl;#intro">introduction</link>.</para> - </example> - - <example> - <title><tag>link</tag> to a &os; Web Page Example</title> - - <para>Usage:</para> - - <programlisting><tag class="starttag">para</tag>Of course, you could stop reading this document and go to the - <tag class="starttag">link xlink:href="&url.base;/index.html"</tag>FreeBSD home page<tag class="endtag">link</tag> instead.<tag class="endtag">para</tag></programlisting> - - <para>Appearance:</para> - - <para>Of course, you could stop reading this document and go - to the <link xlink:href="&url.base;/index.html">FreeBSD - home page</link> instead.</para> - </example> - - <example> - <title><tag>link</tag> to an External Web - Page Example</title> - - <para>Usage:</para> - - <programlisting><tag class="starttag">para</tag>Wikipedia has an excellent reference on - <tag class="starttag">link - xlink:href="http://en.wikipedia.org/wiki/GUID_Partition_Table"</tag>GUID - Partition Tables<tag class="endtag">link</tag>.<tag class="endtag">para</tag></programlisting> - - <para>Appearance:</para> - - <para>Wikipedia has an excellent reference on <link - xlink:href="http://en.wikipedia.org/wiki/GUID_Partition_Table">GUID - Partition Tables</link>.</para> - - <para>The link text can be omitted to show the actual - URL:</para> - - <programlisting><tag class="starttag">para</tag>Wikipedia has an excellent reference on - GUID Partition Tables: <tag class="starttag">link - xlink:href="http://en.wikipedia.org/wiki/GUID_Partition_Table"</tag><tag class="endtag">link</tag>.<tag class="endtag">para</tag></programlisting> - - <para>The same link can be entered using shorter - notation instead of a separate ending tag:</para> - - <programlisting><tag class="starttag">para</tag>Wikipedia has an excellent reference on - GUID Partition Tables: <tag class="emptytag">link - xlink:href="http://en.wikipedia.org/wiki/GUID_Partition_Table"</tag>.<tag class="endtag">para</tag></programlisting> - - <para>The two methods are equivalent. Appearance:</para> - - <para>Wikipedia has an excellent reference on GUID Partition - Tables: <uri - xlink:href="http://en.wikipedia.org/wiki/GUID_Partition_Table">http://en.wikipedia.org/wiki/GUID_Partition_Table</uri>.</para> - </example> - </sect2> - </sect1> -</chapter> diff --git a/nl_NL.ISO8859-1/books/fdp-primer/editor-config/chapter.xml b/nl_NL.ISO8859-1/books/fdp-primer/editor-config/chapter.xml deleted file mode 100644 index d3453b379b..0000000000 --- a/nl_NL.ISO8859-1/books/fdp-primer/editor-config/chapter.xml +++ /dev/null @@ -1,170 +0,0 @@ -<?xml version="1.0" encoding="iso-8859-1"?> -<!-- Copyright (c) 2013 Warren Block - All rights reserved. - - Redistribution and use in source and binary forms, with or without - modification, are permitted provided that the following conditions - are met: - 1. Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. - 2. Redistributions in binary form must reproduce the above - copyright notice, this list of conditions and the following - disclaimer in the documentation and/or other materials provided - with the distribution. - - THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS - IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT - LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS - FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE - AUTHORS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, - INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES - (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR - SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) - HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN - CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR - OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, - EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - - $FreeBSD$ ---> -<chapter xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" - xml:id="editor-config"> - - <title>Editor Configuration</title> - - <para>Adjusting text editor configuration can make working on - document files quicker and easier, and help documents conform to - <acronym>FDP</acronym> guidelines.</para> - - <sect1 xml:id="editor-config-vim"> - <title><application>Vim</application></title> - - <para>Install from <package>editors/vim</package> - or <package>editors/vim-lite</package>.</para> - - <sect2 xml:id="editor-config-vim-config"> - <title>Configuration</title> - - <para>Edit <filename>~/.vimrc</filename>, adding these - lines:</para> - - <programlisting>if has("autocmd") - au BufNewFile,BufRead *.sgml,*.ent,*.xsl,*.xml call Set_SGML() - au BufNewFile,BufRead *.[1-9] call ShowSpecial() -endif " has(autocmd) - -function Set_Highlights() - "match ExtraWhitespace /^\s* \s*\|\s\+$/ - highlight default link OverLength ErrorMsg - match OverLength /\%71v.\+/ - return 0 -endfunction - -function ShowSpecial() - setlocal list listchars=tab:>>,trail:*,eol:$ - hi def link nontext ErrorMsg - return 0 -endfunction " ShowSpecial() - -function Set_SGML() - setlocal number - syn match sgmlSpecial "&[^;]*;" - setlocal syntax=sgml - setlocal filetype=xml - setlocal shiftwidth=2 - setlocal textwidth=70 - setlocal tabstop=8 - setlocal softtabstop=2 - setlocal formatprg="fmt -p" - setlocal autoindent - setlocal smartindent - " Rewrap paragraphs - noremap P gqj - " Replace spaces with tabs - noremap T :s/ /\t/<CR> - call ShowSpecial() - call Set_Highlights() - return 0 -endfunction " Set_SGML()</programlisting> - </sect2> - - <sect2 xml:id="editor-config-vim-use"> - <title>Use</title> - - <para>Press <keycap>P</keycap> to reformat paragraphs or text that has been selected in Visual mode. Press - <keycap>T</keycap> to replace groups of eight spaces with a - tab.</para> - </sect2> - </sect1> - - <sect1 xml:id="editor-config-emacs"> - <title><application>Emacs</application></title> - - <para>Install from - <package>editors/emacs</package> - or <package>editors/xemacs</package>.</para> - - <para>Edit <filename>~/.emacs</filename>, adding this - line:</para> - - <programlisting>(add-hook 'nxml-mode-hook 'turn-on-auto-fill)</programlisting> - </sect1> - - <sect1 xml:id="editor-config-nano"> - <title><application>nano</application></title> - - <para>Install from - <package>editors/nano</package> or - <package>editors/nano-devel</package>.</para> - - <sect2 xml:id="editor-config-nano-config"> - <title>Configuration</title> - - <para>Copy the sample <acronym>XML</acronym> syntax highlight - file to the user's home directory:</para> - - <screen>&prompt.user; <userinput>cp /usr/local/share/nano/xml.nanorc ~/.nanorc</userinput></screen> - - <para>Add these lines to the new - <filename>~/.nanorc</filename>.</para> - - <programlisting>syntax "xml" "\.([jrs]html?|xml|xslt?)$" -# trailing whitespace -color ,blue "[[:space:]]+$" -# multiples of eight spaces at the start a line -# (after zero or more tabs) should be a tab -color ,blue "^([TAB]*[ ]{8})+" -# tabs after spaces -color ,yellow "( )+TAB" -# highlight indents that have an odd number of spaces -color ,red "^(([ ]{2})+|(TAB+))*[ ]{1}[^ ]{1}" -# lines longer than 70 characters -color ,yellow "^(.{71})|(TAB.{63})|(TAB{2}.{55})|(TAB{3}.{47}).+$"</programlisting> - - <para>Process the file to create embedded tabs:</para> - - <screen>&prompt.user; <userinput>perl -i'' -pe 's/TAB/\t/g' ~/.nanorc</userinput></screen> - </sect2> - - <sect2 xml:id="editor-config-nano-use"> - <title>Use</title> - - <para>Specify additional helpful options when running the - editor:</para> - - <screen>&prompt.user; <userinput>nano -AKipwz -r 70 -T8 <replaceable>chapter.xml</replaceable></userinput></screen> - - <para>Users of &man.csh.1; can define an alias in - <filename>~/.cshrc</filename> to automate these - options:</para> - - <programlisting>alias nano "nano -AKipwz -r 70 -T8"</programlisting> - - <para>After the alias is defined, the options will be added - automatically:</para> - - <screen>&prompt.user; <userinput>nano <replaceable>chapter.xml</replaceable></userinput></screen> - </sect2> - </sect1> -</chapter> diff --git a/nl_NL.ISO8859-1/books/fdp-primer/examples/appendix.xml b/nl_NL.ISO8859-1/books/fdp-primer/examples/appendix.xml deleted file mode 100644 index 514ed39f46..0000000000 --- a/nl_NL.ISO8859-1/books/fdp-primer/examples/appendix.xml +++ /dev/null @@ -1,162 +0,0 @@ -<?xml version="1.0" encoding="iso-8859-1"?> -<!-- Copyright (c) 2000 Nik Clayton, All rights reserved. - - Redistribution and use in source (SGML DocBook) and 'compiled' forms - (SGML HTML, PDF, PostScript, RTF and so forth) with or without - modification, are permitted provided that the following conditions - are met: - - 1. Redistributions of source code (SGML DocBook) must retain the above - copyright notice, this list of conditions and the following - disclaimer as the first lines of this file unmodified. - - 2. Redistributions in compiled form (transformed to other DTDs, - converted to PDF, PostScript, RTF and other formats) must reproduce - the above copyright notice, this list of conditions and the - following disclaimer in the documentation and/or other materials - provided with the distribution. - - THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR - IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES - OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE - DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT, - INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES - (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR - SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) - HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, - STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN - ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE - POSSIBILITY OF SUCH DAMAGE. - - $FreeBSD$ ---> -<appendix xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" - xml:id="examples"> - - <title>Examples</title> - - <para>These examples are not exhaustive—they do not contain - all the elements that might be desirable to use, particularly in a - document's front matter. For more examples of DocBook markup, - examine the <acronym>XML</acronym> source for this and other - documents available in the <application>Subversion</application> - <literal>doc</literal> repository, or available online starting at - <uri - xlink:href="http://svnweb.FreeBSD.org/doc/">http://svnweb.FreeBSD.org/doc/</uri>.</para> - - <sect1 xml:id="examples-docbook-book"> - <title>DocBook <tag>book</tag></title> - - <example> - <title>DocBook <tag>book</tag></title> - - <programlisting><!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN" - "http://www.FreeBSD.org/XML/share/xml/freebsd50.dtd"> - -<tag class="starttag">book xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" - xml:lang="en"</tag> - - <tag class="starttag">info</tag> - <tag class="starttag">title</tag>An Example Book<tag class="endtag">title</tag> - - <tag class="starttag">author</tag> - <tag class="starttag">personname</tag> - <tag class="starttag">firstname</tag>Your first name<tag class="endtag">firstname</tag> - <tag class="starttag">surname</tag>Your surname<tag class="endtag">surname</tag> - <tag class="endtag">personname</tag> - - <tag class="starttag">affiliation</tag> - <tag class="starttag">address</tag> - <tag class="starttag">email</tag>foo@example.com<tag class="endtag">email</tag> - <tag class="endtag">address</tag> - <tag class="endtag">affiliation</tag> - <tag class="endtag">author</tag> - - <tag class="starttag">copyright</tag> - <tag class="starttag">year</tag>2000<tag class="endtag">year</tag> - <tag class="starttag">holder</tag>Copyright string here<tag class="endtag">holder</tag> - <tag class="endtag">copyright</tag> - - <tag class="starttag">abstract</tag> - <tag class="starttag">para</tag>If your book has an abstract then it should go here.<tag class="endtag">para</tag> - <tag class="endtag">abstract</tag> - <tag class="endtag">info</tag> - - <tag class="starttag">preface</tag> - <tag class="starttag">title</tag>Preface<tag class="endtag">title</tag> - - <tag class="starttag">para</tag>Your book may have a preface, in which case it should be placed - here.<tag class="endtag">para</tag> - <tag class="endtag">preface</tag> - - <tag class="starttag">chapter</tag> - <tag class="starttag">title</tag>My First Chapter<tag class="endtag">title</tag> - - <tag class="starttag">para</tag>This is the first chapter in my book.<tag class="endtag">para</tag> - - <tag class="starttag">sect1</tag> - <tag class="starttag">title</tag>My First Section<tag class="endtag">title</tag> - - <tag class="starttag">para</tag>This is the first section in my book.<tag class="endtag">para</tag> - <tag class="endtag">sect1</tag> - <tag class="endtag">chapter</tag> -<tag class="endtag">book</tag></programlisting> - </example> - </sect1> - - <sect1 xml:id="examples-docbook-article"> - <title>DocBook <tag>article</tag></title> - - <example> - <title>DocBook <tag>article</tag></title> - - <programlisting><!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN" - "http://www.FreeBSD.org/XML/share/xml/freebsd50.dtd"> - -<tag class="starttag">article xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" - xml:lang="en"</tag> - - <tag class="starttag">info</tag> - <tag class="starttag">title</tag>An Example Article<tag class="endtag">title</tag> - - <tag class="starttag">author</tag> - <tag class="starttag">personname</tag> - <tag class="starttag">firstname</tag>Your first name<tag class="endtag">firstname</tag> - <tag class="starttag">surname</tag>Your surname<tag class="endtag">surname</tag> - <tag class="endtag">personname</tag> - - <tag class="starttag">affiliation</tag> - <tag class="starttag">address</tag> - <tag class="starttag">email</tag>foo@example.com<tag class="endtag">email</tag> - <tag class="endtag">address</tag> - <tag class="endtag">affiliation</tag> - <tag class="endtag">author</tag> - - <tag class="starttag">copyright</tag> - <tag class="starttag">year</tag>2000<tag class="endtag">year</tag> - <tag class="starttag">holder</tag>Copyright string here<tag class="endtag">holder</tag> - <tag class="endtag">copyright</tag> - - <tag class="starttag">abstract</tag> - <tag class="starttag">para</tag>If your article has an abstract then it should go here.<tag class="endtag">para</tag> - <tag class="endtag">abstract</tag> - <tag class="endtag">info</tag> - - <tag class="starttag">sect1</tag> - <tag class="starttag">title</tag>My First Section<tag class="endtag">title</tag> - - <tag class="starttag">para</tag>This is the first section in my article.<tag class="endtag">para</tag> - - <tag class="starttag">sect2</tag> - <tag class="starttag">title</tag>My First Sub-Section<tag class="endtag">title</tag> - - <tag class="starttag">para</tag>This is the first sub-section in my article.<tag class="endtag">para</tag> - <tag class="endtag">sect2</tag> - <tag class="endtag">sect1</tag> -<tag class="endtag">article</tag></programlisting> - </example> - </sect1> -</appendix> diff --git a/nl_NL.ISO8859-1/books/fdp-primer/overview/chapter.xml b/nl_NL.ISO8859-1/books/fdp-primer/overview/chapter.xml deleted file mode 100644 index 0deb064ee2..0000000000 --- a/nl_NL.ISO8859-1/books/fdp-primer/overview/chapter.xml +++ /dev/null @@ -1,255 +0,0 @@ -<?xml version="1.0" encoding="iso-8859-1"?> -<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved. - - Redistribution and use in source (SGML DocBook) and 'compiled' forms - (SGML HTML, PDF, PostScript, RTF and so forth) with or without - modification, are permitted provided that the following conditions - are met: - - 1. Redistributions of source code (SGML DocBook) must retain the above - copyright notice, this list of conditions and the following - disclaimer as the first lines of this file unmodified. - - 2. Redistributions in compiled form (transformed to other DTDs, - converted to PDF, PostScript, RTF and other formats) must reproduce - the above copyright notice, this list of conditions and the - following disclaimer in the documentation and/or other materials - provided with the distribution. - - THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR - IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES - OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE - DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT, - INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES - (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR - SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) - HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, - STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN - ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE - POSSIBILITY OF SUCH DAMAGE. - - $FreeBSD$ ---> -<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="overview"> - <title>Overview</title> - - <para>Welcome to the &os; Documentation Project - (<acronym>FDP</acronym>). Quality documentation is crucial - to the success of &os;, and we value your contributions very - highly.</para> - - <para>This document describes how the <acronym>FDP</acronym> is - organized, how to write and submit documentation, and how to - effectively use the available tools.</para> - - <para>Everyone is welcome to contribute to the - <acronym>FDP</acronym>. Willingness to contribute is the only - membership requirement.</para> - - <para>This primer shows how to:</para> - - <itemizedlist> - <listitem> - <para>Identify which parts of &os; are maintained by the - <acronym>FDP</acronym>.</para> - </listitem> - - <listitem> - <para>Install the required documentation tools and files.</para> - </listitem> - - <listitem> - <para>Make changes to the documentation.</para> - </listitem> - - <listitem> - <para>Submit changes back for review and inclusion in the &os; - documentation.</para> - </listitem> - </itemizedlist> - - <sect1 xml:id="overview-doc"> - <title>The &os; Documentation Set</title> - - <para>The <acronym>FDP</acronym> is responsible for four - categories of &os; documentation.</para> - - <itemizedlist> - <listitem> - <para><emphasis>Handbook</emphasis>: The Handbook is the - comprehensive online resource and reference for &os; - users.</para> - </listitem> - - <listitem> - <para><emphasis>FAQ</emphasis>: The <acronym>FAQ</acronym> - uses a short question and answer format to address questions - that are frequently asked on the various mailing lists and - forums devoted to &os;. This format does not permit long - and comprehensive answers.</para> - </listitem> - - <listitem> - <para><emphasis>Manual pages</emphasis>: The English language - system manual pages are usually not written by the - <acronym>FDP</acronym>, as they are part of the base system. - However, the <acronym>FDP</acronym> can reword parts of - existing manual pages to make them clearer or to correct - inaccuracies.</para> - </listitem> - - <listitem> - <para><emphasis>Web site</emphasis>: This is the main &os; - presence on the web, visible at <link xlink:href="http://www.freebsd.org/index.html">http://www.FreeBSD.org/</link> - and many mirrors around the world. The web site is - typically a new user's first exposure to &os;.</para> - </listitem> - </itemizedlist> - - <para>Translation teams are responsible for translating the - Handbook and web site into different languages. Manual pages - are not translated at present.</para> - - <para>Documentation source for the &os; web site, Handbook, and - <acronym>FAQ</acronym> is available in the documentation - repository at - <literal>https://svn.FreeBSD.org/doc/</literal>.</para> - - <para>Source for manual pages is available in a separate - source repository located at - <literal>https://svn.FreeBSD.org/base/</literal>.</para> - - <para>Documentation commit messages are visible with - <command>svn log</command>. Commit messages are also - archived at <uri xlink:href="&a.svn-doc-all.url;">&a.svn-doc-all.url;</uri>.</para> - - <para>Web frontends to both of these repositories are available at <link - xlink:href="https://svnweb.FreeBSD.org/doc/"></link> and <link - xlink:href="https://svnweb.FreeBSD.org/base/"></link>.</para> - - <para>Many people have written tutorials or how-to articles about - &os;. Some are stored as part of the <acronym>FDP</acronym> - files. In other cases, the author has decided to keep the - documentation separate. The <acronym>FDP</acronym> endeavors to - provide links to as much of this external documentation as - possible.</para> - </sect1> - - <sect1 xml:id="overview-quick-start"> - <title>Quick Start</title> - - <para>Some preparatory steps must be taken before editing the &os; - documentation. First, subscribe to the &a.doc;. Some team - members also interact on the <literal>#bsddocs</literal> - <acronym>IRC</acronym> channel on - <link xlink:href="http://www.efnet.org/">EFnet</link>. These people - can help with questions or problems involving the - documentation.</para> - - <procedure> - <step> - <para>Install the - <package>textproc/docproj</package> - package or port. This meta-port installs all of the - software needed to edit and build &os; documentation.</para> - </step> - - <step> - <para>Install a local working copy of the documentation from - the &os; repository in - <filename>~/doc</filename> (see - <xref linkend="working-copy"/>).</para> - - <screen>&prompt.user; <userinput>svn checkout https://svn.FreeBSD.org/doc/head <replaceable>~/doc</replaceable></userinput></screen> - </step> - - <step> - <para>Configure the text editor:</para> - - <itemizedlist> - <listitem> - <para>Word wrap set to 70 characters.</para> - </listitem> - - <listitem> - <para>Tab stops set to 2.</para> - </listitem> - - <listitem> - <para>Replace each group of 8 leading spaces with a - single tab.</para> - </listitem> - </itemizedlist> - - <para>Specific editor configurations are listed in - <xref linkend="editor-config"/>.</para> - </step> - - <step> - <para>Update the local working copy:</para> - - <screen>&prompt.user; <userinput>svn up <replaceable>~/doc</replaceable></userinput></screen> - </step> - - <step> - <para>Edit the documentation files that require changes. If a - file needs major changes, consult the mailing list for - input.</para> - - <para>References to tag and entity usage can be found in - <xref linkend="xhtml-markup"/> and - <xref linkend="docbook-markup"/>.</para> - </step> - - <step> - <para>After editing, check for problems by running:</para> - - <screen>&prompt.user; <userinput>igor -R filename.xml | less -RS</userinput></screen> - - <para>Review the output and edit the file to fix any problems - shown, then rerun the command to find any remaining - problems. Repeat until all of the errors are - resolved.</para> - </step> - - <step> - <para><emphasis>Always</emphasis> build-test changes before - submitting them. Running <userinput>make</userinput> in the - top-level directory of the documentation being edited will - generate that documentation in split HTML format. For - example, to build the English version of the Handbook in - <acronym>HTML</acronym>, run <command>make</command> in the - <filename>en_US.ISO8859-1/books/handbook/</filename> - directory.</para> - </step> - - <step> - <para>When changes are complete and tested, generate a - <quote>diff file</quote>:</para> - - <screen>&prompt.user; <userinput>cd ~/doc</userinput> -&prompt.user; <userinput>svn diff > <replaceable>bsdinstall</replaceable>.diff.txt</userinput></screen> - - <para>Give the diff file a descriptive name. In the example - above, changes have been made to the - <filename>bsdinstall</filename> portion of - the Handbook.</para> - </step> - - <step> - <para>Submit the diff file using the web-based - <link xlink:href="&url.base;/support.html#gnats">Problem - Report</link> system. If using - the web form, enter a synopsis of - <emphasis>[patch] <replaceable>short description of - problem</replaceable></emphasis>. Select the category - <literal>docs</literal> and the class - <literal>doc-bug</literal>. In the body of the message, - enter a short description of the changes and any important - details about them. Use the - <guibutton>[ Browse... ]</guibutton> button to - attach the diff file.</para> - </step> - </procedure> - </sect1> -</chapter> diff --git a/nl_NL.ISO8859-1/books/fdp-primer/po-translations/chapter.xml b/nl_NL.ISO8859-1/books/fdp-primer/po-translations/chapter.xml deleted file mode 100644 index f797f6b5c7..0000000000 --- a/nl_NL.ISO8859-1/books/fdp-primer/po-translations/chapter.xml +++ /dev/null @@ -1,823 +0,0 @@ -<?xml version="1.0" encoding="iso-8859-1"?> -<!-- - The FreeBSD Documentation Project - $FreeBSD$ ---> -<chapter xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" - xml:id="po-translations"> - - <title><acronym>PO</acronym> Translations</title> - - <sect1 xml:id="po-translations-introduction"> - <title>Introduction</title> - - <para>The <link - xlink:href="http://www.gnu.org/software/gettext/"><acronym>GNU</acronym> - <application>gettext</application></link> system offers - translators an easy way to create and maintain translations of - documents. Translatable strings are extracted from the original - document into a <acronym>PO</acronym> (Portable Object) file. - Translated versions of the strings are entered with a separate - editor. The strings can be used directly or built into a - complete translated version of the original document.</para> - </sect1> - - <sect1 xml:id="po-translations-quick-start"> - <title>Quick Start</title> - - <para>The procedure shown in - <xref linkend="overview-quick-start"/> is assumed to have - already been performed, but the <literal>TRANSLATOR</literal> - option must be enabled in the - <package role="port">textproc/docproj</package> port. If that - option was not enabled, display the options menu and enable - it, then reinstall the port:</para> - - <screen>&prompt.root; <userinput>cd /usr/ports/textproc/docproj</userinput> -&prompt.root; <userinput>make config</userinput> -&prompt.root; <userinput>make clean deinstall install clean</userinput></screen> - - <para>This example shows the creation of a Spanish translation of - the short <link xlink:href="&url.articles.leap-seconds.en;">Leap - Seconds</link> article.</para> - - <procedure xml:id="po-translations-quick-start-install-po-editor"> - <title>Install a <acronym>PO</acronym> Editor</title> - - <step> - <para>A <acronym>PO</acronym> editor is needed to edit - translation files. This example uses - <package role="ports">editors/poedit</package>.</para> - - <screen>&prompt.root; <userinput>cd /usr/ports/editors/poedit</userinput> -&prompt.root; <userinput>make install clean</userinput></screen> - </step> - </procedure> - - <procedure xml:id="po-translations-quick-start-initial-setup"> - <title>Initial Setup</title> - - <para>When a new translation is first created, the directory - structure and <filename>Makefile</filename> must be created or - copied from the English original:</para> - - <step> - <para>Create a directory for the new translation. The - English article source is in - <filename>~/doc/en_US.ISO8859-1/articles/leap-seconds/</filename>. - The Spanish translation will go in - <filename>~/doc/es_ES.ISO8859-1/articles/leap-seconds/</filename>. - The path is the same except for the name of the language - directory.</para> - - <screen>&prompt.user; <userinput>svn mkdir --parents ~/doc/es_ES.ISO8859-1/articles/leap-seconds/</userinput></screen> - </step> - - <step> - <para>Copy the <filename>Makefile</filename> from the original - document into the translation directory:</para> - - <screen>&prompt.user; <userinput>svn cp ~/doc/en_US.ISO8859-1/articles/leap-seconds/Makefile \ - ~/doc/es_ES.ISO8859-1/articles/leap-seconds/</userinput></screen> - </step> - </procedure> - - <procedure xml:id="po-translations-quick-start-translation"> - <title>Translation</title> - - <para>Translating a document consists of two steps: extracting - translatable strings from the original document, and entering - translations for those strings. These steps are repeated - until the translator feels that enough of the document has - been translated to produce a usable translated - document.</para> - - <step> - <para>Extract the translatable strings from the original - English version into a <acronym>PO</acronym> file:</para> - - <screen>&prompt.user; <userinput>cd ~/doc/es_ES.ISO8859-1/articles/leap-seconds/</userinput> -&prompt.user; <userinput>make po</userinput></screen> - </step> - - <step> - <para>Use a <acronym>PO</acronym> editor to enter translations - in the <acronym>PO</acronym> file. There are several - different editors available. <filename>poedit</filename> - from <package role="port">editors/poedit</package> is shown - here.</para> - - <para>The <acronym>PO</acronym> file name is the - two-character language code followed by an underline and a - two-character region code. For Spanish, the file name is - <filename>es_ES.po</filename>.</para> - - <screen>&prompt.user; <userinput>poedit es_ES.po</userinput></screen> - </step> - </procedure> - - <procedure xml:id="po-translations-quick-generating-a-translated-document"> - <title>Generating a Translated Document</title> - - <step> - <para>Generate the translated document:</para> - - <screen>&prompt.user; <userinput>cd ~/doc/es_ES.ISO8859-1/articles/leap-seconds/</userinput> -&prompt.user; <userinput>make tran</userinput></screen> - - <para>The name of the generated document matches the name - of the English original, usually - <filename>article.xml</filename> for articles or - <filename>book.xml</filename> for books.</para> - </step> - - <step> - <para>Check the generated file by rendering it to - <acronym>HTML</acronym> and viewing it with a - web browser:</para> - - <screen>&prompt.user; <userinput>make FORMATS=html</userinput> -&prompt.user; <userinput>firefox article.html</userinput></screen> - </step> - </procedure> - </sect1> - - <sect1 xml:id="po-translations-creating"> - <title>Creating New Translations</title> - - <para>The first step to creating a new translated document is - locating or creating a directory to hold it. &os; puts - translated documents in a subdirectory named for their - language and region in the format - <filename><replaceable>lang</replaceable>_<replaceable>REGION</replaceable></filename>. - <replaceable>lang</replaceable> is a two-character lowercase - code. It is followed by an underscore character and then the - two-character uppercase <replaceable>REGION</replaceable> - code.</para> - - <table xml:id="po-translations-language-names" frame="none"> - <title>Language Names</title> - - <tgroup cols="5"> - <thead> - <row> - <entry>Language</entry> - <entry>Region</entry> - <entry>Translated Directory Name</entry> - <entry><acronym>PO</acronym> File Name</entry> - <entry>Character Set</entry> - </row> - </thead> - - <tbody> - <row> - <entry>English</entry> - <entry>United States</entry> - <entry><filename>en_US.ISO8859-1</filename></entry> - <entry><filename>en_US.po</filename></entry> - <entry><acronym>ISO</acronym> 8859-1</entry> - </row> - - <row> - <entry>Bengali</entry> - <entry>Bangladesh</entry> - <entry><filename>bn_BD.UTF-8</filename></entry> - <entry><filename>bn_BD.po</filename></entry> - <entry><acronym>UTF</acronym>-8</entry> - </row> - - <row> - <entry>Danish</entry> - <entry>Denmark</entry> - <entry><filename>da_DK.ISO8859-1</filename></entry> - <entry><filename>da_DK.po</filename></entry> - <entry><acronym>ISO</acronym> 8859-1</entry> - </row> - - <row> - <entry>German</entry> - <entry>Germany</entry> - <entry><filename>de_DE.ISO8859-1</filename></entry> - <entry><filename>de_DE.po</filename></entry> - <entry><acronym>ISO</acronym> 8859-1</entry> - </row> - - <row> - <entry>Greek</entry> - <entry>Greece</entry> - <entry><filename>el_GR.ISO8859-7</filename></entry> - <entry><filename>el_GR.po</filename></entry> - <entry><acronym>ISO</acronym> 8859-7</entry> - </row> - - <row> - <entry>Spanish</entry> - <entry>Spain</entry> - <entry><filename>es_ES.ISO8859-1</filename></entry> - <entry><filename>es_ES.po</filename></entry> - <entry><acronym>ISO</acronym> 8859-1</entry> - </row> - - <row> - <entry>French</entry> - <entry>France</entry> - <entry><filename>fr_FR.ISO8859-1</filename></entry> - <entry><filename>fr_FR.po</filename></entry> - <entry><acronym>ISO</acronym> 8859-1</entry> - </row> - - <row> - <entry>Hungarian</entry> - <entry>Hungary</entry> - <entry><filename>hu_HU.ISO8859-2</filename></entry> - <entry><filename>hu_HU.po</filename></entry> - <entry><acronym>ISO</acronym> 8859-2</entry> - </row> - - <row> - <entry>Italian</entry> - <entry>Italy</entry> - <entry><filename>it_IT.ISO8859-15</filename></entry> - <entry><filename>it_IT.po</filename></entry> - <entry><acronym>ISO</acronym> 8859-15</entry> - </row> - - <row> - <entry>Japanese</entry> - <entry>Japan</entry> - <entry><filename>ja_JP.eucJP</filename></entry> - <entry><filename>ja_JP.po</filename></entry> - <entry><acronym>EUC</acronym> JP</entry> - </row> - - <row> - <entry>Korean</entry> - <entry>Korea</entry> - <entry><filename>ko_KR.UTF-8</filename></entry> - <entry><filename>ko_KR.po</filename></entry> - <entry><acronym>UTF</acronym>-8</entry> - </row> - - <row> - <entry>Mongolian</entry> - <entry>Mongolia</entry> - <entry><filename>mn_MN.UTF-8</filename></entry> - <entry><filename>mn_MN.po</filename></entry> - <entry><acronym>UTF</acronym>-8</entry> - </row> - - <row> - <entry>Dutch</entry> - <entry>Netherlands</entry> - <entry><filename>nl_NL.ISO8859-1</filename></entry> - <entry><filename>nl_NL.po</filename></entry> - <entry><acronym>ISO</acronym> 8859-1</entry> - </row> - - <row> - <entry>Norwegian</entry> - <entry>Norway</entry> - <entry><filename>no_NO.ISO8859-1</filename></entry> - <entry><filename>no_NO.po</filename></entry> - <entry><acronym>ISO</acronym> 8859-1</entry> - </row> - - <row> - <entry>Polish</entry> - <entry>Poland</entry> - <entry><filename>pl_PL.ISO8859-2</filename></entry> - <entry><filename>pl_PL.po</filename></entry> - <entry><acronym>ISO</acronym> 8859-2</entry> - </row> - - <row> - <entry>Portuguese</entry> - <entry>Brazil</entry> - <entry><filename>pt_BR.ISO8859-1</filename></entry> - <entry><filename>pt_BR.po</filename></entry> - <entry><acronym>ISO</acronym> 8859-1</entry> - </row> - - <row> - <entry>Russian</entry> - <entry>Russia</entry> - <entry><filename>ru_RU.KOI8-R</filename></entry> - <entry><filename>ru_RU.po</filename></entry> - <entry><acronym>KOI</acronym>8-R</entry> - </row> - - <row> - <entry>Serbian</entry> - <entry>Serbia</entry> - <entry><filename>sr_YU.ISO8859-2</filename></entry> - <entry><filename>sr_YU.po</filename></entry> - <entry><acronym>ISO</acronym> 8859-2</entry> - </row> - - <row> - <entry>Turkish</entry> - <entry>Turkey</entry> - <entry><filename>tr_TR.ISO8859-9</filename></entry> - <entry><filename>tr_TR.po</filename></entry> - <entry><acronym>ISO</acronym> 8859-9</entry> - </row> - - <row> - <entry>Chinese</entry> - <entry>China</entry> - <entry><filename>zh_CN.UTF-8</filename></entry> - <entry><filename>zh_CN.po</filename></entry> - <entry><acronym>UTF</acronym>-8</entry> - </row> - - <row> - <entry>Chinese</entry> - <entry>Taiwan</entry> - <entry><filename>zh_TW.UTF-8</filename></entry> - <entry><filename>zh_TW.po</filename></entry> - <entry><acronym>UTF</acronym>-8</entry> - </row> - </tbody> - </tgroup> - </table> - - <para>The translations are in subdirectories of the main - documentation directory, here assumed to be - <filename>~/doc/</filename> as shown in - <xref linkend="overview-quick-start"/>. For example, German - translations are located in - <filename>~/doc/de_DE.ISO8859-1/</filename>, and French - translations are in - <filename>~/doc/fr_FR.ISO8859-1/</filename>.</para> - - <para>Each language directory contains separate subdirectories - named for the type of documents, usually - <filename>articles/</filename> and - <filename>books/</filename>.</para> - - <para>Combining these directory names gives the complete path to - an article or book. For example, the French translation of the - NanoBSD article is in - <filename>~/doc/fr_FR.ISO8859-1/articles/nanobsd/</filename>, - and the Mongolian translation of the Handbook is in - <filename>~/doc/mn_MN.UTF-8/books/handbook/</filename>.</para> - - <para>A new language directory must be created when translating - a document to a new language. If the language directory already - exists, only a subdirectory in the - <filename>articles/</filename> or <filename>books/</filename> - directory is needed.</para> - - <para>&os; documentation builds are controlled by a - <filename>Makefile</filename> in the same directory. With - simple articles, the <filename>Makefile</filename> can often - just be copied verbatim from the original English directory. - The translation process combines multiple separate - <filename>book.xml</filename> and - <filename>chapter.xml</filename> files in books into a single - file, so the <filename>Makefile</filename> for book translations - must be copied and modified.</para> - - <example xml:id="po-translations-creating-example"> - <title>Creating a Spanish Translation of the Porter's - Handbook</title> - - <para>Create a new Spanish translation of the - <link xlink:href="&url.books.porters-handbook.en;">Porter's - Handbook</link>. The original is a book in - <filename>~/doc/en_US.ISO8859-1/books/porters-handbook/</filename>.</para> - - <procedure> - <step> - <para>The Spanish language books directory - <filename>~/doc/es_ES.ISO8859-1/books/</filename> already - exists, so only a new subdirectory for the Porter's - Handbook is needed:</para> - <screen>&prompt.user; <userinput>cd ~/doc/es_ES.ISO8859-1/books/</userinput> -&prompt.user; <userinput>svn mkdir porters-handbook</userinput> -A porters-handbook</screen> - </step> - - <step> - <para>Copy the <filename>Makefile</filename> from the - original book:</para> - - <screen>&prompt.user; <userinput>cd ~/doc/es_ES.ISO8859-1/books/porters-handbook</userinput> -&prompt.user; <userinput>svn cp ~/doc/en_US.ISO8859-1/books/porters-handbook/Makefile .</userinput> -A Makefile</screen> - - <para>Modify the contents of the - <filename>Makefile</filename> to only expect a single - <filename>book.xml</filename>:</para> - - <programlisting># -# $FreeBSD$ -# -# Build the FreeBSD Porter's Handbook. -# - -MAINTAINER=doc@FreeBSD.org - -DOC?= book - -FORMATS?= html-split - -INSTALL_COMPRESSED?= gz -INSTALL_ONLY_COMPRESSED?= - -# XML content -SRCS= book.xml - -# Images from the cross-document image library -IMAGES_LIB+= callouts/1.png -IMAGES_LIB+= callouts/2.png -IMAGES_LIB+= callouts/3.png -IMAGES_LIB+= callouts/4.png -IMAGES_LIB+= callouts/5.png -IMAGES_LIB+= callouts/6.png -IMAGES_LIB+= callouts/7.png -IMAGES_LIB+= callouts/8.png -IMAGES_LIB+= callouts/9.png -IMAGES_LIB+= callouts/10.png -IMAGES_LIB+= callouts/11.png -IMAGES_LIB+= callouts/12.png -IMAGES_LIB+= callouts/13.png -IMAGES_LIB+= callouts/14.png -IMAGES_LIB+= callouts/15.png -IMAGES_LIB+= callouts/16.png -IMAGES_LIB+= callouts/17.png -IMAGES_LIB+= callouts/18.png -IMAGES_LIB+= callouts/19.png -IMAGES_LIB+= callouts/20.png -IMAGES_LIB+= callouts/21.png - -URL_RELPREFIX?= ../../../.. -DOC_PREFIX?= ${.CURDIR}/../../.. - -SYMLINKS= ${DESTDIR} index.html handbook.html - -.include "${DOC_PREFIX}/share/mk/doc.project.mk"</programlisting> - - <para>Now the document structure is ready for the translator - to begin translating with - <command>make po</command>.</para> - </step> - </procedure> - </example> - - <example xml:id="po-translations-creating-example-french"> - <title>Creating a French Translation of the - <acronym>PGP</acronym> Keys Article</title> - - <para>Create a new French translation of the - <link xlink:href="&url.articles.pgpkeys;"><acronym>PGP</acronym> - Keys article</link>. The original is an article in - <filename>~/doc/en_US.ISO8859-1/articles/pgpkeys/</filename>.</para> - - <procedure> - <step> - <para>The French language article directory - <filename>~/doc/fr_FR.ISO8859-1/articles/</filename> - already exists, so only a new subdirectory for the - <acronym>PGP</acronym> Keys article is needed:</para> - <screen>&prompt.user; <userinput>cd ~/doc/fr_FR.ISO8859-1/articles/</userinput> -&prompt.user; <userinput>svn mkdir pgpkeys</userinput> -A pgpkeys</screen> - </step> - - <step> - <para>Copy the <filename>Makefile</filename> from the - original article:</para> - - <screen>&prompt.user; <userinput>cd ~/doc/fr_FR.ISO8859-1/articles/pgpkeys</userinput> -&prompt.user; <userinput>svn cp ~/doc/en_US.ISO8859-1/articles/pgpkeys/Makefile .</userinput> -A Makefile</screen> - - <para>Check the contents of the - <filename>Makefile</filename>. Because this is a simple - article, in this case the <filename>Makefile</filename> - can be used unchanged. The <literal>$&os;...$</literal> - version string on the third line will be replaced by the - version control system when this file is committed.</para> - - <programlisting># -# $FreeBSD$ -# -# Article: PGP Keys - -DOC?= article - -FORMATS?= html -WITH_ARTICLE_TOC?= YES - -INSTALL_COMPRESSED?= gz -INSTALL_ONLY_COMPRESSED?= - -SRCS= article.xml - -# To build with just key fingerprints, set FINGERPRINTS_ONLY. - -URL_RELPREFIX?= ../../../.. -DOC_PREFIX?= ${.CURDIR}/../../.. - -.include "${DOC_PREFIX}/share/mk/doc.project.mk"</programlisting> - - <para>With the document structure complete, the - <acronym>PO</acronym> file can be created with - <command>make po</command>.</para> - </step> - </procedure> - </example> - </sect1> - - <sect1 xml:id="po-translations-translating"> - <title>Translating</title> - - <para>The <application>gettext</application> system greatly - reduces the number of things that must be tracked by a - translator. Strings to be translated are extracted from the - original document into a <acronym>PO</acronym> file. Then a - <acronym>PO</acronym> editor is used to enter the translated - versions of each string.</para> - - <para>The &os; <acronym>PO</acronym> translation system does not - overwrite <acronym>PO</acronym> files, so the extraction step - can be run at any time to update the <acronym>PO</acronym> - file.</para> - - <para>A <acronym>PO</acronym> editor is used to edit the file. - <package role="port">editors/poedit</package> is shown in - these examples because it is simple and has minimal - requirements. Other <acronym>PO</acronym> editors offer - features to make the job of translating easier. The Ports - Collection offers several of these editors, including - <package role="port">devel/gtranslator</package>.</para> - - <para>It is important to preserve the <acronym>PO</acronym> file. - It contains all of the work that translators have done.</para> - - <example xml:id="po-translations-translating-example"> - <title>Translating the Porter's Handbook to Spanish</title> - - <para>Enter Spanish translations of the contents of the Porter's - Handbook.</para> - - <procedure> - <step> - <para>Change to the Spanish Porter's Handbook directory and - update the <acronym>PO</acronym> file. The generated - <acronym>PO</acronym> file is called - <filename>es_ES.po</filename> as shown in - <xref linkend="po-translations-language-names"/>.</para> - - <screen>&prompt.user; <userinput>cd ~/doc/es_ES.ISO8859-1/books/porters-handbook</userinput> -&prompt.user; <userinput>make po</userinput></screen> - </step> - - <step> - <para>Enter translations using a <acronym>PO</acronym> - editor:</para> - - <screen>&prompt.user; <userinput>poedit es_ES.po</userinput></screen> - </step> - </procedure> - </example> - </sect1> - - <sect1 xml:id="po-translations-tips"> - <title>Tips for Translators</title> - - <sect2 xml:id="po-translations-tips-xmltags"> - <title>Preserving <acronym>XML</acronym> Tags</title> - - <para>Preserve <acronym>XML</acronym> tags that are shown in - the English original.</para> - - <example> - <title>Preserving <acronym>XML</acronym> Tags</title> - - <para>English original:</para> - - <programlisting>If <tag class="starttag">acronym</tag>NTP<tag class="endtag">acronym</tag> is not being used</programlisting> - - <para>Spanish translation:</para> - - <programlisting>Si <tag class="starttag">acronym</tag>NTP<tag class="endtag">acronym</tag> no se utiliza</programlisting> - </example> - </sect2> - - <sect2 xml:id="po-translations-tips-spaces"> - <title>Preserving Spaces</title> - - <para>Preserve existing spaces at the beginning and end of - strings to be translated. The translated version must have - these spaces also.</para> - </sect2> - - <sect2 xml:id="po-translations-tips-verbatim"> - <title>Verbatim Tags</title> - - <para>The contents of some tags should be copied verbatim, not - translated:</para> - - <itemizedlist xml:id="po-translations-tips-verbatim-list"> - <listitem> - <para><tag class="starttag">citerefentry</tag></para> - </listitem> - - <listitem> - <para><tag class="starttag">command</tag></para> - </listitem> - - <listitem> - <para><tag class="starttag">filename</tag></para> - </listitem> - - <listitem> - <para><tag class="starttag">literal</tag></para> - </listitem> - - <listitem> - <para><tag class="starttag">manvolnum</tag></para> - </listitem> - - <listitem> - <para><tag class="starttag">orgname</tag></para> - </listitem> - - <listitem> - <para><tag class="starttag">package</tag></para> - </listitem> - - <listitem> - <para><tag class="starttag">programlisting</tag></para> - </listitem> - - <listitem> - <para><tag class="starttag">prompt</tag></para> - </listitem> - - <listitem> - <para><tag class="starttag">refentrytitle</tag></para> - </listitem> - - <listitem> - <para><tag class="starttag">screen</tag></para> - </listitem> - - <listitem> - <para><tag class="starttag">userinput</tag></para> - </listitem> - - <listitem> - <para><tag class="starttag">varname</tag></para> - </listitem> - </itemizedlist> - </sect2> - - <!-- - <sect2 xml:id="po-translations-tips-makefile"> - <title>Modifying the <filename>Makefile</filename></title> - - <para>What needs to be changed in the - <filename>Makefile</filename>?</para> - </sect2> - - <sect2 xml:id="po-translations-tips-locale"> - <title>Setting Locales for Editing</title> - - <para>Locale settings so the <acronym>PO</acronym> editor works - correctly?</para> - </sect2> - - <sect2 xml:id="po-translations-tips-poeditors"> - <title>Settings for Specific <acronym>PO</acronym> - Editors</title> - - <para>Per bcr: turn off "intelligent quotes" in - Mac poedit.</para> - </sect2> - - <sect2 xml:id="po-translations-tips-tm"> - <title>Using Translation Memory</title> - - <para>Using translation memory. Saving, updating, sharing - with other members of a translation team.</para> - </sect2> - - <sect2 xml:id="po-translations-tips-submitting"> - <title>Submitting Translations</title> - - <para>Submitting translations as diffs, committing - <acronym>PO</acronym> files.</para> - </sect2> - --> - </sect1> - - <sect1 xml:id="po-translations-building"> - <title>Building a Translated Document</title> - - <para>A translated version of the original document can be created - at any time. Any untranslated portions of the original will be - included in English in the resulting document. Most - <acronym>PO</acronym> editors have an indicator that shows how - much of the translation has been completed. This makes it easy - for the translator to see when enough strings have been - translated to make building the final document - worthwhile.</para> - - <example xml:id="po-translations-building-example"> - <title>Building the Spanish Porter's Handbook</title> - - <para>Build and preview the Spanish version of the Porter's - Handbook that was created in an earlier example.</para> - - <procedure> - <step> - <para>Build the translated document. Because the original - is a book, the generated document is - <filename>book.xml</filename>.</para> - - <screen>&prompt.user; <userinput>cd ~/doc/es_ES.ISO8859-1/books/porters-handbook</userinput> -&prompt.user; <userinput>make tran</userinput></screen> - </step> - - <step> - <para>Render the translated <filename>book.xml</filename> to - <acronym>HTML</acronym> and view it with - <application>Firefox</application>. This is the - same procedure used with the English version of the - documents, and other <varname>FORMATS</varname> can - be used here in the same way. See <xref - linkend="doc-build-rendering-common-formats"/>.</para> - - <screen>&prompt.user; <userinput>make FORMATS=html</userinput> -&prompt.user; <userinput>firefox book.html</userinput></screen> - </step> - </procedure> - </example> - </sect1> - - <sect1 xml:id="po-translations-submitting"> - <title>Submitting the New Translation</title> - - <para>Prepare the new translation files for submission. This - example shows a new Spanish translation of the NanoBSD - article in - <filename>~/doc/es_ES.ISO8859-1/articles/nanobsd</filename>.</para> - - <procedure> - <step> - <para>The <acronym>PO</acronym> file must contain a &os; - version string comment on the first line:</para> - - <programlisting>#$FreeBSD$</programlisting> - </step> - - <step> - <para>The <filename>Makefile</filename>, the - <acronym>PO</acronym> file, and the generated - <acronym>XML</acronym> translation must all be added to - version control:</para> - - <screen>&prompt.user; <userinput>cd ~/doc/es_ES.ISO8859-1/articles/nanobsd/</userinput> -&prompt.user; <userinput>ls</userinput> -Makefile article.xml es_ES.po -&prompt.user; <userinput>svn add Makefile article.xml es_ES.po</userinput> -A Makefile -A article.xml -A es_ES.po</screen> - </step> - - <step> - <para>These files must also have the - <application>Subversion</application> - <literal>svn:keywords</literal> property set to - <literal>FreeBSD=%H</literal>:</para> - - <screen>&prompt.user; <userinput>svn propset svn:keywords FreeBSD=%H Makefile article.xml es_ES.po</userinput> -property 'svn:keywords' set on 'Makefile' -property 'svn:keywords' set on 'article.xml' -property 'svn:keywords' set on 'es_ES.po'</screen> - </step> - - <step> - <para>A diff of these new files is created from the - <filename>~/doc/</filename> base directory so the full path - is shown with the filenames. This helps committers identify - the target language directory.</para> - - <screen>&prompt.user; <userinput>cd ~/doc</userinput> -<userinput>svn diff es_ES.ISO8859-1/articles/nanobsd/ > /tmp/es_nanobsd.diff</userinput></screen> - - <para>The diff file is now ready for attachment to a - <link - xlink:href="https://bugs.freebsd.org/bugzilla/enter_bug.cgi?product=Documentation">documentation - bug report</link> or <link - xlink:href="https://reviews.freebsd.org/">code - review</link>.</para> - </step> - </procedure> - </sect1> -</chapter> diff --git a/nl_NL.ISO8859-1/books/fdp-primer/psgml-mode/chapter.xml b/nl_NL.ISO8859-1/books/fdp-primer/psgml-mode/chapter.xml deleted file mode 100644 index 03c12c8545..0000000000 --- a/nl_NL.ISO8859-1/books/fdp-primer/psgml-mode/chapter.xml +++ /dev/null @@ -1,171 +0,0 @@ -<?xml version="1.0" encoding="iso-8859-1"?> -<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved. - - Redistribution and use in source (SGML DocBook) and 'compiled' forms - (SGML HTML, PDF, PostScript, RTF and so forth) with or without - modification, are permitted provided that the following conditions - are met: - - 1. Redistributions of source code (SGML DocBook) must retain the above - copyright notice, this list of conditions and the following - disclaimer as the first lines of this file unmodified. - - 2. Redistributions in compiled form (transformed to other DTDs, - converted to PDF, PostScript, RTF and other formats) must reproduce - the above copyright notice, this list of conditions and the - following disclaimer in the documentation and/or other materials - provided with the distribution. - - THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR - IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES - OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE - DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT, - INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES - (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR - SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) - HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, - STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN - ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE - POSSIBILITY OF SUCH DAMAGE. - - $FreeBSD$ ---> -<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="psgml-mode"> - <title>Using <literal>sgml-mode</literal> with - <application>Emacs</application></title> - - <para>Recent versions of <application>Emacs</application> or - <application>XEmacs</application> (available from the Ports - Collection) contain a very useful package called PSGML (can be - installed from <package>editors/psgml</package>). - Automatically invoked when a file with the - <filename>.xml</filename> extension is loaded, or by typing - <command>M-x sgml-mode</command>, it is a major mode for dealing - with SGML files, elements and attributes.</para> - - <para>An understanding of some of the commands provided by this mode - can make working with SGML documents such as the Handbook much - easier.</para> - - <variablelist> - <varlistentry> - <term><command>C-c C-e</command></term> - - <listitem> - <para>Runs <function>sgml-insert-element</function>. You will - be prompted for the name of the element to insert at the - current point. You can use the <keycap>Tab</keycap> key to - complete the element. Elements that are not valid at the - current point will be disallowed.</para> - - <para>The start and end tags for the element will be inserted. - If the element contains other, mandatory, elements then - these will be inserted as well.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>C-c =</command></term> - - <listitem> - <para>Runs <function>sgml-change-element-name</function>. - Place the point within an element and run this command. You - will be prompted for the name of the element to change to. - Both the start and end tags of the current element will be - changed to the new element.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>C-c C-r</command></term> - - <listitem> - <para>Runs <function>sgml-tag-region</function>. Select some - text (move to start of text, <command>C-space</command>, - move to end of text, <command>C-space</command>) and then - run this command. You will be prompted for the element to - use. This element will then be inserted immediately before - and after your marked region.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>C-c -</command></term> - - <listitem> - <para>Runs <function>sgml-untag-element</function>. Place the - point within the start or end tag of an element you want to - remove, and run this command. The element's start and end - tags will be removed.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>C-c C-q</command></term> - - <listitem> - <para>Runs <function>sgml-fill-element</function>. Will - recursively fill (i.e., reformat) content from the current - element in. The filling <emphasis>will</emphasis> affect - content in which whitespace is significant, such as within - <tag>programlisting</tag> elements, so run this - command with care.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>C-c C-a</command></term> - - <listitem> - <para>Runs <function>sgml-edit-attributes</function>. Opens a - second buffer containing a list of all the attributes for - the closest enclosing element, and their current values. - Use <keycap>Tab</keycap> to navigate between attributes, - <command>C-k</command> to remove an existing value and - replace it with a new one, <command>C-c C-c</command> to - close this buffer and return to the main document.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>C-c C-v</command></term> - - <listitem> - <para>Runs <function>sgml-validate</function>. Prompts you to - save the current document (if necessary) and then runs an - SGML validator. The output from the validator is captured - into a new buffer, and you can then navigate from one - troublespot to the next, fixing markup errors as you - go.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>C-c /</command></term> - - <listitem> - <para>Runs <function>sgml-insert-end-tag</function>. Inserts - the end tag for the current open element.</para> - </listitem> - </varlistentry> - </variablelist> - - <para>Doubtless there are other useful functions of this mode, but - those are the ones I use most often.</para> - - <para>You can also use the following entries in - <filename>.emacs</filename> to set proper spacing, indentation, - and column width for working with the Documentation - Project.</para> - - <programlisting> (defun local-sgml-mode-hook - (setq fill-column 70 - indent-tabs-mode nil - next-line-add-newlines nil - standard-indent 4 - sgml-indent-data t) - (auto-fill-mode t) - (setq sgml-catalog-files '("/usr/local/share/xml/catalog"))) - (add-hook 'psgml-mode-hook - '(lambda () (local-psgml-mode-hook)))</programlisting> -</chapter> diff --git a/nl_NL.ISO8859-1/books/fdp-primer/see-also/chapter.xml b/nl_NL.ISO8859-1/books/fdp-primer/see-also/chapter.xml deleted file mode 100644 index 62764fb0e1..0000000000 --- a/nl_NL.ISO8859-1/books/fdp-primer/see-also/chapter.xml +++ /dev/null @@ -1,108 +0,0 @@ -<?xml version="1.0" encoding="iso-8859-1"?> -<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved. - - Redistribution and use in source (SGML DocBook) and 'compiled' forms - (SGML HTML, PDF, PostScript, RTF and so forth) with or without - modification, are permitted provided that the following conditions - are met: - - 1. Redistributions of source code (SGML DocBook) must retain the above - copyright notice, this list of conditions and the following - disclaimer as the first lines of this file unmodified. - - 2. Redistributions in compiled form (transformed to other DTDs, - converted to PDF, PostScript, RTF and other formats) must reproduce - the above copyright notice, this list of conditions and the - following disclaimer in the documentation and/or other materials - provided with the distribution. - - THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR - IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES - OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE - DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT, - INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES - (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR - SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) - HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, - STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN - ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE - POSSIBILITY OF SUCH DAMAGE. - - $FreeBSD$ ---> -<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="see-also"> - <title>See Also</title> - - <para>This document is deliberately not an exhaustive discussion of - XML, the DTDs listed, and the FreeBSD Documentation Project. For - more information about these, you are encouraged to see the - following web sites.</para> - - <sect1 xml:id="see-also-fdp"> - <title>The FreeBSD Documentation Project</title> - - <itemizedlist> - <listitem> - <para><link xlink:href="&url.base;/docproj/index.html">The FreeBSD - Documentation Project web pages</link></para> - </listitem> - - <listitem> - <para><link xlink:href="&url.books.handbook;/index.html">The FreeBSD - Handbook</link></para> - </listitem> - </itemizedlist> - </sect1> - - <sect1 xml:id="see-also-xml"> - <title>XML</title> - - <itemizedlist> - <listitem> - <para><link xlink:href="http://www.w3.org/XML/">W3C's XML page - SGML/XML web page</link></para> - </listitem> - </itemizedlist> - </sect1> - - <sect1 xml:id="see-also-html"> - <title>HTML</title> - - <itemizedlist> - <listitem> - <para><link xlink:href="http://www.w3.org/">The World Wide Web - Consortium</link></para> - </listitem> - - <listitem> - <para><link xlink:href="http://www.w3.org/TR/REC-html40/">The HTML - 4.0 specification</link></para> - </listitem> - </itemizedlist> - </sect1> - - <sect1 xml:id="see-also-docbook"> - <title>DocBook</title> - - <itemizedlist> - <listitem> - <para><link xlink:href="http://www.oasis-open.org/docbook/">The - DocBook Technical Committee</link>, maintainers of the - DocBook DTD</para> - </listitem> - - <listitem> - <para><link xlink:href="http://www.docbook.org/">DocBook: The - Definitive Guide</link>, the online documentation for the - DocBook DTD</para> - </listitem> - - <listitem> - <para><link xlink:href="http://docbook.sourceforge.net/">The DocBook - Open Repository</link> contains DSSSL stylesheets and - other resources for people using DocBook</para> - </listitem> - </itemizedlist> - </sect1> - -</chapter> diff --git a/nl_NL.ISO8859-1/books/fdp-primer/structure/chapter.xml b/nl_NL.ISO8859-1/books/fdp-primer/structure/chapter.xml deleted file mode 100644 index a5fb852efd..0000000000 --- a/nl_NL.ISO8859-1/books/fdp-primer/structure/chapter.xml +++ /dev/null @@ -1,305 +0,0 @@ -<?xml version="1.0" encoding="iso-8859-1"?> -<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved. - - Redistribution and use in source (SGML DocBook) and 'compiled' forms - (SGML HTML, PDF, PostScript, RTF and so forth) with or without - modification, are permitted provided that the following conditions - are met: - - 1. Redistributions of source code (SGML DocBook) must retain the above - copyright notice, this list of conditions and the following - disclaimer as the first lines of this file unmodified. - - 2. Redistributions in compiled form (transformed to other DTDs, - converted to PDF, PostScript, RTF and other formats) must reproduce - the above copyright notice, this list of conditions and the - following disclaimer in the documentation and/or other materials - provided with the distribution. - - THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR - IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES - OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE - DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT, - INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES - (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR - SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) - HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, - STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN - ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE - POSSIBILITY OF SUCH DAMAGE. - - $FreeBSD$ ---> -<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="structure"> - <title>Documentation Directory Structure</title> - - <para>Files and directories in the - <filename>doc/</filename> tree follow a - structure meant to:</para> - - <orderedlist> - <listitem> - <para>Make it easy to automate converting the document to other - formats.</para> - </listitem> - - <listitem> - <para>Promote consistency between the different documentation - organizations, to make it easier to switch between working on - different documents.</para> - </listitem> - - <listitem> - <para>Make it easy to decide where in the tree new documentation - should be placed.</para> - </listitem> - </orderedlist> - - <para>In addition, the documentation tree must accommodate - documents in many different languages and encodings. It is - important that the documentation tree structure does not enforce - any particular defaults or cultural preferences.</para> - - <sect1 xml:id="structure-top"> - <title>The Top Level, - <filename>doc/</filename></title> - - <para>There are two types of directory under - <filename>doc/</filename>, each with very - specific directory names and meanings.</para> - - <informaltable pgwide="1" frame="none"> - <tgroup cols="2"> - <thead> - <row> - <entry>Directory</entry> - <entry>Usage</entry> - </row> - </thead> - - <tbody> - <row> - <entry valign="top"> - <filename>share</filename></entry> - - <entry>Contains files that are not specific to the various - translations and encodings of the documentation. - Contains subdirectories to further categorize the - information. For example, the files that comprise the - &man.make.1; infrastructure are in - <filename>share/mk</filename>, while - the additional <acronym>XML</acronym> support files - (such as the &os; extended DocBook - <acronym>DTD</acronym>) are in <filename>share/xml</filename>.</entry> - </row> - - <row> - <entry valign="top"> - <filename><replaceable>lang</replaceable>.<replaceable>encoding</replaceable></filename></entry> - - <entry>One directory exists for each available translation - and encoding of the documentation, for example - <filename>en_US.ISO8859-1/</filename> - and <filename>zh_TW.UTF-8/</filename>. - The names are long, but by fully specifying the language - and encoding we prevent any future headaches when a - translation team wants to provide documentation in the - same language but in more than one encoding. This also - avoids problems that might be caused by a future switch - to Unicode.</entry> - </row> - </tbody> - </tgroup> - </informaltable> - </sect1> - - <sect1 xml:id="structure-locale"> - <title>The - <filename><replaceable>lang</replaceable>.<replaceable>encoding</replaceable>/</filename> - Directories</title> - - <para>These directories contain the documents themselves. The - documentation is split into up to three more categories at - this level, indicated by the different directory names.</para> - - <informaltable pgwide="1" frame="none"> - <tgroup cols="2"> - <thead> - <row> - <entry>Directory</entry> - <entry>Usage</entry> - </row> - </thead> - - <tbody> - <row> - <entry valign="top"> - <filename>articles</filename></entry> - - <entry>Documentation marked up as a DocBook - <tag>article</tag> (or equivalent). Reasonably - short, and broken up into sections. Normally only - available as one <acronym>XHTML</acronym> file.</entry> - </row> - - <row> - <entry valign="top"><filename>books</filename></entry> - - <entry>Documentation marked up as a DocBook - <tag>book</tag> (or equivalent). Book length, - and broken up into chapters. Normally available as both - one large <acronym>XHTML</acronym> file (for people with - fast connections, or who want to print it easily from a - browser) and as a collection of linked, smaller - files.</entry> - </row> - - <row> - <entry valign="top"> - <filename>man</filename></entry> - - <entry>For translations of the system manual pages. This - directory will contain one or more <filename role="directory">man<replaceable>n</replaceable></filename> - directories, corresponding to the sections that have - been translated.</entry> - </row> - </tbody> - </tgroup> - </informaltable> - - <para>Not every <filename role="directory"><replaceable>lang</replaceable>.<replaceable>encoding</replaceable></filename> - directory will have all of these subdirectories. It depends - on how much translation has been accomplished by that - translation team.</para> - </sect1> - - <sect1 xml:id="structure-document"> - <title>Document-Specific Information</title> - - <para>This section contains specific notes about particular - documents managed by the FDP.</para> - - <sect2> - <title>The Handbook</title> - - <subtitle><filename>books/handbook/</filename></subtitle> - - <para>The Handbook is written in DocBook <acronym>XML</acronym> - using the &os; DocBook extended <acronym>DTD</acronym>.</para> - - <para>The Handbook is organized as a DocBook - <tag>book</tag>. The book is divided into - <tag>part</tag>s, each of which contains several - <tag>chapter</tag>s. <tag>chapter</tag>s are - further subdivided into sections (<tag>sect1</tag>) - and subsections (<tag>sect2</tag>, - <tag>sect3</tag>) and so on.</para> - - <sect3> - <title>Physical Organization</title> - - <para>There are a number of files and directories within the - <filename>handbook</filename> directory.</para> - - <note> - <para>The Handbook's organization may change over time, and - this document may lag in detailing the organizational - changes. Post questions about Handbook organization to the - &a.doc;.</para> - </note> - - <sect4> - <title><filename>Makefile</filename></title> - - <para>The <filename>Makefile</filename> defines some - variables that affect how the <acronym>XML</acronym> - source is converted to other formats, and lists the - various source files that make up the Handbook. It then - includes the standard <filename>doc.project.mk</filename>, - to bring in the rest of the code that handles converting - documents from one format to another.</para> - </sect4> - - <sect4> - <title><filename>book.xml</filename></title> - - <para>This is the top level document in the Handbook. It - contains the Handbook's <link linkend="xml-primer-doctype-declaration">DOCTYPE - declaration</link>, as well as the elements that - describe the Handbook's structure.</para> - - <para><filename>book.xml</filename> uses <link linkend="xml-primer-parameter-entities">parameter - entities</link> to load in the files with the - <filename>.ent</filename> extension. These files - (described later) then define <link linkend="xml-primer-general-entities">general - entities</link> that are used throughout the rest of the - Handbook.</para> - </sect4> - - <sect4> - <title><filename role="directory"><replaceable>directory</replaceable>/chapter.xml</filename></title> - - <para>Each chapter in the Handbook is stored in a file - called <filename>chapter.xml</filename> in a separate - directory from the other chapters. Each directory is - named after the value of the <literal>id</literal> - attribute on the <tag>chapter</tag> - element.</para> - - <para>For example, if one of the chapter files - contains:</para> - - <programlisting><tag class="starttag">chapter id="kernelconfig"</tag> -... -<tag class="endtag">chapter</tag></programlisting> - - <para>Then it will be called - <filename>chapter.xml</filename> in the - <filename>kernelconfig</filename> directory. In general, - the entire contents of the chapter are in this one - file.</para> - - <para>When the <acronym>XHTML</acronym> version of the - Handbook is produced, this will yield - <filename>kernelconfig.html</filename>. This is because - of the <literal>id</literal> value, and is not related to - the name of the directory.</para> - - <para>In earlier versions of the Handbook, the files were - stored in the same directory as - <filename>book.xml</filename>, and named after the value - of the <literal>id</literal> attribute on the file's - <tag>chapter</tag> element. Now, it is possible - to include images in each chapter. Images for each - Handbook chapter are stored within <filename>share/images/books/handbook</filename>. - The localized version of these images should be - placed in the same directory as the <acronym>XML</acronym> - sources for each chapter. Namespace collisions are - inevitable, and it is easier to work with several - directories with a few files in them than it is to work - with one directory that has many files in it.</para> - - <para>A brief look will show that there are many directories - with individual <filename>chapter.xml</filename> files, - including <filename>basics/chapter.xml</filename>, - <filename>introduction/chapter.xml</filename>, and - <filename>printing/chapter.xml</filename>.</para> - - <important> - <para>Do not name chapters or directories after - their ordering within the Handbook. This ordering can - change as the content within the Handbook is - reorganized. Reorganization should be possible without - renaming files, unless entire chapters are being - promoted or demoted within the hierarchy.</para> - </important> - - <para>The <filename>chapter.xml</filename> files are not - complete <acronym>XML</acronym> documents that can be - built individually. They can only be built - as parts of the whole Handbook.</para> - </sect4> - </sect3> - </sect2> - </sect1> -</chapter> diff --git a/nl_NL.ISO8859-1/books/fdp-primer/stylesheets/chapter.xml b/nl_NL.ISO8859-1/books/fdp-primer/stylesheets/chapter.xml deleted file mode 100644 index d8d48f16ae..0000000000 --- a/nl_NL.ISO8859-1/books/fdp-primer/stylesheets/chapter.xml +++ /dev/null @@ -1,75 +0,0 @@ -<?xml version="1.0" encoding="iso-8859-1"?> -<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved. - - Redistribution and use in source (SGML DocBook) and 'compiled' forms - (SGML HTML, PDF, PostScript, RTF and so forth) with or without - modification, are permitted provided that the following conditions - are met: - - 1. Redistributions of source code (SGML DocBook) must retain the above - copyright notice, this list of conditions and the following - disclaimer as the first lines of this file unmodified. - - 2. Redistributions in compiled form (transformed to other DTDs, - converted to PDF, PostScript, RTF and other formats) must reproduce - the above copyright notice, this list of conditions and the - following disclaimer in the documentation and/or other materials - provided with the distribution. - - THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR - IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES - OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE - DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT, - INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES - (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR - SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) - HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, - STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN - ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE - POSSIBILITY OF SUCH DAMAGE. - - $FreeBSD$ ---> -<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="stylesheets"> - <title>Style Sheets</title> - - <para><acronym>XML</acronym> is concerned with content, and says - nothing about how that content should be presented to the reader - or rendered on paper. Multiple <emphasis>style sheet</emphasis> - languages have been developed to describe visual layout, including - Extensible Stylesheet Language Transformation - (<acronym>XSLT</acronym>), Document Style Semantics and - Specification Language (<acronym>DSSSL</acronym>), and Cascading - Style Sheets (<acronym>CSS</acronym>).</para> - - <para>The <acronym>FDP</acronym> documents use - <acronym>XSLT</acronym> stylesheets to transform DocBook into - <acronym>XHTML</acronym>, and then <acronym>CSS</acronym> - formatting is applied to the <acronym>XHTML</acronym> pages. - Printable output is currently rendered with legacy - <acronym>DSSSL</acronym> stylesheets, but this will probably - change in the future.</para> - - <sect1 xml:id="stylesheets-css"> - <title><acronym>CSS</acronym></title> - - <para>Cascading Style Sheets (<acronym>CSS</acronym>) are a - mechanism for attaching style information (font, weight, size, - color, and so forth) to elements in an <acronym>XHTML</acronym> - document without abusing <acronym>XHTML</acronym> to do - so.</para> - - <sect2> - <title>The DocBook Documents</title> - - <para>The &os; <acronym>XSLT</acronym> and - <acronym>DSSSL</acronym> stylesheets refer to - <filename>docbook.css</filename>, which is expected to be - present in the same directory as the <acronym>XHTML</acronym> - files. The project-wide <acronym>CSS</acronym> file is copied - from <filename>doc/share/misc/docbook.css</filename> when - documents are converted to <acronym>XHTML</acronym>, and is - installed automatically.</para> - </sect2> - </sect1> -</chapter> diff --git a/nl_NL.ISO8859-1/books/fdp-primer/the-website/chapter.xml b/nl_NL.ISO8859-1/books/fdp-primer/the-website/chapter.xml deleted file mode 100644 index b5c617e7d3..0000000000 --- a/nl_NL.ISO8859-1/books/fdp-primer/the-website/chapter.xml +++ /dev/null @@ -1,200 +0,0 @@ -<?xml version="1.0" encoding="iso-8859-1"?> -<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved. - - Redistribution and use in source (SGML DocBook) and 'compiled' forms - (SGML HTML, PDF, PostScript, RTF and so forth) with or without - modification, are permitted provided that the following conditions - are met: - - 1. Redistributions of source code (SGML DocBook) must retain the above - copyright notice, this list of conditions and the following - disclaimer as the first lines of this file unmodified. - - 2. Redistributions in compiled form (transformed to other DTDs, - converted to PDF, PostScript, RTF and other formats) must reproduce - the above copyright notice, this list of conditions and the - following disclaimer in the documentation and/or other materials - provided with the distribution. - - THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR - IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES - OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE - DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT, - INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES - (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR - SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) - HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, - STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN - ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE - POSSIBILITY OF SUCH DAMAGE. - - $FreeBSD$ ---> -<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="the-website"> - <title>The Website</title> - - <para>The &os; web site is part of the &os; documents. Files for - the web site are stored in the - <filename>en_US.ISO8859-1/htdocs</filename> subdirectory of the - document tree directory, <filename>~/doc</filename> in this - example.</para> - - <sect1 xml:id="the-website-env"> - <title>Environment Variables</title> - - <para>Several environment variables control which parts of the the - web site are built or installed, and to which - directories.</para> - - <tip> - <para>The web build system uses &man.make.1;, and considers - variables to be set when they have been defined, even if they - are empty. The examples here show the recommended ways of - defining and using these variables. Setting or defining these - variables with other values or methods might lead to - unexpected surprises.</para> - </tip> - - <variablelist> - <varlistentry xml:id="the-website-env-destdir"> - <term><varname>DESTDIR</varname></term> - - <listitem> - <para>DESTDIR specifies the path where the web site files - are to be installed.</para> - - <para>This variable is best set with &man.env.1; or the user - shell's method of setting environment variables, - <command>setenv</command> for &man.csh.1; or - <command>export</command> for &man.sh.1;.</para> - </listitem> - </varlistentry> - </variablelist> - - <variablelist> - <varlistentry xml:id="the-website-env-englishonly"> - <term><varname>ENGLISH_ONLY</varname></term> - - <listitem> - <para>Default: undefined. Build and include all - translations.</para> - - <para><userinput>ENGLISH_ONLY=yes</userinput>: use only - the English documents and ignore all translations.</para> - </listitem> - </varlistentry> - - <varlistentry xml:id="the-website-env-webonly"> - <term><varname>WEB_ONLY</varname></term> - - <listitem> - <para>Default: undefined. Build both the web site - and all the books and articles.</para> - - <para><userinput>WEB_ONLY=yes</userinput>: build or install - only <acronym>HTML</acronym> pages from the - <filename>en_US.ISO8859-1/htdocs</filename> directory. - Other directories and documents, including books and - articles, will be ignored.</para> - </listitem> - </varlistentry> - - <varlistentry xml:id="the-website-env-weblang"> - <term><varname>WEB_LANG</varname></term> - - <listitem> - <para>Default: undefined. Build and include all the - available languages on the web site.</para> - - <para>Set to a space-separated list of languages to be - included in the build - or install. The formats are the same as the directory - names in the document root directory. For example, to - include the German and French documents:</para> - - <screen><userinput>WEB_LANG="de_DE.ISO8859-1 fr_FR.ISO8859-1"</userinput></screen> - </listitem> - </varlistentry> - </variablelist> - - <para><varname>WEB_ONLY</varname>, <varname>WEB_LANG</varname>, - and <varname>ENGLISH_ONLY</varname> are &man.make.1; variables - and can be set in <filename>/etc/make.conf</filename>, - <filename>Makefile.inc</filename>, as environment variables on - the command line, or in dot files.</para> - </sect1> - - <sect1 xml:id="the-website-build"> - <title>Building and Installing the Web Pages</title> - - <para>Having obtained the documentation and web site source files, - the web site can be built.</para> - - <para>An actual installation of the web site is run as the <systemitem class="username">root</systemitem> - user because the permissions on the web server directory will - not allow files to be installed by an unprivileged user. - For testing, it can be useful to install the files as a normal - user to a temporary directory.</para> - - <para>In these examples, the web site files are built by user - <systemitem class="username">jru</systemitem> in their home - directory, <filename>~/doc</filename>, with a full path of - <filename>/usr/home/jru/doc</filename>.</para> - - <tip> - <para>The web site build uses the <filename>INDEX</filename> - from the Ports Collection and might fail if that file or - <filename>/usr/ports</filename> is not - present. The simplest approach is to install the <link xlink:href="&url.books.handbook;/ports.html#ports-tree">Ports - Collection</link>.</para> - </tip> - - <example xml:id="the-website-examples-build"> - <title>Build the Full Web Site and All Documents</title> - - <para>Build the web site and all documents. The resulting files - are left in the document tree:</para> - - <screen>&prompt.user; <userinput>cd ~/doc/en_US.ISO8859-1/htdocs/</userinput> -&prompt.user; <userinput>make all</userinput></screen> - </example> - - <example xml:id="the-website-examples-buildinstall-englishonly"> - <title>Build Only the Web Site in English</title> - - <para>Build the web site only, in English, as user - <systemitem class="username">jru</systemitem>, and install - the resulting files into <filename>/tmp/www</filename> for - testing:</para> - - <screen>&prompt.user; <userinput>cd ~/doc/en_US.ISO8859-1/htdocs/</userinput> -&prompt.user; <userinput>env DESTDIR=/tmp/www make ENGLISH_ONLY=yes WEB_ONLY=yes all install</userinput></screen> - </example> - - <example xml:id="the-website-examples-buildinstall"> - <title>Build and Install the Web Site</title> - - <para>Build the web site and all documents as user - <systemitem class="username">jru</systemitem>. Install the - resulting files as - <systemitem class="username">root</systemitem> into the - default directory, - <filename>/root/public_html</filename>:</para> - - <screen>&prompt.user; <userinput>cd ~/doc/en_US.ISO8859-1/htdocs</userinput> -&prompt.user; <userinput>make all</userinput> -&prompt.user; <userinput>su -</userinput> -Password: -&prompt.root; <userinput>cd /usr/home/jru/doc/en_US.ISO8859-1/htdocs</userinput> -&prompt.root; <userinput>make install</userinput></screen> - </example> - - <para>The install process does not delete any old or outdated - files that existed previously in the same directory. If a new - copy of the site is built and installed every day, this command - will find and delete all files that have not been updated in - three days:</para> - - <screen>&prompt.root; <userinput>find <replaceable>/usr/local/www</replaceable> -ctime 3 -delete</userinput></screen> - </sect1> -</chapter> diff --git a/nl_NL.ISO8859-1/books/fdp-primer/tools/chapter.xml b/nl_NL.ISO8859-1/books/fdp-primer/tools/chapter.xml deleted file mode 100644 index f911e934ab..0000000000 --- a/nl_NL.ISO8859-1/books/fdp-primer/tools/chapter.xml +++ /dev/null @@ -1,141 +0,0 @@ -<?xml version="1.0" encoding="iso-8859-1"?> -<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved. - - Redistribution and use in source (SGML DocBook) and 'compiled' forms - (SGML, HTML, PDF, PostScript, RTF and so forth) with or without - modification, are permitted provided that the following conditions - are met: - - 1. Redistributions of source code (SGML DocBook) must retain the above - copyright notice, this list of conditions and the following - disclaimer as the first lines of this file unmodified. - - 2. Redistributions in compiled form (transformed to other DTDs, - converted to PDF, PostScript, RTF and other formats) must reproduce - the above copyright notice, this list of conditions and the - following disclaimer in the documentation and/or other materials - provided with the distribution. - - THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR - IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES - OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE - DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT, - INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES - (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR - SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) - HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, - STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN - ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE - POSSIBILITY OF SUCH DAMAGE. - - $FreeBSD$ ---> -<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="tools"> - <title>Tools</title> - - <para>Several software tools are used to manage the FreeBSD - documentation and render it to different output formats. Some of - these tools are required and must be installed before working - through the examples in the following chapters. Some are - optional, adding capabilities or making the job of creating - documentation less demanding.</para> - - <sect1 xml:id="tools-required"> - <title>Required Tools</title> - - <para>Install - <package>textproc/docproj</package> from the - Ports Collection. This <emphasis>meta-port</emphasis> installs - all the applications required to do useful work with the &os; - documentation. Some further notes on particular components are - given below.</para> - - <sect2> - <title><acronym>DTD</acronym>s and - <acronym>Entities</acronym></title> - - <para>&os; documentation uses several Document Type Definitions - (<acronym>DTD</acronym>s) and sets of <acronym>XML</acronym> - entities. These are all installed by the - <package>textproc/docproj</package> - port.</para> - - <variablelist> - <varlistentry> - <term><acronym>XHTML</acronym> <acronym>DTD</acronym> - (<package>textproc/xhtml</package>)</term> - - <listitem> - <para><acronym>XHTML</acronym> is the markup language of - choice for the World Wide Web, and is used throughout - the &os; web site.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>DocBook <acronym>DTD</acronym> (<package>textproc/docbook-xml-450</package>)</term> - - <listitem> - <para>DocBook is designed for marking up technical - documentation. Most of the &os; documentation is - written in DocBook.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>ISO 8879 entities - (<package>textproc/iso8879</package>)</term> - - <listitem> - <para>Character entities from the ISO 8879:1986 standard - used by many <acronym>DTD</acronym>s. Includes named - mathematical symbols, additional characters in the Latin - character set (accents, diacriticals, and so on), and - Greek symbols.</para> - </listitem> - </varlistentry> - </variablelist> - </sect2> - </sect1> - - <sect1 xml:id="tools-optional"> - <title>Optional Tools</title> - - <para>These applications are not required, but can make working on - the documentation easier or add capabilities.</para> - - <sect2> - <title>Software</title> - - <variablelist> - - <varlistentry> - <term><application>Vim</application> - (<package>editors/vim</package>)</term> - - <listitem> - <para>A popular editor for working with - <acronym>XML</acronym> and derived documents, like - DocBook <acronym>XML</acronym>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><application>Emacs</application> or - <application>XEmacs</application> - (<package>editors/emacs</package> or - <package>editors/xemacs</package>)</term> - - <listitem> - <para>Both of these editors include a special mode for - editing documents marked up according to an - <acronym>XML</acronym> <acronym>DTD</acronym>. This - mode includes commands to reduce the amount of typing - needed, and help reduce the possibility of - errors.</para> - </listitem> - </varlistentry> - </variablelist> - </sect2> - </sect1> -</chapter> diff --git a/nl_NL.ISO8859-1/books/fdp-primer/translations/chapter.xml b/nl_NL.ISO8859-1/books/fdp-primer/translations/chapter.xml deleted file mode 100644 index 51f93618dc..0000000000 --- a/nl_NL.ISO8859-1/books/fdp-primer/translations/chapter.xml +++ /dev/null @@ -1,473 +0,0 @@ -<?xml version="1.0" encoding="iso-8859-1"?> -<!-- Copyright (c) 1999 Nik Clayton, All rights reserved. - - Redistribution and use in source (SGML DocBook) and 'compiled' forms - (SGML HTML, PDF, PostScript, RTF and so forth) with or without - modification, are permitted provided that the following conditions - are met: - - 1. Redistributions of source code (SGML DocBook) must retain the above - copyright notice, this list of conditions and the following - disclaimer as the first lines of this file unmodified. - - 2. Redistributions in compiled form (transformed to other DTDs, - converted to PDF, PostScript, RTF and other formats) must reproduce - the above copyright notice, this list of conditions and the - following disclaimer in the documentation and/or other materials - provided with the distribution. - - THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR - IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES - OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE - DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT, - INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES - (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR - SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) - HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, - STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN - ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE - POSSIBILITY OF SUCH DAMAGE. - - $FreeBSD$ ---> -<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="translations"> - <title>Translations</title> - - <para>This is the FAQ for people translating the FreeBSD - documentation (FAQ, Handbook, tutorials, manual pages, and others) - to different languages.</para> - - <para>It is <emphasis>very</emphasis> heavily based on the - translation FAQ from the FreeBSD German Documentation Project, - originally written by Frank Gründer - <email>elwood@mc5sys.in-berlin.de</email> and translated back to - English by Bernd Warken <email>bwarken@mayn.de</email>.</para> - - <para>The FAQ is maintained by the &a.doceng;.</para> - - <qandaset> - <qandaentry> - <question> - <para>What do <phrase>i18n</phrase> and <phrase>l10n</phrase> - mean?</para> - </question> - - <answer> - <para><phrase>i18n</phrase> means - <phrase>internationalization</phrase> and - <phrase>l10n</phrase> means <phrase>localization</phrase>. - They are just a convenient shorthand.</para> - - <para><phrase>i18n</phrase> can be read as <quote>i</quote> - followed by 18 letters, followed by <quote>n</quote>. - Similarly, <phrase>l10n</phrase> is <quote>l</quote> - followed by 10 letters, followed by <quote>n</quote>.</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>Is there a mailing list for translators?</para> - </question> - - <answer> - <para>Yes. Different translation groups have their own - mailing lists. The <link xlink:href="http://www.freebsd.org/docproj/translations.html">list - of translation projects</link> has more information about - the mailing lists and web sites run by each translation - project. In addition there is - <email>freebsd-translators@freebsd.org</email> for general - translation discussion.</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>Are more translators needed?</para> - </question> - - <answer> - <para>Yes. The more people work on translation the faster it - gets done, and the faster changes to the English - documentation are mirrored in the translated - documents.</para> - - <para>You do not have to be a professional translator to be - able to help.</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>What languages do I need to know?</para> - </question> - - <answer> - <para>Ideally, you will have a good knowledge of written - English, and obviously you will need to be fluent in the - language you are translating to.</para> - - <para>English is not strictly necessary. For example, you - could do a Hungarian translation of the FAQ from the Spanish - translation.</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>What software do I need to know?</para> - </question> - - <answer> - <para>It is strongly recommended that you maintain a local - copy of the FreeBSD Subversion repository (at least the - documentation part). This can be done by running:</para> - - <screen>&prompt.user; <userinput>svn checkout https://svn.FreeBSD.org/doc/head/ head</userinput></screen> - - <para><link xlink:href="https://svn.FreeBSD.org/">svn.FreeBSD.org</link> - is a public <literal>SVN</literal> server. - Verify the server - certificate from the list of <link xlink:href="&url.books.handbook;/svn.html#svn-mirrors">Subversion - mirror sites</link>.</para> - - <note> - <para>This will require the <package>devel/subversion</package> package to - be installed.</para> - </note> - - <para>You should be comfortable using - <application>svn</application>. This will allow you to see - what has changed between different versions of the files - that make up the documentation.</para> - - <para>For example, to view the differences between revisions - <literal>r33733</literal> and <literal>r33734</literal> of - <filename>en_US.ISO8859-1/books/fdp-primer/book.xml</filename>, - run:</para> - - <screen>&prompt.user; <userinput>svn diff -r<replaceable>33733</replaceable>:<replaceable>33734</replaceable> en_US.ISO8859-1/books/fdp-primer/book.xml</userinput></screen> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>How do I find out who else might be translating to the - same language?</para> - </question> - - <answer> - <para>The <link xlink:href="http://www.FreeBSD.org/docproj/translations.html">Documentation - Project translations page</link> lists the translation - efforts that are currently known about. If others are - already working on translating documentation to your - language, please do not duplicate their efforts. Instead, - contact them to see how you can help.</para> - - <para>If no one is listed on that page as translating for your - language, then send a message to the &a.doc; in case someone - else is thinking of doing a translation, but has not - announced it yet.</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>No one else is translating to my language. What do I - do?</para> - </question> - - <answer> - <para>Congratulations, you have just started the - <quote>FreeBSD <replaceable>your-language-here</replaceable> - Documentation Translation Project</quote>. Welcome - aboard.</para> - - <para>First, decide whether or not you have got the time to - spare. Since you are the only person working on your - language at the moment it is going to be your responsibility - to publicize your work and coordinate any volunteers that - might want to help you.</para> - - <para>Write an email to the Documentation Project mailing - list, announcing that you are going to translate the - documentation, so the Documentation Project translations - page can be maintained.</para> - - <para>If there is already someone in your country providing - FreeBSD mirroring services you should contact them and ask - if you can have some webspace for your project, and possibly - an email address or mailing list services.</para> - - <para>Then pick a document and start translating. It is best - to start with something fairly small—either the FAQ, - or one of the tutorials.</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>I have translated some documentation, where do I send - it?</para> - </question> - - <answer> - <para>That depends. If you are already working with a - translation team (such as the Japanese team, or the German - team) then they will have their own procedures for handling - submitted documentation, and these will be outlined on their - web pages.</para> - - <para>If you are the only person working on a particular - language (or you are responsible for a translation project - and want to submit your changes back to the FreeBSD project) - then you should send your translation to the FreeBSD project - (see the next question).</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>I am the only person working on translating to this - language, how do I submit my translation?</para> - - <para>or</para> - - <para>We are a translation team, and want to submit - documentation that our members have translated for - us.</para> - </question> - - <answer> - <para>First, make sure your translation is organized properly. - This means that it should drop into the existing - documentation tree and build straight away.</para> - - <para>Currently, the FreeBSD documentation is stored in a top - level directory called <filename>head/</filename>. - Directories below this are named according to the language - code they are written in, as defined in ISO639 - (<filename>/usr/share/misc/iso639</filename> on a version of - FreeBSD newer than 20th January 1999).</para> - - <para>If your language can be encoded in different ways (for - example, Chinese) then there should be directories below - this, one for each encoding format you have provided.</para> - - <para>Finally, you should have directories for each - document.</para> - - <para>For example, a hypothetical Swedish translation might - look like:</para> - - <programlisting>head/ - sv_SE.ISO8859-1/ - Makefile - htdocs/ - docproj/ - books/ - faq/ - Makefile - book.xml</programlisting> - - <para><literal>sv_SE.ISO8859-1</literal> is the name of the - translation, in - <filename><replaceable>lang</replaceable>.<replaceable>encoding</replaceable></filename> - form. Note the two Makefiles, which will be used to build - the documentation.</para> - - <para>Use &man.tar.1; and &man.gzip.1; to compress up your - documentation, and send it to the project.</para> - - <screen>&prompt.user; <userinput>cd doc</userinput> -&prompt.user; <userinput>tar cf swedish-docs.tar sv_SE.ISO8859-1</userinput> -&prompt.user; <userinput>gzip -9 swedish-docs.tar</userinput></screen> - - <para>Put <filename>swedish-docs.tar.gz</filename> somewhere. - If you do not have access to your own webspace (perhaps your - ISP does not let you have any) then you can email - &a.doceng;, and arrange to email the files when it is - convenient.</para> - - <para>Either way, you should use Bugzilla to submit a - report indicating that you have submitted the documentation. - It would be very helpful if you could get other people to - look over your translation and double check it first, since - it is unlikely that the person committing it will be fluent - in the language.</para> - - <para>Someone (probably the Documentation Project Manager, - currently &a.doceng;) will then take your translation and - confirm that it builds. In particular, the following things - will be looked at:</para> - - <orderedlist> - <listitem> - <para>Do all your files use RCS strings (such as - "ID")?</para> - </listitem> - - <listitem> - <para>Does <command>make all</command> in the - <filename>sv_SE.ISO8859-1</filename> directory work - correctly?</para> - </listitem> - - <listitem> - <para>Does <command>make install</command> work - correctly?</para> - </listitem> - </orderedlist> - - <para>If there are any problems then whoever is looking at the - submission will get back to you to work them out.</para> - - <para>If there are no problems your translation will be - committed as soon as possible.</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>Can I include language or country specific text in my - translation?</para> - </question> - - <answer> - <para>We would prefer that you did not.</para> - - <para>For example, suppose that you are translating the - Handbook to Korean, and want to include a section about - retailers in Korea in your Handbook.</para> - - <para>There is no real reason why that information should not - be in the English (or German, or Spanish, or Japanese, or - …) versions as well. It is feasible that an English - speaker in Korea might try to pick up a copy of FreeBSD - whilst over there. It also helps increase FreeBSD's - perceived presence around the globe, which is not a bad - thing.</para> - - <para>If you have country specific information, please submit - it as a change to the English Handbook (using - Bugzilla) and then translate the change back to your - language in the translated Handbook.</para> - - <para>Thanks.</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>How should language specific characters be - included?</para> - </question> - - <answer> - <para>Non-ASCII characters in the documentation should be - included using SGML entities.</para> - - <para>Briefly, these look like an ampersand (&), the name - of the entity, and a semi-colon (;).</para> - - <para>The entity names are defined in ISO8879, which is in the - ports tree as <package>textproc/iso8879</package>.</para> - - <para>A few examples include:</para> - - <segmentedlist> - <segtitle>Entity</segtitle> - - <segtitle>Appearance</segtitle> - - <segtitle>Description</segtitle> - - <seglistitem> - <seg>&eacute;</seg> - <seg>é</seg> - <seg>Small <quote>e</quote> with an acute accent</seg> - </seglistitem> - - <seglistitem> - <seg>&Eacute;</seg> - <seg>É</seg> - <seg>Large <quote>E</quote> with an acute accent</seg> - </seglistitem> - - <seglistitem> - <seg>&uuml;</seg> - <seg>ü</seg> - <seg>Small <quote>u</quote> with an umlaut</seg> - </seglistitem> - </segmentedlist> - - <para>After you have installed the iso8879 port, the files in - <filename>/usr/local/share/xml/iso8879</filename> contain - the complete list.</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>Addressing the reader</para> - </question> - - <answer> - <para>In the English documents, the reader is addressed as - <quote>you</quote>, there is no formal/informal distinction - as there is in some languages.</para> - - <para>If you are translating to a language which does - distinguish, use whichever form is typically used in other - technical documentation in your language. If in doubt, use - a mildly polite form.</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>Do I need to include any additional information in my - translations?</para> - </question> - - <answer> - <para>Yes.</para> - - <para>The header of the English version of each document will - look something like this:</para> - - <programlisting><!-- - The FreeBSD Documentation Project - - $FreeBSD: head/en_US.ISO8859-1/books/faq/book.xml 38674 2012-04-14 13:52:52Z $ ---></programlisting> - - <para>The exact boilerplate may change, but it will always - include a $FreeBSD$ line and the phrase - <literal>The FreeBSD Documentation Project</literal>. - Note that the $FreeBSD part is expanded automatically - by Subversion, so it should be empty (just - <literal>$FreeBSD$</literal>) for new - files.</para> - - <para>Your translated documents should include their own - $FreeBSD$ line, and change the - <literal>FreeBSD Documentation Project</literal> line to - <literal>The FreeBSD <replaceable>language</replaceable> - Documentation Project</literal>.</para> - - <para>In addition, you should add a third line which indicates - which revision of the English text this is based on.</para> - - <para>So, the Spanish version of this file might start:</para> - - <programlisting><!-- - The FreeBSD Spanish Documentation Project - - $FreeBSD: head/es_ES.ISO8859-1/books/faq/book.xml 38826 2012-05-17 19:12:14Z hrs $ - Original revision: r38674 ---></programlisting> - </answer> - </qandaentry> - </qandaset> -</chapter> diff --git a/nl_NL.ISO8859-1/books/fdp-primer/working-copy/chapter.xml b/nl_NL.ISO8859-1/books/fdp-primer/working-copy/chapter.xml deleted file mode 100644 index 2291246250..0000000000 --- a/nl_NL.ISO8859-1/books/fdp-primer/working-copy/chapter.xml +++ /dev/null @@ -1,177 +0,0 @@ -<?xml version="1.0" encoding="iso-8859-1"?> -<!-- Copyright (c) 2013 Warren Block - All rights reserved. - - Redistribution and use in source and binary forms, with or without - modification, are permitted provided that the following conditions - are met: - 1. Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. - 2. Redistributions in binary form must reproduce the above - copyright notice, this list of conditions and the following - disclaimer in the documentation and/or other materials provided - with the distribution. - - THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS - IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT - LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS - FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE - AUTHORS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, - INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES - (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR - SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) - HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN - CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR - OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, - EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - - $FreeBSD$ ---> -<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="working-copy"> - <title>The Working Copy</title> - - <para>The <emphasis>working copy</emphasis> is a copy of the &os; - repository documentation tree downloaded onto the local computer. - Changes are made to the local working copy, tested, and then - submitted as patches to be committed to the main - repository.</para> - - <para>A full copy of the documentation tree can occupy 700 megabytes - of disk space. Allow for a full gigabyte of space to have room - for temporary files and test versions of various output - formats.</para> - - <para><link xlink:href="&url.books.handbook;/svn.html"><application>Subversion</application></link> - is used to manage the &os; documentation files. It is installed - by <package>textproc/docproj</package> as one of - the required applications.</para> - - <sect1 xml:id="working-copy-doc-and-src"> - <title>Documentation and Manual Pages</title> - - <para>&os; documentation is not just books and articles. Manual - pages for all the commands and configuration files are also part - of the documentation, and part of the <acronym>FDP</acronym>'s - territory. Two repositories are involved: - <literal>doc</literal> for the books and articles, and - <literal>base</literal> for the operating system and manual - pages. To edit manual pages, the <literal>base</literal> - repository must be checked out separately.</para> - - <para>Repositories may contain multiple versions of documentation - and source code. New modifications are almost always made only - to the latest version, called <literal>head</literal>.</para> - </sect1> - - <sect1 xml:id="working-copy-choosing-directory"> - <title>Choosing a Directory</title> - - <para>&os; documentation is traditionally stored in - <filename>/usr/doc/</filename>, and system - source code with manual pages in - <filename>/usr/src/</filename>. These - directory trees are relocatable, and users may want to put the - working copies in other locations to avoid interfering with - existing information in the main directories. The examples - that follow use <filename>~/doc</filename> - and <filename>~/src</filename>, both - subdirectories of the user's home directory.</para> - </sect1> - - <sect1 xml:id="working-copy-checking-out"> - <title>Checking Out a Copy</title> - - <para>A download of a working copy from the repository is called - a <emphasis>checkout</emphasis>, and done with - <command>svn checkout</command>. This example checks out a - copy of the latest version (<literal>head</literal>) of - the main documentation tree:</para> - - <screen>&prompt.user; <userinput>svn checkout https://svn.FreeBSD.org/doc/head <replaceable>~/doc</replaceable></userinput></screen> - - <para>A checkout of the source code to work on manual pages is - very similar:</para> - - <screen>&prompt.user; <userinput>svn checkout https://svn.FreeBSD.org/base/head <replaceable>~/src</replaceable></userinput></screen> - </sect1> - - <sect1 xml:id="working-copy-updating"> - <title>Updating a Working Copy</title> - - <para>The documents and files in the &os; repository change daily. - People modify files and commit changes frequently. Even a short - time after an initial checkout, there will already be - differences between the local working copy and the main &os; - repository. To update the local version with the changes that - have been made to the main repository, use - <command>svn update</command> on the directory containing the - local working copy:</para> - - <screen>&prompt.user; <userinput>svn update <replaceable>~/doc</replaceable></userinput></screen> - - <para>Get in the protective habit of using - <command>svn update</command> before editing document files. - Someone else may have edited that file very recently, and the - local working copy will not include the latest changes until it - has been updated. Editing the newest version of a file is much - easier than trying to combine an older, edited local file with - the newer version from the repository.</para> - </sect1> - - <sect1 xml:id="working-copy-revert"> - <title>Reverting Changes</title> - - <para>Sometimes it turns out that changes were - not necessary after all, or the writer just wants to start over. - Files can be <quote>reset</quote> to their unchanged form with - <command>svn revert</command>. For example, to erase the edits - made to <filename>chapter.xml</filename> and reset it to - unmodified form:</para> - - <screen>&prompt.user; <userinput>svn revert chapter.xml</userinput></screen> - </sect1> - - <sect1 xml:id="working-copy-making-diff"> - <title>Making a Diff</title> - - <para>After edits to a file or group of files are completed, the - differences between the local working copy and the version on - the &os; repository must be collected into a single file for - submission. These <emphasis>diff</emphasis> files are produced - by redirecting the output of <command>svn diff</command> into a - file:</para> - - <screen>&prompt.user; <userinput>cd <replaceable>~/doc</replaceable></userinput> -&prompt.user; <userinput>svn diff > <replaceable>doc-fix-spelling.diff</replaceable></userinput></screen> - - <para>Give the file a meaningful name that identifies the - contents. The example above is for spelling fixes to the whole - documentation tree.</para> - - <para>If the diff file is to be submitted with the web - <quote><link xlink:href="https://bugs.FreeBSD.org/bugzilla/enter_bug.cgi">Submit a &os; - problem report</link></quote> interface, add a - <filename>.txt</filename> extension to give the earnest and - simple-minded web form a clue that the contents are plain - text.</para> - - <para>Be careful: <command>svn diff</command> includes all changes - made in the current directory and any subdirectories. If there - are files in the working copy with edits that are not ready to - be submitted yet, provide a list of only the files that are to - be included:</para> - - <screen>&prompt.user; <userinput>cd <replaceable>~/doc</replaceable></userinput> -&prompt.user; <userinput>svn diff <replaceable>disks/chapter.xml printers/chapter.xml</replaceable> > <replaceable>disks-printers.diff</replaceable></userinput></screen> - </sect1> - - <sect1 xml:id="working-copy-subversion-references"> - <title><application>Subversion</application> References</title> - - <para>These examples show very basic usage of - <application>Subversion</application>. More detail is available - in the <link xlink:href="http://svnbook.red-bean.com/">Subversion Book</link> - and the <link xlink:href="http://subversion.apache.org/docs/">Subversion - documentation</link>.</para> - </sect1> -</chapter> diff --git a/nl_NL.ISO8859-1/books/fdp-primer/writing-style/chapter.xml b/nl_NL.ISO8859-1/books/fdp-primer/writing-style/chapter.xml deleted file mode 100644 index 59f0945fdb..0000000000 --- a/nl_NL.ISO8859-1/books/fdp-primer/writing-style/chapter.xml +++ /dev/null @@ -1,592 +0,0 @@ -<?xml version="1.0" encoding="iso-8859-1"?> -<!-- Copyright (c) 1998 Nik Clayton, All rights reserved. - - Redistribution and use in source (SGML DocBook) and 'compiled' forms - (SGML HTML, PDF, PostScript, RTF and so forth) with or without - modification, are permitted provided that the following conditions - are met: - - 1. Redistributions of source code (SGML DocBook) must retain the above - copyright notice, this list of conditions and the following - disclaimer as the first lines of this file unmodified. - - 2. Redistributions in compiled form (transformed to other DTDs, - converted to PDF, PostScript, RTF and other formats) must reproduce - the above copyright notice, this list of conditions and the - following disclaimer in the documentation and/or other materials - provided with the distribution. - - THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR - IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES - OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE - DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT, - INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES - (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR - SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) - HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, - STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN - ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE - POSSIBILITY OF SUCH DAMAGE. - - $FreeBSD$ ---> -<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="writing-style"> - <title>Writing Style</title> - - <sect1 xml:id="writing-style-tips"> - <title>Tips</title> - - <para>Technical documentation can be improved by consistent use of - several principles. Most of these can be classified into three - goals: <emphasis>be clear</emphasis>, - <emphasis>be complete</emphasis>, and - <emphasis>be concise</emphasis>. These goals can conflict with - each other. Good writing consists of a balance between - them.</para> - - <sect2 xml:id="writing-style-be-clear"> - <title>Be Clear</title> - - <para>Clarity is extremely important. The reader may be a - novice, or reading the document in a second language. Strive - for simple, uncomplicated text that clearly explains the - concepts.</para> - - <para>Avoid flowery or embellished speech, jokes, or colloquial - expressions. Write as simply and clearly as possible. Simple - text is easier to understand and translate.</para> - - <para>Keep explanations as short, simple, and clear as possible. - Avoid empty phrases like <quote>in order to</quote>, which - usually just means <quote>to</quote>. Avoid potentially - patronizing words like <quote>basically</quote>. Avoid Latin - terms like <quote>i.e.</quote> or <quote>cf.</quote>, which - may be unknown outside of academic or scientific - groups.</para> - - <para>Write in a formal style. Avoid addressing the reader - as <quote>you</quote>. For example, say - <quote>copy the file to <filename>/tmp</filename></quote> - rather than <quote>you can copy the file to - <filename>/tmp</filename></quote>.</para> - - <para>Give clear, correct, <emphasis>tested</emphasis> examples. - A trivial example is better than no example. A good example - is better yet. Do not give bad examples, identifiable by - apologies or sentences like <quote>but really it should never - be done that way</quote>. Bad examples are worse than no - examples. Give good examples, because <emphasis>even when - warned not to use the example as shown</emphasis>, the - reader will usually just use the example as shown.</para> - - <para>Avoid <emphasis>weasel words</emphasis> like - <quote>should</quote>, <quote>might</quote>, - <quote>try</quote>, or <quote>could</quote>. These words - imply that the speaker is unsure of the facts, and - create doubt in the reader.</para> - - <para>Similarly, give instructions as imperative commands: not - <quote>you should do this</quote>, but merely - <quote>do this</quote>.</para> - </sect2> - - <sect2 xml:id="writing-style-be-complete"> - <title>Be Complete</title> - - <para>Do not make assumptions about the reader's abilities or - skill level. Tell them what they need to know. Give links to - other documents to provide background information without - having to recreate it. Put yourself in the reader's place, - anticipate the questions they will ask, and answer - them.</para> - </sect2> - - <sect2 xml:id="writing-style-be-concise"> - <title>Be Concise</title> - - <para>While features should be documented completely, sometimes - there is so much information that the reader cannot easily - find the specific detail needed. The balance between being - complete and being concise is a challenge. One approach is to - have an introduction, then a <quote>quick start</quote> - section that describes the most common situation, followed by - an in-depth reference section.</para> - </sect2> - </sect1> - - <sect1 xml:id="writing-style-guidelines"> - <title>Guidelines</title> - - <para>To promote consistency between the myriad authors of the - &os; documentation, some guidelines have been drawn up for - authors to follow.</para> - - <variablelist> - <varlistentry> - <term>Use American English Spelling</term> - - <listitem> - <para>There are several variants of English, with different - spellings for the same word. Where spellings differ, use - the American English variant. <quote>color</quote>, not - <quote>colour</quote>, <quote>rationalize</quote>, not - <quote>rationalise</quote>, and so on.</para> - - <note> - <para>The use of British English may be accepted in the - case of a contributed article, however the spelling must - be consistent within the whole document. The other - documents such as books, web site, manual pages, etc. - will have to use American English.</para> - </note> - </listitem> - </varlistentry> - - <varlistentry> - <term>Do not use contractions</term> - - <listitem> - <para>Do not use contractions. Always spell the phrase out - in full. <quote>Don't use contractions</quote> is - wrong.</para> - - <para>Avoiding contractions makes for a more formal tone, is - more precise, and is slightly easier for - translators.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Use the serial comma</term> - - <listitem> - <para>In a list of items within a paragraph, separate each - item from the others with a comma. Separate the last item - from the others with a comma and the word - <quote>and</quote>.</para> - - <para>For example:</para> - - <blockquote> - <para>This is a list of one, two and three items.</para> - </blockquote> - - <para>Is this a list of three items, <quote>one</quote>, - <quote>two</quote>, and <quote>three</quote>, or a list of - two items, <quote>one</quote> and <quote>two and - three</quote>?</para> - - <para>It is better to be explicit and include a serial - comma:</para> - - <blockquote> - <para>This is a list of one, two, and three items.</para> - </blockquote> - </listitem> - </varlistentry> - - <varlistentry> - <term>Avoid redundant phrases</term> - - <listitem> - <para>Do not use redundant phrases. In particular, - <quote>the command</quote>, <quote>the file</quote>, and - <quote>man command</quote> are often redundant.</para> - - <para>For example, commands:</para> - - <informalexample> - <para>Wrong: Use the <command>svn</command> command to - update sources.</para> - </informalexample> - - <informalexample> - <para>Right: Use <command>svn</command> to update - sources.</para> - </informalexample> - - <para>Filenames:</para> - - <informalexample> - <para>Wrong: … in the filename - <filename>/etc/rc.local</filename>…</para> - </informalexample> - - <informalexample> - <para>Right: … in - <filename>/etc/rc.local</filename>…</para> - </informalexample> - - <para>Manual page references (the second example uses - <tag>citerefentry</tag> with the - <literal>&man.csh.1;</literal> entity):.</para> - - <informalexample> - <para>Wrong: See <command>man csh</command> for more - information.</para> - </informalexample> - - <informalexample> - <para>Right: See &man.csh.1;.</para> - </informalexample> - </listitem> - </varlistentry> - - <varlistentry> - <term>Two spaces between sentences</term> - - <listitem> - <para>Always use two spaces between sentences, as it - improves readability and eases use of tools such as - <application>Emacs</application>.</para> - - <para>A period and spaces followed by a capital letter - does not always mark a new sentence, especially in names. - <quote>Jordan K. Hubbard</quote> is a good example. It - has a capital <literal>H</literal> following a period and - a space, and is certainly not a new sentence.</para> - </listitem> - </varlistentry> - </variablelist> - - <para>For more information about writing style, see <link xlink:href="http://www.bartleby.com/141/">Elements of - Style</link>, by William Strunk.</para> - </sect1> - - <sect1 xml:id="writing-style-guide"> - <title>Style Guide</title> - - <para>To keep the source for the documentation consistent when - many different people are editing it, please follow these style - conventions.</para> - - <sect2> - <title>Letter Case</title> - - <para>Tags are entered in lower case, <tag>para</tag>, - <emphasis>not</emphasis> <tag>PARA</tag>.</para> - - <para>Text that appears in SGML contexts is generally written in - upper case, <literal><!ENTITY…></literal>, and - <literal><!DOCTYPE…></literal>, - <emphasis>not</emphasis> - <literal><!entity…></literal> and - <literal><!doctype…></literal>.</para> - </sect2> - - <sect2 xml:id="writing-style-acronyms"> - <title>Acronyms</title> - - <para>Acronyms should be defined the first time they appear in a - document, as in: - <quote>Network Time Protocol (<acronym>NTP</acronym>)</quote>. - After the acronym has been defined, use the acronym alone - unless it makes more sense contextually to use the whole term. - Acronyms are usually defined only once per chapter or per - document.</para> - - <para>All acronyms should be enclosed in - <tag>acronym</tag> tags.</para> - </sect2> - - <sect2 xml:id="writing-style-indentation"> - <title>Indentation</title> - - <para>The first line in each file starts with no indentation, - <emphasis>regardless</emphasis> of the indentation level of - the file which might contain the current file.</para> - - <para>Opening tags increase the indentation level by two spaces. - Closing tags decrease the indentation level by two spaces. - Blocks of eight spaces at the start of a line should be - replaced with a tab. Do not use spaces in front of tabs, and - do not add extraneous whitespace at the end of a line. - Content within elements should be indented by two spaces if - the content runs over more than one line.</para> - - <para>For example, the source for this section looks like - this:</para> - - <programlisting><tag class="starttag">chapter</tag> - <tag class="starttag">title</tag>...<tag class="endtag">title</tag> - - <tag class="starttag">sect1</tag> - <tag class="starttag">title</tag>...<tag class="endtag">title</tag> - - <tag class="starttag">sect2</tag> - <tag class="starttag">title</tag>Indentation<tag class="endtag">title</tag> - - <tag class="starttag">para</tag>The first line in each file starts with no indentation, - <tag class="starttag">emphasis</tag>regardless<tag class="endtag">emphasis</tag> of the indentation level of - the file which might contain the current file.<tag class="endtag">para</tag> - - ... - <tag class="endtag">sect2</tag> - <tag class="endtag">sect1</tag> -<tag class="endtag">chapter</tag></programlisting> - - <para>Tags containing long attributes follow the same - rules. Following the indentation rules in this case helps - editors and writers see which content is inside the - tags:</para> - - <programlisting><tag class="starttag">para</tag>See the <tag class="starttag">link - linkend="gmirror-troubleshooting"</tag>Troubleshooting<tag class="endtag">link</tag> - section if there are problems booting. Powering down and - disconnecting the original <tag class="starttag">filename</tag>ada0<tag class="endtag">filename</tag> disk - will allow it to be kept as an offline backup.<tag class="endtag">para</tag> - -<tag class="starttag">para</tag>It is also possible to journal the boot disk of a &os; - system. Refer to the article <tag class="starttag">link - xlink:href="&url.articles.gjournal-desktop;"</tag>Implementing UFS - Journaling on a Desktop PC<tag class="endtag">link</tag> for detailed - instructions.<tag class="endtag">para</tag></programlisting> - - <para>When an element is too long to fit on the remainder of a - line without wrapping, moving the start tag to the next line - can make the source easier to read. In this example, the - <literal>systemitem</literal> element has been moved to the - next line to avoid wrapping and indenting:</para> - - <programlisting><tag class="starttag">para</tag>With file flags, even - <tag class="starttag">systemitem class="username"</tag>root<tag class="endtag">systemitem</tag> can be - prevented from removing or altering files.<tag class="endtag">para</tag></programlisting> - - <para>Configurations to help various text editors conform to - these guidelines can be found in - <xref linkend="editor-config"/>.</para> - </sect2> - - <sect2 xml:id="writing-style-tag-style"> - <title>Tag Style</title> - - <sect3 xml:id="writing-style-tag-style-spacing"> - <title>Tag Spacing</title> - - <para>Tags that start at the same indent as a previous tag - should be separated by a blank line, and those that are not - at the same indent as a previous tag should not:</para> - - <informalexample> - <programlisting><tag class="starttag">article lang='en'</tag> - <tag class="starttag">articleinfo</tag> - <tag class="starttag">title</tag>NIS<tag class="endtag">title</tag> - - <tag class="starttag">pubdate</tag>October 1999<tag class="endtag">pubdate</tag> - - <tag class="starttag">abstract</tag> - <tag class="starttag">para</tag>... - ... - ...<tag class="endtag">para</tag> - <tag class="endtag">abstract</tag> - <tag class="endtag">articleinfo</tag> - - <tag class="starttag">sect1</tag> - <tag class="starttag">title</tag>...<tag class="endtag">title</tag> - - <tag class="starttag">para</tag>...<tag class="endtag">para</tag> - <tag class="endtag">sect1</tag> - - <tag class="starttag">sect1</tag> - <tag class="starttag">title</tag>...<tag class="endtag">title</tag> - - <tag class="starttag">para</tag>...<tag class="endtag">para</tag> - <tag class="endtag">sect1</tag> -<tag class="endtag">article</tag></programlisting> - </informalexample> - </sect3> - - <sect3 xml:id="writing-style-tag-style-separating"> - <title>Separating Tags</title> - - <para>Tags like <tag>itemizedlist</tag> which will - always have further tags inside them, and in fact do not - take character data themselves, are always on a line by - themselves.</para> - - <para>Tags like <tag>para</tag> and - <tag>term</tag> do not need other tags to contain - normal character data, and their contents begin immediately - after the tag, <emphasis>on the same line</emphasis>.</para> - - <para>The same applies to when these two types of tags - close.</para> - - <para>This leads to an obvious problem when mixing these - tags.</para> - - <para>When a starting tag which cannot contain character data - directly follows a tag of the type that requires other tags - within it to use character data, they are on separate lines. - The second tag should be properly indented.</para> - - <para>When a tag which can contain character data closes - directly after a tag which cannot contain character data - closes, they co-exist on the same line.</para> - </sect3> - </sect2> - - <sect2 xml:id="writing-style-whitespace-changes"> - <title>Whitespace Changes</title> - - <para><emphasis>Do not commit changes - to content at the same time as changes to - formatting</emphasis>.</para> - - <para>When content and whitespace changes are kept separate, - translation teams can easily see whether a change was content - that must be translated or only whitespace.</para> - - <para>For example, if two sentences have been added to a - paragraph so that the line lengths now go - over 80 columns, first commit the change with the too-long - lines. Then fix the line wrapping, and commit this - second change. In the commit message for the second change, - indicate that this is a whitespace-only change that can be - ignored by translators.</para> - </sect2> - - <sect2 xml:id="writing-style-nonbreaking-space"> - <title>Non-Breaking Space</title> - - <para>Avoid line breaks in places where they look ugly or make - it difficult to follow a sentence. Line breaks depend on the - width of the chosen output medium. In particular, viewing the - HTML documentation with a text browser can lead to badly - formatted paragraphs like the next one:</para> - - <literallayout class="monospaced">Data capacity ranges from 40 MB to 15 -GB. Hardware compression …</literallayout> - - <para>The general entity <literal>&nbsp;</literal> prohibits - line breaks between parts belonging together. Use - non-breaking spaces in the following places:</para> - - <itemizedlist> - <listitem> - <para>between numbers and units:</para> - <programlisting>57600&nbsp;bps</programlisting> - </listitem> - - <listitem> - <para>between program names and version numbers:</para> - <programlisting>&os;&nbsp;9.2</programlisting> - </listitem> - - <listitem> - <para>between multiword names (use with caution when - applying this to more than 3-4 word names like - <quote>The &os; Brazilian Portuguese Documentation - Project</quote>):</para> - <programlisting><![CDATA[Sun Microsystems]]></programlisting> - </listitem> - </itemizedlist> - </sect2> - </sect1> - - <sect1 xml:id="writing-style-word-list"> - <title>Word List</title> - - <para>This list of words shows the correct spelling and - capitalization when used in &os; documentation. If a word is - not on this list, ask about it on the &a.doc;.</para> - - <informaltable frame="none" pgwide="0"> - <tgroup cols="3"> - <thead> - <row> - <entry>Word</entry> - <entry>XML Code</entry> - <entry>Notes</entry> - </row> - </thead> - - <tbody> - <row> - <entry>CD-ROM</entry> - - <entry><tag class="starttag">acronym</tag><literal>CD-ROM</literal><tag class="endtag">acronym</tag></entry> - </row> - - <row> - <entry>DoS (Denial of Service)</entry> - <entry><tag class="starttag">acronym</tag><literal>DoS</literal><tag class="endtag">acronym</tag></entry> - </row> - - <row> - <entry>email</entry> - </row> - - <row> - <entry>file system</entry> - </row> - - <row> - <entry>IPsec</entry> - </row> - - <row> - <entry>Internet</entry> - </row> - - <row> - <entry>manual page</entry> - </row> - - <row> - <entry>mail server</entry> - </row> - - <row> - <entry>name server</entry> - </row> - - <row> - <entry>Ports Collection</entry> - </row> - - <row> - <entry>read-only</entry> - </row> - - <row> - <entry>Soft Updates</entry> - </row> - - <row> - <entry>stdin</entry> - <entry><tag class="starttag">varname</tag>stdin<tag class="endtag">varname</tag></entry> - </row> - - <row> - <entry>stdout</entry> - <entry><tag class="starttag">varname</tag>stdout<tag class="endtag">varname</tag></entry> - </row> - - <row> - <entry>stderr</entry> - <entry><tag class="starttag">varname</tag>stderr<tag class="endtag">varname</tag></entry> - </row> - - <row> - <entry>Subversion</entry> - - <entry><tag class="starttag">application</tag><literal>Subversion</literal><tag class="endtag">application</tag></entry> - <entry>Do not refer to the Subversion application as - <literal>SVN</literal> in upper case. To refer to the - command, use <tag class="starttag">command</tag><literal>svn</literal><tag class="endtag">command</tag>.</entry> - </row> - - <row> - <entry>&unix;</entry> - <entry><literal>&unix;</literal></entry> - </row> - - <row> - <entry>web server</entry> - </row> - </tbody> - </tgroup> - </informaltable> - </sect1> -</chapter> diff --git a/nl_NL.ISO8859-1/books/fdp-primer/xhtml-markup/chapter.xml b/nl_NL.ISO8859-1/books/fdp-primer/xhtml-markup/chapter.xml deleted file mode 100644 index a0c6907d5b..0000000000 --- a/nl_NL.ISO8859-1/books/fdp-primer/xhtml-markup/chapter.xml +++ /dev/null @@ -1,600 +0,0 @@ -<?xml version="1.0" encoding="iso-8859-1"?> -<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved. - - Redistribution and use in source (SGML DocBook) and 'compiled' forms - (SGML HTML, PDF, PostScript, RTF and so forth) with or without - modification, are permitted provided that the following conditions - are met: - - 1. Redistributions of source code (SGML DocBook) must retain the above - copyright notice, this list of conditions and the following - disclaimer as the first lines of this file unmodified. - - 2. Redistributions in compiled form (transformed to other DTDs, - converted to PDF, PostScript, RTF and other formats) must reproduce - the above copyright notice, this list of conditions and the - following disclaimer in the documentation and/or other materials - provided with the distribution. - - THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR - IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES - OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE - DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT, - INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES - (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR - SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) - HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, - STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN - ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE - POSSIBILITY OF SUCH DAMAGE. - - $FreeBSD$ ---> -<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="xhtml-markup"> - <title><acronym>XHTML</acronym> Markup</title> - - <sect1 xml:id="xhtml-markup-introduction"> - <title>Introduction</title> - - <para>This chapter describes usage of the <acronym>XHTML</acronym> - markup language used for the &os; web site.</para> - - <para><acronym>XHTML</acronym> is the <acronym>XML</acronym> - version of the HyperText Markup Language, the markup language of - choice on the World Wide Web. More information can be found at - <uri xlink:href="http://www.w3.org/">http://www.w3.org/</uri>.</para> - - <para><acronym>XHTML</acronym> is used to mark up pages on the - &os; web site. It is usually not used to mark up other - documentation, since DocBook offers a far richer set of elements - from which to choose. Consequently, <acronym>XHTML</acronym> - pages will normally only be encountered when writing for the web - site.</para> - - <para><acronym>HTML</acronym> has gone through a number of - versions. The <acronym>XML</acronym>-compliant version - described here is called <acronym>XHTML</acronym>. The latest - widespread version is <acronym>XHTML</acronym> 1.0, available in - both <emphasis>strict</emphasis> and - <emphasis>transitional</emphasis> variants.</para> - - <para>The <acronym>XHTML</acronym> <acronym>DTDs</acronym> are - available from the Ports Collection in - <package>textproc/xhtml</package>. They are - automatically installed by the <package>textproc/docproj</package> port.</para> - - <note> - <para>This is <emphasis>not</emphasis> an exhaustive list of - elements, since that would just repeat the documentation for - <acronym>XHTML</acronym>. The aim is to list those elements - most commonly used. Please post questions about elements or - uses not covered here to the &a.doc;.</para> - </note> - - <note> - <title>Inline Versus Block</title> - - <para>In the remainder of this document, when describing - elements, <emphasis>inline</emphasis> means that the element - can occur within a block element, and does not cause a line - break. A <emphasis>block</emphasis> element, by comparison, - will cause a line break (and other processing) when it is - encountered.</para> - </note> - </sect1> - - <sect1 xml:id="xhtml-markup-fpi"> - <title>Formal Public Identifier (<acronym>FPI</acronym>)</title> - - <para>There are a number of <acronym>XHTML</acronym> - <acronym>FPI</acronym>s, depending upon the version, or - <emphasis>level</emphasis> of <acronym>XHTML</acronym> to which - a document conforms. Most <acronym>XHTML</acronym> documents on - the &os; web site comply with the transitional version of - <acronym>XHTML</acronym> 1.0.</para> - - <programlisting>PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"</programlisting> - </sect1> - - <sect1 xml:id="xhtml-markup-sectional-elements"> - <title>Sectional Elements</title> - - <para>An <acronym>XHTML</acronym> document is normally split into - two sections. The first section, called the - <emphasis>head</emphasis>, contains meta-information about the - document, such as its title, the name of the author, the parent - document, and so on. The second section, the - <emphasis>body</emphasis>, contains content that will be - displayed to the user.</para> - - <para>These sections are indicated with <tag>head</tag> - and <tag>body</tag> elements respectively. These - elements are contained within the top-level - <tag>html</tag> element.</para> - - <example> - <title>Normal <acronym>XHTML</acronym> Document - Structure</title> - - <programlisting><tag class="starttag">html xmlns="http://www.w3.org/1999/xhtml"</tag> - <tag class="starttag">head</tag> - <tag class="starttag">title</tag><replaceable>The Document's Title</replaceable><tag class="endtag">title</tag> - <tag class="endtag">head</tag> - - <tag class="starttag">body</tag> - - … - - <tag class="endtag">body</tag> -<tag class="endtag">html</tag></programlisting> - </example> - </sect1> - - <sect1 xml:id="xhtml-markup-block-elements"> - <title>Block Elements</title> - - <sect2 xml:id="xhtml-markup-block-elements-headings"> - <title>Headings</title> - - <para><acronym>XHTML</acronym> has tags to denote headings in - the document at up to six different levels.</para> - - <para>The largest and most prominent heading is - <tag>h1</tag>, then <tag>h2</tag>, - continuing down to <tag>h6</tag>.</para> - - <para>The element's content is the text of the heading.</para> - - <example> - <title><tag>h1</tag>, <tag>h2</tag>, - and Other Header Tags</title> - - <para>Usage:</para> - - <programlisting><tag class="starttag">h1</tag>First section<tag class="endtag">h1</tag> - -<!-- Document introduction goes here --> - -<tag class="starttag">h2</tag>This is the heading for the first section<tag class="endtag">h2</tag> - -<!-- Content for the first section goes here --> - -<tag class="starttag">h3</tag>This is the heading for the first sub-section<tag class="endtag">h3</tag> - -<!-- Content for the first sub-section goes here --> - -<tag class="starttag">h2</tag>This is the heading for the second section<tag class="endtag">h2</tag> - -<!-- Content for the second section goes here --></programlisting> - </example> - - <para>Generally, an <acronym>XHTML</acronym> page should have - one first level heading (<tag>h1</tag>). This can - contain many second level headings (<tag>h2</tag>), - which can in turn contain many third level headings. Do not - leave gaps in the numbering.</para> - </sect2> - - <sect2 xml:id="xhtml-markup-block-elements-paragraphs"> - <title>Paragraphs</title> - - <para><acronym>XHTML</acronym> supports a single paragraph - element, <tag>p</tag>.</para> - - <example> - <title><tag>p</tag> Example</title> - - <para>Usage:</para> - - <programlisting><tag class="starttag">p</tag>This is a paragraph. It can contain just about any - other element.<tag class="endtag">p</tag></programlisting> - </example> - </sect2> - - <sect2 xml:id="xhtml-markup-block-elements-block-quotations"> - <title>Block Quotations</title> - - <para>A block quotation is an extended quotation from another - document that will appear in a separate paragraph.</para> - - <example> - <title><tag>blockquote</tag> Example</title> - - <para>Usage:</para> - - <programlisting><tag class="starttag">p</tag>A small excerpt from the US Constitution:<tag class="endtag">p</tag> - -<tag class="starttag">blockquote</tag>We the People of the United States, in Order to form - a more perfect Union, establish Justice, insure domestic - Tranquility, provide for the common defence, promote the general - Welfare, and secure the Blessings of Liberty to ourselves and our - Posterity, do ordain and establish this Constitution for the - United States of America.<tag class="endtag">blockquote</tag></programlisting> - </example> - </sect2> - - <sect2 xml:id="xhtml-markup-block-elements-lists"> - <title>Lists</title> - - <para><acronym>XHTML</acronym> can present the user with three - types of lists: ordered, unordered, and definition.</para> - - <para>Entries in an ordered list will be numbered, while entries - in an unordered list will be preceded by bullet points. - Definition lists have two sections for each entry. The first - section is the term being defined, and the second section is - the definition.</para> - - <para>Ordered lists are indicated by the <tag>ol</tag> - element, unordered lists by the <tag>ul</tag> - element, and definition lists by the <tag>dl</tag> - element.</para> - - <para>Ordered and unordered lists contain listitems, indicated - by the <tag>li</tag> element. A listitem can - contain textual content, or it may be further wrapped in one - or more <tag>p</tag> elements.</para> - - <para>Definition lists contain definition terms - (<tag>dt</tag>) and definition descriptions - (<tag>dd</tag>). A definition term can only contain - inline elements. A definition description can contain other - block elements.</para> - - <example> - <title><tag>ul</tag> and - <tag>ol</tag> Example</title> - - <para>Usage:</para> - - <programlisting><tag class="starttag">p</tag>An unordered list. Listitems will probably be - preceded by bullets.<tag class="endtag">p</tag> - -<tag class="starttag">ul</tag> - <tag class="starttag">li</tag>First item<tag class="endtag">li</tag> - - <tag class="starttag">li</tag>Second item<tag class="endtag">li</tag> - - <tag class="starttag">li</tag>Third item<tag class="endtag">li</tag> -<tag class="endtag">ul</tag> - -<tag class="starttag">p</tag>An ordered list, with list items consisting of multiple - paragraphs. Each item (note: not each paragraph) will be - numbered.<tag class="endtag">p</tag> - -<tag class="starttag">ol</tag> - <tag class="starttag">li</tag><tag class="starttag">p</tag>This is the first item. It only has one paragraph.<tag class="endtag">p</tag><tag class="endtag">li</tag> - - <tag class="starttag">li</tag><tag class="starttag">p</tag>This is the first paragraph of the second item.<tag class="endtag">p</tag> - - <tag class="starttag">p</tag>This is the second paragraph of the second item.<tag class="endtag">p</tag><tag class="endtag">li</tag> - - <tag class="starttag">li</tag><tag class="starttag">p</tag>This is the first and only paragraph of the third - item.<tag class="endtag">p</tag><tag class="endtag">li</tag> -<tag class="endtag">ol</tag></programlisting> - </example> - - <example> - <title>Definition Lists with <tag>dl</tag></title> - - <para>Usage:</para> - - <programlisting><tag class="starttag">dl</tag> - <tag class="starttag">dt</tag>Term 1<tag class="endtag">dt</tag> - - <tag class="starttag">dd</tag><tag class="starttag">p</tag>Paragraph 1 of definition 1.<tag class="endtag">p</tag> - - <tag class="starttag">p</tag>Paragraph 2 of definition 1.<tag class="endtag">p</tag><tag class="endtag">dd</tag> - - <tag class="starttag">dt</tag>Term 2<tag class="endtag">dt</tag> - - <tag class="starttag">dd</tag><tag class="starttag">p</tag>Paragraph 1 of definition 2.<tag class="endtag">p</tag><tag class="endtag">dd</tag> - - <tag class="starttag">dt</tag>Term 3<tag class="endtag">dt</tag> - - <tag class="starttag">dd</tag><tag class="starttag">p</tag>Paragraph 1 of definition 3.<tag class="endtag">p</tag><tag class="endtag">dd</tag> -<tag class="endtag">dl</tag></programlisting> - </example> - </sect2> - - <sect2 xml:id="xhtml-markup-block-elements-preformatted-text"> - <title>Pre-formatted Text</title> - - <para>Pre-formatted text is shown to the user exactly as it is - in the file. Text is shown in a fixed font. Multiple spaces - and line breaks are shown exactly as they are in the - file.</para> - - <para>Wrap pre-formatted text in the <tag>pre</tag> - element.</para> - - <example> - <title><tag>pre</tag> Example</title> - - <para>For example, the <tag>pre</tag> tags could be - used to mark up an email message:</para> - - <programlisting><tag class="starttag">pre</tag> From: nik@FreeBSD.org - To: freebsd-doc@FreeBSD.org - Subject: New documentation available - - There is a new copy of my primer for contributors to the FreeBSD - Documentation Project available at - - &lt;URL:http://people.FreeBSD.org/~nik/primer/index.html&gt; - - Comments appreciated. - - N<tag class="endtag">pre</tag></programlisting> - - <para>Keep in mind that <literal><</literal> and - <literal>&</literal> still are recognized as special - characters in pre-formatted text. This is why the example - shown had to use <literal>&lt;</literal> instead of - <literal><</literal>. For consistency, - <literal>&gt;</literal> was used in place of - <literal>></literal>, too. Watch out for the special - characters that may appear in text copied from a plain-text - source, like an email message or program code.</para> - </example> - </sect2> - - <sect2 xml:id="xhtml-markup-block-elements-tables"> - <title>Tables</title> - - <para>Mark up tabular information using the - <tag>table</tag> element. A table consists of one or - more table rows (<tag>tr</tag>), each containing one - or more cells of table data (<tag>td</tag>). Each - cell can contain other block elements, such as paragraphs or - lists. It can also contain another table (this nesting can - repeat indefinitely). If the cell only contains one paragraph - then the <tag>p</tag>element is not needed.</para> - - <example> - <title>Simple Use of <tag>table</tag></title> - - <para>Usage:</para> - - <programlisting><tag class="starttag">p</tag>This is a simple 2x2 table.<tag class="endtag">p</tag> - -<tag class="starttag">table</tag> - <tag class="starttag">tr</tag> - <tag class="starttag">td</tag>Top left cell<tag class="endtag">td</tag> - - <tag class="starttag">td</tag>Top right cell<tag class="endtag">td</tag> - <tag class="endtag">tr</tag> - - <tag class="starttag">tr</tag> - <tag class="starttag">td</tag>Bottom left cell<tag class="endtag">td</tag> - - <tag class="starttag">td</tag>Bottom right cell<tag class="endtag">td</tag> - <tag class="endtag">tr</tag> -<tag class="endtag">table</tag></programlisting> - </example> - - <para>A cell can span multiple rows and columns by adding the - <tag class="attribute">rowspan</tag> or - <tag class="attribute">colspan</tag> attributes with - values for the number of rows or columns to be spanned.</para> - - <example> - <title>Using - <tag class="attribute">rowspan</tag></title> - - <para>Usage:</para> - - <programlisting><tag class="starttag">p</tag>One tall thin cell on the left, two short cells next to - it on the right.<tag class="endtag">p</tag> - -<tag class="starttag">table</tag> - <tag class="starttag">tr</tag> - <tag class="starttag">td rowspan="2"</tag>Long and thin<tag class="endtag">td</tag> - <tag class="endtag">tr</tag> - - <tag class="starttag">tr</tag> - <tag class="starttag">td</tag>Top cell<tag class="endtag">td</tag> - - <tag class="starttag">td</tag>Bottom cell<tag class="endtag">td</tag> - <tag class="endtag">tr</tag> -<tag class="endtag">table</tag></programlisting> - </example> - - <example> - <title>Using - <tag class="attribute">colspan</tag></title> - - <para>Usage:</para> - - <programlisting><tag class="starttag">p</tag>One long cell on top, two short cells below it.<tag class="endtag">p</tag> - -<tag class="starttag">table</tag> - <tag class="starttag">tr</tag> - <tag class="starttag">td colspan="2"</tag>Top cell<tag class="endtag">td</tag> - <tag class="endtag">tr</tag> - - <tag class="starttag">tr</tag> - <tag class="starttag">td</tag>Bottom left cell<tag class="endtag">td</tag> - - <tag class="starttag">td</tag>Bottom right cell<tag class="endtag">td</tag> - <tag class="endtag">tr</tag> -<tag class="endtag">table</tag></programlisting> - </example> - - <example> - <title>Using <tag class="attribute">rowspan</tag> and - <tag class="attribute">colspan</tag> - Together</title> - - <para>Usage:</para> - - <programlisting><tag class="starttag">p</tag>On a 3x3 grid, the top left block is a 2x2 set of - cells merged into one. The other cells are normal.<tag class="endtag">p</tag> - -<tag class="starttag">table</tag> - <tag class="starttag">tr</tag> - <tag class="starttag">td colspan="2" rowspan="2"</tag>Top left large cell<tag class="endtag">td</tag> - - <tag class="starttag">td</tag>Top right cell<tag class="endtag">td</tag> - <tag class="endtag">tr</tag> - - <tag class="starttag">tr</tag> - <!-- Because the large cell on the left merges into - this row, the first <td> will occur on its - right --> - - <tag class="starttag">td</tag>Middle right cell<tag class="endtag">td</tag> - <tag class="endtag">tr</tag> - - <tag class="starttag">tr</tag> - <tag class="starttag">td</tag>Bottom left cell<tag class="endtag">td</tag> - - <tag class="starttag">td</tag>Bottom middle cell<tag class="endtag">td</tag> - - <tag class="starttag">td</tag>Bottom right cell<tag class="endtag">td</tag> - <tag class="endtag">tr</tag> -<tag class="endtag">table</tag></programlisting> - </example> - </sect2> - </sect1> - - <sect1 xml:id="xhtml-markup-inline-elements"> - <title>In-line Elements</title> - - <sect2 xml:id="xhtml-markup-inline-elements-emphasizing-information"> - <title>Emphasizing Information</title> - - <para>Two levels of emphasis are available in - <acronym>XHTML</acronym>, <tag>em</tag> and - <tag>strong</tag>. <tag>em</tag> is for a - normal level of emphasis and <tag>strong</tag> - indicates stronger emphasis.</para> - - <para><tag>em</tag> is typically rendered in italic - and <tag>strong</tag> is rendered in bold. This is - not always the case, and should not be relied upon. According - to best practices, web pages only hold structural and - semantical information, and stylesheets are later applied to - them. Think of semantics, not formatting, when using these - tags.</para> - - <example> - <title><tag>em</tag> and - <tag>strong</tag> Example</title> - - <para>Usage:</para> - - <programlisting><tag class="starttag">p</tag><tag class="starttag">em</tag>This<tag class="endtag">em</tag> has been emphasized, while - <tag class="starttag">strong</tag>this<tag class="endtag">strong</tag> has been strongly emphasized.<tag class="endtag">p</tag></programlisting> - </example> - </sect2> - - <sect2 xml:id="xhtml-markup-inline-elements-fixed-pitch-text"> - <title>Indicating Fixed-Pitch Text</title> - - <para>Content that should be rendered in a fixed pitch - (typewriter) typeface is tagged with <tag>tt</tag> - (for <quote>teletype</quote>).</para> - - <example> - <title><tag>tt</tag> Example</title> - - <para>Usage:</para> - - <programlisting><tag class="starttag">p</tag>Many system settings are stored in - <tag class="starttag">tt</tag>/etc<tag class="endtag">tt</tag>.<tag class="endtag">p</tag></programlisting> - </example> - </sect2> - - <sect2 xml:id="xhtml-markup-inline-elements-links"> - <title>Links</title> - - <note> - <para>Links are also inline elements.</para> - </note> - - <sect3 xml:id="xhtml-markup-inline-elements-linking"> - <title>Linking to Other Documents on the Web</title> - - <para>A link points to the <acronym>URL</acronym> of a - document on the web. The link is indicated with - <tag>a</tag>, and the - <tag class="attribute">href</tag> attribute contains - the <acronym>URL</acronym> of the target document. The - content of the element becomes the link, indicated to the - user by showing it in a different color or with an - underline.</para> - - <example> - <title>Using - <tag class="starttag">a href="..."</tag></title> - - <para>Usage:</para> - - <programlisting><tag class="starttag">p</tag>More information is available at the - <tag class="starttag">a href="http://www.&os;.org/"</tag>&os; web site<tag class="endtag">a</tag>.<tag class="endtag">p</tag></programlisting> - </example> - - <para>This link always takes the user to the top of the linked - document.</para> - </sect3> - - <sect3 xml:id="xhtml-markup-inline-elements-specific-parts"> - <title>Linking to Specific Parts of Documents</title> - - <para>To link to a specific point within a document, that - document must include an <emphasis>anchor</emphasis> at the - desired point. Anchors are included by setting the - <tag class="attribute">id</tag> attribute of an - element to a name. This example creates an anchor by - setting the <tag class="attribute">id</tag> - attribute of a <tag class="element">p</tag> - element.</para> - - <example> - <title>Creating an Anchor</title> - - <para>Usage:</para> - - <programlisting><tag class="starttag">p id="samplepara"</tag>This paragraph can be referenced - in other links with the name <tag class="starttag">tt</tag>samplepara<tag class="endtag">tt</tag>.<tag class="endtag">p</tag></programlisting> - </example> - - <para>Links to anchors are similar to plain links, but include - a <literal>#</literal> symbol and the anchor's - <acronym>ID</acronym> at the end of the - <acronym>URL</acronym>.</para> - - <example> - <title>Linking to a Named Part of a Different - Document</title> - - <para>The <literal>samplepara</literal> example is part of a - document called <filename>foo.html</filename>. A link to - that specific paragraph in the document is constructed in - this example.</para> - - <programlisting><tag class="starttag">p</tag>More information can be found in the - <tag class="starttag">a href="foo.html#samplepara"</tag>sample paragraph<tag class="endtag">a</tag> of - <tag class="starttag">tt</tag>foo.html<tag class="endtag">tt</tag>.<tag class="endtag">p</tag></programlisting> - </example> - - <para>To link to a named anchor within the same document, omit - the document's <acronym>URL</acronym>, and just use the - <literal>#</literal> symbol followed by the name of the - anchor.</para> - - <example> - <title>Linking to a Named Part of the Same Document</title> - - <para>The <literal>samplepara</literal> example - resides in this document. To link to it:</para> - - <programlisting><tag class="starttag">p</tag>More information can be found in the - <tag class="starttag">a href="#samplepara"</tag>sample paragraph<tag class="endtag">a</tag> of this - document.<tag class="endtag">p</tag></programlisting> - </example> - </sect3> - </sect2> - </sect1> -</chapter> diff --git a/nl_NL.ISO8859-1/books/fdp-primer/xml-primer/chapter.xml b/nl_NL.ISO8859-1/books/fdp-primer/xml-primer/chapter.xml deleted file mode 100644 index f076dfc2b5..0000000000 --- a/nl_NL.ISO8859-1/books/fdp-primer/xml-primer/chapter.xml +++ /dev/null @@ -1,1433 +0,0 @@ -<?xml version="1.0" encoding="iso-8859-1"?> -<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved. - - Redistribution and use in source (SGML DocBook) and 'compiled' forms - (SGML, HTML, PDF, PostScript, RTF and so forth) with or without - modification, are permitted provided that the following conditions - are met: - - 1. Redistributions of source code (SGML DocBook) must retain the above - copyright notice, this list of conditions and the following - disclaimer as the first lines of this file unmodified. - - 2. Redistributions in compiled form (transformed to other DTDs, - converted to PDF, PostScript, RTF and other formats) must reproduce - the above copyright notice, this list of conditions and the - following disclaimer in the documentation and/or other materials - provided with the distribution. - - THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR - IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES - OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE - DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT, - INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES - (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR - SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) - HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, - STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN - ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE - POSSIBILITY OF SUCH DAMAGE. - - $FreeBSD$ ---> -<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="xml-primer"> - <title>XML Primer</title> - - <para>Most <acronym>FDP</acronym> documentation is written with - markup languages based on <acronym>XML</acronym>. This chapter - explains what that means, how to read and understand the - documentation source, and the <acronym>XML</acronym> techniques - used.</para> - - <para>Portions of this section were inspired by Mark Galassi's - <link xlink:href="http://www.galassi.org/mark/mydocs/docbook-intro/docbook-intro.html">Get - Going With DocBook</link>.</para> - - <sect1 xml:id="xml-primer-overview"> - <title>Overview</title> - - <para>In the original days of computers, electronic text was - simple. There were a few character sets like - <acronym>ASCII</acronym> or <acronym>EBCDIC</acronym>, but that - was about it. Text was text, and what you saw really was what - you got. No frills, no formatting, no intelligence.</para> - - <para>Inevitably, this was not enough. When text is in a - machine-usable format, machines are expected to be able to use - and manipulate it intelligently. Authors want to indicate that - certain phrases should be emphasized, or added to a glossary, or - made into hyperlinks. Filenames could be shown in a - <quote>typewriter</quote> style font for viewing on screen, but - as <quote>italics</quote> when printed, or any of a myriad of - other options for presentation.</para> - - <para>It was once hoped that Artificial Intelligence (AI) would - make this easy. The computer would read the document and - automatically identify key phrases, filenames, text that the - reader should type in, examples, and more. Unfortunately, real - life has not happened quite like that, and computers still - require assistance before they can meaningfully process - text.</para> - - <para>More precisely, they need help identifying what is what. - Consider this text:</para> - - <blockquote> - <para>To remove <filename>/tmp/foo</filename>, use - &man.rm.1;.</para> - - <screen>&prompt.user; <userinput>rm /tmp/foo</userinput></screen> - </blockquote> - - <para>It is easy to see which parts are filenames, which are - commands to be typed in, which parts are references to manual - pages, and so on. But the computer processing the document - cannot. For this we need markup.</para> - - <para><quote>Markup</quote> is commonly used to describe - <quote>adding value</quote> or <quote>increasing cost</quote>. - The term takes on both these meanings when applied to text. - Markup is additional text included in the document, - distinguished from the document's content in some way, so that - programs that process the document can read the markup and use - it when making decisions about the document. Editors can hide - the markup from the user, so the user is not distracted by - it.</para> - - <para>The extra information stored in the markup - <emphasis>adds value</emphasis> to the document. Adding the - markup to the document must typically be done by a - person—after all, if computers could recognize the text - sufficiently well to add the markup then there would be no need - to add it in the first place. This - <emphasis>increases the cost</emphasis> (the effort required) to - create the document.</para> - - <para>The previous example is actually represented in this - document like this:</para> - - <programlisting><tag class="starttag">para</tag>To remove <tag class="starttag">filename</tag>/tmp/foo<tag class="endtag">filename</tag>, use &man.rm.1;.<tag class="endtag">para</tag> - -<tag class="starttag">screen</tag>&prompt.user; <tag class="starttag">userinput</tag>rm /tmp/foo<tag class="endtag">userinput</tag><tag class="endtag">screen</tag></programlisting> - - <para>The markup is clearly separate from the content.</para> - - <para>Markup languages define what the markup means and how it - should be interpreted.</para> - - <para>Of course, one markup language might not be enough. A - markup language for technical documentation has very different - requirements than a markup language that is intended for cookery - recipes. This, in turn, would be very different from a markup - language used to describe poetry. What is really needed is a - first language used to write these other markup languages. A - <emphasis>meta markup language</emphasis>.</para> - - <para>This is exactly what the eXtensible Markup - Language (<acronym>XML</acronym>) is. Many markup languages - have been written in <acronym>XML</acronym>, including the two - most used by the <acronym>FDP</acronym>, - <acronym>XHTML</acronym> and DocBook.</para> - - <para>Each language definition is more properly called a grammar, - vocabulary, schema or Document Type Definition - (<acronym>DTD</acronym>). There are various languages to - specify an <acronym>XML</acronym> grammar, or - <emphasis>schema</emphasis>.</para> - - <para xml:id="xml-primer-validating">A schema is a - <emphasis>complete</emphasis> specification of all the elements - that are allowed to appear, the order in which they should - appear, which elements are mandatory, which are optional, and so - forth. This makes it possible to write an - <acronym>XML</acronym> <emphasis>parser</emphasis> which reads - in both the schema and a document which claims to conform to the - schema. The parser can then confirm whether or not all the - elements required by the vocabulary are in the document in the - right order, and whether there are any errors in the markup. - This is normally referred to as - <quote>validating the document</quote>.</para> - - <note> - <para>Validation confirms that the choice of - elements, their ordering, and so on, conforms to that listed - in the grammar. It does <emphasis>not</emphasis> check - whether <emphasis>appropriate</emphasis> markup has been used - for the content. If all the filenames in a document were - marked up as function names, the parser would not flag this as - an error (assuming, of course, that the schema defines - elements for filenames and functions, and that they are - allowed to appear in the same place).</para> - </note> - - <para>Most contributions to the Documentation - Project will be content marked up in either - <acronym>XHTML</acronym> or DocBook, rather than alterations to - the schemas. For this reason, this book will not touch on how - to write a vocabulary.</para> - </sect1> - - <sect1 xml:id="xml-primer-elements"> - <title>Elements, Tags, and Attributes</title> - - <para>All the vocabularies written in <acronym>XML</acronym> share - certain characteristics. This is hardly surprising, as the - philosophy behind <acronym>XML</acronym> will inevitably show - through. One of the most obvious manifestations of this - philosophy is that of <emphasis>content</emphasis> and - <emphasis>elements</emphasis>.</para> - - <para>Documentation, whether it is a single web page, or a lengthy - book, is considered to consist of content. This content is then - divided and further subdivided into elements. The purpose of - adding markup is to name and identify the boundaries of these - elements for further processing.</para> - - <para>For example, consider a typical book. At the very top - level, the book is itself an element. This <quote>book</quote> - element obviously contains chapters, which can be considered to - be elements in their own right. Each chapter will contain more - elements, such as paragraphs, quotations, and footnotes. Each - paragraph might contain further elements, identifying content - that was direct speech, or the name of a character in the - story.</para> - - <para>It may be helpful to think of this as - <quote>chunking</quote> content. At the very top level is one - chunk, the book. Look a little deeper, and there are more - chunks, the individual chapters. These are chunked further into - paragraphs, footnotes, character names, and so on.</para> - - <para>Notice how this differentiation between different elements - of the content can be made without resorting to any - <acronym>XML</acronym> terms. It really is surprisingly - straightforward. This could be done with a highlighter pen and - a printout of the book, using different colors to indicate - different chunks of content.</para> - - <para>Of course, we do not have an electronic highlighter pen, so - we need some other way of indicating which element each piece of - content belongs to. In languages written in - <acronym>XML</acronym> (<acronym>XHTML</acronym>, DocBook, et - al) this is done by means of <emphasis>tags</emphasis>.</para> - - <para>A tag is used to identify where a particular element starts, - and where the element ends. <emphasis>The tag is not part of - the element itself</emphasis>. Because each grammar was - normally written to mark up specific types of information, each - one will recognize different elements, and will therefore have - different names for the tags.</para> - - <para>For an element called - <replaceable>element-name</replaceable> the start tag will - normally look like <tag class="starttag"><replaceable>element-name</replaceable></tag>. - The corresponding closing tag for this element is <tag class="endtag"><replaceable>element-name</replaceable></tag>.</para> - - <example> - <title>Using an Element (Start and End Tags)</title> - - <para><acronym>XHTML</acronym> has an element for indicating - that the content enclosed by the element is a paragraph, - called <tag>p</tag>.</para> - - <programlisting><tag class="starttag">p</tag>This is a paragraph. It starts with the start tag for - the 'p' element, and it will end with the end tag for the 'p' - element.<tag class="endtag">p</tag> - -<tag class="starttag">p</tag>This is another paragraph. But this one is much shorter.<tag class="endtag">p</tag></programlisting> - </example> - - <para>Some elements have no content. For example, in - <acronym>XHTML</acronym>, a horizontal line can be included in - the document. For these <quote>empty</quote> elements, - <acronym>XML</acronym> introduced a shorthand form that is - completely equivalent to the two-tag version:</para> - - <example> - <title>Using an Element Without Content</title> - - <para><acronym>XHTML</acronym> has an element for indicating a - horizontal rule, called <tag>hr</tag>. This element - does not wrap content, so it looks like this:</para> - - <programlisting><tag class="starttag">p</tag>One paragraph.<tag class="endtag">p</tag> -<tag class="starttag">hr</tag><tag class="endtag">hr</tag> - -<tag class="starttag">p</tag>This is another paragraph. A horizontal rule separates this - from the previous paragraph.<tag class="endtag">p</tag></programlisting> - - <para>The shorthand version consists of a single tag:</para> - - <programlisting><tag class="starttag">p</tag>One paragraph.<tag class="endtag">p</tag> -<tag class="emptytag">hr</tag> - -<tag class="starttag">p</tag>This is another paragraph. A horizontal rule separates this - from the previous paragraph.<tag class="endtag">p</tag></programlisting> - </example> - - <para>As shown above, elements can contain other elements. In the - book example earlier, the book element contained all the chapter - elements, which in turn contained all the paragraph elements, - and so on.</para> - - <example> - <title>Elements Within Elements; <tag>em</tag></title> - - <programlisting><tag class="starttag">p</tag>This is a simple <tag class="starttag">em</tag>paragraph<tag class="endtag">em</tag> where some - of the <tag class="starttag">em</tag>words<tag class="endtag">em</tag> have been <tag class="starttag">em</tag>emphasized<tag class="endtag">em</tag>.<tag class="endtag">p</tag></programlisting> - </example> - - <para>The grammar consists of rules that describe which elements - can contain other elements, and exactly what they can - contain.</para> - - <important> - <para>People often confuse the terms tags and elements, and use - the terms as if they were interchangeable. They are - not.</para> - - <para>An element is a conceptual part of your document. An - element has a defined start and end. The tags mark where the - element starts and ends.</para> - - <para>When this document (or anyone else knowledgeable about - <acronym>XML</acronym>) refers to - <quote>the <tag class="starttag">p</tag> tag</quote> - they mean the literal text consisting of the three characters - <literal><</literal>, <literal>p</literal>, and - <literal>></literal>. But the phrase - <quote>the <tag>p</tag> element</quote> refers to the - whole element.</para> - - <para>This distinction <emphasis>is</emphasis> very subtle. But - keep it in mind.</para> - </important> - - <para>Elements can have attributes. An attribute has a name and a - value, and is used for adding extra information to the element. - This might be information that indicates how the content should - be rendered, or might be something that uniquely identifies that - occurrence of the element, or it might be something else.</para> - - <para>An element's attributes are written - <emphasis>inside</emphasis> the start tag for that element, and - take the form - <literal><replaceable>attribute-name</replaceable>="<replaceable>attribute-value</replaceable>"</literal>.</para> - - <para>In <acronym>XHTML</acronym>, the <tag>p</tag> - element has an attribute called - <tag class="attribute">align</tag>, which suggests an - alignment (justification) for the paragraph to the program - displaying the <acronym>XHTML</acronym>.</para> - - <para>The <tag class="attribute">align</tag> attribute can - take one of four defined values, <literal>left</literal>, - <literal>center</literal>, <literal>right</literal> and - <literal>justify</literal>. If the attribute is not specified - then the default is <literal>left</literal>.</para> - - <example> - <title>Using an Element with an Attribute</title> - - <programlisting><tag class="starttag">p align="left"</tag>The inclusion of the align attribute - on this paragraph was superfluous, since the default is left.<tag class="endtag">p</tag> - -<tag class="starttag">p align="center"</tag>This may appear in the center.<tag class="endtag">p</tag></programlisting> - </example> - - <para>Some attributes only take specific values, such as - <literal>left</literal> or <literal>justify</literal>. Others - allow any value.</para> - - <example> - <title>Single Quotes Around Attributes</title> - - <programlisting><tag class="starttag">p align='right'</tag>I am on the right!<tag class="endtag">p</tag></programlisting> - </example> - - <para>Attribute values in <acronym>XML</acronym> must be enclosed - in either single or double quotes. Double quotes are - traditional. Single quotes are useful when the attribute value - contains double quotes.</para> - - <para>Information about attributes, elements, and tags is stored - in catalog files. The Documentation Project uses standard - DocBook catalogs and includes additional catalogs for - &os;-specific features. Paths to the catalog files are defined - in an environment variable so they can be found by the document - build tools.</para> - - <sect2> - <title>To Do…</title> - - <para>Before running the examples in this document, install - <package>textproc/docproj</package> from - the &os; Ports Collection. This is a - <emphasis>meta-port</emphasis> that downloads and installs - the standard programs and supporting files needed by the - Documentation Project. &man.csh.1; users must use - <command>rehash</command> for the shell to recognize new - programs after they have been installed, or log out - and then log back in again.</para> - - <procedure> - <step> - <para>Create <filename>example.xml</filename>, and enter - this text:</para> - - <programlisting><tag class="starttag">!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"</tag> - -<tag class="starttag">html xmlns="http://www.w3.org/1999/xhtml"</tag> - <tag class="starttag">head</tag> - <tag class="starttag">title</tag>An Example XHTML File<tag class="endtag">title</tag> - <tag class="endtag">head</tag> - - <tag class="starttag">body</tag> - <tag class="starttag">p</tag>This is a paragraph containing some text.<tag class="endtag">p</tag> - - <tag class="starttag">p</tag>This paragraph contains some more text.<tag class="endtag">p</tag> - - <tag class="starttag">p align="right"</tag>This paragraph might be right-justified.<tag class="endtag">p</tag> - <tag class="endtag">body</tag> -<tag class="endtag">html</tag></programlisting> - </step> - - <step> - <para>Try to validate this file using an - <acronym>XML</acronym> parser.</para> - - <para><package>textproc/docproj</package> - includes the <command>xmllint</command> - <link linkend="xml-primer-validating">validating - parser</link>.</para> - - <para>Use <command>xmllint</command> to validate the - document:</para> - - <screen>&prompt.user; <userinput>xmllint --valid --noout example.xml</userinput></screen> - - <para><command>xmllint</command> returns without displaying - any output, showing that the document validated - successfully.</para> - </step> - - <step> - <para>See what happens when required elements are omitted. - Delete the line with the - <tag class="starttag">title</tag> and - <tag class="endtag">title</tag> tags, and re-run - the validation.</para> - - <screen>&prompt.user; <userinput>xmllint --valid --noout example.xml</userinput> -example.xml:5: element head: validity error : Element head content does not follow the DTD, expecting ((script | style | meta | link | object | isindex)* , ((title , (script | style | meta | link | object | isindex)* , (base , (script | style | meta | link | object | isindex)*)?) | (base , (script | style | meta | link | object | isindex)* , title , (script | style | meta | link | object | isindex)*))), got ()</screen> - - <para>This shows that the validation error comes from the - <replaceable>fifth</replaceable> line of the - <replaceable>example.xml</replaceable> file and that the - content of the <tag class="starttag">head</tag> is - the part which does not follow the rules of the - <acronym>XHTML</acronym> grammar.</para> - - <para>Then <command>xmllint</command> shows the line where - the error was found and marks the exact character position - with a <literal>^</literal> sign.</para> - </step> - - <step> - <para>Replace the <tag>title</tag> element.</para> - </step> - </procedure> - </sect2> - </sect1> - - <sect1 xml:id="xml-primer-doctype-declaration"> - <title>The DOCTYPE Declaration</title> - - <para>The beginning of each document can specify the name of the - <acronym>DTD</acronym> to which the document conforms. This - DOCTYPE declaration is used by <acronym>XML</acronym> parsers to - identify the <acronym>DTD</acronym> and ensure that the document - does conform to it.</para> - - <para>A typical declaration for a document written to conform with - version 1.0 of the <acronym>XHTML</acronym> - <acronym>DTD</acronym> looks like this:</para> - - <programlisting><tag class="starttag">!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"</tag></programlisting> - - <para>That line contains a number of different components.</para> - - <variablelist> - <varlistentry> - <term><literal><!</literal></term> - - <listitem> - <para>The <emphasis>indicator</emphasis> shows - this is an <acronym>XML</acronym> declaration.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>DOCTYPE</literal></term> - - <listitem> - <para>Shows that this is an <acronym>XML</acronym> - declaration of the document type.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>html</literal></term> - - <listitem> - <para>Names the first - <link linkend="xml-primer-elements">element</link> that - will appear in the document.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" - "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"</literal></term> - - <listitem> - <para>Lists the Formal Public Identifier - (<acronym>FPI</acronym>) - <indexterm> - <primary>Formal Public Identifier</primary> - </indexterm> - for the <acronym>DTD</acronym> to which this document - conforms. The <acronym>XML</acronym> parser uses this to - find the correct <acronym>DTD</acronym> when processing - this document.</para> - - <para><literal>PUBLIC</literal> is not a part of the - <acronym>FPI</acronym>, but indicates to the - <acronym>XML</acronym> processor how to find the - <acronym>DTD</acronym> referenced in the - <acronym>FPI</acronym>. Other ways of telling the - <acronym>XML</acronym> parser how to find the - <acronym>DTD</acronym> are shown <link linkend="xml-primer-fpi-alternatives">later</link>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"</literal></term> - - <listitem> - <para>A local filename or a <acronym>URL</acronym> to find - the <acronym>DTD</acronym>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>></literal></term> - - <listitem> - <para>Ends the declaration and returns to the - document.</para> - </listitem> - </varlistentry> - </variablelist> - - <sect2> - <title>Formal Public Identifiers - (<acronym>FPI</acronym>s)</title> - - <indexterm significance="preferred"> - <primary>Formal Public Identifier</primary> - </indexterm> - - <note> - <para>It is not necessary to know this, but it is useful - background, and might help debug problems when the - <acronym>XML</acronym> processor can not locate the - <acronym>DTD</acronym>.</para> - </note> - - <para><acronym>FPI</acronym>s must follow a specific - syntax:</para> - - <programlisting>"<replaceable>Owner</replaceable>//<replaceable>Keyword</replaceable> <replaceable>Description</replaceable>//<replaceable>Language</replaceable>"</programlisting> - - <variablelist> - <varlistentry> - <term><replaceable>Owner</replaceable></term> - - <listitem> - <para>The owner of the <acronym>FPI</acronym>.</para> - - <para>The beginning of the string identifies the owner of - the <acronym>FPI</acronym>. For example, the - <acronym>FPI</acronym> - <literal>"ISO 8879:1986//ENTITIES Greek - Symbols//EN"</literal> lists - <literal>ISO 8879:1986</literal> as being the owner for - the set of entities for Greek symbols. - <acronym>ISO</acronym> 8879:1986 is the International - Organization for Standardization - (<acronym>ISO</acronym>) number for the - <acronym>SGML</acronym> standard, the predecessor (and a - superset) of <acronym>XML</acronym>.</para> - - <para>Otherwise, this string will either look like - <literal>-//<replaceable>Owner</replaceable></literal> - or - <literal>+//<replaceable>Owner</replaceable></literal> - (notice the only difference is the leading - <literal>+</literal> or <literal>-</literal>).</para> - - <para>If the string starts with <literal>-</literal> then - the owner information is unregistered, with a - <literal>+</literal> identifying it as - registered.</para> - - <para><acronym>ISO</acronym> 9070:1991 defines how - registered names are generated. It might be derived - from the number of an <acronym>ISO</acronym> - publication, an <acronym>ISBN</acronym> code, or an - organization code assigned according to - <acronym>ISO</acronym> 6523. Additionally, a - registration authority could be created in order to - assign registered names. The <acronym>ISO</acronym> - council delegated this to the American National - Standards Institute (<acronym>ANSI</acronym>).</para> - - <para>Because the &os; Project has not been registered, - the owner string is <literal>-//&os;</literal>. As seen - in the example, the <acronym>W3C</acronym> are not a - registered owner either.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><replaceable>Keyword</replaceable></term> - - <listitem> - <para>There are several keywords that indicate the type of - information in the file. Some of the most common - keywords are <literal>DTD</literal>, - <literal>ELEMENT</literal>, <literal>ENTITIES</literal>, - and <literal>TEXT</literal>. <literal>DTD</literal> is - used only for <acronym>DTD</acronym> files, - <literal>ELEMENT</literal> is usually used for - <acronym>DTD</acronym> fragments that contain only - entity or element declarations. <literal>TEXT</literal> - is used for <acronym>XML</acronym> content (text and - tags).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><replaceable>Description</replaceable></term> - - <listitem> - <para>Any description can be given for the contents - of this file. This may include version numbers or any - short text that is meaningful and unique for the - <acronym>XML</acronym> system.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><replaceable>Language</replaceable></term> - - <listitem> - <para>An <acronym>ISO</acronym> two-character code that - identifies the native language for the file. - <literal>EN</literal> is used for English.</para> - </listitem> - </varlistentry> - </variablelist> - - <sect3> - <title><filename>catalog</filename> Files</title> - - <para>With the syntax above, an <acronym>XML</acronym> - processor needs to have some way of turning the - <acronym>FPI</acronym> into the name of the file containing - the <acronym>DTD</acronym>. A catalog file (typically - called <filename>catalog</filename>) contains lines that map - <acronym>FPI</acronym>s to filenames. For example, if the - catalog file contained the line:</para> - -<!-- XXX: mention XML catalog or maybe replace this totally and only cover XML catalog --> - - <programlisting>PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "1.0/transitional.dtd"</programlisting> - - <para>The <acronym>XML</acronym> processor knows that the - <acronym>DTD</acronym> is called - <filename>transitional.dtd</filename> in the - <filename>1.0</filename> subdirectory of the directory that - held <filename>catalog</filename>.</para> - - <para>Examine the contents of - <filename>/usr/local/share/xml/dtd/xhtml/catalog.xml</filename>. - This is the catalog file for the <acronym>XHTML</acronym> - <acronym>DTD</acronym>s that were installed as part of the - <package>textproc/docproj</package> port.</para> - </sect3> - </sect2> - - <sect2 xml:id="xml-primer-fpi-alternatives"> - <title>Alternatives to <acronym>FPI</acronym>s</title> - - <para>Instead of using an <acronym>FPI</acronym> to indicate the - <acronym>DTD</acronym> to which the document conforms (and - therefore, which file on the system contains the - <acronym>DTD</acronym>), the filename can be explicitly - specified.</para> - - <para>The syntax is slightly different:</para> - - <programlisting><tag class="starttag">!DOCTYPE html SYSTEM "/path/to/file.dtd"</tag></programlisting> - - <para>The <literal>SYSTEM</literal> keyword indicates that the - <acronym>XML</acronym> processor should locate the - <acronym>DTD</acronym> in a system specific fashion. This - typically (but not always) means the <acronym>DTD</acronym> - will be provided as a filename.</para> - - <para>Using <acronym>FPI</acronym>s is preferred for reasons of - portability. If the <literal>SYSTEM</literal> identifier is - used, then the <acronym>DTD</acronym> must be provided and - kept in the same location for everyone.</para> - </sect2> - </sect1> - - <sect1 xml:id="xml-primer-xml-escape"> - <title>Escaping Back to <acronym>XML</acronym></title> - - <para>Some of the underlying <acronym>XML</acronym> syntax can be - useful within documents. For example, comments can be included - in the document, and will be ignored by the parser. Comments - are entered using <acronym>XML</acronym> syntax. Other uses for - <acronym>XML</acronym> syntax will be shown later.</para> - - <para><acronym>XML</acronym> sections begin with a - <literal><!</literal> tag and end with a - <literal>></literal>. These sections contain instructions - for the parser rather than elements of the document. Everything - between these tags is <acronym>XML</acronym> syntax. The - <link linkend="xml-primer-doctype-declaration">DOCTYPE - declaration</link> shown earlier is an example of - <acronym>XML</acronym> syntax included in the document.</para> - - </sect1> - - <sect1 xml:id="xml-primer-comments"> - <title>Comments</title> - - <para>Comments are an <acronym>XML</acronym> construct, and are - normally only valid inside a <acronym>DTD</acronym>. However, - as <xref linkend="xml-primer-xml-escape"/> shows, it is possible - to use <acronym>XML</acronym> syntax within the document.</para> - - <para>The delimiter for XML comments is the string - <quote><literal>--</literal></quote>. The first occurrence of - this string opens a comment, and the second closes it.</para> - - <example> - <title><acronym>XML</acronym> Generic Comment</title> - - <programlisting><!-- This is inside the comment --> - -<!-- This is another comment --> - -<!-- This is one way - of doing multiline comments --> - -<!-- This is another way of -- - -- doing multiline comments --></programlisting> - </example> - - <para><acronym>XHTML</acronym> users may be familiar with different - rules for comments. In particular, it is often believed that - the string <literal><!--</literal> opens a comment, and it is - only closed by <literal>--></literal>.</para> - - <para>This is <emphasis>not</emphasis> correct. Many web browsers - have broken <acronym>XHTML</acronym> parsers, and will accept - incorrect input as valid. However, the <acronym>XML</acronym> - parsers used by the Documentation Project are more strict, and - will reject documents with that error.</para> - - <example> - <title>Erroneous <acronym>XML</acronym> Comments</title> - - <programlisting><!-- This is in the comment -- - - THIS IS OUTSIDE THE COMMENT! - - -- back inside the comment --></programlisting> - - <para>The <acronym>XML</acronym> parser will treat this as - though it were actually:</para> - - <programlisting><!THIS IS OUTSIDE THE COMMENT></programlisting> - - <para>That is not valid <acronym>XML</acronym>, and may give - confusing error messages.</para> - </example> - - <sect2> - <title>To Do…</title> - - <procedure> - <step> - <para>Add some comments to - <filename>example.xml</filename>, and check that the file - still validates using <command>xmllint</command>.</para> - </step> - - <step> - <para>Add some invalid comments to - <filename>example.xml</filename>, and see the error - messages that <command>xmllint</command> gives when it - encounters an invalid comment.</para> - </step> - </procedure> - </sect2> - </sect1> - - <sect1 xml:id="xml-primer-entities"> - <title>Entities</title> - - <para>Entities are a mechanism for assigning names to chunks of - content. As an <acronym>XML</acronym> parser processes a - document, any entities it finds are replaced by the content of - the entity.</para> - - <para>This is a good way to have re-usable, easily changeable - chunks of content in <acronym>XML</acronym> documents. It is - also the only way to include one marked up file inside another - using <acronym>XML</acronym>.</para> - - <para>There are two types of entities for two different - situations: <emphasis>general entities</emphasis> and - <emphasis>parameter entities</emphasis>.</para> - - <sect2 xml:id="xml-primer-general-entities"> - <title>General Entities</title> - - <para>General entities are used to assign names to reusable - chunks of text. These entities can only be used in the - document. They cannot be used in an - <acronym>XML</acronym> context.</para> - - <para>To include the text of a general entity in the document, - include - <literal>&<replaceable>entity-name</replaceable>;</literal> - in the text. For example, consider a general entity called - <literal>current.version</literal> which expands to the - current version number of a product. To use it in the - document, write:</para> - - <programlisting><tag class="starttag">para</tag>The current version of our product is - &current.version;.<tag class="endtag">para</tag></programlisting> - - <para>When the version number changes, edit the definition of - the general entity, replacing the value. Then reprocess the - document.</para> - - <para>General entities can also be used to enter characters that - could not otherwise be included in an <acronym>XML</acronym> - document. For example, <literal><</literal> and - <literal>&</literal> cannot normally appear in an - <acronym>XML</acronym> document. The <acronym>XML</acronym> - parser sees the <literal><</literal> symbol as the start of - a tag. Likewise, when the <literal>&</literal> symbol is - seen, the next text is expected to be an entity name.</para> - - <para>These symbols can be included by using two predefined - general entities: <literal>&lt;</literal> and - <literal>&amp;</literal>.</para> - - <para>General entities can only be defined within an - <acronym>XML</acronym> context. Such definitions are usually - done immediately after the DOCTYPE declaration.</para> - - <example> - <title>Defining General Entities</title> - - <programlisting><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" -"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [ -<!ENTITY current.version "3.0-RELEASE"> -<!ENTITY last.version "2.2.7-RELEASE"> -]></programlisting> - - <para>The DOCTYPE declaration has been extended by adding a - square bracket at the end of the first line. The two - entities are then defined over the next two lines, the - square bracket is closed, and then the DOCTYPE declaration - is closed.</para> - - <para>The square brackets are necessary to indicate that the - DTD indicated by the DOCTYPE declaration is being - extended.</para> - </example> - </sect2> - - <sect2 xml:id="xml-primer-parameter-entities"> - <title>Parameter Entities</title> - - <para>Parameter entities, like - <link linkend="xml-primer-general-entities">general - entities</link>, are used to assign names to reusable chunks - of text. But parameter entities can only be used within an - <link linkend="xml-primer-xml-escape">XML - context</link>.</para> - - <para>Parameter entity definitions are similar to those for - general entities. However, parameter entries are included - with - <literal>%<replaceable>entity-name</replaceable>;</literal>. - The definition also includes the <literal>%</literal> between - the <literal>ENTITY</literal> keyword and the name of the - entity.</para> - - <para>For a mnemonic, think - <quote><emphasis>P</emphasis>arameter entities use the - <emphasis>P</emphasis>ercent symbol</quote>.</para> - - <example> - <title>Defining Parameter Entities</title> - - <programlisting><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" -"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [ -<!ENTITY % param.some "some"> -<!ENTITY % param.text "text"> -<!ENTITY % param.new "%param.some more %param.text"> - -<!-- %param.new now contains "some more text" --> -]></programlisting> - </example> - </sect2> - - <sect2> - <title>To Do…</title> - - <procedure> - <step> - <para>Add a general entity to - <filename>example.xml</filename>.</para> - - <programlisting><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" -"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [ -<!ENTITY version "1.1"> -]> - -<tag class="starttag">html xmlns="http://www.w3.org/1999/xhtml"</tag> - <tag class="starttag">head</tag> - <tag class="starttag">title</tag>An Example XHTML File<tag class="endtag">title</tag> - <tag class="endtag">head</tag> - - <!-- There may be some comments in here as well --> - - <tag class="starttag">body</tag> - <tag class="starttag">p</tag>This is a paragraph containing some text.<tag class="endtag">p</tag> - - <tag class="starttag">p</tag>This paragraph contains some more text.<tag class="endtag">p</tag> - - <tag class="starttag">p align="right"</tag>This paragraph might be right-justified.<tag class="endtag">p</tag> - - <tag class="starttag">p</tag>The current version of this document is: &version;<tag class="endtag">p</tag> - <tag class="endtag">body</tag> -<tag class="endtag">html</tag></programlisting> - </step> - - <step> - <para>Validate the document using - <command>xmllint</command>.</para> - </step> - - <step> - <para>Load <filename>example.xml</filename> into a web - browser. It may have to be copied to - <filename>example.html</filename> before the browser - recognizes it as an <acronym>XHTML</acronym> - document.</para> - - <para>Older browsers with simple parsers may not render this - file as expected. The entity reference - <literal>&version;</literal> may not be replaced by - the version number, or the <acronym>XML</acronym> context - closing <literal>]></literal> may not be recognized and - instead shown in the output.</para> - </step> - - <step> - <para>The solution is to <emphasis>normalize</emphasis> the - document with an <acronym>XML</acronym> normalizer. The - normalizer reads valid <acronym>XML</acronym> and writes - equally valid <acronym>XML</acronym> which has been - transformed in some way. One way the normalizer - transforms the input is by expanding all the entity - references in the document, replacing the entities with - the text that they represent.</para> - - <para><command>xmllint</command> can be used for this. It - also has an option to drop the initial - <acronym>DTD</acronym> section so that the closing - <literal>]></literal> does not confuse browsers:</para> - - <screen>&prompt.user; <userinput>xmllint --noent --dropdtd example.xml > example.html</userinput></screen> - - <para>A normalized copy of the document with entities - expanded is produced in <filename>example.html</filename>, - ready to load into a web browser.</para> - </step> - </procedure> - </sect2> - </sect1> - - <sect1 xml:id="xml-primer-include"> - <title>Using Entities to Include Files</title> - - <para>Both - <link linkend="xml-primer-general-entities">general</link> and - <link linkend="xml-primer-parameter-entities">parameter</link> - entities are particularly useful for including one file inside - another.</para> - - <sect2 xml:id="xml-primer-include-using-gen-entities"> - <title>Using General Entities to Include Files</title> - - <para>Consider some content for an <acronym>XML</acronym> book - organized into files, one file per chapter, called - <filename>chapter1.xml</filename>, - <filename>chapter2.xml</filename>, and so forth, with a - <filename>book.xml</filename> that will contain these - chapters.</para> - - <para>In order to use the contents of these files as the values - for entities, they are declared with the - <literal>SYSTEM</literal> keyword. This directs the - <acronym>XML</acronym> parser to include the contents of the - named file as the value of the entity.</para> - - <example> - <title>Using General Entities to Include Files</title> - - <programlisting><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" -"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [ -<!ENTITY chapter.1 SYSTEM "chapter1.xml"> -<!ENTITY chapter.2 SYSTEM "chapter2.xml"> -<!ENTITY chapter.3 SYSTEM "chapter3.xml"> -<!-- And so forth --> -]> - -<tag class="starttag">html xmlns="http://www.w3.org/1999/xhtml"</tag> - <!-- Use the entities to load in the chapters --> - - &chapter.1; - &chapter.2; - &chapter.3; -<tag class="endtag">html</tag></programlisting> - </example> - - <warning> - <para>When using general entities to include other files - within a document, the files being included - (<filename>chapter1.xml</filename>, - <filename>chapter2.xml</filename>, and so on) - <emphasis>must not</emphasis> start with a DOCTYPE - declaration. This is a syntax error because entities are - low-level constructs and they are resolved before any - parsing happens.</para> - </warning> - </sect2> - - <sect2> - <title>Using Parameter Entities to Include Files</title> - - <para>Parameter entities can only be used inside an - <acronym>XML</acronym> context. Including a file in an - <acronym>XML</acronym> context can be used - to ensure that general entities are reusable.</para> - - <para>Suppose that there are many chapters in the document, and - these chapters were reused in two different books, each book - organizing the chapters in a different fashion.</para> - - <para>The entities could be listed at the top of each book, but - that quickly becomes cumbersome to manage.</para> - - <para>Instead, place the general entity definitions inside one - file, and use a parameter entity to include that file within - the document.</para> - - <example> - <title>Using Parameter Entities to Include Files</title> - - <para>Place the entity definitions in a separate file - called <filename>chapters.ent</filename> and - containing this text:</para> - - <programlisting><!ENTITY chapter.1 SYSTEM "chapter1.xml"> -<!ENTITY chapter.2 SYSTEM "chapter2.xml"> -<!ENTITY chapter.3 SYSTEM "chapter3.xml"></programlisting> - - <para>Create a parameter entity to refer to the contents - of the file. Then use the parameter entity to load the file - into the document, which will then make all the general - entities available for use. Then use the general entities - as before:</para> - - <programlisting><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" -"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [ -<!-- Define a parameter entity to load in the chapter general entities --> -<!ENTITY % chapters SYSTEM "chapters.ent"> - -<!-- Now use the parameter entity to load in this file --> -%chapters; -]> - -<tag class="starttag">html xmlns="http://www.w3.org/1999/xhtml"</tag> - &chapter.1; - &chapter.2; - &chapter.3; -<tag class="endtag">html</tag></programlisting> - </example> - </sect2> - - <sect2> - <title>To Do…</title> - - <sect3> - <title>Use General Entities to Include Files</title> - - <procedure> - <step> - <para>Create three files, <filename>para1.xml</filename>, - <filename>para2.xml</filename>, and - <filename>para3.xml</filename>.</para> - - <para>Put content like this in each file:</para> - - <programlisting><tag class="starttag">p</tag>This is the first paragraph.<tag class="endtag">p</tag></programlisting> - </step> - - <step> - <para>Edit <filename>example.xml</filename> so that it - looks like this:</para> - - <programlisting><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" -"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [ -<!ENTITY version "1.1"> -<!ENTITY para1 SYSTEM "para1.xml"> -<!ENTITY para2 SYSTEM "para2.xml"> -<!ENTITY para3 SYSTEM "para3.xml"> -]> - -<tag class="starttag">html xmlns="http://www.w3.org/1999/xhtml"</tag> - <tag class="starttag">head</tag> - <tag class="starttag">title</tag>An Example XHTML File<tag class="endtag">title</tag> - <tag class="endtag">head</tag> - - <tag class="starttag">body</tag> - <tag class="starttag">p</tag>The current version of this document is: &version;<tag class="endtag">p</tag> - - &para1; - &para2; - &para3; - <tag class="endtag">body</tag> -<tag class="endtag">html</tag></programlisting> - </step> - - <step> - <para>Produce <filename>example.html</filename> by - normalizing <filename>example.xml</filename>.</para> - - <screen>&prompt.user; <userinput>xmllint --dropdtd --noent example.xml > example.html</userinput></screen> - </step> - - <step> - <para>Load <filename>example.html</filename> into the web - browser and confirm that the - <filename>para<replaceable>n</replaceable>.xml</filename> - files have been included in - <filename>example.html</filename>.</para> - </step> - </procedure> - </sect3> - - <sect3> - <title>Use Parameter Entities to Include Files</title> - - <note> - <para>The previous steps must have completed before this - step.</para> - </note> - - <procedure> - <step> - <para>Edit <filename>example.xml</filename> so that it - looks like this:</para> - - <programlisting><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" -"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [ -<!ENTITY % entities SYSTEM "entities.ent"> %entities; -]> - -<tag class="starttag">html xmlns="http://www.w3.org/1999/xhtml"</tag> - <tag class="starttag">head</tag> - <tag class="starttag">title</tag>An Example XHTML File<tag class="endtag">title</tag> - <tag class="endtag">head</tag> - - <tag class="starttag">body</tag> - <tag class="starttag">p</tag>The current version of this document is: &version;<tag class="endtag">p</tag> - - &para1; - &para2; - &para3; - <tag class="endtag">body</tag> -<tag class="endtag">html</tag></programlisting> - </step> - - <step> - <para>Create a new file called - <filename>entities.ent</filename> with this - content:</para> - - <programlisting><!ENTITY version "1.1"> -<!ENTITY para1 SYSTEM "para1.xml"> -<!ENTITY para2 SYSTEM "para2.xml"> -<!ENTITY para3 SYSTEM "para3.xml"></programlisting> - </step> - - <step> - <para>Produce <filename>example.html</filename> by - normalizing <filename>example.xml</filename>.</para> - - <screen>&prompt.user; <userinput>xmllint --dropdtd --noent example.xml > example.html</userinput></screen> - </step> - - <step> - <para>Load <filename>example.html</filename> into the web - browser and confirm that the - <filename>para<replaceable>n</replaceable>.xml</filename> - files have been included in - <filename>example.html</filename>.</para> - </step> - </procedure> - </sect3> - </sect2> - </sect1> - - <sect1 xml:id="xml-primer-marked-sections"> - <title>Marked Sections</title> - - <para><acronym>XML</acronym> provides a mechanism to indicate that - particular pieces of the document should be processed in a - special way. These are called - <quote>marked sections</quote>.</para> - - <example> - <title>Structure of a Marked Section</title> - - <programlisting><![<replaceable>KEYWORD</replaceable>[ - Contents of marked section -]]></programlisting> - </example> - - <para>As expected of an <acronym>XML</acronym> construct, a marked - section starts with <literal><!</literal>.</para> - - <para>The first square bracket begins the marked section.</para> - - <para><replaceable>KEYWORD</replaceable> describes how this marked - section is to be processed by the parser.</para> - - <para>The second square bracket indicates the start of the - marked section's content.</para> - - <para>The marked section is finished by closing the two square - brackets, and then returning to the document context from the - <acronym>XML</acronym> context with - <literal>></literal>.</para> - - <sect2 xml:id="xml-primer-marked-section-keywords"> - <title>Marked Section Keywords</title> - - <sect3 xml:id="xml-primer-cdata"> - <title><literal>CDATA</literal></title> - - <para>These keywords denote the marked sections - <emphasis>content model</emphasis>, and allow you to change - it from the default.</para> - - <para>When an <acronym>XML</acronym> parser is processing a - document, it keeps track of the - <quote>content model</quote>.</para> - - <para>The content model describes the - content the parser is expecting to see and what it will do - with that content.</para> - - <para>The <literal>CDATA</literal> content model is one of the - most useful.</para> - - <para><literal>CDATA</literal> is for - <quote>Character Data</quote>. When the parser is in this - content model, it expects to see only characters. In this - model the <literal><</literal> and - <literal>&</literal> symbols lose their special status, - and will be treated as ordinary characters.</para> - - <note> - <para>When using <literal>CDATA</literal> in examples of - text marked up in <acronym>XML</acronym>, remember that - the content of <literal>CDATA</literal> is not validated. - The included text must be check with other means. For - example, the content could be written in another document, - validated, and then pasted into the - <literal>CDATA</literal> section.</para> - </note> - - <example> - <title>Using a <literal>CDATA</literal> Marked - Section</title> - - <programlisting><tag class="starttag">para</tag>Here is an example of how to include some text that contains - many <tag class="starttag">literal</tag>&lt;<tag class="endtag">literal</tag> and <tag class="starttag">literal</tag>&amp;<tag class="endtag">literal</tag> - symbols. The sample text is a fragment of - <tag class="starttag">acronym</tag>XHTML<tag class="endtag">acronym</tag>. The surrounding text (<tag class="starttag">para</tag> and - <tag class="starttag">programlisting</tag>) are from DocBook.<tag class="endtag">para</tag> - -<tag class="starttag">programlisting</tag><![CDATA[<tag class="starttag">p</tag>This is a sample that shows some of the - elements within <tag class="starttag">acronym</tag>XHTML<tag class="endtag">acronym</tag>. Since the angle - brackets are used so many times, it is simpler to say the whole - example is a CDATA marked section than to use the entity names for - the left and right angle brackets throughout.<tag class="endtag">p</tag> - - <tag class="starttag">ul</tag> - <tag class="starttag">li</tag>This is a listitem<tag class="endtag">li</tag> - <tag class="starttag">li</tag>This is a second listitem<tag class="endtag">li</tag> - <tag class="starttag">li</tag>This is a third listitem<tag class="endtag">li</tag> - <tag class="endtag">ul</tag> - - <tag class="starttag">p</tag>This is the end of the example.<tag class="endtag">p</tag>]]><tag class="endtag">programlisting</tag></programlisting> - </example> - </sect3> - - <sect3 xml:id="xml-primer-include-ignore"> - <title><literal>INCLUDE</literal> and - <literal>IGNORE</literal></title> - - <para>When the keyword is <literal>INCLUDE</literal>, then the - contents of the marked section will be processed. When the - keyword is <literal>IGNORE</literal>, the marked section - is ignored and will not be processed. It will not appear in - the output.</para> - - <example> - <title>Using <literal>INCLUDE</literal> and - <literal>IGNORE</literal> in Marked Sections</title> - - <programlisting><![INCLUDE[ - This text will be processed and included. -]]> - -<![IGNORE[ - This text will not be processed or included. -]]></programlisting> - </example> - - <para>By itself, this is not too useful. Text to be - removed from the document could be cut out, or wrapped - in comments.</para> - - <para>It becomes more useful when controlled by - <link linkend="xml-primer-parameter-entities">parameter - entities</link>, yet this usage is limited - to entity files.</para> - - <para>For example, suppose that documentation was produced in - a hard-copy version and an electronic version. Some extra - text is desired in the electronic version content that was - not to appear in the hard-copy.</para> - - <para>Create an entity file that defines general entities to - include each chapter and guard these definitions with a - parameter entity that can be set to either - <literal>INCLUDE</literal> or <literal>IGNORE</literal> to - control whether the entity is defined. After these - conditional general entity definitions, place one more - definition for each general entity to set them to an empty - value. This technique makes use of the fact that entity - definitions cannot be overridden but the first definition - always takes effect. So the inclusion of the chapter is - controlled with the corresponding parameter entity. Set to - <literal>INCLUDE</literal>, the first general entity - definition will be read and the second one will be ignored. - Set to <literal>IGNORE</literal>, the first definition will - be ignored and the second one will take effect.</para> - - <example> - <title>Using a Parameter Entity to Control a Marked - Section</title> - - <programlisting><!ENTITY % electronic.copy "INCLUDE"> - -<![%electronic.copy;[ -<!ENTITY chap.preface SYSTEM "preface.xml"> -]]> - -<!ENTITY chap.preface ""></programlisting> - - <para>When producing the hard-copy version, change the - parameter entity's definition to:</para> - - <programlisting><!ENTITY % electronic.copy "IGNORE"></programlisting> - </example> - </sect3> - </sect2> - - <sect2> - <title>To Do…</title> - - <procedure> - <step> - <para>Modify <filename>entities.ent</filename> to - contain the following:</para> - - <programlisting><!ENTITY version "1.1"> -<!ENTITY % conditional.text "IGNORE"> - -<![%conditional.text;[ -<!ENTITY para1 SYSTEM "para1.xml"> -]]> - -<!ENTITY para1 ""> - -<!ENTITY para2 SYSTEM "para2.xml"> -<!ENTITY para3 SYSTEM "para3.xml"></programlisting> - </step> - - <step> - <para>Normalize <filename>example.xml</filename> - and notice that the conditional text is not present in the - output document. Set the parameter entity - guard to <literal>INCLUDE</literal> and regenerate the - normalized document and the text will appear again. - This method makes sense if there are more - conditional chunks depending on the same condition. For - example, to control generating printed or online - text.</para> - </step> - </procedure> - </sect2> - </sect1> - - <sect1 xml:id="xml-primer-conclusion"> - <title>Conclusion</title> - - <para>That is the conclusion of this <acronym>XML</acronym> - primer. For reasons of space and complexity, several things - have not been covered in depth (or at all). However, the - previous sections cover enough <acronym>XML</acronym> to - introduce the organization of the <acronym>FDP</acronym> - documentation.</para> - </sect1> -</chapter> |