diff options
| author | Sergio Carlavilla Delgado <carlavilla@FreeBSD.org> | 2021-01-25 23:31:29 +0000 |
|---|---|---|
| committer | Sergio Carlavilla Delgado <carlavilla@FreeBSD.org> | 2021-01-25 23:31:29 +0000 |
| commit | 989d921f5d4ac8d8b7c831c13b8954ad1901be24 (patch) | |
| tree | a5d768f9af4b55422fdf5b17064879ae1c7ce032 /en_US.ISO8859-1/books/fdp-primer | |
| parent | 0cff342f42461c5081b98bce7581f43df319e4f4 (diff) | |
| download | doc-989d921f5d4ac8d8b7c831c13b8954ad1901be24.tar.gz doc-989d921f5d4ac8d8b7c831c13b8954ad1901be24.zip | |
Migrate doc to Hugo/AsciiDoctor
I'm very pleased to announce the release of
our new website and documentation using
the new toolchain with Hugo and AsciiDoctor.
To get more information about the new toolchain
please read the FreeBSD Documentation Project Primer[1],
Hugo docs[2] and AsciiDoctor docs[3].
Acknowledgment:
Benedict Reuschling <bcr@>
Glen Barber <gjb@>
Hiroki Sato <hrs@>
Li-Wen Hsu <lwhsu@>
Sean Chittenden <seanc@>
The FreeBSD Foundation
[1] https://docs.FreeBSD.org/en/books/fdp-primer/
[2] https://gohugo.io/documentation/
[3] https://docs.asciidoctor.org/home/
Approved by: doceng, core
Diffstat (limited to 'en_US.ISO8859-1/books/fdp-primer')
21 files changed, 0 insertions, 10404 deletions
diff --git a/en_US.ISO8859-1/books/fdp-primer/Makefile b/en_US.ISO8859-1/books/fdp-primer/Makefile deleted file mode 100644 index 4b48491169..0000000000 --- a/en_US.ISO8859-1/books/fdp-primer/Makefile +++ /dev/null @@ -1,59 +0,0 @@ -# -# $FreeBSD$ -# -# Build the FreeBSD Documentation Project Primer. -# - -MAINTAINER=doc@FreeBSD.org - -DOC?= book - -FORMATS?= html-split html - -INSTALL_COMPRESSED?= gz -INSTALL_ONLY_COMPRESSED?= - -# -# SRCS lists the individual XML files that make up the document. Changes -# to any of these files will force a rebuild -# - -# XML content -SRCS= book.xml -SRCS+= overview/chapter.xml -SRCS+= tools/chapter.xml -SRCS+= working-copy/chapter.xml -SRCS+= structure/chapter.xml -SRCS+= doc-build/chapter.xml -SRCS+= the-website/chapter.xml -SRCS+= xml-primer/chapter.xml -SRCS+= xhtml-markup/chapter.xml -SRCS+= docbook-markup/chapter.xml -SRCS+= stylesheets/chapter.xml -SRCS+= translations/chapter.xml -SRCS+= po-translations/chapter.xml -SRCS+= manpages/chapter.xml -SRCS+= writing-style/chapter.xml -SRCS+= editor-config/chapter.xml -SRCS+= see-also/chapter.xml - -SRCS+= examples/appendix.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 - -# Entities -SRCS+= chapters.ent - -URL_RELPREFIX?= ../../../.. -DOC_PREFIX?= ${.CURDIR}/../../.. - -.include "${DOC_PREFIX}/share/mk/doc.project.mk" diff --git a/en_US.ISO8859-1/books/fdp-primer/book.xml b/en_US.ISO8859-1/books/fdp-primer/book.xml deleted file mode 100644 index 27f8e90d87..0000000000 --- a/en_US.ISO8859-1/books/fdp-primer/book.xml +++ /dev/null @@ -1,281 +0,0 @@ -<?xml version="1.0" encoding="iso-8859-1"?> -<!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN" - "http://www.FreeBSD.org/XML/share/xml/freebsd50.dtd" [ -<!ENTITY % chapters SYSTEM "chapters.ent"> %chapters; -<!-- ENTITY index SYSTEM "index.xml" --> -]> -<!-- 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. - ---> -<book xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" - xml:lang="en"> - <info> - <title>FreeBSD Documentation Project Primer for New - Contributors</title> - - <author> - <orgname>The FreeBSD Documentation Project</orgname> - </author> - - <copyright> - <year>1998</year> - <year>1999</year> - <year>2000</year> - <year>2001</year> - <year>2002</year> - <year>2003</year> - <year>2004</year> - <year>2005</year> - <year>2006</year> - <year>2007</year> - <year>2008</year> - <year>2009</year> - <year>2010</year> - <year>2011</year> - <year>2012</year> - <year>2013</year> - <year>2014</year> - <year>2015</year> - <year>2016</year> - <year>2017</year> - <year>2018</year> - <year>2019</year> - <year>2020</year> - <holder role="mailto:doceng@FreeBSD.org">DocEng</holder> - </copyright> - - <pubdate /> - - <releaseinfo /> - - &legalnotice; - - <abstract> - <para>Thank you for becoming a part of the FreeBSD Documentation - Project. Your contribution is extremely valuable, and we - appreciate it.</para> - - <para>This primer covers details needed - to start contributing to the FreeBSD Documentation - Project, or <acronym>FDP</acronym>, including tools, software, - and the philosophy behind the - Documentation Project.</para> - - <para>This is a work in progress. Corrections and - additions are always welcome.</para> - </abstract> - </info> - - <preface xml:id="preface"> - <title>Preface</title> - - <sect1 xml:id="preface-prompts"> - <title>Shell Prompts</title> - - <para>This table shows the default system prompt and - superuser prompt. The examples use these prompts to - indicate which type of user is running the example.</para> - - <informaltable frame="none" pgwide="1"> - <tgroup cols="2"> - <thead> - <row> - <entry>User</entry> - <entry>Prompt</entry> - </row> - </thead> - - <tbody> - <row> - <entry>Normal user</entry> - <entry>&prompt.user;</entry> - </row> - - <row> - <entry><systemitem - class="username">root</systemitem></entry> - <entry>&prompt.root;</entry> - </row> - </tbody> - </tgroup> - </informaltable> - </sect1> - - <sect1 xml:id="preface-conventions"> - <title>Typographic Conventions</title> - - <para>This table describes the typographic conventions - used in this book.</para> - - <informaltable frame="none" pgwide="1"> - <tgroup cols="2"> - <thead> - <row> - <entry>Meaning</entry> - <entry>Examples</entry> - </row> - </thead> - - <tbody> - <row> - <entry>The names of commands.</entry> - <entry>Use <command>ls -l</command> to list all - files.</entry> - </row> - - <row> - <entry>The names of files.</entry> - <entry>Edit <filename>.login</filename>.</entry> - </row> - - <row> - <entry>On-screen computer output.</entry> - <entry><screen>You have mail.</screen></entry> - </row> - - <row> - <entry>What the user types, contrasted with on-screen - computer output.</entry> - - <entry><screen>&prompt.user; <userinput>date +"The time is %H:%M"</userinput> -The time is 09:18</screen></entry> - </row> - - <row> - <entry>Manual page references.</entry> - <entry>Use &man.su.1; to change user identity.</entry> - </row> - - <row> - <entry>User and group names.</entry> - <entry>Only <systemitem - class="username">root</systemitem> can do - this.</entry> - </row> - - <row> - <entry>Emphasis.</entry> - <entry>The user <emphasis>must</emphasis> do - this.</entry> - </row> - - <row> - <entry>Text that the user is expected to replace with - the actual text.</entry> - - <entry>To search for a keyword in the manual pages, type - <command>man -k - <replaceable>keyword</replaceable></command></entry> - </row> - - <row> - <entry>Environment variables.</entry> - <entry><envar>$HOME</envar> is set to the user's home - directory.</entry> - </row> - </tbody> - </tgroup> - </informaltable> - </sect1> - - <sect1 xml:id="preface-notes"> - <title>Notes, Tips, Important Information, Warnings, and - Examples</title> - - <para>Notes, warnings, and examples appear within the - text.</para> - - <note> - <para>Notes are represented like this, and contain information - to take note of, as it may affect what the user - does.</para> - </note> - - <tip> - <para>Tips are represented like this, and contain information - helpful to the user, like showing an easier way to do - something.</para> - </tip> - - <important> - <para>Important information is represented like this. - Typically, these show extra steps the user may need to - take.</para> - </important> - - <warning> - <para>Warnings are represented like this, and contain - information warning about possible damage if the - instructions are not followed. This damage may be physical, - to the hardware or the user, or it may be non-physical, such - as the inadvertent deletion of important files.</para> - </warning> - - <example> - <title>A Sample Example</title> - - <para>Examples are represented like this, and typically - contain examples showing a walkthrough, or - the results of a particular action.</para> - </example> - </sect1> - - <sect1 xml:id="preface-acknowledgements"> - <title>Acknowledgments</title> - - <para>My thanks to Sue Blake, Patrick Durusau, Jon Hamilton, - Peter Flynn, and Christopher Maden, who took the time to read - early drafts of this document and offer many valuable comments - and criticisms.</para> - </sect1> - </preface> - - &chap.overview; - &chap.tools; - &chap.working-copy; - &chap.structure; - &chap.doc-build; - &chap.the-website; - &chap.xml-primer; - &chap.xhtml-markup; - &chap.docbook-markup; - &chap.stylesheets; - &chap.translations; - &chap.po-translations; - &chap.manpages; - &chap.writing-style; - &chap.editor-config; - &chap.see-also; - - &app.examples; - - <index/> -</book> diff --git a/en_US.ISO8859-1/books/fdp-primer/chapters.ent b/en_US.ISO8859-1/books/fdp-primer/chapters.ent deleted file mode 100644 index 2bfc029895..0000000000 --- a/en_US.ISO8859-1/books/fdp-primer/chapters.ent +++ /dev/null @@ -1,30 +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.manpages SYSTEM "manpages/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/en_US.ISO8859-1/books/fdp-primer/doc-build/chapter.xml b/en_US.ISO8859-1/books/fdp-primer/doc-build/chapter.xml deleted file mode 100644 index e55650a560..0000000000 --- a/en_US.ISO8859-1/books/fdp-primer/doc-build/chapter.xml +++ /dev/null @@ -1,531 +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. - ---> -<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.8;.</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 - documents that are 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 xml:id="includes-doc-project-mk"> - <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 xml:id="doc-project-mk-variables"> - - <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 xml:id="doc-project-mk-conditionals"> - <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 xml:id="includes-doc-subdir-mk"> - <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 xml:id="doc-subdir-mk-variables"> - <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 xml:id="doc-subdir-mk-targets-macro"> - <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 xml:id="doc-subdir-mk-provided-targets"> - <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 xml:id="doc-subdir-mk-conditionals"> - <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 xml:id="doc-subdir-mk-looping"> - <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/en_US.ISO8859-1/books/fdp-primer/docbook-markup/chapter.xml b/en_US.ISO8859-1/books/fdp-primer/docbook-markup/chapter.xml deleted file mode 100644 index 7c2ece8dba..0000000000 --- a/en_US.ISO8859-1/books/fdp-primer/docbook-markup/chapter.xml +++ /dev/null @@ -1,2761 +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. - ---> - -<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">substeps</tag> - <tag class="starttag">step</tag> - <tag class="starttag">para</tag>And now do this smaller thing.<tag class="endtag">para</tag> - <tag class="endtag">step</tag> - - <tag class="starttag">step</tag> - <tag class="starttag">para</tag>And now do this other smaller thing.<tag class="endtag">para</tag> - <tag class="endtag">step</tag> - <tag class="endtag">substeps</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> - <substeps> - <step> - <para>And now do this small thing.</para> - </step> - - <step> - <para>And this other small thing.</para> - </step> - </substeps> - </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"); - return 0; -}<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"); - return 0; -}</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="emptytag">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/en_US.ISO8859-1/books/fdp-primer/editor-config/chapter.xml b/en_US.ISO8859-1/books/fdp-primer/editor-config/chapter.xml deleted file mode 100644 index 72f1c5f3c4..0000000000 --- a/en_US.ISO8859-1/books/fdp-primer/editor-config/chapter.xml +++ /dev/null @@ -1,248 +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. - ---> -<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>, - <package>editors/vim-console</package>, or - <package>editors/vim-tiny</package> then follow the - configuration instructions in - <xref linkend="editor-config-vim-config"/>.</para> - - <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> - - <sect2 xml:id="editor-config-vim-config"> - <title>Configuration</title> - - <para>Edit <filename>~/.vimrc</filename>, adding these - lines to the end of the file:</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 " Set_Highlights() - -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> - </sect1> - - <sect1 xml:id="editor-config-emacs"> - <title><application>Emacs</application></title> - - <para>Install from <package>editors/emacs</package> or - <package>editors/emacs-devel</package>.</para> - - <sect2 xml:id="editor-config-emacs-validation"> - <title>Validation</title> - - <para>Emacs's nxml-mode uses compact relax NG schemas for - validating XML. A compact relax NG schema for FreeBSD's - extension to DocBook 5.0 is included in the documentation - repository. To configure nxml-mode to validate using this - schema, create - <filename>~/.emacs.d/schema/schemas.xml</filename> and add - these lines to the file:</para> - - <programlisting><tag class="starttag">locatingRules xmlns="http://thaiopensource.com/ns/locating-rules/1.0"</tag> - <tag class="starttag">documentElement localName="section" typeId="DocBook"</tag> - <tag class="starttag">documentElement localName="chapter" typeId="DocBook"</tag> - <tag class="starttag">documentElement localName="article" typeId="DocBook"</tag> - <tag class="starttag">documentElement localName="book" typeId="DocBook"</tag> - <tag class="starttag">typeId id="DocBook" uri="/usr/local/share/xml/docbook/5.0/rng/docbook.rnc"</tag> -<tag class="endtag">locatingRules</tag></programlisting> - - </sect2> - - <sect2 xml:id="editor-config-emacs-igor"> - <title>Automated Proofreading with Flycheck and Igor</title> - - <para>The Flycheck package is available from Milkypostman's - Emacs Lisp Package Archive (<acronym>MELPA</acronym>). If - <acronym>MELPA</acronym> is not already in Emacs's - packages-archives, it can be added by evaluating</para> - - <programlisting>(add-to-list 'package-archives '("melpa" . "http://stable.melpa.org/packages/") t)</programlisting> - - <para>Add the line to Emacs's initialization file (one of - <filename>~/.emacs</filename>, - <filename>~/.emacs.el</filename>, or - <filename>~.emacs.d/init.el</filename>) to make this change - permanent.</para> - - <para>To install Flycheck, evaluate</para> - - <programlisting>(package-install 'flycheck)</programlisting> - - <para>Create a Flycheck checker for - <package>textproc/igor</package> by evaluating</para> - - <programlisting>(flycheck-define-checker igor - "FreeBSD Documentation Project sanity checker. - -See URLs https://www.freebsd.org/docproj/ and -http://www.freshports.org/textproc/igor/." - :command ("igor" "-X" source-inplace) - :error-parser flycheck-parse-checkstyle - :modes (nxml-mode) - :standard-input t) - - (add-to-list 'flycheck-checkers 'igor 'append)</programlisting> - - <para>Again, add these lines to Emacs's initialization file to - make the changes permanent.</para> - </sect2> - - <sect2 xml:id="editor-config-emacs-specifc"> - <title>FreeBSD Documentation Specific Settings</title> - - <para>To apply settings specific to the FreeBSD documentation - project, create <filename>.dir-locals.el</filename> in the - root directory of the documentation repository and add these - lines to the file:</para> - - <programlisting>;;; Directory Local Variables -;;; For more information see (info "(emacs) Directory Variables") - -((nxml-mode - (eval . (turn-on-auto-fill)) - (fill-column . 70) - (eval . (require 'flycheck)) - (eval . (flycheck-mode 1)) - (flycheck-checker . igor) - (eval . (add-to-list 'rng-schema-locating-files "~/.emacs.d/schema/schemas.xml"))))</programlisting> - </sect2> - </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>Use an editor to replace the lines in the - <filename>~/.nanorc</filename> <literal>syntax "xml"</literal> - block with these rules:</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/en_US.ISO8859-1/books/fdp-primer/examples/appendix.xml b/en_US.ISO8859-1/books/fdp-primer/examples/appendix.xml deleted file mode 100644 index 7dc16ab1ab..0000000000 --- a/en_US.ISO8859-1/books/fdp-primer/examples/appendix.xml +++ /dev/null @@ -1,161 +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. - ---> -<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/en_US.ISO8859-1/books/fdp-primer/manpages/chapter.xml b/en_US.ISO8859-1/books/fdp-primer/manpages/chapter.xml deleted file mode 100644 index c951cbd85e..0000000000 --- a/en_US.ISO8859-1/books/fdp-primer/manpages/chapter.xml +++ /dev/null @@ -1,746 +0,0 @@ -<?xml version="1.0" encoding="iso-8859-1"?> -<!-- - The FreeBSD Documentation Project ---> -<chapter xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" - xml:id="manpages"> - - <title>Manual Pages</title> - - <sect1 xml:id="manpages-introduction"> - <title>Introduction</title> - - <para><emphasis>Manual pages</emphasis>, commonly shortened to - <emphasis>man pages</emphasis>, were conceived as - readily-available reminders for command syntax, device driver - details, or configuration file formats. They have become an - extremely valuable quick-reference from the command line for - users, system administrators, and programmers.</para> - - <para>Although intended as reference material rather than - tutorials, the EXAMPLES sections of manual pages often - provide detailed use case.</para> - - <para>Manual pages are generally shown interactively by the - &man.man.1; command. When the user types - <command>man ls</command>, a search is performed for a manual - page matching <literal>ls</literal>. The first matching result - is displayed.</para> - </sect1> - - <sect1 xml:id="manpages-sections"> - <title>Sections</title> - - <para>Manual pages are grouped into <emphasis>sections</emphasis>. - Each section contains manual pages for a specific category of - documentation:</para> - - <informaltable> - <tgroup cols="2"> - <thead> - <row> - <entry>Section Number</entry> - <entry>Category</entry> - </row> - </thead> - - <tbody> - <row> - <entry>1</entry> - <entry>General Commands</entry> - </row> - - <row> - <entry>2</entry> - <entry>System Calls</entry> - </row> - - <row> - <entry>3</entry> - <entry>Library Functions</entry> - </row> - - <row> - <entry>4</entry> - <entry>Kernel Interfaces</entry> - </row> - - <row> - <entry>5</entry> - <entry>File Formats</entry> - </row> - - <row> - <entry>6</entry> - <entry>Games</entry> - </row> - - <row> - <entry>7</entry> - <entry>Miscellaneous</entry> - </row> - - <row> - <entry>8</entry> - <entry>System Manager</entry> - </row> - - <row> - <entry>9</entry> - <entry>Kernel Developer</entry> - </row> - </tbody> - </tgroup> - </informaltable> - </sect1> - - <sect1 xml:id="manpages-markup"> - <title>Markup</title> - - <para>Various markup forms and rendering programs have been used - for manual pages. &os; has used &man.groff.7; and the newer - &man.mandoc.1;. Most existing &os; manual pages, and all new - ones, use the &man.mdoc.7; form of markup. This is a simple - line-based markup that is reasonably expressive. It is mostly - semantic: parts of text are marked up for what they are, rather - than for how they should appear when rendered. There is some - appearance-based markup which is usually best avoided.</para> - - <para>Manual page source is usually interpreted and displayed to - the screen interactively. The source files can be ordinary text - files or compressed with &man.gzip.1; to save space.</para> - - <para>Manual pages can also be rendered to other formats, - including PostScript for printing or <acronym>PDF</acronym> - generation. See &man.man.1;.</para> - - <sect2 xml:id="manpages-markup-sections"> - <title>Manual Page Sections</title> - - <para>Manual pages are composed of several standard sections. - Each section has a title in upper case, and the sections for a - particular type of manual page appear in a specific order. - For a category 1 General Command manual page, the sections - are:</para> - - <informaltable> - <tgroup cols="2"> - <thead> - <row> - <entry>Section Name</entry> - <entry>Description</entry> - </row> - </thead> - - <tbody> - <row> - <entry>NAME</entry> - <entry>Name of the command</entry> - </row> - - <row> - <entry>SYNOPSIS</entry> - <entry>Format of options and arguments</entry> - </row> - - <row> - <entry>DESCRIPTION</entry> - <entry>Description of purpose and usage</entry> - </row> - - <row> - <entry>ENVIRONMENT</entry> - <entry>Environment settings that affect - operation</entry> - </row> - - <row> - <entry>EXIT STATUS</entry> - <entry>Error codes returned on exit</entry> - </row> - - <row> - <entry>EXAMPLES</entry> - <entry>Examples of usage</entry> - </row> - - <row> - <entry>COMPATIBILITY</entry> - <entry>Compatibility with other implementations</entry> - </row> - - <row> - <entry>SEE ALSO</entry> - <entry>Cross-reference to related manual pages</entry> - </row> - - <row> - <entry>STANDARDS</entry> - <entry>Compatibility with standards like POSIX</entry> - </row> - - <row> - <entry>HISTORY</entry> - <entry>History of implementation</entry> - </row> - - <row> - <entry>BUGS</entry> - <entry>Known bugs</entry> - </row> - - <row> - <entry>AUTHORS</entry> - <entry>People who created the command or wrote the - manual page.</entry> - </row> - </tbody> - </tgroup> - </informaltable> - - <para>Some sections are optional, and the combination of - sections for a specific type of manual page vary. Examples of - the most common types are shown later in this chapter.</para> - </sect2> - - <sect2 xml:id="manpages-markup-macros"> - <title>Macros</title> - - <para>&man.mdoc.7; markup is based on - <emphasis>macros</emphasis>. Lines that begin with a dot - contain macro commands, each two or three letters long. For - example, consider this portion of the &man.ls.1; manual - page:</para> - - <programlisting xml:id="manpages-markup-macros-example-ls"> -.Dd December 1, 2015 <co xml:id="co-manpages-macro-example-ls-1"/> -.Dt LS 1 -.Sh NAME <co xml:id="co-manpages-macro-example-ls-2"/> -.Nm ls -.Nd list directory contents -.Sh SYNOPSIS <co xml:id="co-manpages-macro-example-ls-3"/> -.Nm <co xml:id="co-manpages-macro-example-ls-4"/> -.Op Fl -libxo <co xml:id="co-manpages-macro-example-ls-5"/> -.Op Fl ABCFGHILPRSTUWZabcdfghiklmnopqrstuwxy1, <co xml:id="co-manpages-macro-example-ls-6"/> -.Op Fl D Ar format <co xml:id="co-manpages-macro-example-ls-7"/> -.Op Ar <co xml:id="co-manpages-macro-example-ls-8"/> -.Sh DESCRIPTION <co xml:id="co-manpages-macro-example-ls-9"/> -For each operand that names a -.Ar file -of a type other than -directory, -.Nm -displays its name as well as any requested, -associated information. -For each operand that names a -.Ar file -of type directory, -.Nm -displays the names of files contained -within that directory, as well as any requested, associated -information.</programlisting> - - <calloutlist> - <callout arearefs="co-manpages-macro-example-ls-1"> - <para>A <emphasis>Document date</emphasis> and - <emphasis>Document title</emphasis> are defined.</para> - </callout> - - <callout arearefs="co-manpages-macro-example-ls-2"> - <para>A <emphasis>Section header</emphasis> for the NAME - section is defined. Then the <emphasis>Name</emphasis> - of the command and a one-line - <emphasis>Name description</emphasis> are defined.</para> - </callout> - - <callout arearefs="co-manpages-macro-example-ls-3"> - <para>The SYNOPSIS section begins. This section describes - the command-line options and arguments accepted.</para> - </callout> - - <callout arearefs="co-manpages-macro-example-ls-4"> - <para><emphasis>Name</emphasis> (<literal>.Nm</literal>) has - already been defined, and repeating it here just displays - the defined value in the text.</para> - </callout> - - <callout arearefs="co-manpages-macro-example-ls-5"> - <para>An <emphasis>Optional</emphasis> - <emphasis>Flag</emphasis> called <literal>-libxo</literal> - is shown. The <literal>Fl</literal> macro adds a dash to - the beginning of flags, so this appears in the manual - page as <literal>--libxo</literal>.</para> - </callout> - - <callout arearefs="co-manpages-macro-example-ls-6"> - <para>A long list of optional single-character flags are - shown.</para> - </callout> - - <callout arearefs="co-manpages-macro-example-ls-7"> - <para>An optional <literal>-D</literal> flag is defined. If - the <literal>-D</literal> flag is given, it must be - followed by an <emphasis>Argument</emphasis>. The - argument is a <emphasis>format</emphasis>, a string that - tells &man.ls.1; what to display and how to display it. - Details on the format string are given later in the manual - page.</para> - </callout> - - <callout arearefs="co-manpages-macro-example-ls-8"> - <para>A final optional argument is defined. Since no name - is specified for the argument, the default of - <literal>file ...</literal> is used.</para> - </callout> - - <callout arearefs="co-manpages-macro-example-ls-9"> - <para>The <emphasis>Section header</emphasis> for the - DESCRIPTION section is defined.</para> - </callout> - </calloutlist> - - <para>When rendered with the command <command>man ls</command>, - the result displayed on the screen looks like this:</para> - - <programlisting>LS(1) FreeBSD General Commands Manual LS(1) - -NAME - ls — list directory contents - -SYNOPSIS - ls [--libxo] [-ABCFGHILPRSTUWZabcdfghiklmnopqrstuwxy1,] [-D format] - [file ...] - -DESCRIPTION - For each operand that names a file of a type other than directory, ls - displays its name as well as any requested, associated information. For - each operand that names a file of type directory, ls displays the names - of files contained within that directory, as well as any requested, - associated information.</programlisting> - - <para>Optional values are shown inside square brackets.</para> - </sect2> - - <sect2 xml:id="manpages-markup-guidelines"> - <title>Markup Guidelines</title> - - <para>The &man.mdoc.7; markup language is not very strict. For - clarity and consistency, the &os; Documentation project adds - some additional style guidelines:</para> - - <variablelist> - <varlistentry> - <term>Only the first letter of macros is upper case</term> - - <listitem> - <para>Always use upper case for the first letter of a - macro and lower case for the remaining letters.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Begin new sentences on new lines</term> - - <listitem> - <para>Start a new sentence on a new line, do not begin it - on the same line as an existing sentence.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Update <literal>.Dd</literal> when making non-trivial - changes to a manual page</term> - - <listitem> - <para>The <emphasis>Document date</emphasis> informs the - reader about the last time the manual page was updated. - It is important to update whenever non-trivial changes - are made to the manual pages. Trivial changes like - spelling or punctuation fixes that do not affect usage - can be made without updating - <literal>.Dd</literal>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Give examples</term> - - <listitem> - <para>Show the reader examples when possible. Even - trivial examples are valuable, because what is trivial - to the writer is not necessarily trivial to the reader. - Three examples are a good goal. A trivial example shows - the minimal requirements, a serious example shows actual - use, and an in-depth example demonstrates unusual or - non-obvious functionality.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Include the BSD license</term> - - <listitem> - <para>Include the BSD license on new manual pages. The - preferred license is available from the <link - xlink:href="&url.articles.committers-guide;pref-license">Committer's - Guide</link>.</para> - </listitem> - </varlistentry> - </variablelist> - </sect2> - - <sect2 xml:id="manpages-markup-tricks"> - <title>Markup Tricks</title> - - <para>Add a space before punctuation on a line with - macros. Example:</para> - - <programlisting>.Sh SEE ALSO -.Xr geom 4 , -.Xr boot0cfg 8 , -.Xr geom 8 , -.Xr gptboot 8</programlisting> - - <para>Note how the commas at the end of the - <literal>.Xr</literal> lines have been placed after a space. - The <literal>.Xr</literal> macro expects two parameters to - follow it, the name of an external manual page, and a section - number. The space separates the punctuation from the section - number. Without the space, the external links would - incorrectly point to section <literal>4,</literal> or - <literal>8,</literal>.</para> - </sect2> - - <sect2 xml:id="manpages-markup-important-macros"> - <title>Important Macros</title> - - <para>Some very common macros will be shown here. For - more usage examples, see &man.mdoc.7;, &man.groff.mdoc.7;, or - search for actual use in - <filename>/usr/share/man/man*</filename> directories. For - example, to search for examples of the <literal>.Bd</literal> - <emphasis>Begin display</emphasis> macro:</para> - - <screen>&prompt.user; <userinput>find /usr/share/man/man* | xargs zgrep '.Bd'</userinput></screen> - - <sect3 xml:id="manpages-markup-important-macros-organizational"> - <title>Organizational Macros</title> - - <para>Some macros are used to define logical blocks of a - manual page.</para> - - <informaltable> - <tgroup cols="2"> - <thead> - <row> - <entry>Organizational Macro</entry> - <entry>Use</entry> - </row> - </thead> - - <tbody> - <row> - <entry><literal>.Sh</literal></entry> - <entry>Section header. Followed by the name of - the section, traditionally all upper case. - Think of these as chapter titles.</entry> - </row> - - <row> - <entry><literal>.Ss</literal></entry> - <entry>Subsection header. Followed by the name of - the subsection. Used to divide a - <literal>.Sh</literal> section into - subsections.</entry> - </row> - - <row> - <entry><literal>.Bl</literal></entry> - <entry>Begin list. Start a list of items.</entry> - </row> - - <row> - <entry><literal>.El</literal></entry> - <entry>End a list.</entry> - </row> - - <row> - <entry><literal>.Bd</literal></entry> - <entry>Begin display. Begin a special area of - text, like an indented area.</entry> - </row> - - <row> - <entry><literal>.Ed</literal></entry> - <entry>End display.</entry> - </row> - </tbody> - </tgroup> - </informaltable> - </sect3> - - <sect3 xml:id="manpages-markup-important-macros-inline"> - <title>Inline Macros</title> - - <para>Many macros are used to mark up inline text.</para> - - <informaltable> - <tgroup cols="2"> - <thead> - <row> - <entry>Inline Macro</entry> - <entry>Use</entry> - </row> - </thead> - - <tbody> - <row> - <entry><literal>.Nm</literal></entry> - <entry>Name. Called with a name as a parameter on the - first use, then used later without the parameter to - display the name that has already been - defined.</entry> - </row> - - <row> - <entry><literal>.Pa</literal></entry> - <entry>Path to a file. Used to mark up filenames and - directory paths.</entry> - </row> - </tbody> - </tgroup> - </informaltable> - </sect3> - </sect2> - </sect1> - - <sect1 xml:id="manpages-sample-structures"> - <title>Sample Manual Page Structures</title> - - <para>This section shows minimal desired man page contents for - several common categories of manual pages.</para> - - <sect2 xml:id="manpages-sample-structures-section-1-8"> - <title>Section 1 or 8 Command</title> - - <para>The preferred basic structure for a section 1 or 8 - command:</para> - - <programlisting xml:id="manpages-sample-structures-section-1-8-sample">.Dd August 25, 2017 -.Dt EXAMPLECMD 8 -.Os -.Sh NAME -.Nm examplecmd -.Nd "command to demonstrate section 1 and 8 man pages" -.Sh SYNOPSIS -.Nm -.Op Fl v -.Sh DESCRIPTION -The -.Nm -utility does nothing except demonstrate a trivial but complete -manual page for a section 1 or 8 command. -.Sh SEE ALSO -.Xr exampleconf 5 -.Sh AUTHORS -.An Firstname Lastname Aq Mt flastname@example.com</programlisting> - </sect2> - - <sect2 xml:id="manpages-sample-structures-section-4"> - <title>Section 4 Device Driver</title> - - <para>The preferred basic structure for a section 4 device - driver:</para> - - <programlisting xml:id="manpages-sample-structures-section-4-sample">.Dd August 25, 2017 -.Dt EXAMPLEDRIVER 4 -.Os -.Sh NAME -.Nm exampledriver -.Nd "driver to demonstrate section 4 man pages" -.Sh SYNOPSIS -To compile this driver into the kernel, add this line to the -kernel configuration file: -.Bd -ragged -offset indent -.Cd "device exampledriver" -.Ed -.Pp -To load the driver as a module at boot, add this line to -.Xr loader.conf 5 : -.Bd -literal -offset indent -exampledriver_load="YES" -.Ed -.Sh DESCRIPTION -The -.Nm -driver provides an opportunity to show a skeleton or template -file for section 4 manual pages. -.Sh HARDWARE -The -.Nm -driver supports these cards from the aptly-named Nonexistent -Technologies: -.Pp -.Bl -bullet -compact -.It -NT X149.2 (single and dual port) -.It -NT X149.8 (single port) -.El -.Sh DIAGNOSTICS -.Bl -diag -.It "flashing green light" -Something bad happened. -.It "flashing red light" -Something really bad happened. -.It "solid black light" -Power cord is unplugged. -.El -.Sh SEE ALSO -.Xr example 8 -.Sh HISTORY -The -.Nm -device driver first appeared in -.Fx 49.2 . -.Sh AUTHORS -.An Firstname Lastname Aq Mt flastname@example.com</programlisting> - </sect2> - - <sect2 xml:id="manpages-sample-structures-section-5"> - <title>Section 5 Configuration File</title> - - <para>The preferred basic structure for a section 5 - configuration file:</para> - - <programlisting xml:id="manpages-sample-structures-section-5-sample">.Dd August 25, 2017 -.Dt EXAMPLECONF 5 -.Os -.Sh NAME -.Nm example.conf -.Nd "config file to demonstrate section 5 man pages" -.Sh DESCRIPTION -.Nm -is an example configuration file. -.Sh SEE ALSO -.Xr example 8 -.Sh AUTHORS -.An Firstname Lastname Aq Mt flastname@example.com</programlisting> - </sect2> - </sect1> - - <sect1 xml:id="manpages-testing"> - <title>Testing</title> - - <para>Testing a new manual page can be challenging. Fortunately - there are some tools that can assist in the task. Some of them, - like &man.man.1;, do not look in the current directory. It is a - good idea to prefix the filename with <literal>./</literal> if - the new manual page is in the current directory. An absolute - path can also be used.</para> - <para>Use &man.mandoc.1;'s linter to check for parsing - errors:</para> - - <screen>&prompt.user; <userinput>mandoc -T lint ./mynewmanpage.8</userinput></screen> - - <para>Use <package>textproc/igor</package> to proofread the - manual page:</para> - - <screen>&prompt.user; <userinput>igor ./mynewmanpage.8</userinput></screen> - - <para>Use &man.man.1; to check the final result of your - changes:</para> - - <screen>&prompt.user; <userinput>man ./mynewmanpage.8</userinput></screen> - - <para>You can use &man.col.1; to filter the output of - &man.man.1; and get rid of the backspace characters before - loading the result in your favorite editor for - spell checking:</para> - - <screen>&prompt.user; <userinput>man ./mynewmanpage.8 | col -b | vim -R -</userinput></screen> - - <para>Spell-checking with fully-featured dictionaries is - encouraged, and can be accomplished by using - <package>textproc/hunspell</package> or - <package>textproc/aspell</package> combined with - <package>textproc/en-hunspell</package> or - <package>textproc/en-aspell</package>, respectively. - For instance:</para> - - <screen>&prompt.user; <userinput>aspell check --lang=en --mode=nroff ./mynewmanpage.8</userinput></screen> - - </sect1> - - <sect1 xml:id="manpages-examples-as-templates"> - <title>Example Manual Pages to Use as Templates</title> - - <para>Some manual pages are suitable as in-depth examples.</para> - - <informaltable> - <tgroup cols="2"> - <thead> - <row> - <entry>Manual Page</entry> - <entry>Path to Source Location</entry> - </row> - </thead> - - <tbody> - <row> - <entry>&man.cp.1;</entry> - <entry><filename>/usr/src/bin/cp/cp.1</filename></entry> - </row> - - <row> - <entry>&man.vt.4;</entry> - <entry><filename>/usr/src/share/man/man4/vt.4</filename></entry> - </row> - - <row> - <entry>&man.crontab.5;</entry> - <entry><filename>/usr/src/usr.sbin/cron/crontab/crontab.5</filename></entry> - </row> - - <row> - <entry>&man.gpart.8;</entry> - <entry><filename>/usr/src/sbin/geom/class/part/gpart.8</filename></entry> - </row> - </tbody> - </tgroup> - </informaltable> - </sect1> - - <sect1 xml:id="manpages-resources"> - <title>Resources</title> - - <para>Resources for manual page writers:</para> - - <itemizedlist> - <listitem> - <para>&man.man.1;</para> - </listitem> - - <listitem> - <para>&man.mandoc.1;</para> - </listitem> - - <listitem> - <para>&man.groff.mdoc.7;</para> - </listitem> - - <listitem> - <para><link - xlink:href="http://manpages.bsd.lv/mdoc.html">Practical - UNIX Manuals: mdoc</link></para> - </listitem> - - <listitem> - <para><link - xlink:href="http://manpages.bsd.lv/history.html">History - of UNIX Manpages</link></para> - </listitem> - </itemizedlist> - </sect1> -</chapter> diff --git a/en_US.ISO8859-1/books/fdp-primer/overview/chapter.xml b/en_US.ISO8859-1/books/fdp-primer/overview/chapter.xml deleted file mode 100644 index 1d806b1e60..0000000000 --- a/en_US.ISO8859-1/books/fdp-primer/overview/chapter.xml +++ /dev/null @@ -1,273 +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. - ---> -<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-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> meta-package - and <application>Subversion</application>. - This meta-package installs all of the software needed to - edit and build &os; documentation. The - <application>Subversion</application> package is needed to - obtain a working copy of the documentation and generate - patches with.</para> - - <screen>&prompt.root; <userinput>pkg install docproj subversion</userinput></screen> - </step> - - <step> - <para>Optional: to generate PDF documentation, install the - <package>textproc/fop</package> package as it is not - installed by default by <package>textproc/docproj</package>. - </para> - - <screen>&prompt.root; <userinput>pkg install fop</userinput></screen> - </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="https://bugs.FreeBSD.org/bugzilla/enter_bug.cgi?product=Documentation">Problem - Report</link> system. If using the web form, enter a - Summary of <emphasis>[patch] <replaceable>short description - of problem</replaceable></emphasis>. Select the - Component <literal>Documentation</literal>. In the - Description field, enter a short description of the changes - and any important details about them. Use the - <guibutton>[ Add an attachment ]</guibutton> - button to attach the diff file. Finally, use the - <guibutton>[ Submit Bug ]</guibutton> button to - submit your diff to the problem report system.</para> - </step> - </procedure> - </sect1> - - <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="https://www.freebsd.org/index.html"> - https://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> -</chapter> diff --git a/en_US.ISO8859-1/books/fdp-primer/po-translations/chapter.xml b/en_US.ISO8859-1/books/fdp-primer/po-translations/chapter.xml deleted file mode 100644 index cc5681e7a5..0000000000 --- a/en_US.ISO8859-1/books/fdp-primer/po-translations/chapter.xml +++ /dev/null @@ -1,921 +0,0 @@ -<?xml version="1.0" encoding="iso-8859-1"?> -<!-- - The FreeBSD Documentation Project ---> -<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. The <literal>TRANSLATOR</literal> - option is required and already enabled by default in the - <package role="port">textproc/docproj</package> port.</para> - - <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>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>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}/../../.. - -.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>. As this is a simple - article, in this case the <filename>Makefile</filename> - can be used unchanged. The <literal>$&os;...$</literal> - version string on the second 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-literal-dollar"> - <title><literal>$FreeBSD$</literal> - Strings</title> - - <para>The $FreeBSD$ version strings used in - files require special handling. In examples like - <xref linkend="po-translations-creating-example"/>, these - strings are not meant to be expanded. The English documents - use <literal>&dollar;</literal> entities to avoid - including actual literal dollar signs in the file:</para> - - <programlisting>&dollar;FreeBSD&dollar;</programlisting> - - <para>The <literal>&dollar;</literal> entities are not seen - as dollar signs by the version control system and so the - string is not expanded into a version string.</para> - - <para>When a <acronym>PO</acronym> file is created, the - <literal>&dollar;</literal> entities used in examples are - replaced with actual dollar signs. The resulting literal - <literal>$FreeBSD$</literal> string will be - wrongly expanded by the version control system when the file - is committed.</para> - - <para>The same technique as used in the English documents can be - used in the translation. The <literal>&dollar;</literal> - is used to replace the dollar sign in the translation entered - into the <acronym>PO</acronym> editor:</para> - - <programlisting>&dollar;FreeBSD&dollar;</programlisting> - </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. As 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 - includes adding the files to the version control system, setting - additional properties on them, then creating a diff for - submission.</para> - - <para>The diff files created by these examples can be attached 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> - - <example xml:id="po-translations-submitting-spanish"> - <title>Spanish Translation of the NanoBSD Article</title> - - <procedure> - <step> - <para>Add a &os; version string comment as the first - line of the <acronym>PO</acronym> file:</para> - - <programlisting>#$FreeBSD$</programlisting> - </step> - - <step> - <para>Add the <filename>Makefile</filename>, the - <acronym>PO</acronym> file, and the generated - <acronym>XML</acronym> translation 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>Set the - <application>Subversion</application> - <literal>svn:keywords</literal> properties on these files - to <literal>FreeBSD=%H</literal> so - <literal>$FreeBSD$</literal> strings are - expanded into the path, revision, date, and author when - committed:</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>Set the <acronym>MIME</acronym> types of the files. - These are <literal>text/xml</literal> for books and - articles, and - <literal>text/x-gettext-translation</literal> for the - <acronym>PO</acronym> file.</para> - - <screen>&prompt.user; <userinput>svn propset svn:mime-type text/x-gettext-translation es_ES.po</userinput> -property 'svn:mime-type' set on 'es_ES.po' -&prompt.user; <userinput>svn propset svn:mime-type text/xml article.xml</userinput> -property 'svn:mime-type' set on 'article.xml'</screen> - </step> - - <step> - <para>Create a diff of the new files 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> - </step> - </procedure> - </example> - - <example xml:id="po-translations-submitting-korean-utf8"> - <title>Korean <acronym>UTF-8</acronym> Translation of the - Explaining-BSD Article</title> - - <procedure> - <step> - <para>Add a &os; version string comment as the first - line of the <acronym>PO</acronym> file:</para> - - <programlisting>#$FreeBSD$</programlisting> - </step> - - <step> - <para>Add the <filename>Makefile</filename>, the - <acronym>PO</acronym> file, and the generated - <acronym>XML</acronym> translation to - version control:</para> - - <screen>&prompt.user; <userinput>cd ~/doc/ko_KR.UTF-8/articles/explaining-bsd/</userinput> -&prompt.user; <userinput>ls</userinput> -Makefile article.xml ko_KR.po -&prompt.user; <userinput>svn add Makefile article.xml ko_KR.po</userinput> -A Makefile -A article.xml -A ko_KR.po</screen> - </step> - - <step> - <para>Set the <application>Subversion</application> - <literal>svn:keywords</literal> properties on these files - to <literal>FreeBSD=%H</literal> so - <literal>$FreeBSD$</literal> strings are - expanded into the path, revision, date, and author when - committed:</para> - - <screen>&prompt.user; <userinput>svn propset svn:keywords FreeBSD=%H Makefile article.xml ko_KR.po</userinput> -property 'svn:keywords' set on 'Makefile' -property 'svn:keywords' set on 'article.xml' -property 'svn:keywords' set on 'ko_KR.po'</screen> - </step> - - <step> - <para>Set the <acronym>MIME</acronym> types of the files. - These files use the <acronym>UTF-8</acronym> - character set, so that is also specified. To prevent the - version control system from mistaking these files for - binary data, the <literal>fbsd:notbinary</literal> - property is also set:</para> - - <screen>&prompt.user; <userinput>svn propset svn:mime-type 'text/x-gettext-translation; charset=UTF-8' ko_KR.po</userinput> -property 'svn:mime-type' set on 'ko_KR.po' -&prompt.user; <userinput>svn propset fbsd:notbinary yes ko_KR.po</userinput> -property 'fbsd:notbinary' set on 'ko_KR.po' -&prompt.user; <userinput>svn propset svn:mime-type 'text/xml; charset=UTF-8' article.xml</userinput> -property 'svn:mime-type' set on 'article.xml' -&prompt.user; <userinput>svn propset fbsd:notbinary yes article.xml</userinput> -property 'fbsd:notbinary' set on 'article.xml'</screen> - </step> - - <step> - <para>Create a diff of these new files from the - <filename>~/doc/</filename> base directory:</para> - - <screen>&prompt.user; <userinput>cd ~/doc</userinput> -<userinput>svn diff ko_KR.UTF-8/articles/explaining-bsd > /tmp/ko-explaining.diff</userinput></screen> - </step> - </procedure> - </example> - </sect1> -</chapter> diff --git a/en_US.ISO8859-1/books/fdp-primer/psgml-mode/chapter.xml b/en_US.ISO8859-1/books/fdp-primer/psgml-mode/chapter.xml deleted file mode 100644 index 3f2177820f..0000000000 --- a/en_US.ISO8859-1/books/fdp-primer/psgml-mode/chapter.xml +++ /dev/null @@ -1,169 +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. - ---> -<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> (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/en_US.ISO8859-1/books/fdp-primer/see-also/chapter.xml b/en_US.ISO8859-1/books/fdp-primer/see-also/chapter.xml deleted file mode 100644 index 75914209e0..0000000000 --- a/en_US.ISO8859-1/books/fdp-primer/see-also/chapter.xml +++ /dev/null @@ -1,107 +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. - ---> -<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/en_US.ISO8859-1/books/fdp-primer/structure/chapter.xml b/en_US.ISO8859-1/books/fdp-primer/structure/chapter.xml deleted file mode 100644 index 8b6c3e2361..0000000000 --- a/en_US.ISO8859-1/books/fdp-primer/structure/chapter.xml +++ /dev/null @@ -1,314 +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. - ---> -<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 xml:id="structure-document-handbook"> - <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 xml:id="structure-document-handbook-physical"> - <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 xml:id="structure-document-handbook-physical-Makefile"> - <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 xml:id="structure-document-handbook-physical-book-xml"> - <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 - xml:id="structure-document-handbook-physical-chapters-xml"> - <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/en_US.ISO8859-1/books/fdp-primer/stylesheets/chapter.xml b/en_US.ISO8859-1/books/fdp-primer/stylesheets/chapter.xml deleted file mode 100644 index 952c46964c..0000000000 --- a/en_US.ISO8859-1/books/fdp-primer/stylesheets/chapter.xml +++ /dev/null @@ -1,76 +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. - ---> -<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 xml:id="stylesheets-css-documents"> - <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/en_US.ISO8859-1/books/fdp-primer/the-website/chapter.xml b/en_US.ISO8859-1/books/fdp-primer/the-website/chapter.xml deleted file mode 100644 index 1c6feb6dbb..0000000000 --- a/en_US.ISO8859-1/books/fdp-primer/the-website/chapter.xml +++ /dev/null @@ -1,285 +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. - ---> -<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 - 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-docdir"> - <term><varname>DOCDIR</varname></term> - - <listitem> - <para>DOCDIR 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 DOCDIR=/tmp/www make ENGLISH_ONLY=yes WEB_ONLY=yes all install</userinput></screen> - - <para>Changes to static files can usually be tested by viewing - the modified files directly with a web browser. If the site - has been built as shown above, a modified main page can be - viewed with:</para> - - <screen>&prompt.user; <userinput>firefox /tmp/www/data/index.html</userinput></screen> - - <para>Modifications to dynamic files can be tested with a web - server running on the local system. After building the site - as shown above, this - <filename>/usr/local/etc/apache24/httpd.conf</filename> can be - used with <package>www/apache24</package>:</para> - - <programlisting># httpd.conf for testing the FreeBSD website -Define TestRoot "/tmp/www/data" - -# directory for configuration files -ServerRoot "/usr/local" - -Listen 80 - -# minimum required modules -LoadModule authz_core_module libexec/apache24/mod_authz_core.so -LoadModule mime_module libexec/apache24/mod_mime.so -LoadModule unixd_module libexec/apache24/mod_unixd.so -LoadModule cgi_module libexec/apache24/mod_cgi.so -LoadModule dir_module libexec/apache24/mod_dir.so - -# run the webserver as user and group -User www -Group www - -ServerAdmin you@example.com -ServerName fbsdtest - -# deny access to all files -<Directory /> - AllowOverride none - Require all denied -</Directory> - -# allow access to the website directory -DocumentRoot "${TestRoot}" -<Directory "${TestRoot}"> - Options Indexes FollowSymLinks - AllowOverride None - Require all granted -</Directory> - -# prevent access to .htaccess and .htpasswd files -<Files ".ht*"> - Require all denied -</Files> - -ErrorLog "/var/log/httpd-error.log" -LogLevel warn - -# set up the CGI script directory -<Directory "${TestRoot}/cgi"> - AllowOverride None - Options None - Require all granted - Options +ExecCGI - AddHandler cgi-script .cgi -</Directory> - -Include etc/apache24/Includes/*.conf</programlisting> - - <para>Start the web server with</para> - - <screen>&prompt.root; <userinput>service apache24 onestart</userinput></screen> - - <para>The web site can be viewed at <link - xlink:href="http://localhost"/>. Be aware that many links - refer to the real &os; site by name, and those links will - still go to the external site instead of the local test - version. Fully testing the local site will require - temporarily setting <acronym>DNS</acronym> so - <literal>www.FreeBSD.org</literal> resolves to - <literal>localhost</literal> or the local - <acronym>IP</acronym> address.</para> - </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/en_US.ISO8859-1/books/fdp-primer/tools/chapter.xml b/en_US.ISO8859-1/books/fdp-primer/tools/chapter.xml deleted file mode 100644 index ca8eb88553..0000000000 --- a/en_US.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. - ---> -<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 xml:id="tools-required-dtd-entities"> - <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</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 xml:id="tools-optional-software"> - <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> - (<package>editors/emacs</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/en_US.ISO8859-1/books/fdp-primer/translations/chapter.xml b/en_US.ISO8859-1/books/fdp-primer/translations/chapter.xml deleted file mode 100644 index 0c39f75d7b..0000000000 --- a/en_US.ISO8859-1/books/fdp-primer/translations/chapter.xml +++ /dev/null @@ -1,483 +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. - ---> -<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="https://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> - - <para>Please see the complete explanation of using - <application>Subversion</application> in &os; in the <link - xlink:href="&url.books.handbook;/svn.html">&os; - Handbook</link>.</para> - </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="https://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/en_US.ISO8859-1/books/fdp-primer/working-copy/chapter.xml b/en_US.ISO8859-1/books/fdp-primer/working-copy/chapter.xml deleted file mode 100644 index 28f5fc2aa5..0000000000 --- a/en_US.ISO8859-1/books/fdp-primer/working-copy/chapter.xml +++ /dev/null @@ -1,184 +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. - ---> -<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 obtained by - installing the <application>Subversion</application> - package:</para> - - <screen>&prompt.root; <userinput>pkg install subversion</userinput></screen> - - <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/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.xml b/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.xml deleted file mode 100644 index 6116b4d6a3..0000000000 --- a/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.xml +++ /dev/null @@ -1,607 +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. - ---> -<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 xml:id="writing-style-letter-case"> - <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>userland</entry> - <entry /> - <entry>things that apply to user space, not the - kernel</entry> - </row> - - <row> - <entry>web server</entry> - </row> - </tbody> - </tgroup> - </informaltable> - </sect1> -</chapter> diff --git a/en_US.ISO8859-1/books/fdp-primer/xhtml-markup/chapter.xml b/en_US.ISO8859-1/books/fdp-primer/xhtml-markup/chapter.xml deleted file mode 100644 index e9e1cb4ccd..0000000000 --- a/en_US.ISO8859-1/books/fdp-primer/xhtml-markup/chapter.xml +++ /dev/null @@ -1,604 +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. - ---> -<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:https://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/en_US.ISO8859-1/books/fdp-primer/xml-primer/chapter.xml b/en_US.ISO8859-1/books/fdp-primer/xml-primer/chapter.xml deleted file mode 100644 index a91251c25b..0000000000 --- a/en_US.ISO8859-1/books/fdp-primer/xml-primer/chapter.xml +++ /dev/null @@ -1,1423 +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. - ---> -<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>. As 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 xml:id="xml-primer-elements-to-do"> - <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"</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 xml:id="doctype-declaration-fpi"> - <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 cannot 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>Since the &os; Project has not been registered, - the owner string is <literal>-//&os;</literal>. As seen - in the example, the <acronym>W3C</acronym> is 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 xml:id="doctype-declaration-fpi-catalog"> - <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>An <acronym>XML</acronym> document may contain comments. - They may appear anywhere as long as they are not inside tags. - They are even allowed in some locations inside the - <acronym>DTD</acronym> (e.g., between <link - linkend="xml-primer-entities">entity - declarations</link>).</para> - - <para><acronym>XML</acronym> comments start with the string - <quote><literal><!--</literal></quote> and end with the - string <quote><literal>--></literal></quote>.</para> - - <para>Here are some examples of valid <acronym>XML</acronym> - comments:</para> - - <example> - <title><acronym>XML</acronym> Generic Comments</title> - - <programlisting><!-- This is inside the comment --> - -<!--This is another comment--> - -<!-- This is how you - write multiline comments --> - -<p>A simple <!-- Comment inside an element's content --> paragraph.</p></programlisting> - </example> - - <para><acronym>XML</acronym> comments may contain any strings - except <quote><literal>--</literal></quote>:</para> - - <example> - <title>Erroneous <acronym>XML</acronym> Comment</title> - - <programlisting><!-- This comment--is wrong --></programlisting> - </example> - - <sect2 xml:id="xml-primer-comments-to-do"> - <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 entities 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 % entity "<!ENTITY version '1.0'>"> -<!-- use the parameter entity --> -%entity; -]></programlisting> - </example> - - <para>At first sight, parameter entities do not look very - useful, but they make it possible to <link - linkend="xml-primer-include">include other files</link> into - an XML document.</para> - </sect2> - - <sect2 xml:id="xml-primer-to-do"> - <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 xml:id="xml-primer-include-parameter"> - <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 xml:id="xml-primer-include-parameter-to-do"> - <title>To Do…</title> - - <sect3 xml:id="xml-primer-include-general-entities-include"> - <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 xml:id="xml-primer-include-parameter-entities-include"> - <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 xml:id="xml-primer-marked-section-keywords-to-do"> - <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> |