diff options
Diffstat (limited to 'en_US.ISO_8859-1/books/fdp-primer')
17 files changed, 0 insertions, 7478 deletions
diff --git a/en_US.ISO_8859-1/books/fdp-primer/Makefile b/en_US.ISO_8859-1/books/fdp-primer/Makefile deleted file mode 100644 index 3e9ced1ea7..0000000000 --- a/en_US.ISO_8859-1/books/fdp-primer/Makefile +++ /dev/null @@ -1,50 +0,0 @@ -# -# $FreeBSD: doc/en_US.ISO_8859-1/books/fdp-primer/Makefile,v 1.9 2000/07/16 16:40:36 nik Exp $ -# -# Build the FreeBSD Documentation Project Primer. -# - -MAINTAINER=nik@FreeBSD.org - -DOC?= book - -FORMATS?= html-split html - -INSTALL_COMPRESSED?= gz -INSTALL_ONLY_COMPRESSED?= - -# -# SRCS lists the individual SGML files that make up the document. Changes -# to any of these files will force a rebuild -# - -# SGML content -SRCS= book.sgml -SRCS+= overview/chapter.sgml -SRCS+= psgml-mode/chapter.sgml -SRCS+= see-also/chapter.sgml -SRCS+= sgml-markup/chapter.sgml -SRCS+= sgml-primer/chapter.sgml -SRCS+= stylesheets/chapter.sgml -SRCS+= structure/chapter.sgml -SRCS+= doc-build/chapter.sgml -SRCS+= the-website/chapter.sgml -SRCS+= tools/chapter.sgml -SRCS+= translations/chapter.sgml -SRCS+= writing-style/chapter.sgml - -SRCS+= examples/appendix.sgml - -# 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 - -# Entities -SRCS+= chapters.ent - -DOC_PREFIX?= ${.CURDIR}/../../.. - -.include "${DOC_PREFIX}/share/mk/doc.project.mk" diff --git a/en_US.ISO_8859-1/books/fdp-primer/book.sgml b/en_US.ISO_8859-1/books/fdp-primer/book.sgml deleted file mode 100644 index 46559464e1..0000000000 --- a/en_US.ISO_8859-1/books/fdp-primer/book.sgml +++ /dev/null @@ -1,299 +0,0 @@ -<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved. - - Redistribution and use in source (SGML DocBook) and 'compiled' forms - (SGML, HTML, PDF, PostScript, RTF and so forth) with or without - modification, are permitted provided that the following conditions - are met: - - 1. Redistributions of source code (SGML DocBook) must retain the above - copyright notice, this list of conditions and the following - disclaimer as the first lines of this file unmodified. - - 2. Redistributions in compiled form (transformed to other DTDs, - converted to PDF, PostScript, RTF and other formats) must reproduce - the above copyright notice, this list of conditions and the - following disclaimer in the documentation and/or other materials - provided with the distribution. - - THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR - IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES - OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE - DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT, - INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES - (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR - SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) - HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, - STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN - ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE - POSSIBILITY OF SUCH DAMAGE. - - $FreeBSD: doc/en_US.ISO_8859-1/books/fdp-primer/book.sgml,v 1.12 2000/07/16 16:36:17 nik Exp $ ---> - -<!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [ - -<!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"> -%man; - -<!ENTITY % chapters SYSTEM "chapters.ent"> %chapters; -<!ENTITY % not.published "INCLUDE"> -<!-- ENTITY index SYSTEM "index.sgml" --> -]> - -<book> - <bookinfo> - <title>FreeBSD Documentation Project Primer for New Contributors</title> - - <author> - <firstname>Nik</firstname> - <surname>Clayton</surname> - <affiliation> - <address><email>nik@FreeBSD.org</email></address> - </affiliation> - </author> - - <copyright> - <year>1998</year> - <year>1999</year> - <year>2000</year> - <holder role="mailto:nik@FreeBSD.org">Nik Clayton</holder> - </copyright> - - <pubdate role="rcs">$FreeBSD: doc/en_US.ISO_8859-1/books/fdp-primer/book.sgml,v 1.12 2000/07/16 16:36:17 nik Exp $</pubdate> - - <releaseinfo>$FreeBSD: doc/en_US.ISO_8859-1/books/fdp-primer/book.sgml,v 1.12 2000/07/16 16:36:17 nik Exp $</releaseinfo> - - <legalnotice> - <para>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:</para> - - <orderedlist> - <listitem> - <para>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.</para> - </listitem> - - <listitem> - <para>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.</para> - </listitem> - </orderedlist> - - <important> - <para>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.</para> - </important> - </legalnotice> - - <abstract> - <para>Thank you for becoming a part of the FreeBSD Documentation - Project. Your contribution is extremely valuable.</para> - - <para>This primer covers everything you will need to know in order - to start contributing to the FreeBSD Documentation Project, from - the tools and software you will be using (both mandatory and - recommended) to the philosophy behind the Documentation - Project.</para> - - <para>This document is a work in progress, and is not complete. Sections - that are known to be incomplete are indicated with a - <literal>*</literal> in their name.</para> - </abstract> - </bookinfo> - - <preface> - <title>Preface</title> - - <sect1> - <title>Shell Prompts</title> - - <para>The following table shows the default system prompt and superuser - prompt. The examples will use this prompt to indicate which user you - should be running the example as.</para> - - <informaltable frame="none"> - <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><username>root</username></entry> - <entry>&prompt.root;</entry> - </row> - </tbody> - </tgroup> - </informaltable> - </sect1> - - <sect1> - <title>Typographic Conventions</title> - - <para>The following table describes the typographic conventions used in - this book.</para> - - <informaltable frame="none"> - <tgroup cols="2"> - <thead> - <row> - <entry>Meaning</entry> - <entry>Examples</entry> - </row> - </thead> - - <tbody> - <row> - <entry>The name of commands, files, and directories. On screen - computer output.</entry> - <entry><para>Edit your <filename>.login</filename> - file.</para><para>Use <command>ls -a</command> to list all - files.</para><para><screen>You have mail.</screen> - </para></entry> - </row> - - <row> - <entry>What you type, when contrasted with on-screen computer - output.</entry> - - <entry><screen>&prompt.user; <userinput>su</userinput> -Password:</screen></entry> - </row> - - <row> - <entry>Manual page references.</entry> - - <entry>Use <citerefentry> - <refentrytitle>su</refentrytitle> - <manvolnum>1</manvolnum> - </citerefentry> to change user names.</entry> - </row> - - <row> - <entry>User and group names</entry> - - <entry>Only <username>root</username> can do this.</entry> - </row> - - <row> - <entry>Emphasis</entry> - - <entry>You <emphasis>must</emphasis> do this.</entry> - </row> - - <row> - <entry>Command line variables; replace with the real name or - variable.</entry> - - <entry>To delete a file, type <command>rm <filename><replaceable>filename</replaceable></filename></command></entry> - </row> - - <row> - <entry>Environment variables</entry> - - <entry><envar>$HOME</envar> is your home directory.</entry> - </row> - </tbody> - </tgroup> - </informaltable> - </sect1> - - <sect1> - <title>Notes, tips, important information, warnings, and examples</title> - - <para>Within the text appear notes, warnings, and examples.</para> - - <note> - <para>Notes are represented like this, and contain information that - you should take note of, as it may affect what you do.</para> - </note> - - <tip> - <para>Tips are represented like this, and contain information that you - might find useful, or lead to an easier way to do something.</para> - </tip> - - <important> - <para>Important information is represented like this. Typically they - flag extra steps you may need to carry out.</para> - </important> - - <warning> - <para>Warnings are represented like this, and contain information - warning you about possible damage if you do not follow the - instructions. This damage may be physical, to your hardware or to - you, or it may be non-physical, such as the inadvertant deletion of - important files.</para> - </warning> - - <example> - <title>A sample example</title> - - <para>Examples are represented like this, and typically contain - examples you should walk through, or show you what the results of a - particular action should be.</para> - </example> - </sect1> - - <sect1> - <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.sgml-primer; - &chap.sgml-markup; - &chap.stylesheets; - &chap.structure; - &chap.doc-build; - &chap.the-website; - &chap.translations; - &chap.writing-style; - &chap.psgml-mode; - &chap.see-also; - - &app.examples; - -<!-- - &index; ---> -</book> - -<!-- - Local Variables: - mode: sgml - sgml-indent-data: t - sgml-omittag: nil - sgml-always-quote-attributes: t - End: ---> diff --git a/en_US.ISO_8859-1/books/fdp-primer/chapter.decl b/en_US.ISO_8859-1/books/fdp-primer/chapter.decl deleted file mode 100644 index ce0a7ed16a..0000000000 --- a/en_US.ISO_8859-1/books/fdp-primer/chapter.decl +++ /dev/null @@ -1 +0,0 @@ -<!DOCTYPE chapter PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN"> diff --git a/en_US.ISO_8859-1/books/fdp-primer/chapters.ent b/en_US.ISO_8859-1/books/fdp-primer/chapters.ent deleted file mode 100644 index 651a2bd465..0000000000 --- a/en_US.ISO_8859-1/books/fdp-primer/chapters.ent +++ /dev/null @@ -1,25 +0,0 @@ -<!-- - 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 .sgml file is stored. - - Chapters should be listed in the order in which they are referenced. - - $FreeBSD: doc/en_US.ISO_8859-1/books/fdp-primer/chapters.ent,v 1.5 2000/06/23 00:37:53 nik Exp $ ---> - -<!ENTITY chap.overview SYSTEM "overview/chapter.sgml"> -<!ENTITY chap.sgml-primer SYSTEM "sgml-primer/chapter.sgml"> -<!ENTITY chap.tools SYSTEM "tools/chapter.sgml"> -<!ENTITY chap.sgml-markup SYSTEM "sgml-markup/chapter.sgml"> -<!ENTITY chap.stylesheets SYSTEM "stylesheets/chapter.sgml"> -<!ENTITY chap.structure SYSTEM "structure/chapter.sgml"> -<!ENTITY chap.the-website SYSTEM "the-website/chapter.sgml"> -<!ENTITY chap.translations SYSTEM "translations/chapter.sgml"> -<!ENTITY chap.writing-style SYSTEM "writing-style/chapter.sgml"> -<!ENTITY chap.psgml-mode SYSTEM "psgml-mode/chapter.sgml"> -<!ENTITY chap.see-also SYSTEM "see-also/chapter.sgml"> -<!ENTITY chap.doc-build SYSTEM "doc-build/chapter.sgml"> - -<!ENTITY app.examples SYSTEM "examples/appendix.sgml"> diff --git a/en_US.ISO_8859-1/books/fdp-primer/doc-build/chapter.sgml b/en_US.ISO_8859-1/books/fdp-primer/doc-build/chapter.sgml deleted file mode 100644 index 910bf3cf22..0000000000 --- a/en_US.ISO_8859-1/books/fdp-primer/doc-build/chapter.sgml +++ /dev/null @@ -1,501 +0,0 @@ -<!-- 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. - - $Id: chapter.sgml,v 1.1 2000-06-23 00:37:15 nik Exp $ ---> - -<chapter id="doc-build"> - <title>The Documentation Build Process</title> - - <para>This chapter's main purpose is to clearly explain <emphasis>how - the documentation build process is organised</emphasis>, and - <emphasis>how to affect modifications to this process</emphasis>. - </para> - - <para>After you have finished reading this chapter you should:</para> - - <itemizedlist> - <listitem> - <para>Know what you need to build the FDP documentation, in - addition to those mentioned in the <link - linkend="tools">SGML tools chapter</link>.</para> - </listitem> - - <listitem> - <para>Be able to read and understand the - <application>make</application> instructions that are present in - each document's <filename>Makefile</filename>s, as well as an - overview of the <filename>doc.project.mk</filename> includes.</para> - </listitem> - - <listitem> - <para>Be able to customize the build process by using - <application>make</application> variables and - <application>make</application> targets.</para> - </listitem> - </itemizedlist> - - <sect1> - <title>The FreeBSD Documentation Build Toolset</title> - - <para>Here are your tools. Use them every way you can.</para> - - <itemizedlist> - <listitem> - <para>The primary build tool you will need is - <application>make</application>, but specifically - <application>Berkeley Make</application>.</para> - </listitem> - - <listitem> - <para>Package building is handled by FreeBSD's - <application>pkg_create</application>. If you are not using - FreeBSD, you will either have to live without packages, or - compile the source yourself.</para> - </listitem> - - <listitem> - <para><application>gzip</application> is needed to create - compressed versions of the document. - <application>bzip2</application> compression and - <application>zip</application> archives are also supported. - <application>tar</application> is supported, but package - building demands it.</para> - </listitem> - - <listitem> - <para><application>install</application> is the default method - to install the documentation. There are alternatives, - however.</para - </listitem> - </itemizedlist> - - <note> - <para>It is unlikely you will not be able to find these last two, they - are mentioned for completeness.</para> - </note> - </sect1> - - <sect1> - <title>Understanding Makefiles in the Documentation tree</title> - - <para>There are three main types of <filename>Makefile</filename>s - in the FreeBSD Documentation Project tree.</para> - - <itemizedlist> - <listitem> - <para><link linkend="sub-make">Subdirectory - <filename>Makefile</filename>s</link> simply pass - commands to those directories below them.</para> - </listitem> - - <listitem> - <para><link linkend="doc-make">Documentation - <filename>Makefile</filename>s</link> describe the - document(s) that should be produced from this directory.</para> - </listitem> - - <listitem> - <para><link linkend="make-includes"><application>Make</application> - includes</link> are the glue that perform the document production, - and are usually of the form - <filename>doc.<replaceable>xxx</replaceable>.mk</filename>.</para> - </listitem> - </itemizedlist> - - <para><application>Make</application> syntax is quickly revised as - the we explore these types.</para> - - <sect2 id="sub-make"> - <title>Subdirectory Makefiles</title> - - <para>These directories 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>In quick summary, the first four non-empty lines define the - <application>make</application> variables, - <makevar>SUBDIR</makevar>, <makevar>COMPAT_SYMLINK</makevar>, - and <makevar>DOC_PREFIX</makevar>.</para> - - <para>The first <makevar>SUBDIR</makevar> statement, as well as - the <makevar>COMPAT_SYMLINK</makevar> statement, shows how to - assign a value to a variable, overriding any previous - value.</para> - - <para>The second <makevar>SUBDIR</makevar> statement shows how a - value is appended to the current value of a variable. The - <makevar>SUBDIR</makevar> variable is now <literal>articles - books</literal>.</para> - - <para>The <makevar>DOC_PREFIX</makevar> assignment shows how a - value is assigned to the variable, but only if it is not already - defined. This is useful if <makevar>DOC_PREFIX</makevar> is not - where this <filename>Makefile</filename> thinks it is - the user - can override this and provide the correct value.</para> - - <para>Now what does it all mean? <makevar>SUBDIR</makevar> - mentions which subdirectories below this one the build process - should pass any work on to.</para> - - <para><makevar>COMPAT_SYMLINK</makevar> 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><makevar>DOC_PREFIX</makevar> is the path to the root of the - FreeBSD Document Project tree. This is not always that easy to - find, and is also easily overridable, to allow for flexibility. - <makevar>.CURDIR</makevar> is a <application>make</application> - builtin variable with the path to the current directory.</para> - - <para>The final line includes the FreeBSD Documentation Project's - project-wide <application>make</application> system file - <filename>doc.project.mk</filename> which is the glue which - converts these variables into build instructions.</para> - - </sect2> - <sect2 id="doc-make"> - <title>Documentation Makefiles</title> - - <para>These <filename>Makefile</filename>s set a bunch of - <application>make</application> 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.sgml - -DOC_PREFIX?= ${.CURDIR}/../../.. - -.include "$(DOC_PREFIX)/share/mk/docproj.docbook.mk"</programlisting> - - <para>The <makevar>MAINTAINER</makevar> variable is a very - important one. This variable provides the ability to claim - ownership over a document in the FreeBSD Documentation - Project, whereby you gain the responsibility for maintaining - it.</para> - - <para><makevar>DOC</makevar> is the name (sans the - <filename>.sgml</filename> extension) of the main document - created by this directory. <makevar>SRCS</makevar> 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><makevar>FORMATS</makevar> indicates the default formats - that should be built for this document. - <makevar>INSTALL_COMPRESSED</makevar> is the default list of - compression techniques that should be used in the document - build. <makevar>INSTALL_ONLY_COMPRESS</makevar>, empty by - default, should be non-empty if only compressed documents are - desired in the build.</para> - - <note> - <para>We covered optional variable assignments in the - <link linkend="sub-make">previous section</link>.</para> - </note> - - <para>The <makevar>DOC_PREFIX</makevar> and include statements - should be familiar already.</para> - </sect2> - </sect1> - - <sect1 id="make-includes"> - <title>FreeBSD Documentation Project make includes</title> - - <para>This is 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 - <makevar>DOCFORMAT</makevar> is <literal>docbook</literal> - and <makevar>DOC</makevar> is set.</para> - </listitem> - </itemizedlist> - - <sect2> - <title>doc.project.mk</title> - - <para>By inspection:</para> - - <programlisting>DOCFORMAT?= docbook -MAINTAINER?= doc@FreeBSD.org - -PREFIX?= /usr/local -PRI_LANG?= en_US.ISO_8859-1 - -.if defined(DOC) -.if ${DOCFORMAT} == "docbook" -.include "doc.docbook.mk" -.endif -.endif - -.include "doc.subdir.mk" -.include "doc.install.mk"</programlisting> - - <sect3> - - <title>Variables</title> - - <para><makevar>DOCFORMAT</makevar> and <makevar>MAINTAINER</makevar> - are assigned default values, if these are not set by the - document make file.</para> - - <para><makevar>PREFIX</makevar> 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><makevar>PRI_LANG</makevar> 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><makevar>PRI_LANG</makevar> in no way affects what documents - can, or even will, be built. It's main use is creating links to - commonly referenced documents into the FreeBSD documentation - install root.</para> - </note> - </sect3> - - <sect3> - <title>Conditionals</title> - - <para>The <literal>.if defined(DOC)</literal> line is an example of - a <application>make</application> conditional which, like in - other programs, defines behaviour 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 <makevar>DOCFORMAT</makevar> variable is - <literal>"docbook"</literal>, and in this case, includes - <filename>doc.docbook.mk</filename>.</para> - - <para>The two <literal>.endif</literal>s close the two above - conditionals, marking the end of their application.</para> - </sect3> - </sect2> - - <sect2> - <title>doc.subdir.mk</title> - - <para>This is too long to explain by inspection, you should be - able to work it out with the knowledge gained from the previous - chapters, and a little help given here.</para> - - <sect3> - <title>Variables</title> - - <itemizedlist> - <listitem> - <para><makevar>SUBDIR</makevar> is a list of subdirectories - that the build process should go further down - into.</para> - </listitem> - - <listitem> - <para><makevar>ROOT_SYMLINKS</makevar> 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 - <makevar>PRI_LANG</makevar>).</para> - </listitem> - - <listitem> - <para><makevar>COMPAT_SYMLINK</makevar> is described in the - <link linkend="sub-make">Subdirectory Makefile</link> - section.</para> - </listitem> - </itemizedlist> - </sect3> - - <sect3> - <title>Targets and macros</title> - - <para>Dependencies are described by - <literal><replaceable>target</replaceable>: - <replaceable>dependency1 dependency2 ...</replaceable></literal> - tuples, where to build <literal>target</literal>, you need to build - the given dependencies 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 it's 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, <maketarget>_SUBDIRUSE</maketarget> 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 doesn't adjust <makevar>.TARGET</makevar>, 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, <maketarget>clean</maketarget> will use the - <maketarget>_SUBDIRUSE</maketarget> macro after it has - executed the instruction - <command>rm -f ${CLEANFILES}</command>. In effect, this causes - <maketarget>clean</maketarget> to go further and further down - the directory tree, deleting built files as it goes - <emphasis>down</emphasis>, not on the way back up.</para> - - <sect4> - <title>Provided targets</title> - - <itemizedlist> - <listitem> - <para><maketarget>install</maketarget> and - <maketarget>package</maketarget> both go down the - directory tree calling the real versions of themselves - in the subdirectories. - (<maketarget>realinstall</maketarget> and - <maketarget>realpackage</maketarget> - respectively)</para> - </listitem> - - <listitem> - <para><maketarget>clean</maketarget> removes files created - by the build process (and goes down the directory tree - too). <maketarget>cleandir</maketarget> does the same, - and also removes the object directory, if any.</para> - </listitem> - </itemizedlist> - </sect4> - </sect3> - - <sect3> - <title>More on conditionals</title> - - <itemizedlist> - <listitem> - <para><literal>exists</literal> is another condition - function which returns true if the given file exists.</para> - </listitem> - - <listitem> - <para><literal>empty</literal> returns true if the given - variable is empty.</para> - </listitem> - - <listitem> - <para><literal>target</literal> returns true if the given - target does not already exist.</para> - </listitem> - </itemizedlist> - </sect3> - - <sect3> - <title>Looping constructs in make (.for)</title> - - <para><literal>.for</literal> provides a way to repeat a set of - instructions for each space-seperated 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 <makevar>SUBDIR</makevar> 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 <makevar>entry</makevar> being replaced with the value of - the current element.</para> - </sect3> - </sect2> - </sect1> -</chapter> - -<!-- - Local Variables: - mode: sgml - sgml-declaration: "../chapter.decl" - sgml-indent-data: t - sgml-omittag: nil - sgml-always-quote-attributes: t - sgml-parent-document: ("../book.sgml" "part" "chapter") - End: ---> - diff --git a/en_US.ISO_8859-1/books/fdp-primer/examples/appendix.sgml b/en_US.ISO_8859-1/books/fdp-primer/examples/appendix.sgml deleted file mode 100644 index e093732098..0000000000 --- a/en_US.ISO_8859-1/books/fdp-primer/examples/appendix.sgml +++ /dev/null @@ -1,355 +0,0 @@ -<!-- Copyright (c) 2000 Nik Clayton, All rights reserved. - - Redistribution and use in source (SGML DocBook) and 'compiled' forms - (SGML HTML, PDF, PostScript, RTF and so forth) with or without - modification, are permitted provided that the following conditions - are met: - - 1. Redistributions of source code (SGML DocBook) must retain the above - copyright notice, this list of conditions and the following - disclaimer as the first lines of this file unmodified. - - 2. Redistributions in compiled form (transformed to other DTDs, - converted to PDF, PostScript, RTF and other formats) must reproduce - the above copyright notice, this list of conditions and the - following disclaimer in the documentation and/or other materials - provided with the distribution. - - THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR - IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES - OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE - DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT, - INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES - (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR - SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) - HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, - STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN - ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE - POSSIBILITY OF SUCH DAMAGE. - - $FreeBSD: doc/en_US.ISO_8859-1/books/fdp-primer/examples/appendix.sgml,v 1.2 2001/04/17 16:02:19 nik Exp $ ---> - -<appendix id="examples"> - <title>Examples</title> - - <para>This appendix contains example SGML files and command lines you can - use to convert them from one output format to another. If you have - successfully installed the Documentation Project tools then you should - be able to to use these examples directly.</para> - - <para>These examples are not exhaustive—they do not contain all the - elements you might want to use, particularly in your document's front - matter. For more examples of DocBook markup you should examine the SGML - source for this and other documents, available in the - <application>CVSup</application> <literal>doc</literal> collection, or - available online starting at <ulink - url="http://www.FreeBSD.org/cgi/cvsweb.cgi/doc/">http://www.FreeBSD.org/cgi/cvsweb.cgi/doc/</ulink>.</para> - - <para>To avoid confusion, these examples use the standard DocBook 3.1 DTD - rather than the FreeBSD extension. They also use the stock stylesheets - distributed by Norm Walsh, rather than any customisations made to those - stylesheets by the FreeBSD Documentation Project. This makes them more - useful as generic DocBook examples.</para> - - <sect1> - <title>DocBook <sgmltag>book</sgmltag></title> - - <example> - <title>DocBook <sgmltag>book</sgmltag></title> - - <programlisting><![ CDATA [<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.1//EN"> - -<book> - <bookinfo> - <title>An Example Book</title> - - <author> - <firstname>Your first name</firstname> - <surname>Your surname</surname> - <affiliation> - <address><email>foo@example.com</email></address> - </affiliation> - </author> - - <copyright> - <year>2000</year> - <holder>Copyright string here</holder> - </copyright> - - <abstract> - <para>If your book has an abstract then it should go here.</para> - </abstract> - </bookinfo> - - <preface> - <title>Preface</title> - - <para>Your book may have a preface, in which case it should be placed - here.</para> - </preface> - - <chapter> - <title>My first chapter</title> - - <para>This is the first chapter in my book.</para> - - <sect1> - <title>My first section</title> - - <para>This is the first section in my book.</para> - </sect1> - </chapter> -</book>]]></programlisting> - </example> - </sect1> - - <sect1> - <title>DocBook <sgmltag>article</sgmltag></title> - - <example> - <title>DocBook <sgmltag>article</sgmltag></title> - - <programlisting><![ CDATA [<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V4.1//EN"> - -<article> - <articleinfo> - <title>An example article</title> - - <author> - <firstname>Your first name</firstname> - <surname>Your surname</surname> - <affiliation> - <address><email>foo@example.com</email></address> - </affiliation> - </author> - - <copyright> - <year>2000</year> - <holder>Copyright string here</holder> - </copyright> - - <abstract> - <para>If your article has an abstract then it should go here.</para> - </abstract> - </articleinfo> - - <sect1> - <title>My first section</title> - - <para>This is the first section in my article.</para> - - <sect2> - <title>My first sub-section</title> - - <para>This is the first sub-section in my article.</para> - </sect2> - </sect1> -</article>]]></programlisting> - </example> - </sect1> - - <sect1> - <title>Producing formatted output</title> - - <para>This section assumes that you have installed the software listed in - the <filename>textproc/docproj</filename> port, either by hand, or by - using the port. Further, it is assumed that your software is installed - in subdirectories under <filename>/usr/local/</filename>, and the - directory where binaries have been installed is in your - <envar>PATH</envar>. Adjust the paths as necessary for your - system.</para> - - <sect2> - <title>Using Jade</title> - - <example> - <title>Converting DocBook to HTML (one large file)</title> - - <screen>&prompt.user; <userinput>jade -V nochunks \ <co id="examples-co-jade-1-nochunks"> - -c /usr/local/share/sgml/docbook/dsssl/modular/catalog \ <co id="examples-co-jade-1-catalog"> - -c /usr/local/share/sgml/docbook/catalog \ - -c /usr/local/share/sgml/jade/catalog \ - -d /usr/local/share/sgml/docbook/dsssl/modular/html/docbook.dsl <co id="examples-co-jade-1-dsssl"> - -t sgml <co id="examples-co-jade-1-transform"> file.sgml > file.html <co id="examples-co-jade-1-filename"></userinput></screen> - - <calloutlist> - <callout arearefs="examples-co-jade-1-nochunks"> - <para>Specifies the <literal>nochunks</literal> parameter to the - stylesheets, forcing all output to be written to - <abbrev>STDOUT</abbrev> (using Norm Walsh's stylesheets).</para> - </callout> - - <callout arearefs="examples-co-jade-1-catalog"> - <para>Specifies the catalogs that Jade will need to process. - Three catalogs are required. The first is a catalog that - contains information about the DSSSL stylesheets. The second - contains information about the DocBook DTD. The third contains - information specific to Jade.</para> - </callout> - - <callout arearefs="examples-co-jade-1-dsssl"> - <para>Specifies the full path to the DSSSL stylesheet that Jade - will use when processing the document.</para> - </callout> - - <callout arearefs="examples-co-jade-1-transform"> - <para>Instructs Jade to perform a - <emphasis>transformation</emphasis> from one DTD to another. In - this case, the input is being transformed from the DocBook DTD - to the HTML DTD.</para> - </callout> - - <callout arearefs="examples-co-jade-1-filename"> - <para>Specifies the file that Jade should process, and redirects - output to the specified <filename>.html</filename> file.</para> - </callout> - </calloutlist> - </example> - - <example> - <title>Converting DocBook to HTML (several small files)</title> - - <screen>&prompt.user; <userinput>jade \ - -c /usr/local/share/sgml/docbook/dsssl/modular/catalog \ <co id="examples-co-jade-2-catalog"> - -c /usr/local/share/sgml/docbook/catalog \ - -c /usr/local/share/sgml/jade/catalog \ - -d /usr/local/share/sgml/docbook/dsssl/modular/html/docbook.dsl <co id="examples-co-jade-2-dsssl"> - -t sgml <co id="examples-co-jade-2-transform"> <replaceable>file</replaceable>.sgml <co id="examples-co-jade-2-filename"></userinput></screen> - - <calloutlist> - <callout arearefs="examples-co-jade-2-catalog"> - <para>Specifies the catalogs that Jade will need to process. - Three catalogs are required. The first is a catalog that - contains information about the DSSSL stylesheets. The second - contains information about the DocBook DTD. The third contains - information specific to Jade.</para> - </callout> - - <callout arearefs="examples-co-jade-2-dsssl"> - <para>Specifies the full path to the DSSSL stylesheet that Jade - will use when processing the document.</para> - </callout> - - <callout arearefs="examples-co-jade-2-transform"> - <para>Instructs Jade to perform a - <emphasis>transformation</emphasis> from one DTD to another. In - this case, the input is being transformed from the DocBook DTD - to the HTML DTD.</para> - </callout> - - <callout arearefs="examples-co-jade-2-filename"> - <para>Specifies the file that Jade should process. The - stylesheets determine how the individual HTML files will be - named, and the name of the <quote>root</quote> file (i.e., the - one that contains the start of the document.</para> - </callout> - </calloutlist> - - <para>This example may still only generate one HTML file, depending on - the structure of the document you are processing, and the - stylesheet's rules for splitting output.</para> - </example> - - <example id="examples-docbook-postscript"> - <title>Converting DocBook to Postscript</title> - - <para>The source SGML file must be converted to a TeX file.</para> - - <screen>&prompt.user; <userinput>jade -Vtex-backend \ <co id="examples-co-jade-3-tex-backend"> - -c /usr/local/share/sgml/docbook/dsssl/modular/catalog \ <co id="examples-co-jade-3-catalog"> - -c /usr/local/share/sgml/docbook/catalog \ - -c /usr/local/share/sgml/jade/catalog \ - -d /usr/local/share/sgml/docbook/dsssl/modular/print/docbook.dsl <co id="examples-co-jade-3-dsssl"> - -t tex <co id="examples-co-jade-3-tex"> <replaceable>file</replaceable>.sgml</userinput></screen> - - <calloutlist> - <callout arearefs="examples-co-jade-3-tex-backend"> - <para>Customises the stylesheets to use various options - specific to producing output for TeX.</para> - </callout> - - <callout arearefs="examples-co-jade-3-catalog"> - <para>Specifies the catalogs that Jade will need to process. Three - catalogs are required. The first is a catalog that contains - information about the DSSSL stylesheets. The second contains - information about the DocBook DTD. The third contains - information specific to Jade.</para> - </callout> - - <callout arearefs="examples-co-jade-3-dsssl"> - <para>Specifies the full path to the DSSSL stylesheet that - Jade will use when processing the document.</para> - </callout> - - <callout arearefs="examples-co-jade-3-tex"> - <para>Instructs Jade to convert the output to TeX.</para> - </callout> - </calloutlist> - - <para>The generated <filename>.tex</filename> file must now be run - through <command>tex</command>, specifying the - <literal>&jadetex</literal> macro package.</para> - - <screen>&prompt.user; <userinput>tex "&jadetex" <replaceable>file</replaceable>.tex</userinput></screen> - - <para>You have to run <command>tex</command> <emphasis>at - least</emphasis> three times. The first run processes the - document, and determines areas of the document which are referenced - from other parts of the document, for use in indexing, and so - on.</para> - - <para>Do not be alarmed if you see warning messages such as - <literal>LaTeX Warning: Reference `136' on page 5 undefined on input - line 728.</literal> at this point.</para> - - <para>The second run reprocesses the document now that certain pieces - of information are known (such as the document's page length). This - allows index entries and other cross-references to be fixed - up.</para> - - <para>The third pass performs any final cleanup necessary.</para> - - <para>The output from this stage will be - <filename><replaceable>file</replaceable>.dvi</filename>.</para> - - <para>Finally, run <command>dvips</command> to convert the - <filename>.dvi</filename> file to Postscript.</para> - - <screen>&prompt.user; <userinput>dvips -o <replaceable>file</replaceable>.ps <replaceable>file.dvi</replaceable></userinput></screen> - </example> - - <example> - <title>Converting DocBook to PDF</title> - - <para>The first part of this process is identical to that when - converting DocBook to Postscript, using the same - <command>jade</command> command line (<xref - linkend="examples-docbook-postscript">).</para> - - <para>When the <filename>.tex</filename> file has been generated you - run TeX as before. However, use the &pdfjadetex macro package - instead.</para> - - <screen>&prompt.user; <userinput>tex "&pdfjadetex" <replaceable>file</replaceable>.tex</userinput></screen> - - <para>Again, run this command three times.</para> - - <para>This will generate - <filename><replaceable>file</replaceable>.pdf</filename>, which does - not need to be processed any further.</para> - </example> - </sect2> - </sect1> -</appendix> - -<!-- - Local Variables: - mode: sgml - sgml-declaration: "../appendix.decl" - sgml-indent-data: t - sgml-omittag: nil - sgml-always-quote-attributes: t - sgml-parent-document: ("../book.sgml" "part" "appendix") - End: ---> diff --git a/en_US.ISO_8859-1/books/fdp-primer/overview/chapter.sgml b/en_US.ISO_8859-1/books/fdp-primer/overview/chapter.sgml deleted file mode 100644 index aff71edf08..0000000000 --- a/en_US.ISO_8859-1/books/fdp-primer/overview/chapter.sgml +++ /dev/null @@ -1,182 +0,0 @@ -<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved. - - Redistribution and use in source (SGML DocBook) and 'compiled' forms - (SGML HTML, PDF, PostScript, RTF and so forth) with or without - modification, are permitted provided that the following conditions - are met: - - 1. Redistributions of source code (SGML DocBook) must retain the above - copyright notice, this list of conditions and the following - disclaimer as the first lines of this file unmodified. - - 2. Redistributions in compiled form (transformed to other DTDs, - converted to PDF, PostScript, RTF and other formats) must reproduce - the above copyright notice, this list of conditions and the - following disclaimer in the documentation and/or other materials - provided with the distribution. - - THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR - IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES - OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE - DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT, - INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES - (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR - SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) - HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, - STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN - ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE - POSSIBILITY OF SUCH DAMAGE. - - $FreeBSD: doc/en_US.ISO_8859-1/books/fdp-primer/overview/chapter.sgml,v 1.5 2000/07/07 18:38:23 dannyboy Exp $ ---> - -<chapter id="overview"> - <title>Overview</title> - - <para>Welcome to the FreeBSD Documentation Project. Good quality - documentation is very important to the success of FreeBSD, and the - FreeBSD Documentation Project (FDP) is how a lot of that documentation - is produced. Your contributions are very valuable.</para> - - <para>This document's main purpose is to clearly explain <emphasis>how - the FDP is organised</emphasis>, <emphasis>how to write and submit - documentation to the FDP</emphasis>, and <emphasis>how to - effectively use the tools available to you when writing - documentation</emphasis>.</para> - - <para><indexterm> - <primary>Membership</primary> - </indexterm> -Every one is welcome to join the FDP. There is no minimum - membership requirement, no quota of documentation you need to - produce per month. All you need to do is subscribe to the - <email>freebsd-doc@FreeBSD.org</email> mailing list.</para> - - <para>After you have finished reading this document you should:</para> - - <itemizedlist> - <listitem> - <para>Know which documentation is maintained by the FDP.</para> - </listitem> - - <listitem> - <para>Be able to read and understand the SGML source code for the - documentation maintained by the FDP.</para> - </listitem> - - <listitem> - <para>Be able to make changes to the documentation.</para> - </listitem> - - <listitem> - <para>Be able to submit your changes back for review and eventual - inclusion in the FreeBSD documentation.</para> - </listitem> - </itemizedlist> - - <sect1> - <title>The FreeBSD Documentation Set</title> - - <para>The FDP is responsible for four categories of FreeBSD - documentation.</para> - - <variablelist> - <varlistentry> - <term>Manual pages</term> - - <listitem> - <para>The English language system manual pages are not written by - the FDP, as they are part of the base system. However, the FDP can - (and has) re-worded parts of existing manual pages to make them - clearer, or to correct inaccuracies.</para> - - <para>The translation teams are responsible for translating the - system manual pages in to different languages. These translations - are kept within the FDP.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>FAQ</term> - - <listitem> - <para>The FAQ aims to address (in short question and answer format) - questions that are asked, or should be asked, on the various - mailing lists and newsgroups devoted to FreeBSD. The format does - not permit long and comprehensive answers.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Handbook</term> - - <listitem> - <para>The Handbook aims to be the comprehensive on-line resource and - reference for FreeBSD users.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Web site</term> - - <listitem> - <para>This is the main FreeBSD presence on the World Wide Web, - visible at <ulink - url="http://www.FreeBSD.org/">http://www.FreeBSD.org/</ulink> - and many mirrors around the world. The web site is many people's - first exposure to FreeBSD.</para> - </listitem> - </varlistentry> - </variablelist> - - <para>These four groups of documentation are all available in the - FreeBSD CVS tree. This means that the logs of changes to these - files are visible to anyone, and anyone can use a program such as - <application>CVSup</application> or - <application>CTM</application> to keep local copies of - this documentation.</para> - - <para>In addition, many people have written tutorials or other web - sites relating to FreeBSD. Some of these are stored in the CVS - repository as well (where the author has agreed to this). In - other cases the author has decided to keep his documentation - separate from the main FreeBSD repository. The FDP endeavours to - provide links to as much of this documentation as - possible.</para> - </sect1> - - <sect1> - <title>Before you start</title> - - <para>This document assumes that you already know:</para> - - <itemizedlist> - <listitem> - <para>How to maintain an up-to-date local copy of the FreeBSD - documentation by maintaining a local copy of the - FreeBSD CVS repository (using <application>CVS</application> - and either <application>CVSup</application> or - <application>CTM</application>) or by using - <application>CVSup</application> to download just a - <emphasis>checked-out</emphasis> copy.</para> - </listitem> - - <listitem> - <para>How to download and install new software using either the - FreeBSD Ports system or &man.pkg.add.1;.</para> - </listitem> - </itemizedlist> - </sect1> -</chapter> - -<!-- - Local Variables: - mode: sgml - sgml-declaration: "../chapter.decl" - sgml-indent-data: t - sgml-omittag: nil - sgml-always-quote-attributes: t - sgml-parent-document: ("../book.sgml" "part" "chapter") - End: ---> - diff --git a/en_US.ISO_8859-1/books/fdp-primer/psgml-mode/chapter.sgml b/en_US.ISO_8859-1/books/fdp-primer/psgml-mode/chapter.sgml deleted file mode 100644 index 8abcde6496..0000000000 --- a/en_US.ISO_8859-1/books/fdp-primer/psgml-mode/chapter.sgml +++ /dev/null @@ -1,150 +0,0 @@ -<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved. - - Redistribution and use in source (SGML DocBook) and 'compiled' forms - (SGML HTML, PDF, PostScript, RTF and so forth) with or without - modification, are permitted provided that the following conditions - are met: - - 1. Redistributions of source code (SGML DocBook) must retain the above - copyright notice, this list of conditions and the following - disclaimer as the first lines of this file unmodified. - - 2. Redistributions in compiled form (transformed to other DTDs, - converted to PDF, PostScript, RTF and other formats) must reproduce - the above copyright notice, this list of conditions and the - following disclaimer in the documentation and/or other materials - provided with the distribution. - - THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR - IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES - OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE - DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT, - INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES - (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR - SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) - HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, - STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN - ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE - POSSIBILITY OF SUCH DAMAGE. - - $FreeBSD: doc/en_US.ISO_8859-1/books/fdp-primer/psgml-mode/chapter.sgml,v 1.3 1999/09/06 06:52:41 peter Exp $ ---> - -<chapter id="psgml-mode"> - <title>Using <literal>sgml-mode</literal> with - <application>Emacs</application></title> - - <para>Recent versions of Emacs or Xemacs (available from the ports - collection) contain a very useful package called PSGML. Automatically - invoked when a file with the <filename>.sgml</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 <literal>sgml-insert-element</literal>. You will be - prompted for the name of the element to insert at the current point. - You can use the TAB 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 <literal>sgml-change-element-name</literal>. 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 <literal>sgml-tag-region</literal>. Select some text (move - to start of text, C-space, move to end of text, C-space) 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 <literal>sgml-untag-element</literal>. 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 <literal>sgml-fill-element</literal>. 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 <sgmltag>programlisting</sgmltag> - elements, so run this command with care.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>C-c C-a</command></term> - - <listitem> - <para>Runs <literal>sgml-edit-attributes</literal>. Opens a second - buffer containing a list of all the attributes for the closest - enclosing element, and their current values. Use TAB to navigate - between attributes, <command>C-k</command> to remove an existing - value and replace it with a new one, <command>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 <literal>sgml-validate</literal>. 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> - </variablelist> - - <para>Doubtless there are other useful functions of this mode, but those are - the ones I use most often.</para> -</chapter> - - -<!-- - Local Variables: - mode: sgml - sgml-declaration: "../chapter.decl" - sgml-indent-data: t - sgml-omittag: nil - sgml-always-quote-attributes: t - sgml-parent-document: ("../book.sgml" "part" "chapter") - End: ---> - diff --git a/en_US.ISO_8859-1/books/fdp-primer/see-also/chapter.sgml b/en_US.ISO_8859-1/books/fdp-primer/see-also/chapter.sgml deleted file mode 100644 index 9f8ac6dd06..0000000000 --- a/en_US.ISO_8859-1/books/fdp-primer/see-also/chapter.sgml +++ /dev/null @@ -1,121 +0,0 @@ -<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved. - - Redistribution and use in source (SGML DocBook) and 'compiled' forms - (SGML HTML, PDF, PostScript, RTF and so forth) with or without - modification, are permitted provided that the following conditions - are met: - - 1. Redistributions of source code (SGML DocBook) must retain the above - copyright notice, this list of conditions and the following - disclaimer as the first lines of this file unmodified. - - 2. Redistributions in compiled form (transformed to other DTDs, - converted to PDF, PostScript, RTF and other formats) must reproduce - the above copyright notice, this list of conditions and the - following disclaimer in the documentation and/or other materials - provided with the distribution. - - THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR - IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES - OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE - DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT, - INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES - (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR - SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) - HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, - STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN - ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE - POSSIBILITY OF SUCH DAMAGE. - - $FreeBSD: doc/en_US.ISO_8859-1/books/fdp-primer/see-also/chapter.sgml,v 1.4 1999/09/06 06:52:41 peter Exp $ ---> - -<chapter id="see-also"> - <title>See Also</title> - - <para>This document is deliberately not an exhaustive discussion of SGML, - the DTDs listed, and the FreeBSD Documentation Project. For more - information about these, you are encouraged to see the following web - sites.</para> - - <sect1> - <title>The FreeBSD Documentation Project</title> - - <itemizedlist> - <listitem> - <para><ulink url="http://www.FreeBSD.org/docproj/">The FreeBSD - Documentation Project web pages</ulink></para> - </listitem> - - <listitem> - <para><ulink url="http://www.FreeBSD.org/handbook/">The FreeBSD Handbook</ulink></para> - </listitem> - </itemizedlist> - </sect1> - - <sect1> - <title>SGML</title> - - <itemizedlist> - <listitem> - <para><ulink url="http://www.oasis-open.org/cover/">The SGML/XML web - page</ulink>, a comprehensive SGML resource</para> - </listitem> - - <listitem> - <para><ulink - url='http://etext.virginia.edu/bin/tei-tocs?div=DIV1&id=SG">http://etext.virginia.edu/bin/tei-tocs?div=DIV1&id=SG'>Gentle introduction to SGML</ulink></para> - </listitem> - </itemizedlist> - </sect1> - - <sect1> - <title>HTML</title> - - <itemizedlist> - <listitem> - <para><ulink url="http://www.w3.org/">The World Wide Web - Consortium</ulink></para> - </listitem> - - <listitem> - <para><ulink url="http://www.w3.org/TR/REC-html40/">The HTML 4.0 - specification</ulink></para> - </listitem> - </itemizedlist> - </sect1> - - <sect1> - <title>DocBook</title> - - <itemizedlist> - <listitem> - <para><ulink url="http://www.oasis-open.org/docbook/">The DocBook - Technical Committee</ulink>, maintainers of the DocBook DTD</para> - </listitem> - </itemizedlist> - </sect1> - - <sect1> - <title>The Linux Documentation Project</title> - - <itemizedlist> - <listitem> - <para><ulink url="http://www.linuxdoc.org/">The Linux Documentation - Project web pages</ulink></para> - </listitem> - </itemizedlist> - </sect1> -</chapter> - -<!-- - Local Variables: - mode: sgml - sgml-declaration: "../chapter.decl" - sgml-indent-data: t - sgml-omittag: nil - sgml-always-quote-attributes: t - sgml-parent-document: ("../book.sgml" "part" "chapter") - End: ---> - diff --git a/en_US.ISO_8859-1/books/fdp-primer/sgml-markup/chapter.sgml b/en_US.ISO_8859-1/books/fdp-primer/sgml-markup/chapter.sgml deleted file mode 100644 index d497523e7b..0000000000 --- a/en_US.ISO_8859-1/books/fdp-primer/sgml-markup/chapter.sgml +++ /dev/null @@ -1,2563 +0,0 @@ -<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved. - - Redistribution and use in source (SGML DocBook) and 'compiled' forms - (SGML HTML, PDF, PostScript, RTF and so forth) with or without - modification, are permitted provided that the following conditions - are met: - - 1. Redistributions of source code (SGML DocBook) must retain the above - copyright notice, this list of conditions and the following - disclaimer as the first lines of this file unmodified. - - 2. Redistributions in compiled form (transformed to other DTDs, - converted to PDF, PostScript, RTF and other formats) must reproduce - the above copyright notice, this list of conditions and the - following disclaimer in the documentation and/or other materials - provided with the distribution. - - THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR - IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES - OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE - DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT, - INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES - (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR - SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) - HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, - STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN - ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE - POSSIBILITY OF SUCH DAMAGE. - - $FreeBSD: doc/en_US.ISO_8859-1/books/fdp-primer/sgml-markup/chapter.sgml,v 1.19 2001/04/17 16:02:54 nik Exp $ ---> - -<chapter id="sgml-markup"> - <title>SGML Markup</title> - - <para>This chapter describes the three markup languages you will encounter - when you contribute to the FreeBSD documentation project. Each section - describes the markup language, and details the markup that you are likely - to want to use, or that is already in use.</para> - - <para>These markup languages contain a large number of elements, and it can - be confusing sometimes to know which element to use for a particular - situation. This section goes through the elements you are most likely to - need, and gives examples of how you would use them.</para> - - <para>This is <emphasis>not</emphasis> an exhaustive list of elements, since - that would just reiterate the documentation for each language. The aim of - this section is to list those elements more likely to be useful to you. - If you have a question about how best to markup a particular piece of - content, please post it to the FreeBSD Documentation Project mailing list - <email>freebsd-doc@FreeBSD.org</email>.</para> - - <note> - <title>Inline vs. 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> - <title>HTML</title> - - <para>HTML, the HyperText Markup Language, is the markup language of - choice on the World Wide Web. More information can be found at - <URL:<ulink - url="http://www.w3.org/">http://www.w3.org/</ulink>>.</para> - - <para>HTML is used to markup pages on the FreeBSD web site. It should not - (generally) be used to mark up other documention, since DocBook offers a - far richer set of elements to choose from. Consequently, you will - normally only encounter HTML pages if you are writing for the web - site.</para> - - <para>HTML has gone through a number of versions, 1, 2, 3.0, 3.2, and the - latest, 4.0 (available in both <emphasis>strict</emphasis> and - <emphasis>loose</emphasis> variants).</para> - - <para>The HTML DTDs are available from the ports collection in the - <filename>textproc/html</filename> port. They are automatically - installed as part of the <filename>textproc/docproj</filename> - port.</para> - - <sect2> - <title>Formal Public Identifier (FPI)</title> - - <para>There are a number of HTML FPIs, depending upon the version (also - known as the level) of HTML that you want to declare your document to - be compliant with.</para> - - <para>The majority of HTML documents on the FreeBSD web site comply with - the loose version of HTML 4.0.</para> - - <programlisting>PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting> - </sect2> - - <sect2> - <title>Sectional elements</title> - - <para>An HTML document is normally split in to 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 the content that will be displayed - to the user.</para> - - <para>These sections are indicated with <sgmltag>head</sgmltag> and - <sgmltag>body</sgmltag> elements respectively. These elements are - contained within the top-level <sgmltag>html</sgmltag> element.</para> - - <example> - <title>Normal HTML document structure</title> - - <programlisting><html> - <head> - <title><replaceable>The document's title</replaceable></title> - </head> - - <body> - - … - - </body> -</html></programlisting> - </example> - </sect2> - - <sect2> - <title>Block elements</title> - - <sect3> - <title>Headings</title> - - <para>HTML allows you to denote headings in your document, at up to - six different levels.</para> - - <para>The largest and most prominent heading is <sgmltag>h1</sgmltag>, - then <sgmltag>h2</sgmltag>, continuing down to - <sgmltag>h6</sgmltag>.</para> - - <para>The element's content is the text of the heading.</para> - - <example> - <title><sgmltag>h1</sgmltag>, <sgmltag>h2</sgmltag>, etc.</title> - - <para>Use:</para> - - <programlisting><![ CDATA [<h1>First section</h1> - -<!-- Document introduction goes here --> - -<h2>This is the heading for the first section</h2> - -<!-- Content for the first section goes here --> - -<h3>This is the heading for the first sub-section</h3> - -<!-- Content for the first sub-section goes here --> - -<h2>This is the heading for the second section</h2> - -<!-- Content for the second section goes here -->]]></programlisting> - </example> - - <para>Generally, an HTML page should have one first level heading - (<sgmltag>h1</sgmltag>). This can contain many second level - headings (<sgmltag>h2</sgmltag>), which can in turn contain many - third level headings. Each - <sgmltag>h<replaceable>n</replaceable></sgmltag> element should have - the same element, but one further up the hierarchy, preceeding it. - Leaving gaps in the numbering is to be avoided.</para> - - <example> - <title>Bad ordering of - <sgmltag>h<replaceable>n</replaceable></sgmltag> elements</title> - - <para>Use:</para> - - <programlisting><![ CDATA [<h1>First section</h1> - -<!-- Document introduction --> - -<h3>Sub-section</h3> - -<!-- This is bad, <h2> has been left out -->]]></programlisting> - </example> - </sect3> - - <sect3> - <title>Paragraphs</title> - - <para>HTML supports a single paragraph element, - <sgmltag>p</sgmltag>.</para> - - <example> - <title><sgmltag>p</sgmltag></title> - - <para>Use:</para> - - <programlisting><![ CDATA [<p>This is a paragraph. It can contain just about any - other element.</p>]]></programlisting> - </example> - </sect3> - - <sect3> - <title>Block quotations</title> - - <para>A block quotation is an extended quotation from another document - that should not appear within the current paragraph.</para> - - <example> - <title><sgmltag>blockquote</sgmltag></title> - - <para>Use:</para> - - <programlisting><![ CDATA [<p>A small excerpt from the US Constitution:</p> - -<blockquote>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.</blockquote>]]></programlisting> - </example> - </sect3> - - <sect3> - <title>Lists</title> - - <para>You can present the user with three types of lists, ordered, - unordered, and definition.</para> - - <para>Typically, each entry in an ordered list will be numbered, while - each entry in an unordered list will be preceded by a bullet point. - Definition lists are composed of two sections for each entry. The - first section is the term being defined, and the second section is - the definition of the term.</para> - - <para>Ordered lists are indicated by the <sgmltag>ol</sgmltag> - element, unordered lists by the <sgmltag>ul</sgmltag> element, and - definition lists by the <sgmltag>dl</sgmltag> element.</para> - - <para>Ordered and unordered lists contain listitems, indicated by the - <sgmltag>li</sgmltag> element. A listitem can contain textual - content, or it may be further wrapped in one or more - <sgmltag>p</sgmltag> elements.</para> - - <para>Definition lists contain definition terms - (<sgmltag>dt</sgmltag>) and definition descriptions - (<sgmltag>dd</sgmltag>). A definition term can only contain inline - elements. A definition description can contain other block - elements.</para> - - <example> - <title><sgmltag>ul</sgmltag> and <sgmltag>ol</sgmltag></title> - - <para>Use:</para> - - <programlisting><![ CDATA [<p>An unordered list. Listitems will probably be - preceeded by bullets.</p> - -<ul> - <li>First item</li> - - <li>Second item</li> - - <li>Third item</li> -</ul> - -<p>An ordered list, with list items consisting of multiple - paragraphs. Each item (note: not each paragraph) will be - numbered.</p> - -<ol> - <li><p>This is the first item. It only has one paragraph.</p></li> - - <li><p>This is the first paragraph of the second item.</p> - - <p>This is the second paragraph of the second item.</p></li> - - <li><p>This is the first and only paragraph of the third - item.</p></li> -</ol>]]></programlisting> - </example> - - <example> - <title>Definition lists with <sgmltag>dl</sgmltag></title> - - <para>Use:</para> - - <programlisting><![ CDATA [<dl> - <dt>Term 1</dt> - - <dd><p>Paragraph 1 of definition 1.</p></dd> - - <p>Paragraph 2 of definition 1.</p></dd> - - <dt>Term 2</dt> - - <dd><p>Paragraph 1 of definition 2.</p></dd> - - <dt>Term 3</dt> - - <dd>Paragraph 1 of definition 3. Note that the <p> - element is not required in the single paragraph case.</dd> -</dl>]]></programlisting> - </example> - </sect3> - - <sect3> - <title>Pre-formatted text</title> - - <para>You can indicate that text should be shown to the user exactly - as it is in the file. Typically, this means that the text is shown - in a fixed font, multiple spaces are not merged in to one, and line - breaks in the text are significant.</para> - - <para>In order to do this, wrap the content in the - <sgmltag>pre</sgmltag> element.</para> - - <example> - <title><sgmltag>pre</sgmltag></title> - - <para>You could use <sgmltag>pre</sgmltag> to mark up an e-mail - message;</para> - - <programlisting><![ CDATA [<pre> From: nik@FreeBSD.org - To: freebsd-doc@FreeBSD.org - Subject: New documentation available - - There's a new copy of my primer for contributers to the FreeBSD - Documentation Project available at - - <URL:http://people.FreeBSD.org/~nik/primer/index.html> - - Comments appreciated. - - N</pre>]]></programlisting> - </example> - </sect3> - - <sect3> - <title>Tables</title> - - <note> - <para>Most text-mode browsers (such as Lynx) do not render tables - particularly effectively. If you are relying on the tabular - display of your content, you should consider using alternative - markup to prevent confusion.</para> - </note> - - <para>Mark up tabular information using the <sgmltag>table</sgmltag> - element. A table consists of one or more table rows - (<sgmltag>tr</sgmltag>), each containing one or more cells of table - data (<sgmltag>td</sgmltag>). 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 you do not need to include the - <sgmltag>p</sgmltag> element.</para> - - <example> - <title>Simple use of <sgmltag>table</sgmltag></title> - - <para>Use:</para> - - <programlisting><![ CDATA [<p>This is a simple 2x2 table.</p> - -<table> - <tr> - <td>Top left cell</td> - - <td>Top right cell</td> - </tr> - - <tr> - <td>Bottom left cell</td> - - <td>Bottom right cell</td> - </tr> -</table>]]></programlisting></example> - - <para>A cell can span multiple rows and columns. To indicate this, - add the <literal>rowspan</literal> and/or <literal>colspan</literal> - attributes, with values indicating the number of rows of columns - that should be spanned.</para> - - <example> - <title>Using <literal>rowspan</literal></title> - - <para>Use:</para> - - <programlisting><![ CDATA [<p>One tall thin cell on the left, two short cells next to - it on the right.</p> - -<table> - <tr> - <td rowspan="2">Long and thin</td> - </tr> - - <tr> - <td>Top cell</td> - - <td>Bottom cell</td> - </tr> -</table>]]></programlisting> - </example> - - <example> - <title>Using <literal>colspan</literal></title> - - <para>Use:</para> - - <programlisting><![ CDATA [<p>One long cell on top, two short cells below it.</p> - -<table> - <tr> - <td colspan="2">Top cell</td> - </tr> - - <tr> - <td>Bottom left cell</td> - - <td>Bottom right cell</td> - </tr> -</table>]]></programlisting> - </example> - - <example> - <title>Using <literal>rowspan</literal> and - <literal>colspan</literal> together</title> - - <para>Use:</para> - - <programlisting><![ CDATA [<p>On a 3x3 grid, the top left block is a 2x2 set of - cells merged in to one. The other cells are normal.</p> - -<table> - <tr> - <td colspan="2" rowspan="2">Top left large cell</td> - - <td>Top right cell</td> - </tr> - - <tr> - <!-- Because the large cell on the left merges in to - this row, the first <td> will occur on its - right --> - - <td>Middle right cell</td> - </tr> - - <tr> - <td>Bottom left cell</td> - - <td>Bottom middle cell</td> - - <td>Bottom right cell</td> - </tr> -</table>]]></programlisting> - </example> - </sect3> - </sect2> - - <sect2> - <title>In-line elements</title> - - <sect3> - <title>Emphasising information</title> - - <para>You have two levels of emphasis available in HTML, - <sgmltag>em</sgmltag> and <sgmltag>strong</sgmltag>. - <sgmltag>em</sgmltag> is for a normal level of emphasis and - <sgmltag>strong</sgmltag> indicates stronger emphasis.</para> - - <para>Typically, <sgmltag>em</sgmltag> is rendered in italic and - <sgmltag>strong</sgmltag> is rendered in bold. This is not always - the case, however, and you should not rely on it.</para> - - <example> - <title><sgmltag>em</sgmltag> and <sgmltag>strong</sgmltag></title> - - <para>Use:</para> - - <programlisting><![ CDATA [<p><em>This</em> has been emphasised, while - <strong>this</strong> has been strongly emphasised.</p>]]></programlisting> - </example> - </sect3> - - <sect3> - <title>Bold and italics</title> - - <para>Because HTML includes presentational markup, you can also - indicate that particular content should be rendered in bold or - italic. The elements are <sgmltag>b</sgmltag> and - <sgmltag>i</sgmltag> respectively.</para> - - <example> - <title><sgmltag>b</sgmltag> and <sgmltag>i</sgmltag></title> - - <programlisting><![ CDATA [<p><b>This</b> is in bold, while <i>this</i> is - in italics.</p>]]></programlisting> - </example> - </sect3> - - <sect3> - <title>Indicating fixed pitch text</title> - - <para>If you have content that should be rendered in a fixed pitch - (typewriter) typeface, use <sgmltag>tt</sgmltag> (for - “teletype”).</para> - - <example> - <title><sgmltag>tt</sgmltag></title> - - <para>Use:</para> - - <programlisting><![ CDATA [<p>This document was originally written by - Nik Clayton, who can be reached by e-mail as - <tt>nik@FreeBSD.org</tt>.</p>]]></programlisting> - </example> - </sect3> - - <sect3> - <title>Content size</title> - - <para>You can indicate that content should be shown in a larger or - smaller font. There are three ways of doing this.</para> - - <orderedlist> - <listitem> - <para>Use <sgmltag>big</sgmltag> and <sgmltag>small</sgmltag> - around the content you wish to change size. These tags can be - nested, so <literal><big><big>This is much - bigger</big></big></literal> is possible.</para> - </listitem> - - <listitem> - <para>Use <sgmltag>font</sgmltag> with the <literal>size</literal> - attribute set to <literal>+1</literal> or <literal>-1</literal> - respectively. This has the same effect as using - <sgmltag>big</sgmltag> or <sgmltag>small</sgmltag>. However, - the use of this approach is deprecated.</para> - </listitem> - - <listitem> - <para>Use <sgmltag>font</sgmltag> with the <literal>size</literal> - attribute set to a number between 1 and 7. The default font size - is <literal>3</literal>. This approach is deprecated.</para> - </listitem> - </orderedlist> - - <example> - <title><sgmltag>big</sgmltag>, <sgmltag>small</sgmltag>, and - <sgmltag>font</sgmltag></title> - - <para>The following fragments all do the same thing.</para> - - <programlisting><![ CDATA [<p>This text is <small>slightly smaller</small>. But - this text is <big>slightly bigger</big>.</p> - -<p>This text is <font size="-1">slightly smaller</font>. But - this text is <font size="+1">slightly bigger</font.</p> - -<p>This text is <font size="2">slightly smaller</font>. But - this text is <font size="4">slightly bigger</font>.</p>]]></programlisting> - </example> - </sect3> - </sect2> - - <sect2> - <title>Links</title> - - <note> - <para>Links are also in-line elements.</para> - </note> - - <sect3> - <title>Linking to other documents on the WWW</title> - - <para>In order to include a link to another document on the WWW you - must know the URL of the document you want to link to.</para> - - <para>The link is indicated with <sgmltag>a</sgmltag>, and the - <literal>href</literal> attribute contains the URL of the target - document. The content of the element becomes the link, and is - normally indicated to the user in some way (underlining, change of - colour, different mouse cursor when over the link, and so - on).</para> - - <example> - <title>Using <literal><a href="..."></literal></title> - - <para>Use:</para> - - <programlisting><![ CDATA [<p>More information is available at the - <a href="http://www.FreeBSD.org/">FreeBSD web site</a>.</p>]]></programlisting> - </example> - - <para>These links will take the user to the top of the chosen - document.</para> - </sect3> - - <sect3> - <title>Linking to other parts of documents</title> - - <para>Linking to a point within another document (or within the same - document) requires that the document author include anchors that you - can link to.</para> - - <para>Anchors are indicated with <sgmltag>a</sgmltag> and the - <literal>name</literal> attribute instead of - <literal>href</literal>.</para> - - <example> - <title>Using <literal><a name="..."></literal></title> - - <para>Use:</para> - - <programlisting><![ CDATA [<p><a name="para1">This</a> paragraph can be referenced - in other links with the name <tt>para1</tt>.</p>]]></programlisting> - </example> - - <para>To link to a named part of a document, write a normal link to - that document, but include the name of the anchor after a - <literal>#</literal> symbol.</para> - - <example> - <title>Linking to a named part of another document</title> - - <para>Assume that the <literal>para1</literal> example resides in a - document called <filename>foo.html</filename>.</para> - - <programlisting><![ CDATA [<p>More information can be found in the - <a href="foo.html#para1">first paragraph</a> of - <tt>foo.html</tt>.</p>]]></programlisting> - </example> - - <para>If you are linking to a named anchor within the same document - then you can omit the document's URL, and just include the name of - the anchor (with the preceeding <literal>#</literal>).</para> - - <example> - <title>Linking to a named part of the same document</title> - - <para>Assume that the <literal>para1</literal> example resides in - this document</para> - - <programlisting><![ CDATA [<p>More information can be found in the - <a href="#para1">first paragraph</a> of this - document.</p>]]></programlisting> - </example> - </sect3> - </sect2> - </sect1> - - <sect1> - <title>DocBook</title> - - <para>DocBook was designed by the <ulink - url="http://www.oreilly.com/davenport/">Davenport Group</ulink> to be - a DTD for writing technical documentation. As such, and unlike LinuxDoc - and HTML, 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> - - <note> - <title><literal>formal</literal> vs. <literal>informal</literal></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 information - version of the element. The informal version will not have a - title.</para> - </note> - - <para>The DocBook DTD is available from the ports collection in the - <filename>textproc/docbook</filename> port. It is automatically - installed as part of the <filename>textproc/docproj</filename> - port.</para> - - <sect2> - <title>FreeBSD extensions</title> - - <para>The FreeBSD Documentation Project has extended the DocBook DTD by - adding some new elements. These elements serve to make some of the - markup more precise.</para> - - <para>Where a FreeBSD specific element is listed below it is clearly - marked.</para> - - <para>Throughout the rest of this document, the term - “DocBook” is used to mean the FreeBSD extended DocBook - DTD.</para> - - <note> - <para>There is nothing about these extensions that is FreeBSD - specific, 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 get in - touch with Nik Clayton <email>nik@FreeBSD.org</email>.</para> - </note> - - <para>The FreeBSD extensions are not (currently) in the ports - collection. They are stored in the FreeBSD CVS tree, as <ulink - url="http://www.freebsd.org/cgi/cvsweb.cgi/doc/share/sgml/freebsd.dtd">doc/share/sgml/freebsd.dtd</ulink>.</para> - </sect2> - - <sect2> - <title>Formal Public Identifier (FPI)</title> - - <para>In compliance with the DocBook guidelines for writing FPIs for - DocBook customisations, the FPI for the FreeBSD extended DocBook DTD - is;</para> - - <programlisting>PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN"</programlisting> - </sect2> - - <sect2> - <title>Document structure</title> - - <para>DocBook allows you to structure your documentation in several - ways. In the FreeBSD Documentation Project we are using two primary - types of DocBook document: the book and the article.</para> - - <para>A book is organised into <sgmltag>chapter</sgmltag>s. This is a - mandatory requirement. There may be <sgmltag>part</sgmltag>s between - the book and the chapter to provide another layer of organisation. - 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 <sgmltag>sect1</sgmltag> element. If a section - contains another section then use the <sgmltag>sect2</sgmltag> - element, and so on, up to <sgmltag>sect5</sgmltag>.</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 organised into one or more - sections, using the same <sgmltag>sect1</sgmltag> (and - <sgmltag>sect2</sgmltag> and so on) elements that are used in - books.</para> - - <para>Obviously, you should consider the nature of the documentation you - are writing in order to decide 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 <ulink url="http://www.FreeBSD.org/tutorials/">FreeBSD - tutorials</ulink> are all marked up as articles, while this - document, the <ulink url="http://www.FreeBSD.org/FAQ/">FreeBSD - FAQ</ulink>, and the <ulink - url="http://www.FreeBSD.org/handbook/">FreeBSD Handbook</ulink> are - all marked up as books.</para> - - <sect3> - <title>Starting a book</title> - - <para>The content of the book is contained within the - <sgmltag>book</sgmltag> 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 should be contained within - <sgmltag>bookinfo</sgmltag>.</para> - - <example> - <title>Boilerplate <sgmltag>book</sgmltag> with - <sgmltag>bookinfo</sgmltag></title> - - <!-- Can't put this in a marked section because of the - replaceable elements --> - <programlisting><book> - <bookinfo> - <title><replaceable>Your title here</replaceable></title> - - <author> - <firstname><replaceable>Your first name</replaceable></firstname> - <surname><replaceable>Your surname</replaceable></surname> - <affiliation> - <address><email><replaceable>Your e-mail address</replaceable></email></address> - </affiliation> - </author> - - <copyright> - <year><replaceable>1998</replaceable></year> - <holder role="mailto:<replaceable>your e-mail address</replaceable>"><replaceable>Your name</replaceable></holder> - </copyright> - - <pubdate role="rcs">$Date$</pubdate> - - <releaseinfo>$Id$</releaseinfo> - - <abstract> - <para><replaceable>Include an abstract of the book's contents here.</replaceable></para> - </abstract> - </bookinfo> - - … - -</book></programlisting> - </example> - </sect3> - - <sect3> - <title>Starting an article</title> - - <para>The content of the article is contained within the - <sgmltag>article</sgmltag> 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 should be contained within - <sgmltag>articleinfo</sgmltag>.</para> - - <example> - <title>Boilerplate <sgmltag>article</sgmltag> with - <sgmltag>articleinfo</sgmltag></title> - - <!-- Can't put this in a marked section because of the - replaceable elements --> - <programlisting><article> - <articleinfo> - <title><replaceable>Your title here</replaceable></title> - - <author> - <firstname><replaceable>Your first name</replaceable></firstname> - <surname><replaceable>Your surname</replaceable></surname> - <affiliation> - <address><email><replaceable>Your e-mail address</replaceable></email></address> - </affiliation> - </author> - - <copyright> - <year><replaceable>1998</replaceable></year> - <holder role="mailto:<replaceable>your e-mail address</replaceable>"><replaceable>Your name</replaceable></holder> - </copyright> - - <pubdate role="rcs">$Date$</pubdate> - - <releaseinfo>$Id$</releaseinfo> - - <abstract> - <para><replaceable>Include an abstract of the article's contents here.</replaceable></para> - </abstract> - </articleinfo> - - … - -</article></programlisting> - </example> - </sect3> - <sect3> - <title>Indicating chapters</title> - - <para>Use <sgmltag>chapter</sgmltag> to mark up your chapters. Each - chapter has a mandatory <sgmltag>title</sgmltag>. Articles do not - contain chapters, they are reserved for books.</para> - - <example> - <title>A simple chapter</title> - - <programlisting><![ CDATA [<chapter> - <title>The chapter's title</title> - - ... -</chapter>]]></programlisting> - </example> - - <para>A chapter cannot be empty; it must contain elements in addition - to <sgmltag>title</sgmltag>. If you need to include an empty - chapter then just use an empty paragraph.</para> - - <example> - <title>Empty chapters</title> - - <programlisting><![ CDATA [<chapter> - <title>This is an empty chapter</title> - - <para></para> -</chapter>]]></programlisting> - </example> - </sect3> - - <sect3> - <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 - <sgmltag>sect<replaceable>n</replaceable></sgmltag> element. The - <replaceable>n</replaceable> indicates the section number, which - identifies the section level.</para> - - <para>The first <sgmltag>sect<replaceable>n</replaceable></sgmltag> is - <sgmltag>sect1</sgmltag>. You can have one or more of these in a - chapter. They can contain one or more <sgmltag>sect2</sgmltag> - elements, and so on, down to <sgmltag>sect5</sgmltag>.</para> - - <example> - <title>Sections in chapters</title> - - <programlisting><![ RCDATA [<chapter> - <title>A sample chapter</title> - - <para>Some text in the chapter.</para> - - <sect1> - <title>First section (1.1)</title> - - … - </sect1> - - <sect1> - <title>Second section (1.2)</title> - - <sect2> - <title>First sub-section (1.2.1)</title> - - <sect3> - <title>First sub-sub-section (1.2.1.1)</title> - - … - </sect3> - </sect2> - - <sect2> - <title>Second sub-section (1.2.2)</title> - - … - </sect2> - </sect1> -</chapter>]]></programlisting> - </example> - - <note> - <para>This example includes section numbers in the section titles. - You should not do this in your documents. Adding the section - numbers is carried out the by the stylesheets (of which more - later), and you do not need to manage them yourself.</para> - </note> - </sect3> - - <sect3> - <title>Subdividing using <sgmltag>part</sgmltag>s</title> - - <para>You can introduce another layer of organisation between - <sgmltag>book</sgmltag> and <sgmltag>chapter</sgmltag> with one or - more <sgmltag>part</sgmltag>s. This cannot be done in an - <sgmltag>article</sgmltag>.</para> - - <programlisting><![ CDATA [<part> - <title>Introduction</title> - - <chapter> - <title>Overview</title> - - ... - </chapter> - - <chapter> - <title>What is FreeBSD?</title> - - ... - </chapter> - - <chapter> - <title>History</title> - - ... - </chapter> -</part>]]></programlisting> - </sect3> - </sect2> - - <sect2> - <title>Block elements</title> - - <sect3> - <title>Paragraphs</title> - - <para>DocBook supports three types of paragraphs: - <sgmltag>formalpara</sgmltag>, <sgmltag>para</sgmltag>, and - <sgmltag>simpara</sgmltag>.</para> - - <para>Most of the time you will only need to use - <sgmltag>para</sgmltag>. <sgmltag>formalpara</sgmltag> includes a - <sgmltag>title</sgmltag> element, and <sgmltag>simpara</sgmltag> - disallows some elements from within <sgmltag>para</sgmltag>. Stick - with <sgmltag>para</sgmltag>.</para> - - <example> - <title><sgmltag>para</sgmltag></title> - - <para>Use:</para> - - <programlisting><![ CDATA [<para>This is a paragraph. It can contain just about any - other element.</para> ]]></programlisting> - - <para>Appearance:</para> - - <para>This is a paragraph. It can contain just about any other - element.</para> - </example> - </sect3> - - <sect3> - <title>Block quotations</title> - - <para>A block quotation is an extended quotation from another document - that should not appear within the current paragraph. You will - probably only need it infrequently.</para> - - <para>Blockquotes can optionally contain a title and an attribution - (or they can be left untitled and unattributed).</para> - - <example> - <title><sgmltag>blockquote</sgmltag></title> - - <para>Use:</para> - - <programlisting><![ CDATA [<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>]]></programlisting> - - <para>Appearance:</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> - </sect3> - - <sect3> - <title>Tips, notes, warnings, cautions, important information and - sidebars.</title> - - <para>You may need to include extra information separate from the - main body of the text. Typically this is “meta” - information that the user should be aware of.</para> - - <para>Depending on the nature of the information, one of - <sgmltag>tip</sgmltag>, <sgmltag>note</sgmltag>, - <sgmltag>warning</sgmltag>, <sgmltag>caution</sgmltag>, and - <sgmltag>important</sgmltag> should be used. Alternatively, if the - information is related to the main text but is not one of the above, - use <sgmltag>sidebar</sgmltag>.</para> - - <para>The circumstances in which to choose one of these elements over - another is unclear. The DocBook documentation suggests;</para> - - <itemizedlist> - <listitem> - <para>A Note is for information that should be heeded by all - readers.</para> - </listitem> - - <listitem> - <para>An Important element is a variation on Note.</para> - </listitem> - - <listitem> - <para>A Caution is for information regarding possible data loss - or software damage.</para> - </listitem> - - <listitem> - <para>A Warning is for information regarding possible hardware - damage or injury to life or limb.</para> - </listitem> - </itemizedlist> - - <example> - <title><sgmltag>warning</sgmltag></title> - - <para>Use:</para> - - <programlisting><![ CDATA [<warning> - <para>Installing FreeBSD may make you want to delete Windows from your - harddisk.</para> -</warning>]]></programlisting> - </example> - - <!-- Need to do this outside of the example --> - <warning> - <para>Installing FreeBSD may make you want to delete Windows from - your harddisk.</para> - </warning> - </sect3> - - <sect3> - <title>Lists and procedures</title> - - <para>You will often need to list pieces of information to the user, - or present them with a number of steps that must be carried out in - order to accomplish a particular goal.</para> - - <para>In order to do this, use <sgmltag>itemizedlist</sgmltag>, - <sgmltag>orderedlist</sgmltag>, or - <sgmltag>procedure</sgmltag><footnote><para>There are other types of - list element in DocBook, but we're not concerned with those at - the moment.</para> - </footnote> - </para> - - <para><sgmltag>itemizedlist</sgmltag> and - <sgmltag>orderedlist</sgmltag> are similar to their counterparts in - HTML, <sgmltag>ul</sgmltag> and <sgmltag>ol</sgmltag>. Each one - consists of one or more <sgmltag>listitem</sgmltag> elements, and - each <sgmltag>listitem</sgmltag> contains one or more block - elements. The <sgmltag>listitem</sgmltag> elements are analagous to - HTML's <sgmltag>li</sgmltag> tags. However, unlike HTML, they are - required.</para> - - <para><sgmltag>procedure</sgmltag> is slightly different. It consists - of <sgmltag>step</sgmltag>s, which may in turn consists of more - <sgmltag>step</sgmltag>s or <sgmltag>substep</sgmltag>s. Each - <sgmltag>step</sgmltag> contains block elements.</para> - - <example> - <title><sgmltag>itemizedlist</sgmltag>, - <sgmltag>orderedlist</sgmltag>, and - <sgmltag>procedure</sgmltag></title> - - <para>Use:</para> - - <programlisting><![ CDATA [<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> - -<procedure> - <step> - <para>Do this.</para> - </step> - - <step> - <para>Then do this.</para> - </step> - - <step> - <para>And now do this.</para> - </step> -</procedure>]]></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> - - <!-- Can't have <procedure> inside <example>, so this is a cheat --> - - <procedure> - <step> - <para>Do this.</para> - </step> - - <step> - <para>Then do this.</para> - </step> - - <step> - <para>And now do this.</para> - </step> - </procedure> - </sect3> - - <sect3> - <title>Showing file samples</title> - - <para>If you want to show a fragment of a file (or perhaps a complete - file) to the user, wrap it in the <sgmltag>programlisting</sgmltag> - element.</para> - - <para>White space and line breaks within - <sgmltag>programlisting</sgmltag> <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><sgmltag>programlisting</sgmltag></title> - - <para>Use:</para> - - <programlisting><![ CDATA[<para>When you have finished, your program should look like - this;</para> - -<programlisting>#include <stdio.h> - -int -main(void) -{ - printf("hello, world\n"); -}</programlisting>]]></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 you have finished, your program should look like - this;</para> - - <programlisting>#include <stdio.h> - -int -main(void) -{ - printf("hello, world\n"); -}</programlisting> - </example> - </sect3> - - <sect3> - <title>Callouts</title> - - <para>A callout is a mechanism for referring back to an earlier piece - of text or specific position within an earlier example without - linking to it within the text.</para> - - <para>To do this, mark areas of interest in your example - (<sgmltag>programlisting</sgmltag>, - <sgmltag>literallayout</sgmltag>, or whatever) with the - <sgmltag>co</sgmltag> element. Each element must have a unique - <literal>id</literal> assigned to it. After the example include a - <sgmltag>calloutlist</sgmltag> that refers back to the example and - provides additional commentary.</para> - - <example> - <title><sgmltag>co</sgmltag> and - <sgmltag>calloutlist</sgmltag></title> - - <programlisting><![ CDATA[<para>When you have finished, your program should look like - this;</para> - -<programlisting>#include <stdio.h> <co id="co-ex-include"> - -int <co id="co-ex-return"> -main(void) -{ - printf("hello, world\n"); <co 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>]]></programlisting> - - <para>Appearance:</para> - - <para>When you have finished, your program should look like - this;</para> - - <programlisting>#include <stdio.h> <co id="co-ex-include"> - -int <co id="co-ex-return"> -main(void) -{ - printf("hello, world\n"); <co 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> - </sect3> - - <sect3> - <title>Tables</title> - - <para>Unlike HTML, you do not need to use tables for layout purposes, - as the stylesheet handles those issues for you. 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 <sgmltag>table</sgmltag> element. This contains at least one - <sgmltag>tgroup</sgmltag> element, which specifies (as an attribute) - the number of columns in this table group. Within the tablegroup - you can then have one <sgmltag>thead</sgmltag> element, which - contains elements for the table headings (column headings), and one - <sgmltag>tbody</sgmltag> which contains the body of the - table.</para> - - <para>Both <sgmltag>tgroup</sgmltag> and <sgmltag>thead</sgmltag> - contain <sgmltag>row</sgmltag> elements, which in turn contain - <sgmltag>entry</sgmltag> elements. Each <sgmltag>entry</sgmltag> - element specifies one cell in the table.</para> - - <example> - <title><sgmltag>informaltable</sgmltag></title> - - <para>Use:</para> - - <programlisting><![ CDATA [<informaltable> - <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>]]></programlisting> - - <para>Appearance:</para> - - <informaltable> - <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>If you don't want a border around the table the - <literal>frame</literal> attribute can be added to the - <sgmltag>informaltable</sgmltag> element with a value of - <literal>none</literal> (i.e., <literal><informaltable - frame="none"></literal>).</para> - - <example> - <title>Tables where <literal>frame="none"</literal></title> - - <para>Appearance:</para> - - <informaltable frame="none"> - <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> - </sect3> - - <sect3> - <title>Examples for the user to follow</title> - - <para>A lot of the time you need to show examples for the user to - follow. Typically, these will consist of dialogs with the computer; - the user types in a command, the user gets a response back, they - type in another command, and so on.</para> - - <para>A number of distinct elements and entities come in to play - here.</para> - - <variablelist> - <varlistentry> - <term><sgmltag>screen</sgmltag></term> - - <listitem> - <para>Everything the user sees in this example will be on the - computer screen, so the next element is - <sgmltag>screen</sgmltag>.</para> - - <para>Within <sgmltag>screen</sgmltag>, white space is - significant.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><sgmltag>prompt</sgmltag>, - <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 OS, command - shell, or application. These should be marked up using - <sgmltag>prompt</sgmltag>.</para> - - <para>As a special case, the two shell prompts for the normal - user and the root user have been provided as entities. Every - time you want 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 <sgmltag>prompt</sgmltag>.</para> - - <note> - <para><literal>&prompt.root;</literal> and - <literal>&prompt.user;</literal> are FreeBSD - extensions to DocBook, and are not part of the original - DTD.</para> - </note> - </listitem> - </varlistentry> - - <varlistentry> - <term><sgmltag>userinput</sgmltag></term> - - <listitem> - <para>When displaying text that the user should type in, wrap it - in <sgmltag>userinput</sgmltag> tags. It will probably be - displayed differently to the user.</para> - </listitem> - </varlistentry> - </variablelist> - - <example> - <title><sgmltag>screen</sgmltag>, <sgmltag>prompt</sgmltag>, and - <sgmltag>userinput</sgmltag></title> - - <para>Use:</para> - - <programlisting><![ CDATA [<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>]]></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 <sgmltag>programlisting</sgmltag>. Reserve - <sgmltag>programlisting</sgmltag> for showing fragments of files - outside the context of user actions.</para> - </note> - </sect3> - </sect2> - - <sect2> - <title>In-line elements</title> - - <sect3> - <title>Emphasising information</title> - - <para>When you want to emphasise a particular word or phrase, use - <sgmltag>emphasis</sgmltag>. 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 your document, no equivalent of HTML's <sgmltag>b</sgmltag> - and <sgmltag>i</sgmltag>. If the information you are presenting is - important then consider presenting it in - <sgmltag>important</sgmltag> rather than - <sgmltag>emphasis</sgmltag>.</para> - - <example> - <title><sgmltag>emphasis</sgmltag></title> - - <para>Use:</para> - - <programlisting><![ CDATA [<para>FreeBSD is without doubt <emphasis>the</emphasis> - premiere Unix like operating system for the Intel architecture.</para>]]></programlisting> - - <para>Appearance:</para> - - <para>FreeBSD is without doubt <emphasis>the</emphasis> premiere Unix - like operating system for the Intel architecture.</para> - </example> - </sect3> - - <sect3> - <title>Applications, commands, options, and cites</title> - - <para>You will frequently want to refer to both applications and - commands when writing for the Handbook. The distinction between - them is simple: an application is the name for a suite (or possibly - just 1) of programs that fulfil a particular task. A command is the - name of a program that the user can run.</para> - - <para>In addition, you will occasionally need to list one or more of - the options that a command might take.</para> - - <para>Finally, you will often want to list a command with its manual - section number, in the “command(number)” format so - common in Unix manuals.</para> - - <para>Mark up application names with - <sgmltag>application</sgmltag>.</para> - - <para>When you want to list a command with its manual section number - (which should be most of the time) the DocBook element is - <sgmltag>citerefentry</sgmltag>. This will contain a further two - elements, <sgmltag>refentrytitle</sgmltag> and - <sgmltag>manvolnum</sgmltag>. The content of - <sgmltag>refentrytitle</sgmltag> is the name of the command, and the - content of <sgmltag>manvolnum</sgmltag> is the manual page - section.</para> - - <para>This can be cumbersome to write, and so a series of <link - linkend="sgml-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/sgml/man-refs.ent</filename>, and can be - referred to using this FPI:</para> - - <programlisting>PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"</programlisting> - - <para>Therefore, the introduction to your documentation will probably - look like 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 <sgmltag>command</sgmltag> when you want to include a - command name “in-line” but present it as something the - user should type in.</para> - - <para>Use <sgmltag>option</sgmltag> to mark up a command's - options.</para> - - <para>This can be confusing, and sometimes the choice is not always - clear. Hopefully this example makes it clearer.</para> - - <example> - <title>Applications, commands, and options.</title> - - <para>Use:</para> - - <programlisting><![ CDATA [<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.8;, and &man.newaliases.8; - 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>]]></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>, <citerefentry> - <refentrytitle>mailq</refentrytitle> - <manvolnum>8</manvolnum> - </citerefentry>, and <citerefentry> - <refentrytitle>newaliases</refentrytitle> - <manvolnum>8</manvolnum> - </citerefentry> 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> - </sect3> - - <sect3> - <title>Files, directories, extensions</title> - - <para>Whenever you wish to refer to the name of a file, a directory, - or a file extension, use <sgmltag>filename</sgmltag>.</para> - - <example> - <title><sgmltag>filename</sgmltag></title> - - <para>Use:</para> - - <programlisting><![ CDATA [<para>The SGML source for the Handbook in English can be - found in <filename>/usr/doc/en/handbook/</filename>. The first - file is called <filename>handbook.sgml</filename> in that - directory. You should also see a <filename>Makefile</filename> - and a number of files with a <filename>.ent</filename> - extension.</para>]]></programlisting> - - <para>Appearance:</para> - - <para>The SGML source for the Handbook in English can be found in - <filename>/usr/doc/en/handbook/</filename>. The first file is - called <filename>handbook.sgml</filename> in that directory. You - should also see a <filename>Makefile</filename> and a number of - files with a <filename>.ent</filename> extension.</para> - </example> - </sect3> - - <sect3> - <title>Devices</title> - - <note> - <title>FreeBSD extension</title> - - <para>These elements are part of the FreeBSD extension to DocBook, - and do not exist in the original DocBook DTD.</para> - </note> - - <para>When referring to devices you have two choices. You can either - refer to the device as it appears in <filename>/dev</filename>, or - you can use the name of the device as it appears in the kernel. For - this latter course, use <sgmltag>devicename</sgmltag>.</para> - - <para>Sometimes you will not have a choice. Some devices, such as - networking cards, do not have entries in <filename>/dev</filename>, - or the entries are markedly different from those entries.</para> - - <example> - <title><sgmltag>devicename</sgmltag></title> - - <para>Use:</para> - - <programlisting><![ CDATA [<para><devicename>sio</devicename> is used for serial - communication in FreeBSD. <devicename>sio</devicename> manifests - through a number of entries in <filename>/dev</filename>, including - <filename>/dev/ttyd0</filename> and <filename>/dev/cuaa0</filename>.</para> - -<para>By contrast, the networking devices, such as - <devicename>ed0</devicename> do not appear in <filename>/dev</filename>. - -<para>In MS-DOS, the first floppy drive is referred to as - <devicename>a:</devicename>. In FreeBSD it is - <filename>/dev/fd0</filename>.</para>]]></programlisting> - - <para>Appearance:</para> - - <para><devicename>sio</devicename> is used for serial communication - in FreeBSD. <devicename>sio</devicename> manifests through a - number of entries in <filename>/dev</filename>, including - <filename>/dev/ttyd0</filename> and - <filename>/dev/cuaa0</filename>.</para> - - <para>By contrast, the networking devices, such as - <devicename>ed0</devicename> do not appear in - <filename>/dev</filename>.</para> - - <para>In MS-DOS, the first floppy drive is referred to as - <devicename>a:</devicename>. In FreeBSD it is - <filename>/dev/fd0</filename>.</para> - </example> - </sect3> - - <sect3> - <title>Hosts, domains, IP addresses, and so forth</title> - - <note> - <title>FreeBSD extension</title> - - <para>These elements are part of the FreeBSD extension to DocBook, - and do not exist in the original DocBook DTD.</para> - </note> - - <para>You can markup identification information for networked - computers (hosts) in several ways, depending on the nature of the - information. All of them use <sgmltag>hostid</sgmltag> as the - element, with the <literal>role</literal> attribute selecting the - type of the marked up information.</para> - - <variablelist> - <varlistentry> - <term>No role attribute, or - <literal>role="hostname"</literal></term> - - <listitem> - <para>With no role attribute (i.e., - <sgmltag>hostid</sgmltag>...<sgmltag>hostid</sgmltag> the - marked up information is the simple hostname, such as - <literal>freefall</literal> or <literal>wcarchive</literal>. - You can explicitly specify this with - <literal>role="hostname"</literal>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>role="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>role="fqdn"</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>role="ipaddr"</literal></term> - - <listitem> - <para>The text is an IP address, probably expressed as a dotted - quad.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>role="ip6addr"</literal></term> - - <listitem> - <para>The text is an IPv6 address.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>role="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.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>role="mac"</literal></term> - - <listitem> - <para>The text is an ethernet MAC address, expressed as a series - of 2 digit hexadecimal numbers seperated by colons.</para> - </listitem> - </varlistentry> - </variablelist> - - <example> - <title><sgmltag>hostid</sgmltag> and roles</title> - - <para>Use:</para> - - <programlisting><![ CDATA [<para>The local machine can always be referred to by the - name <hostid>localhost</hostid>, which will have the IP address - <hostid role="ipaddr">127.0.0.1</hostid>.</para> - -<para>The <hostid role="domainname">FreeBSD.org</hostid> domain - contains a number of different hosts, including - <hostid role="fqdn">freefall.FreeBSD.org</hostid> and - <hostid role="fqdn">bento.FreeBSD.org</hostid>.</para> - -<para>When adding an IP alias to an interface (using - <command>ifconfig</command>) <emphasis>always</emphasis> use a - netmask of <hostid role="netmask">255.255.255.255</hostid> - (which can also be expressed as <hostid - role="netmask">0xffffffff</hostid>.</para> - -<para>The MAC address uniquely identifies every network card in - in existence. A typical MAC address looks like <hostid - role="mac">08:00:20:87:ef:d0</hostid>.</para>]]></programlisting> - - <para>Appearance:</para> - - <para>The local machine can always be referred to by the name - <hostid>localhost</hostid>, which will have the IP address <hostid - role="ipaddr">127.0.0.1</hostid>.</para> - - <para>The <hostid role="domainname">FreeBSD.org</hostid> domain - contains a number of different hosts, including <hostid - role="fqdn">freefall.FreeBSD.org</hostid> and <hostid - role="fqdn">bento.FreeBSD.org</hostid>.</para> - - <para>When adding an IP alias to an interface (using - <command>ifconfig</command>) <emphasis>always</emphasis> use a - netmask of <hostid role="netmask">255.255.255.255</hostid> (which - can also be expressed as <hostid - role="netmask">0xffffffff</hostid>.</para> - - <para>The MAC address uniquely identifies every network card in - existence. A typical MAC address looks like <hostid - role="mac">08:00:20:87:ef:d0</hostid>.</para> - </example> - </sect3> - - <sect3> - <title>Usernames</title> - - <note> - <title>FreeBSD extension</title> - - <para>These elements are part of the FreeBSD extension to DocBook, - and do not exist in the original DocBook DTD.</para> - </note> - - <para>When you need to refer to a specific username, such as - <literal>root</literal> or <literal>bin</literal>, use - <sgmltag>username</sgmltag>.</para> - - <example> - <title><sgmltag>username</sgmltag></title> - - <para>Use:</para> - - <programlisting><![ CDATA [<para>To carry out most system administration functions you - will need to be <username>root</username>.</para>]]></programlisting> - - <para>Appearance:</para> - - <para>To carry out most system administration functions you will - need to be <username>root</username>.</para> - </example> - </sect3> - - <sect3> - <title>Describing <filename>Makefile</filename>s</title> - - <note> - <title>FreeBSD extension</title> - - <para>These elements are part of the FreeBSD extension to DocBook, - and do not exist in the original DocBook DTD.</para> - </note> - - <para>Two elements exist to describe parts of - <filename>Makefile</filename>s, <sgmltag>maketarget</sgmltag> and - <sgmltag>makevar</sgmltag>.</para> - - <para><sgmltag>maketarget</sgmltag> identifies a build target exported - by a <filename>Makefile</filename> that can be given as a parameter - to <command>make</command>. <sgmltag>makevar</sgmltag> identifies a - variable that can be set (in the environment, on the - <command>make</command> command line, or within the - <filename>Makefile</filename>) to influence the process.</para> - - <example> - <title><sgmltag>maketarget</sgmltag> and - <sgmltag>makevar</sgmltag></title> - - <para>Use:</para> - - <programlisting><![ CDATA [<para>Two common targets in a <filename>Makefile</filename> - are <maketarget>all</maketarget> and <maketarget>clean</maketarget>.</para> - -<para>Typically, invoking <maketarget>all</maketarget> will rebuild the - application, and invoking <maketarget>clean</maketarget> will remove - the temporary files (<filename>.o</filename> for example) created by - the build process.</para> - -<para><maketarget>clean</maketarget> may be controlled by a number of - variables, including <makevar>CLOBBER</makevar> and - <makevar>RECURSE</makevar>.</para>]]></programlisting> - - <para>Appearance:</para> - - <para>Two common targets in a <filename>Makefile</filename> are - <maketarget>all</maketarget> and - <maketarget>clean</maketarget>.</para> - - <para>Typically, invoking <maketarget>all</maketarget> will rebuild - the application, and invoking <maketarget>clean</maketarget> will - remove the temporary files (<filename>.o</filename> for example) - created by the build process.</para> - - <para><maketarget>clean</maketarget> may be controlled by a number - of variables, including <makevar>CLOBBER</makevar> and - <makevar>RECURSE</makevar>.</para> - </example> - </sect3> - - <sect3> - <title>Literal text</title> - - <para>You will often need to include “literal” text in the - Handbook. This is text that is excerpted from another file, or - which should be copied from the Handbook into another file - verbatim.</para> - - <para>Some of the time, <sgmltag>programlisting</sgmltag> will be - sufficient to denote this text. <sgmltag>programlisting</sgmltag> - is not always appropriate, particularly when you want to include a - portion of a file “in-line” with the rest of the - paragraph.</para> - - <para>On these occasions, use <sgmltag>literal</sgmltag>.</para> - - <example> - <title><sgmltag>literal</sgmltag></title> - - <para>Use:</para> - - <programlisting><![ CDATA [<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>]]></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> - </sect3> - - <sect3> - <title>Showing items that the user <emphasis>must</emphasis> fill - in</title> - - <para>There will often be times when you want to show the user what to - do, or refer to a file, or command line, or similar, where the user - can not simply copy the examples that you provide, but must instead - include some information themselves.</para> - - <para><sgmltag>replaceable</sgmltag> 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><sgmltag>replaceable</sgmltag></title> - - <para>Use:</para> - - <programlisting><![ CDATA [<informalexample> - <screen>&prompt.user; <userinput>man <replaceable>command</replaceable></userinput></screen> -</informalexample>]]></programlisting> - - <para>Appearance:</para> - - <informalexample> - <screen>&prompt.user; <userinput>man <replaceable>command</replaceable></userinput></screen> - </informalexample> - - <para><sgmltag>replaceable</sgmltag> can be used in many different - elements, including <sgmltag>literal</sgmltag>. This example also - shows that <sgmltag>replaceable</sgmltag> 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>Use:</para> - - <programlisting><![ CDATA [<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>]]></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> - </sect3> - </sect2> - - <sect2> - <title>Images</title> - - <important> - <para>Image support in the documentation is currently extremely - experimental. I think the mechanisms described here are unlikely to - change, but that's not guaranteed.</para> - - <para>You will also need to install the - <filename>graphics/ImageMagick</filename> port, which is used to - convert between the different image formats. This is a big port, - and most of it is not required. However, while we're working on the - <filename>Makefile</filename>s and other infrastructure it makes - things easier. This port is <emphasis>not</emphasis> in the - <filename>textproc/docproj</filename> meta port, you must install it - by hand.</para> - - <para>The best example of what follows in practice is the - <filename>en_US.ISO_8859-1/articles/vm-design/</filename> document. - If you're unsure of the description that follows, take a look at the - files in that directory to see how everything hangs togther. - Experiment with creating different formatted versions of the - document to see how the image markup appears in the formatted - output.</para> - </important> - - <sect3> - <title>Image formats</title> - - <para>We currently support two formats for images. The format you - should use will depend on the nature of your image.</para> - - <para>For images that are primarily vector based, such as network - diagrams, timelines, and similar, use Encapsulated Postscript, and - make sure that your images have the <filename>.eps</filename> - extension.</para> - - <para>For bitmaps, such as screen captures, use the Portable Network - Graphic format, and make sure that your images have the - <filename>.png</filename> extension.</para> - - <para>These are the <emphasis>only</emphasis> formats in which images - should be committed to the CVS repository.</para> - - <para>Use the right format for the right image. It is to be expected - that your documentation will have a mix of EPS and PNG images. The - <filename>Makefile</filename>s ensure that the correct format image - is chosen depending on the output format that you use for your - documentation. <emphasis>Do not commit the same image to the - repository in two different formats</emphasis>.</para> - - <important> - <para>It is anticipated that the Documentation Project will switch to - using the Scalable Vector Graphic (SVG) format for vector images. - However, the current state of SVG capable editing tools makes this - impractical.</para> - </important> - </sect3> - - <sect3> - <title>Markup</title> - - <para>The markup for an image is relatively simple. First, markup a - <sgmltag>mediaobject</sgmltag>. The <sgmltag>mediaobject</sgmltag> - can contain other, more specific objects. We are concerned with - two, the <sgmltag>imageobject</sgmltag> and the - <sgmltag>textobject</sgmltag>.</para> - - <para>You should include one <sgmltag>imageobject</sgmltag>, and two - <sgmltag>textobject</sgmltag> elements. The - <sgmltag>imageobject</sgmltag> will point to the name of the image - file that will be used (without the extension). The - <sgmltag>textobject</sgmltag> elements contain information that will - be presented to the user as well as, or instead of, the - image.</para> - - <para>There are two circumstances where this can happen.</para> - - <itemizedlist> - <listitem> - <para>When the reader is viewing the documentation in HTML. In - this case, each image will need to have associated alternate - text to show the user, typically whilst the image is loading, or - if they hover the mouse pointer over the image.</para> - </listitem> - - <listitem> - <para>When the reader is viewing the documentation in plain text. - In this case, each image should have an ASCII art equivalent to - show the user.</para> - </listitem> - </itemizedlist> - - <para>An example will probably make things easier to understand. - Suppose you have an image, called <filename>fig1</filename>, that - you want to include in the document. This image is of a rectangle - with an A inside it. The markup for this would be as - follows.</para> - - <programlisting><mediaobject> - <imageobject> - <imagedata fileref="fig1"> <co id="co-image-ext"> - </imageobject> - - <textobject> - <literallayout class="monospaced">+---------------+ <co id="co-image-literal"> -| A | -+---------------+</literallayout> - </textobject> - - <textobject> - <phrase>A picture</phrase> <co id="co-image-phrase"> - </textobject> -</mediaobject></programlisting> - - <calloutlist> - <callout arearefs="co-image-ext"> - <para>Include an <sgmltag>imagedata</sgmltag> element inside the - <sgmltag>imageobject</sgmltag> 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 <sgmltag>textobject</sgmltag> should contain a - <sgmltag>literallayout</sgmltag> element, where the - <literal>class</literal> attribute is set to - <literal>monospaced</literal>. This is your opportunity to - demonstrate your ASCII 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 - <sgmltag>literallayout</sgmltag> 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 <sgmltag>textobject</sgmltag> should contain a - single <sgmltag>phrase</sgmltag> element. The contents of this - will become the <literal>alt</literal> attribute for the image - when this document is converted to HTML.</para> - </callout> - </calloutlist> - </sect3> - - <sect3> - <title><filename>Makefile</filename> entries</title> - - <para>Your images must be listed in the - <filename>Makefile</filename> in the <makevar>IMAGES</makevar> - variable. This variable should contain the name of all your - <emphasis>source</emphasis> images. For example, if you have - created three figures, <filename>fig1.eps</filename>, - <filename>fig2.png</filename>, <filename>fig3.png</filename>, then - your <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 your source document, you - only need to list the image files <emphasis>you</emphasis> - provided.</para> - </sect3> - - <sect3> - <title>Images and chapters in subdirectories</title> - - <para>You must be careful when you separate your documentation in to - smaller files (see <xref linkend="sgml-primer-include-using-gen-entities">) in - different directories.</para> - - <para>Suppose you have a book with three chapters, and the chapters - are stored in their own directories, called - <filename>chapter1/chapter.sgml</filename>, - <filename>chapter2/chapter.sgml</filename>, and - <filename>chapter3/chapter.sgml</filename>. If each chapter has - images associated with it, I suggest you place those images in each - chapter's subdirectory (<filename>chapter1/</filename>, - <filename>chapter2/</filename>, and - <filename>chapter3/</filename>).</para> - - <para>However, if you do this you must include the directory names in - the <makevar>IMAGES</makevar> variable in the - <filename>Makefile</filename>, <emphasis>and</emphasis> you must - include the directory name in the <sgmltag>imagedata</sgmltag> - element in your document.</para> - - <para>For example, if you have <filename>chapter1/fig1.png</filename>, - then <filename>chapter1/chapter.sgml</filename> should - contain</para> - - <programlisting><mediaobject> - <imageobject> - <imagedata fileref="chapter1/fig1"> <co id="co-image-dir"> - </imageobject> - - … - -</mediaobject></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> - - <para>Then everything should just work.</para> - </sect3> - </sect2> - - <sect2> - <title>Links</title> - - <note> - <para>Links are also in-line elements.</para> - </note> - - <sect3> - <title>Linking to other parts of the same document</title> - - <para>Linking within the same document requires you to to specify - where you are linking from (i.e., the text the user will click, or - otherwise indicate, as the source of the link) and where you are - linking to (the link's destination).</para> - - <para>Each element within DocBook has an attribute called - <literal>id</literal>. You can place text in this attribute to - uniquely name the element it is attached to.</para> - - <para>This value will be used when you specify the link - source.</para> - - <para>Normally, you will only be linking to chapters or sections, so - you would add the <literal>id</literal> attribute to these - elements.</para> - - <example> - <title><literal>id on chapters and sections</literal></title> - - <programlisting><![ CDATA [<chapter id="chapter1"> - <title>Introduction</title> - - <para>This is the introduction. It contains a subsection, - which is identified as well.</para> - - <sect1 id="chapter1-sect1"> - <title>Sub-sect 1</title> - - <para>This is the subsection.</para> - </sect1> -</chapter>]]></programlisting> - </example> - - <para>Obviously, you should use more descriptive values. The values - must be unique within the document (i.e., not just the file, but the - document the file might be included in as well). Notice how the - <literal>id</literal> for the subsection is constructed by appending - text to the <literal>id</literal> of the chapter. This helps to - ensure that they are unique.</para> - - <para>If you want to allow the user to jump into a specific portion of - the document (possibly in the middle of a paragraph or an example), - use <sgmltag>anchor</sgmltag>. This element has no content, but - takes an <literal>id</literal> attribute.</para> - - <example> - <title><sgmltag>anchor</sgmltag></title> - - <programlisting><![ CDATA [<para>This paragraph has an embedded - <anchor id="para1">link target in it. It won't show up in - the document.</para>]]></programlisting> - </example> - - <para>When you want to provide the user with a link they can activate - (probably by clicking) to go to a section of the document that has - an <literal>id</literal> attribute, you can use either - <sgmltag>xref</sgmltag> or <sgmltag>link</sgmltag>.</para> - - <para>Both of these elements have a <literal>linkend</literal> - attribute. The value of this attribute should be the value that you - have used in a <literal>id</literal> attribute (it does not matter - if that value has not yet occurred in your document; this will work - for forward links as well as backward links).</para> - - <para>If you use <sgmltag>xref</sgmltag> then you have no control over - the text of the link. It will be generated for you.</para> - - <example> - <title>Using <sgmltag>xref</sgmltag></title> - - <para>Assume that this fragment appears somewhere in a document that - includes the <literal>id</literal> example;</para> - - <programlisting><![ CDATA [<para>More information can be found - in <xref linkend="chapter1">.</para> - -<para>More specific information can be found - in <xref linkend="chapter1-sect1">.</para>]]></programlisting> - - <para>The text of the link will be generated automatically, and will - look like (<emphasis>emphasised</emphasis> text indicates the text - that will be the link);</para> - - <blockquote> - <para>More information can be found in <emphasis>Chapter - One</emphasis>.</para> - - <para>More specific information can be found in <emphasis>the - section called Sub-sect 1</emphasis>.</para> - </blockquote> - </example> - - <para>Notice how the text from the link is derived from the section - title or the chapter number.</para> - - <note> - <para>This means that you <emphasis>can not</emphasis> use - <sgmltag>xref</sgmltag> to link to an <literal>id</literal> - attribute on an <sgmltag>anchor</sgmltag> element. The - <sgmltag>anchor</sgmltag> has no content, so the - <sgmltag>xref</sgmltag> can not generate the text for the - link.</para> - </note> - - <para>If you want to control the text of the link then use - <sgmltag>link</sgmltag>. This element wraps content, and the - content will be used for the link.</para> - - <example> - <title>Using <sgmltag>link</sgmltag></title> - - <para>Assume that this fragment appears somewhere in a document that - includes the <literal>id</literal> example.</para> - - <programlisting><![ CDATA [<para>More information can be found in - <link linkend="chapter1">the first chapter</link>.</para> - -<para>More specific information can be found in - <link linkend="chapter1-sect1>this</link> section.</para>]]></programlisting> - - <para>This will generate the following - (<emphasis>emphasised</emphasis> text indicates the text that will - be the link);</para> - - <blockquote> - <para>More information can be found in <emphasis>the first - chapter</emphasis>.</para> - - <para>More specific information can be found in - <emphasis>this</emphasis> section.</para> - </blockquote> - </example> - - <note> - <para>That last one is a bad example. Never use words like - “this” or “here” as the source for the - link. The reader will need to hunt around the surrounding context - to see where the link is actually taking them.</para> - </note> - - <note> - <para>You <emphasis>can</emphasis> use <sgmltag>link</sgmltag> to - include a link to an <literal>id</literal> on an - <sgmltag>anchor</sgmltag> element, since the - <sgmltag>link</sgmltag> content defines the text that will be used - for the link.</para> - </note> - </sect3> - - <sect3> - <title>Linking to documents on the WWW</title> - - <para>Linking to external documents is much simpler, as long as you - know the URL of the document you want to link to. Use - <sgmltag>ulink</sgmltag>. The <literal>url</literal> attribute is - the URL of the page that the link points to, and the content of the - element is the text that will be displayed for the user to - activate.</para> - - <example> - <title><sgmltag>ulink</sgmltag></title> - - <para>Use:</para> - - <programlisting><![ CDATA [<para>Of course, you could stop reading this document and - go to the <ulink url="http://www.FreeBSD.org/">FreeBSD - home page</ulink> instead.</para>]]></programlisting> - - <para>Appearance:</para> - - <para>Of course, you could stop reading this document and go to the - <ulink url="http://www.FreeBSD.org/">FreeBSD home page</ulink> - instead.</para> - </example> - </sect3> - </sect2> - </sect1> - - <sect1> - <title>* LinuxDoc</title> - - <para>LinuxDoc is an adaptation of the QWERTZ DTD, first adopted by the - <ulink url="http://www.linuxdoc.org/">Linux Documentation - Project</ulink>, and subsequently adopted by the FreeBSD Documentation - Project.</para> - - <para>The LinuxDoc DTD contains primarily appearance related markup rather - than content related markup (i.e., it describes what something looks - like rather than what it is).</para> - - <para>Both the FreeBSD Documentation Project and the Linux Documentation - Project are migrating from the LinuxDoc DTD to the DocBook DTD.</para> - - <para>The LinuxDoc DTD is available from the ports collection in the - <filename>textproc/linuxdoc</filename> category.</para> - </sect1> -</chapter> - - -<!-- - Local Variables: - mode: sgml - sgml-declaration: "../chapter.decl" - sgml-indent-data: t - sgml-omittag: nil - sgml-always-quote-attributes: t - sgml-parent-document: ("../book.sgml" "part" "chapter") - End: ---> - diff --git a/en_US.ISO_8859-1/books/fdp-primer/sgml-primer/chapter.sgml b/en_US.ISO_8859-1/books/fdp-primer/sgml-primer/chapter.sgml deleted file mode 100644 index e6378df431..0000000000 --- a/en_US.ISO_8859-1/books/fdp-primer/sgml-primer/chapter.sgml +++ /dev/null @@ -1,1556 +0,0 @@ -<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved. - - Redistribution and use in source (SGML DocBook) and 'compiled' forms - (SGML, HTML, PDF, PostScript, RTF and so forth) with or without - modification, are permitted provided that the following conditions - are met: - - 1. Redistributions of source code (SGML DocBook) must retain the above - copyright notice, this list of conditions and the following - disclaimer as the first lines of this file unmodified. - - 2. Redistributions in compiled form (transformed to other DTDs, - converted to PDF, PostScript, RTF and other formats) must reproduce - the above copyright notice, this list of conditions and the - following disclaimer in the documentation and/or other materials - provided with the distribution. - - THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR - IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES - OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE - DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT, - INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES - (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR - SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) - HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, - STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN - ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE - POSSIBILITY OF SUCH DAMAGE. - - $FreeBSD: doc/en_US.ISO_8859-1/books/fdp-primer/sgml-primer/chapter.sgml,v 1.16 2001/04/09 00:33:47 dd Exp $ ---> - -<chapter id="sgml-primer"> - <title>SGML Primer</title> - - <para>The majority of FDP documentation is written in applications of - SGML. This chapter explains exactly what that means, how to read - and understand the source to the documentation, and the sort of SGML - tricks you will see used in the documentation.</para> - - <para>Portions of this section were inspired by Mark Galassi's <ulink - url="http://nis-www.lanl.gov/~rosalia/mydocs/docbook-intro/docbook-intro.html">Get Going With DocBook</ulink>.</para> - - <sect1> - <title>Overview</title> - - <para>Way back when, electronic text was simple to deal with. Admittedly, - you had to know which character set your document was written in (ASCII, - EBCDIC, or one of a number of others) 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. Once you have text in a - machine-usable format, you expect machines to be able to use it and - manipulate it intelligently. You would like to indicate that certain - phrases should be emphasised, or added to a glossary, or be hyperlinks. - You might want filenames to be shown in a “typewriter” style - font for viewing on screen, but as “italics” 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. Your computer would read in 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 our computers require some assistance before they can - meaningfully process our text.</para> - - <para>More precisely, they need help identifying what is what. You or I - can look at - - <blockquote> - <para>To remove <filename>/tmp/foo</filename> use &man.rm.1;.</para> - - <screen>&prompt.user; <userinput>rm /tmp/foo</userinput></screen> - </blockquote> - - and easily 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 can not. For this we need - markup.</para> - - <para>“Markup” is commonly used to describe “adding - value” or “increasing cost”. 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 - recognise 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> (i.e., the effort required) to create the - document.</para> - - <para>The previous example is actually represented in this document like - this;</para> - - <programlisting><![ CDATA [ -<para>To remove <filename>/tmp/foo</filename> use &man.rm.1;.</para> - -<screen>&prompt.user; <userinput>rm /tmp/foo</userinput></screen>]]></programlisting> - - <para>As you can see, the markup is clearly separate from the - content.</para> - - <para>Obviously, if you are going to use markup you need to define what - your markup means, and how it should be interpreted. You will need a - markup language that you can follow when marking up your - documents.</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 was to be used for cookery recipes. This, - in turn, would be very different from a markup language used to describe - poetry. What you really need is a first language that you use to write - these other markup languages. A <emphasis>meta markup - language</emphasis>.</para> - - <para>This is exactly what the Standard Generalised Markup Language (SGML) - is. Many markup languages have been written in SGML, including the two - most used by the FDP, HTML and DocBook.</para> - - <para>Each language definition is more properly called a Document Type - Definition (DTD). The DTD specifies the name of the elements that can - be used, what order they appear in (and whether some markup can be used - inside other markup) and related information. A DTD is sometimes - referred to as an <emphasis>application</emphasis> of SGML.</para> - - <para id="sgml-primer-validating">A DTD 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 SGML - <emphasis>parser</emphasis> which reads in both the DTD and a document - which claims to conform to the DTD. The parser can then confirm whether - or not all the elements required by the DTD 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>This processing simply confirms that the choice of elements, their - ordering, and so on, conforms to that listed in the DTD. It does - <emphasis>not</emphasis> check that you have used - <emphasis>appropriate</emphasis> markup for the content. If you were - to try and mark up all the filenames in your document as function - names, the parser would not flag this as an error (assuming, of - course, that your DTD defines elements for filenames and functions, - and that they are allowed to appear in the same place).</para> - </note> - - <para>It is likely that most of your contributions to the Documentation - Project will consist of content marked up in either HTML or DocBook, - rather than alterations to the DTDs. For this reason this book will - not touch on how to write a DTD.</para> - </sect1> - - <sect1 id="sgml-primer-elements"> - <title>Elements, tags, and attributes</title> - - <para>All the DTDs written in SGML share certain characteristics. This is - hardly surprising, as the philosophy behind SGML will inevitably show - through. One of the most obvious manifestations of this philisophy is - that of <emphasis>content</emphasis> and - <emphasis>elements</emphasis>.</para> - - <para>Your 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 “book” 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>You might like to think of this as “chunking” content. - At the very top level you have one chunk, the book. Look a little - deeper, and you have more chunks, the individual chapters. These are - chunked further into paragraphs, footnotes, character names, and so - on.</para> - - <para>Notice how you can make this differentation between different - elements of the content without resorting to any SGML terms. It really - is surprisingly straightforward. You could do this with a highlighter - pen and a printout of the book, using different colours 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 SGML (HTML, DocBook, et al) this is done by - means of <emphasis>tags</emphasis>.</para> - - <para>A tag is used to identify where a particular element starts, and - where the element ends. <emphasis>The tag is not part of the element - itself</emphasis>. Because each DTD was normally written to mark up - specific types of information, each one will recognise 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 - <literal><<replaceable>element-name</replaceable>></literal>. The - corresponding closing tag for this element is - <literal></<replaceable>element-name</replaceable>></literal>.</para> - - <example> - <title>Using an element (start and end tags)</title> - - <para>HTML has an element for indicating that the content enclosed by - the element is a paragraph, called <literal>p</literal>. This - element has both start and end tags.</para> - - <programlisting><![ CDATA [<p>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.</p> - -<p>This is another paragraph. But this one is much shorter.</p>]]></programlisting> - </example> - - <para>Not all elements require an end tag. Some elements have no content. - For example, in HTML you can indicate that you want a horizontal line to - appear in the document. Obviously, this line has no content, so just - the start tag is required for this element.</para> - - <example> - <title>Using an element (start tag only)</title> - - <para>HTML has an element for indicating a horizontal rule, called - <literal>hr</literal>. This element does not wrap content, so only - has a start tag.</para> - - <programlisting><![ CDATA [<p>This is a paragraph.</p> - -<hr> - -<p>This is another paragraph. A horizontal rule separates this - from the previous paragraph.</p>]]></programlisting> - </example> - - <para>If it is not obvious by now, 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; <sgmltag>em</sgmltag></title> - - <programlisting><![ CDATA [<p>This is a simple <em>paragraph</em> where some - of the <em>words</em> have been <em>emphasised</em>.</p>]]></programlisting> - </example> - - <para>The DTD will specify the rules detailing 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 - end.</para> - - <para>When this document (or anyone else knowledgable about SGML) refers - to “the <p> tag” they mean the literal text - consisting of the three characters <literal><</literal>, - <literal>p</literal>, and <literal>></literal>. But the phrase - “the <p> element” 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 occurence 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 sufficiently recent versions of HTML, the <sgmltag>p</sgmltag> - element has an attribute called <literal>align</literal>, which suggests - an alignment (justification) for the paragraph to the program displaying - the HTML.</para> - - <para>The <literal>align</literal> 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><![ CDATA [<p align="left">The inclusion of the align attribute - on this paragraph was superfluous, since the default is left.</p> - -<p align="center">This may appear in the center.</p>]]></programlisting> - </example> - - <para>Some attributes will only take specific values, such as - <literal>left</literal> or <literal>justify</literal>. Others will - allow you to enter anything you want. If you need to include quotes - (<literal>"</literal>) within an attribute then use single quotes around - the attribute value.</para> - - <example> - <title>Single quotes around attributes</title> - - <programlisting><![ CDATA [<p align='right'>I'm on the right!</p>]]></programlisting> - </example> - - <para>Sometimes you do not need to use quotes around attribute values at - all. However, the rules for doing this are subtle, and it is far - simpler just to <emphasis>always</emphasis> quote your attribute - values.</para> - - <sect2> - <title>For you to do…</title> - - <para>In order to run the examples in this document you will need to - install some software on your system and ensure that an environment - variable is set correctly.</para> - - <procedure> - <step> - <para>Download and install <filename>textproc/docproj</filename> - from the FreeBSD ports system. This is a - <emphasis>meta-port</emphasis> that should download and install - all of the programs and supporting files that are used by the - Documentation Project.</para> - </step> - - <step> - <para>Add lines to your shell startup files to set - <envar>SGML_CATALOG_FILES</envar>.</para> - - <example id="sgml-primer-envars"> - <title><filename>.profile</filename>, for &man.sh.1; and - &man.bash.1; users</title> - - <programlisting>SGML_ROOT=/usr/local/share/sgml -SGML_CATALOG_FILES=${SGML_ROOT}/jade/catalog -SGML_CATALOG_FILES=${SGML_ROOT}/iso8879/catalog:$SGML_CATALOG_FILES -SGML_CATALOG_FILES=${SGML_ROOT}/html/catalog:$SGML_CATALOG_FILES -SGML_CATALOG_FILES=${SGML_ROOT}/docbook/catalog:$SGML_CATALOG_FILES -export SGML_CATALOG_FILES</programlisting> - </example> - - <example> - <title><filename>.login</filename>, for &man.csh.1; and - &man.tcsh.1; users</title> - - <programlisting>setenv SGML_ROOT /usr/local/share/sgml -setenv SGML_CATALOG_FILES ${SGML_ROOT}/jade/catalog -setenv SGML_CATALOG_FILES ${SGML_ROOT}/iso8879/catalog:$SGML_CATALOG_FILES -setenv SGML_CATALOG_FILES ${SGML_ROOT}/html/catalog:$SGML_CATALOG_FILES -setenv SGML_CATALOG_FILES ${SGML_ROOT}/docbook/catalog:$SGML_CATALOG_FILES</programlisting> - </example> - - <para>Then either log out, and log back in again, or run those - commands from the command line to set the variable values.</para> - </step> - </procedure> - - <procedure> - <step> - <para>Create <filename>example.sgml</filename>, and enter the - following text;</para> - - <programlisting><![ CDATA [<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> - -<html> - <head> - <title>An example HTML file</title> - </head> - - <body> - <p>This is a paragraph containing some text.</p> - - <p>This paragraph contains some more text.</p> - - <p align="right">This paragraph might be right-justified.</p> - </body> -</html>]]></programlisting> - </step> - - <step> - <para>Try and validate this file using an SGML parser.</para> - - <para>Part of <filename>textproc/docproj</filename> is the - &man.nsgmls.1; <link linkend="sgml-primer-validating">validating - parser</link>. Normally, &man.nsgmls.1; reads in a document - marked up according to an SGML DTD and returns a copy of the - document's Element Structure Information Set (ESIS, but that is - not important right now).</para> - - <para>However, when &man.nsgmls.1; is given the <option>-s</option> - parameter, &man.nsgmls.1; will suppress its normal output, and - just print error messages. This makes it a useful way to check to - see if your document is valid or not.</para> - - <para>Use &man.nsgmls.1; to check that your document is - valid;</para> - - <screen>&prompt.user; <userinput>nsgmls -s example.sgml</userinput></screen> - - <para>As you will see, &man.nsgmls.1; returns without displaying any - output. This means that your document validated - successfully.</para> - </step> - - <step> - <para>See what happens when required elements are omitted. Try - removing the <sgmltag>title</sgmltag> and - <sgmltag>/title</sgmltag> tags, and re-run the validation.</para> - - <screen>&prompt.user; <userinput>nsgmls -s example.sgml</userinput> -nsgmls:example.sgml:5:4:E: character data is not allowed here -nsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished</screen> - - <para>The error output from &man.nsgmls.1; is organised into - colon-separated groups, or columns.</para> - - <informaltable frame="none"> - <tgroup cols="2"> - <thead> - <row> - <entry>Column</entry> - <entry>Meaning</entry> - </row> - </thead> - - <tbody> - <row> - <entry>1</entry> - <entry>The name of the program generating the error. This - will always be <literal>nsgmls</literal>.</entry> - </row> - - <row> - <entry>2</entry> - <entry>The name of the file that contains the error.</entry> - </row> - - <row> - <entry>3</entry> - <entry>Line number where the error appears.</entry> - </row> - - <row> - <entry>4</entry> - <entry>Column number where the error appears.</entry> - </row> - - <row> - <entry>5</entry> - <entry>A one letter code indicating the nature of the - message. <literal>I</literal> indicates an informational - message, <literal>W</literal> is for warnings, and - <literal>E</literal> is for errors<footnote> - <para>It is not always the fifth column either. - <command>nsgmls -sv</command> displays - <literal>nsgmls:I: SP version "1.3"</literal> - (depending on the installed version). As you can see, - this is an informational message.</para> - </footnote>, and <literal>X</literal> is for - cross-references. As you can see, these messages are - errors.</entry> - </row> - - <row> - <entry>6</entry> - <entry>The text of the error message.</entry> - </row> - </tbody> - </tgroup> - </informaltable> - - <para>Simply omitting the <sgmltag>title</sgmltag> tags has - generated 2 different errors.</para> - - <para>The first error indicates that content (in this case, - characters, rather than the start tag for an element) has occured - where the SGML parser was expecting something else. In this case, - the parser was expecting to see one of the start tags for elements - that are valid inside <sgmltag>head</sgmltag> (such as - <sgmltag>title</sgmltag>).</para> - - <para>The second error is because <sgmltag>head</sgmltag> elements - <emphasis>must</emphasis> contain a <sgmltag>title</sgmltag> - element. Because it does not &man.nsgmls.1; considers that the - element has not been properly finished. However, the closing tag - indicates that the element has been closed before it has been - finished.</para> - </step> - - <step> - <para>Put the <literal>title</literal> element back in.</para> - </step> - </procedure> - </sect2> - </sect1> - - <sect1 id="sgml-primer-doctype-declaration"> - <title>The DOCTYPE declaration</title> - - <para>The beginning of each document that you write must specify the name - of the DTD that the document conforms to. This is so that SGML parsers - can determine the DTD and ensure that the document does conform to - it.</para> - - <para>This information is generally expressed on one line, in the DOCTYPE - declaration.</para> - - <para>A typical declaration for a document written to conform with version - 4.0 of the HTML DTD looks like this;</para> - - <programlisting><![ CDATA [<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN">]]></programlisting> - - <para>That line contains a number of different components.</para> - - <variablelist> - <varlistentry> - <term><literal><!</literal></term> - - <listitem> - <para>Is the <emphasis>indicator</emphasis> that indicates that this - is an SGML declaration. This line is declaring the document type. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>DOCTYPE</literal></term> - - <listitem> - <para>Shows that this is an SGML declaration for the document - type.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>html</literal></term> - - <listitem> - <para>Names the first <link linkend="sgml-primer-elements">element</link> that - will appear in the document.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>PUBLIC "-//W3C//DTD HTML 4.0//EN"</literal></term> - - <listitem> - <para>Lists the Formal Public Identifier (FPI)<indexterm> - <primary>Formal Public Identifier</primary> - </indexterm> - for the DTD that this - document conforms to. Your SGML parser will use this to find the - correct DTD when processing this document.</para> - - <para><literal>PUBLIC</literal> is not a part of the FPI, but - indicates to the SGML processor how to find the DTD referenced in - the FPI. Other ways of telling the SGML parser how to find the - DTD are shown <link - linkend="sgml-primer-fpi-alternatives">later</link>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>></literal></term> - - <listitem> - <para>Returns to the document.</para> - </listitem> - </varlistentry> - </variablelist> - - <sect2> - <title>Formal Public Identifiers (FPIs)<indexterm significance="preferred"> - <primary>Formal Public Identifier</primary> - </indexterm> -</title> - - <note> - <para>You don't need to know this, but it's useful background, and - might help you debug problems when your SGML processor can't locate - the DTD you are using.</para> - </note> - - <para>FPIs must follow a specific syntax. This syntax is as - follows;</para> - - <programlisting>"<replaceable>Owner</replaceable>//<replaceable>Keyword</replaceable> <replaceable>Description</replaceable>//<replaceable>Language</replaceable>"</programlisting> - - <variablelist> - <varlistentry> - <term><replaceable>Owner</replaceable></term> - - <listitem> - <para>This indicates the owner of the FPI.</para> - - <para>If this string starts with “ISO” then this is an - ISO owned FPI. For example, the FPI <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. ISO 8879:1986 is the ISO number - for the SGML standard.</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> - it identifies it as being registered.</para> - - <para>ISO 9070:1991 defines how registered names are generated; it - might be derived from the number of an ISO publication, an ISBN - code, or an organisation code assigned according to ISO 6523. - In addition, a registration authority could be created in order - to assign registered names. The ISO council delegated this to - the American National Standards Institute (ANSI).</para> - - <para>Because the FreeBSD Project hasn't been registered the - owner string is <literal>-//FreeBSD</literal>. And as you can - see, the W3C are not a registered owner either.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><replaceable>Keyword</replaceable></term> - - <listitem> - <para>There are several keywords that indicate the type of - information in the file. Some of the most common keywords are - <literal>DTD</literal>, <literal>ELEMENT</literal>, - <literal>ENTITIES</literal>, and <literal>TEXT</literal>. - <literal>DTD</literal> is used only for DTD files, - <literal>ELEMENT</literal> is usually used for DTD fragments - that contain only entity or element declarations. - <literal>TEXT</literal> is used for SGML content (text and - tags).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><replaceable>Description</replaceable></term> - - <listitem> - <para>Any description you want to supply for the contents of this - file. This may include version numbers or any short text that - is meaningful to you and unique for the SGML system.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><replaceable>Language</replaceable></term> - - <listitem> - <para>This is an ISO two-character code that identifies the native - language for the file. <literal>EN</literal> is used for - English.</para> - </listitem> - </varlistentry> - </variablelist> - - <sect3> - <title><filename>catalog</filename> files</title> - - <para>If you use the syntax above and try and process this document - using an SGML processor, the processor will need to have some way of - turning the FPI into the name of the file on your computer that - contains the DTD.</para> - - <para>In order to do this it can use a catalog file. A catalog file - (typically called <filename>catalog</filename>) contains lines that - map FPIs to filenames. For example, if the catalog file contained - the line;</para> - - <programlisting>PUBLIC "-//W3C//DTD HTML 4.0//EN" "4.0/strict.dtd"</programlisting> - - <para>The SGML processor would know to look up the DTD from - <filename>strict.dtd</filename> in the <filename>4.0</filename> - subdirectory of whichever directory held the - <filename>catalog</filename> file that contained that line.</para> - - <para>Look at the contents of - <filename>/usr/local/share/sgml/html/catalog</filename>. This is - the catalog file for the HTML DTDs that will have been installed as - part of the <filename>textproc/docproj</filename> port.</para> - </sect3> - - <sect3> - <title><envar>SGML_CATALOG_FILES</envar></title> - - <para>In order to locate a <filename>catalog</filename> file, your - SGML processor will need to know where to look. Many of them - feature command line parameters for specifying the path to one or - more catalogs.</para> - - <para>In addition, you can set <envar>SGML_CATALOG_FILES</envar> to - point to the files. This environment variable should consist of a - colon-separated list of catalog files (including their full - path).</para> - - <para>Typically, you will want to include the following files;</para> - - <itemizedlist> - <listitem> - <para><filename>/usr/local/share/sgml/docbook/catalog</filename></para> - </listitem> - - <listitem> - <para><filename>/usr/local/share/sgml/html/catalog</filename></para> - </listitem> - - <listitem> - <para><filename>/usr/local/share/sgml/iso8879/catalog</filename></para> - </listitem> - - <listitem> - <para><filename>/usr/local/share/sgml/jade/catalog</filename></para> - </listitem> - </itemizedlist> - - <para>You should <link linkend="sgml-primer-envars">already have done - this</link>.</para> - </sect3> - </sect2> - - <sect2 id="sgml-primer-fpi-alternatives"> - <title>Alternatives to FPIs</title> - - <para>Instead of using an FPI to indicate the DTD that the document - conforms to (and therefore, which file on the system contains the DTD) - you can explicitly specify the name of the file.</para> - - <para>The syntax for this is slightly different:</para> - - <programlisting><![ CDATA [<!DOCTYPE html SYSTEM "/path/to/file.dtd">]]></programlisting> - - <para>The <literal>SYSTEM</literal> keyword indicates that the SGML - processor should locate the DTD in a system specific fashion. This - typically (but not always) means the DTD will be provided as a - filename.</para> - - <para>Using FPIs is preferred for reasons of portability. You don't - want to have to ship a copy of the DTD around with your document, and - if you used the <literal>SYSTEM</literal> identifier then everyone - would need to keep their DTDs in the same place.</para> - </sect2> - </sect1> - - <sect1 id="sgml-primer-sgml-escape"> - <title>Escaping back to SGML</title> - - <para>Earlier in this primer I said that SGML is only used when writing a - DTD. This is not strictly true. There is certain SGML syntax that you - will want to be able to use within your documents. For example, - comments can be included in your document, and will be ignored by the - parser. Comments are entered using SGML syntax. Other uses for SGML - syntax in your document will be shown later too.</para> - - <para>Obviously, you need some way of indicating to the SGML processor - that the following content is not elements within the document, but is - SGML that the parser should act upon.</para> - - <para>These sections are marked by <literal><! ... ></literal> in - your document. Everything between these delimiters is SGML syntax as - you might find within a DTD.</para> - - <para>As you may just have realised, the <link - linkend="sgml-primer-doctype-declaration">DOCTYPE declaration</link> - is an example of SGML syntax that you need to include in your - document…</para> - </sect1> - - <sect1> - <title>Comments</title> - - <para>Comments are an SGML construction, and are normally only valid - inside a DTD. However, as <xref linkend="sgml-primer-sgml-escape"> - shows, it is possible to use SGML syntax within your document.</para> - - <para>The delimiter for SGML comments is the string - “<literal>--</literal>”. The first occurence of this string - opens a comment, and the second closes it.</para> - - <example> - <title>SGML generic comment</title> - - <programlisting><!-- test comment --></programlisting> - - <programlisting><![ CDATA [ -<!-- This is inside the comment --> - -<!-- This is another comment --> - -<!-- This is one way - of doing multiline comments --> - -<!-- This is another way of -- - -- doing multiline comments -->]]></programlisting> - </example> - - <![ %output.print; [ - <important> - <title>Use 2 dashes</title> - - <para>There is a problem with producing the Postscript and PDF versions - of this document. The above example probably shows just one hyphen - symbol, <literal>-</literal> after the <literal><!</literal> and - before the <literal>></literal>.</para> - - <para>You <emphasis>must</emphasis> use two <literal>-</literal>, - <emphasis>not</emphasis> one. The Postscript and PDF versions have - translated the two <literal>-</literal> in the original to a longer, - more professional <emphasis>em-dash</emphasis>, and broken this - example in the process.</para> - - <para>The HTML, plain text, and RTF versions of this document are not - affected.</para> - </important> - ]]> - - <para>If you have used HTML before you may have been shown different rules - for comments. In particular, you may think that the string - <literal><!--</literal> opens a comment, and it is only closed by - <literal>--></literal>.</para> - - <para>This is <emphasis>not</emphasis> the case. A lot of web browsers - have broken HTML parsers, and will accept that as valid. However, the - SGML parsers used by the Documentation Project are much stricter, and - will reject documents that make that error.</para> - - <example> - <title>Errorneous SGML comments</title> - - <programlisting><![ CDATA [ -<!-- This is in the comment -- - - THIS IS OUTSIDE THE COMMENT! - - -- back inside the comment -->]]></programlisting> - - <para>The SGML parser will treat this as though it were actually;</para> - - <programlisting><!THIS IS OUTSIDE THE COMMENT></programlisting> - - <para>This is not valid SGML, and may give confusing error - messages.</para> - - <programlisting><![ CDATA [<!--------------- This is a very bad idea --------------->]]></programlisting> - - <para>As the example suggests, <emphasis>do not</emphasis> write - comments like that.</para> - - <programlisting><![ CDATA [<!--===================================================-->]]></programlisting> - - <para>That is a (slightly) better approach, but it still potentially - confusing to people new to SGML.</para> - </example> - - <sect2> - <title>For you to do…</title> - - <procedure> - <step> - <para>Add some comments to <filename>example.sgml</filename>, and - check that the file still validates using &man.nsgmls.1;</para> - </step> - - <step> - <para>Add some invalid comments to - <filename>example.sgml</filename>, and see the error messages that - &man.nsgmls.1; gives when it encounters an invalid comment.</para> - </step> - </procedure> - </sect2> - </sect1> - - <sect1> - <title>Entities</title> - - <para>Entities are a mechanism for assigning names to chunks of content. - As an SGML parser processes your 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 your SGML documents. It is also the only way to include one - marked up file inside another using SGML.</para> - - <para>There are two types of entities which can be used in two different - situations; <emphasis>general entities</emphasis> and - <emphasis>parameter entities</emphasis>.</para> - - <sect2 id="sgml-primer-general-entities"> - <title>General Entities</title> - - <para>You can not use general entities in an SGML context (although you - define them in one). They can only be used in your document. - Contrast this with <link - linkend="sgml-primer-parameter-entities">parameter - entities</link>.</para> - - <para>Each general entity has a name. When you want to reference a - general entity (and therefore include whatever text it represents in - your document), you write - <literal>&<replaceable>entity-name</replaceable>;</literal>. For - example, suppose you had an entity called - <literal>current.version</literal> which expanded to the current - version number of your product. You could write;</para> - - <programlisting><![ CDATA [<para>The current version of our product is - ¤t.version;.</para>]]></programlisting> - - <para>When the version number changes you can simply change the - definition of the value of the general entity and reprocess your - document.</para> - - <para>You can also use general entities to enter characters that you - could not otherwise include in an SGML document. For example, < - and & can not normally appear in an SGML document. When the SGML - parser sees the < symbol it assumes that a tag (either a start tag - or an end tag) is about to appear, and when it sees the & symbol - it assumes the next text will be the name of an entity.</para> - - <para>Fortunately, you can use the two general entities &lt; and - &amp; whenever you need to include one or other of these </para> - - <para>A general entity can only be defined within an SGML context. - Typically, this is done immediately after the DOCTYPE - declaration.</para> - - <example> - <title>Defining general entities</title> - - <programlisting><![ CDATA [<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [ -<!ENTITY current.version "3.0-RELEASE"> -<!ENTITY last.version "2.2.7-RELEASE"> -]>]]></programlisting> - - <para>Notice how 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, before the square bracket is - closed, and then the DOCTYPE declaration is closed.</para> - - <para>The square brackets are necessary to indicate that we are - extending the DTD indicated by the DOCTYPE declaration.</para> - </example> - </sect2> - - <sect2 id="sgml-primer-parameter-entities"> - <title>Parameter entities</title> - - <para>Like <link linkend="sgml-primer-general-entities">general - entities</link>, parameter entities are used to assign names to - reusable chunks of text. However, where as general entities can only - be used within your document, parameter entities can only be used - within an <link linkend="sgml-primer-sgml-escape">SGML - context</link>.</para> - - <para>Parameter entities are defined in a similar way to general - entities. However, instead of using - <literal>&<replaceable>entity-name</replaceable>;</literal> to - refer to them, use - <literal>%<replaceable>entity-name</replaceable>;</literal><footnote> - <para><emphasis>P</emphasis>arameter entities use the - <emphasis>P</emphasis>ercent symbol.</para> - </footnote>. The definition also includes the <literal>%</literal> - between the <literal>ENTITY</literal> keyword and the name of the - entity.</para> - - <example> - <title>Defining parameter entities</title> - - <programlisting><![ CDATA [<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [ -<!ENTITY % param.some "some"> -<!ENTITY % param.text "text"> -<!ENTITY % param.new "%param.some more %param.text"> - -<!-- %param.new now contains "some more text" --> -]>]]></programlisting> - </example> - - <para>This may not seem particularly useful. It will be.</para> - </sect2> - - <sect2> - <title>For you to do…</title> - - <procedure> - <step> - <para>Add a general entity to - <filename>example.sgml</filename>.</para> - - <programlisting><![ CDATA [<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" [ -<!ENTITY version "1.1"> -]> - -<html> - <head> - <title>An example HTML file</title> - </head> - - <!-- You might well have some comments in here as well --> - - <body> - <p>This is a paragraph containing some text.</p> - - <p>This paragraph contains some more text.</p> - - <p align="right">This paragraph might be right-justified.</p> - - <p>The current version of this document is: &version;</p> - </body> -</html>]]></programlisting> - </step> - - <step> - <para>Validate the document using &man.nsgmls.1;</para> - </step> - - <step> - <para>Load <filename>example.sgml</filename> into your web browser - (you may need to copy it to <filename>example.html</filename> - before your browser recognises it as an HTML document).</para> - - <para>Unless your browser is very advanced, you won't see the entity - reference <literal>&version;</literal> replaced with the - version number. Most web browsers have very simplistic parsers - which do not handle proper SGML<footnote> - <para>This is a shame. Imagine all the problems and hacks (such - as Server Side Includes) that could be avoided if they - did.</para> - </footnote>.</para> - </step> - - <step> - <para>The solution is to <emphasis>normalise</emphasis> your - document using an SGML normaliser. The normaliser reads in valid - SGML and outputs equally valid SGML which has been transformed in - some way. One of the ways in which the normaliser transforms the - SGML is to expand all the entity references in the document, - replacing the entities with the text that they represent.</para> - - <para>You can use &man.sgmlnorm.1; to do this.</para> - - <screen>&prompt.user; <userinput>sgmlnorm example.sgml > example.html</userinput></screen> - - <para>You should find a normalised (i.e., entity references - expanded) copy of your document in - <filename>example.html</filename>, ready to load into your web - browser.</para> - </step> - - <step> - <para>If you look at the output from &man.sgmlnorm.1; you will see - that it does not include a DOCTYPE declaration at the start. To - include this you need to use the <option>-d</option> - option;</para> - - <screen>&prompt.user; <userinput>sgmlnorm -d example.sgml > example.html</userinput></screen> - </step> - </procedure> - </sect2> - </sect1> - - <sect1> - <title>Using entities to include files</title> - - <para>Entities (both <link - linkend="sgml-primer-general-entities">general</link> and <link - linkend="sgml-primer-parameter-entities">parameter</link>) are - particularly useful when used to include one file inside another.</para> - - <sect2 id="sgml-primer-include-using-gen-entities"> - <title>Using general entities to include files</title> - - <para>Suppose you have some content for an SGML book organised into - files, one file per chapter, called - <filename>chapter1.sgml</filename>, - <filename>chapter2.sgml</filename>, and so forth, with a - <filename>book.sgml</filename> file that will contain these - chapters.</para> - - <para>In order to use the contents of these files as the values for your - entities, you declare them with the <literal>SYSTEM</literal> keyword. - This directs the SGML parser to use the contents of the named file as - the value of the entity.</para> - - <example> - <title>Using general entities to include files</title> - - <programlisting><![ CDATA [<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [ -<!ENTITY chapter.1 SYSTEM "chapter1.sgml"> -<!ENTITY chapter.2 SYSTEM "chapter2.sgml"> -<!ENTITY chapter.3 SYSTEM "chapter3.sgml"> -<!-- And so forth --> -]> - -<html> - <!-- Use the entities to load in the chapters --> - - &chapter.1; - &chapter.2; - &chapter.3; -</html>]]></programlisting> - </example> - - <warning> - <para>When using general entities to include other files within a - document, the files being included - (<filename>chapter1.sgml</filename>, - <filename>chapter2.sgml</filename>, and so on) <emphasis>must - not</emphasis> start with a DOCTYPE declaration. This is a syntax - error.</para> - </warning> - </sect2> - - <sect2> - <title>Using parameter entities to include files</title> - - <para>Recall that parameter entities can only be used inside an SGML - context. Why then would you want to include a file within an SGML - context?</para> - - <para>You can use this to ensure that you can reuse your general - entities.</para> - - <para>Suppose that you had many chapters in your document, and you - reused these chapters in two different books, each book organising the - chapters in a different fashion.</para> - - <para>You could list the entities at the top of each book, but this - 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 your - document.</para> - - <example> - <title>Using parameter entities to include files</title> - - <para>First, place your entity definitions in a separate file, called - <filename>chapters.ent</filename>. This file contains the - following;</para> - - <programlisting><![ CDATA [<!ENTITY chapter.1 SYSTEM "chapter1.sgml"> -<!ENTITY chapter.2 SYSTEM "chapter2.sgml"> -<!ENTITY chapter.3 SYSTEM "chapter3.sgml">]]></programlisting> - - <para>Now 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><![ CDATA [<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [ -<!-- 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; -]> - -<html> - &chapter.1; - &chapter.2; - &chapter.3; -</html>]]></programlisting> - </example> - </sect2> - - <sect2> - <title>For you to do…</title> - - <sect3> - <title>Use general entities to include files</title> - - <procedure> - <step> - <para>Create three files, <filename>para1.sgml</filename>, - <filename>para2.sgml</filename>, and - <filename>para3.sgml</filename>.</para> - - <para>Put content similar to the following in each file;</para> - - <programlisting><![ CDATA [<p>This is the first paragraph.</p>]]></programlisting> - </step> - - <step> - <para>Edit <filename>example.sgml</filename> so that it looks like - this;</para> - - <programlisting><![ CDATA [<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [ -<!ENTITY version "1.1"> -<!ENTITY para1 SYSTEM "para1.sgml"> -<!ENTITY para2 SYSTEM "para2.sgml"> -<!ENTITY para3 SYSTEM "para3.sgml"> -]> - -<html> - <head> - <title>An example HTML file</title> - </head> - - <body> - <p>The current version of this document is: &version;</p> - - ¶1; - ¶2; - ¶3; - </body> -</html>]]></programlisting> - </step> - - <step> - <para>Produce <filename>example.html</filename> by normalising - <filename>example.sgml</filename>.</para> - - <screen>&prompt.user; <userinput>sgmlnorm -d example.sgml > example.html</userinput></screen> - </step> - - <step> - <para>Load <filename>example.html</filename> in to your web - browser, and confirm that the - <filename>para<replaceable>n</replaceable>.sgml</filename> files - have been included in <filename>example.html</filename>.</para> - </step> - </procedure> - </sect3> - - <sect3> - <title>Use parameter entities to include files</title> - - <note> - <para>You must have taken the previous steps first.</para> - </note> - - <procedure> - <step> - <para>Edit <filename>example.sgml</filename> so that it looks like - this;</para> - - <programlisting><![ CDATA [<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [ -<!ENTITY % entities SYSTEM "entities.sgml"> %entities; -]> - -<html> - <head> - <title>An example HTML file</title> - </head> - - <body> - <p>The current version of this document is: &version;</p> - - ¶1; - ¶2; - ¶3; - </body> -</html>]]></programlisting> - </step> - - <step> - <para>Create a new file, <filename>entities.sgml</filename>, with - this content:</para> - - <programlisting><![ CDATA [<!ENTITY version "1.1"> -<!ENTITY para1 SYSTEM "para1.sgml"> -<!ENTITY para2 SYSTEM "para2.sgml"> -<!ENTITY para3 SYSTEM "para3.sgml">]]></programlisting> - </step> - - <step> - <para>Produce <filename>example.html</filename> by normalising - <filename>example.sgml</filename>.</para> - - <screen>&prompt.user; <userinput>sgmlnorm -d example.sgml > example.html</userinput></screen> - </step> - - <step> - <para>Load <filename>example.html</filename> in to your web - browser, and confirm that the - <filename>para<replaceable>n</replaceable>.sgml</filename> files - have been included in <filename>example.html</filename>.</para> - </step> - </procedure> - </sect3> - </sect2> - </sect1> - - <sect1 id="sgml-primer-marked-sections"> - <title>Marked sections</title> - - <para>SGML provides a mechanism to indicate that particular pieces of the - document should be processed in a special way. These are termed - “marked sections”.</para> - - <example> - <title>Structure of a marked section</title> - - <programlisting><![ <replaceable>KEYWORD</replaceable> [ - Contents of marked section -]]></programlisting> - </example> - - <para>As you would expect, being an SGML construct, a marked section - starts with <literal><!</literal>.</para> - - <para>The first square bracket begins to delimit the marked - section.</para> - - <para><replaceable>KEYWORD</replaceable> describes how this marked - section should be processed by the parser.</para> - - <para>The second square bracket indicates that the content of the marked - section starts here.</para> - - <para>The marked section is finished by closing the two square brackets, - and then returning to the document context from the SGML context with - <literal>></literal></para> - - <sect2> - <title>Marked section keywords</title> - - <sect3> - <title><literal>CDATA</literal>, <literal>RCDATA</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 SGML parser is processing a document it keeps track - of what is called the “content model”.</para> - - <para>Briefly, the content model describes what sort of content the - parser is expecting to see, and what it will do with it when it - finds it.</para> - - <para>The two content models you will probably find most useful are - <literal>CDATA</literal> and <literal>RCDATA</literal>.</para> - - <para><literal>CDATA</literal> is for “Character Data”. - If the parser is in this content model then it is expecting to see - characters, and characters only. In this model the < and & - symbols lose their special status, and will be treated as ordinary - characters.</para> - - <para><literal>RCDATA</literal> is for “Entity references and - character data” If the parser is in this content model then it - is expecting to see characters <emphasis>and</emphasis> entities. - < loses its special status, but & will still be treated as - starting the beginning of a general entity.</para> - - <para>This is particularly useful if you are including some verbatim - text that contains lots of < and & characters. While you - could go through the text ensuring that every < is converted to a - &lt; and every & is converted to a &amp;, it can be - easier to mark the section as only containing CDATA. When the SGML - parser encounters this it will ignore the < and & symbols - embedded in the content.</para> - - <!-- The nesting of CDATA within the next example is disgusting --> - - <example> - <title>Using a CDATA marked section</title> - - <programlisting><para>Here is an example of how you would include some text - that contained many &lt; and &amp; symbols. The sample - text is a fragment of HTML. The surrounding text (<para> and - <programlisting>) are from DocBook.</para> - -<programlisting> - <![ CDATA [ <![ CDATA [ - <p>This is a sample that shows you some of the elements within - HTML. Since the angle brackets are used so many times, it's - 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.</p> - - <ul> - <li>This is a listitem</li> - <li>This is a second listitem</li> - <li>This is a third listitem</li> - </ul> - - <p>This is the end of the example.</p>]]> - ]]> -</programlisting></programlisting> - - <para>If you look at the source for this document you will see this - technique used throughout.</para> - </example> - </sect3> - - <sect3> - <title><literal>INCLUDE</literal> and - <literal>IGNORE</literal></title> - - <para>If the keyword is <literal>INCLUDE</literal> then the contents - of the marked section will be processed. If the keyword is - <literal>IGNORE</literal> then 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 isn't too useful. If you wanted to remove text - from your document you could cut it out, or wrap it in - comments.</para> - - <para>It becomes more useful when you realise you can use <link - linkend="sgml-primer-parameter-entities">parameter entities</link> - to control this. Remember that parameter entities can only be used - in SGML contexts, and the keyword of a marked section - <emphasis>is</emphasis> an SGML context.</para> - - <para>For example, suppose that you produced a hard-copy version of - some documentation and an electronic version. In the electronic - version you wanted to include some extra content that wasn't to - appear in the hard-copy.</para> - - <para>Create a parameter entity, and set it's value to - <literal>INCLUDE</literal>. Write your document, using marked - sections to delimit content that should only appear in the - electronic version. In these marked sections use the parameter - entity in place of the keyword.</para> - - <para>When you want to produce the hard-copy version of the document, - change the parameter entity's value to <literal>IGNORE</literal> and - reprocess the document.</para> - - <example> - <title>Using a parameter entity to control a marked - section</title> - - <programlisting><!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [ -<!ENTITY % electronic.copy "INCLUDE"> -]]> - -... - -<![ %electronic.copy [ - This content should only appear in the electronic - version of the document. -]]></programlisting> - - <para>When producing the hard-copy version, change the entity's - definition to;</para> - - <programlisting><!ENTITY % electronic.copy "IGNORE"></programlisting> - - <para>On reprocessing the document, the marked sections that use - <literal>%electronic.copy</literal> as their keyword will be - ignored.</para> - </example> - </sect3> - </sect2> - - <sect2> - <title>For you to do…</title> - - <procedure> - <step> - <para>Create a new file, <filename>section.sgml</filename>, that - contains the following;</para> - - <programlisting><!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [ -<!ENTITY % text.output "INCLUDE"> -]> - -<html> - <head> - <title>An example using marked sections</title> - </head> - - <body> - <p>This paragraph <![ CDATA [contains many < - characters (< < < < <) so it is easier - to wrap it in a CDATA marked section ]]></p> - - <![ IGNORE [ - <p>This paragraph will definitely not be included in the - output.</p> - ]]> - - <![ <![ CDATA [%text.output]]> [ - <p>This paragraph might appear in the output, or it - might not.</p> - - <p>Its appearance is controlled by the <![CDATA[%text.output]]> - parameter entity.</p> - ]]> - </body> -</html></programlisting> - </step> - - <step> - <para>Normalise this file using &man.sgmlnorm.1; and examine the - output. Notice which paragraphs have appeared, which have - disappeared, and what has happened to the content of the CDATA - marked section.</para> - </step> - - <step> - <para>Change the definition of the <literal>text.output</literal> - entity from <literal>INCLUDE</literal> to - <literal>IGNORE</literal>. Re-normalise the file, and examine the - output to see what has changed. </para> - </step> - </procedure> - </sect2> - </sect1> - - <sect1> - <title>Conclusion</title> - - <para>That is the conclusion of this SGML primer. For reasons of space - and complexity several things have not been covered in depth (or at - all). However, the previous sections cover enough SGML for you to be - able to follow the organisation of the FDP documentation.</para> - </sect1> -</chapter> - -<!-- - Local Variables: - mode: sgml - sgml-declaration: "../chapter.decl" - sgml-indent-data: t - sgml-omittag: nil - sgml-always-quote-attributes: t - sgml-parent-document: ("../book.sgml" "part" "chapter") - End: ---> diff --git a/en_US.ISO_8859-1/books/fdp-primer/structure/chapter.sgml b/en_US.ISO_8859-1/books/fdp-primer/structure/chapter.sgml deleted file mode 100644 index 2de30fe013..0000000000 --- a/en_US.ISO_8859-1/books/fdp-primer/structure/chapter.sgml +++ /dev/null @@ -1,295 +0,0 @@ -<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved. - - Redistribution and use in source (SGML DocBook) and 'compiled' forms - (SGML HTML, PDF, PostScript, RTF and so forth) with or without - modification, are permitted provided that the following conditions - are met: - - 1. Redistributions of source code (SGML DocBook) must retain the above - copyright notice, this list of conditions and the following - disclaimer as the first lines of this file unmodified. - - 2. Redistributions in compiled form (transformed to other DTDs, - converted to PDF, PostScript, RTF and other formats) must reproduce - the above copyright notice, this list of conditions and the - following disclaimer in the documentation and/or other materials - provided with the distribution. - - THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR - IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES - OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE - DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT, - INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES - (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR - SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) - HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, - STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN - ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE - POSSIBILITY OF SUCH DAMAGE. - - $FreeBSD: doc/en_US.ISO_8859-1/books/fdp-primer/structure/chapter.sgml,v 1.4 2000/07/07 18:38:38 dannyboy Exp $ ---> - -<chapter id="structure"> - <title>Structuring documents under <filename>doc/</filename></title> - - <para>The <filename>doc/</filename> tree is organised in a particular - fashion, and the documents that are part of the FDP are in turn organised - in a particular fashion. The aim is to make it simple to add new - documentation in to the tree and:</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 - organisations, 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 has to accommodate documentation - that could be in many different languages and in many different - encodings. It is important that the structure of the documentation tree - does not enforce any particular defaults or cultural preferences.</para> - - <sect1> - <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> - - <segmentedlist> - <segtitle>Directory</segtitle> - - <segtitle>Meaning</segtitle> - - <seglistitem> - <seg><filename>share/</filename></seg> - - <seg>Contains files that are not specific to the various translations - and encodings of the documentation. Contains subdirectories to - further categorise the information. For example, the files that - comprise the &man.make.1; infrastructure are in - <filename>share/mk</filename>, while the additional SGML support - files (such as the FreeBSD extended DocBook DTD) are in - <filename>share/sgml</filename>.</seg> - </seglistitem> - - <seglistitem> - <seg><filename><replaceable>lang</replaceable>.<replaceable>encoding</replaceable>/</filename></seg> - - <seg>One directory exists for each available translation and encoding - of the documentation, for example - <filename>en_US.ISO_8859-1/</filename> and - <filename>zh_TW.Big5/</filename>. The names are long, but by fully - specifying the language and encoding we prevent any future headaches - should a translation team want to provide the documentation in the - same language but in more than one encoding. This also completely - isolates us from any problems that might be caused by a switch to - Unicode.</seg> - </seglistitem> - </segmentedlist> - </sect1> - - <sect1> - <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> - - <segmentedlist> - <segtitle>Directory</segtitle> - - <segtitle>Contents</segtitle> - - <seglistitem> - <seg><filename>articles</filename></seg> - - <seg>Documentation marked up as a DocBook <sgmltag>article</sgmltag> - (or equivalent). Reasonably short, and broken up into sections. - Normally only available as one HTML file.</seg> - </seglistitem> - - <seglistitem> - <seg><filename>books</filename></seg> - - <seg>Documentation marked up as a DocBook <sgmltag>book</sgmltag> (or - equivalent). Book length, and broken up in to chapters. Normally - available as both one large HTML file (for people with fast - connections, or who want to print it easily from a browser) and - as a collection of linked, smaller files.</seg> - </seglistitem> - - <seglistitem> - <seg><filename>man</filename></seg> - - <seg>For translations of the system manual pages. This directory will - contain one or more - <filename>man<replaceable>n</replaceable></filename> directories, - corresponding to the sections that have been translated.</seg> - </seglistitem> - </segmentedlist> - - <para>Not every - <filename><replaceable>lang</replaceable>.<replaceable>encoding</replaceable></filename> directory will contain all of these directories. It depends - on how much translation has been accomplished by that translation - team.</para> - </sect1> - - <sect1> - <title>Document specific information</title> - - <para>This section contains specific notes about particular documents - managed by the FDP.</para> - - <sect2> - <title>The Handbook</title> - - <subtitle><filename>books/handbook/</filename></subtitle> - - <para>The Handbook is written to comply with the FreeBSD DocBook - extended DTD.</para> - - <para>The Handbook is organised as a DocBook <sgmltag>book</sgmltag>. - It is then divided into <sgmltag>part</sgmltag>s, each of which may - contain several <sgmltag>chapter</sgmltag>s. - <sgmltag>chapter</sgmltag>s are further subdivided into sections - (<sgmltag>sect1</sgmltag>) and subsections (<sgmltag>sect2</sgmltag>, - <sgmltag>sect3</sgmltag>) and so on.</para> - - <sect3> - <title>Physical organisation</title> - - <para>There are a number of files and directories within the - <filename>handbook</filename> directory.</para> - - <note> - <para>The Handbook's organisation may change over time, and this - document may lag in detailing the organisational changes. If you - have any questions about how the Handbook is organised, please - contact the FreeBSD Documentation Project, - <email>freebsd-doc@FreeBSD.org</email>.</para> - </note> - - <sect4> - <title><filename>Makefile</filename></title> - - <para>The <filename>Makefile</filename> defines some variables that - affect how the SGML 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> file, to - bring in the rest of the code that handles converting documents - from one format to another.</para> - </sect4> - - <sect4> - <title><filename>book.sgml</filename></title> - - <para>This is the top level document in the Handbook. It contains - the Handbook's <link - linkend="sgml-primer-doctype-declaration">DOCTYPE - declaration</link>, as well as the elements that describe the - Handbook's structure.</para> - - <para><filename>book.sgml</filename> uses <link - linkend="sgml-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="sgml-primer-general-entities">general - entities</link> that are used throughout the rest of the - Handbook.</para> - </sect4> - - <sect4> - <title><filename><replaceable>directory</replaceable>/chapter.sgml</filename></title> - - <para>Each chapter in the Handbook is stored in a file called - <filename>chapter.sgml</filename> in a separate directory from the - other chapters. Each directory is named after the value of the - <literal>id</literal> attribute on the <sgmltag>chapter</sgmltag> - element.</para> - - <para>For example, if one of the chapter files contains:</para> - - <programlisting><![ CDATA [ -<chapter id="kernelconfiguration"> -... -</chapter>]]></programlisting> - - <para>then it will be called <filename>chapter.sgml</filename> in - the <filename>kernelconfiguration</filename> directory. In - general, the entire contents of the chapter will be held in this - file.</para> - - <para>When the HTML version of the Handbook is produced, this will - yield <filename>kernelconfiguration.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.sgml</filename>, and named - after the value of the <literal>id</literal> attribute on the - file's <sgmltag>chapter</sgmltag> element. Moving them in to - separate directories prepares for future plans for the Handbook. - Specifically, it will soon be possible to include images in each - chapter. It makes more sense for each image to be stored in a - directory with the text for the chapter than to try and keep the - text for all the chapters, and all the images, in one large - directory. Namespace collisions would be 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.sgml</filename> files, including - <filename>basics/chapter.sgml</filename>, - <filename>introduction/chapter.sgml</filename>, and - <filename>printing/chapter.sgml</filename>.</para> - - <important> - <para>Chapters and/or directories should not be named in a fashion - that reflects their ordering within the Handbook. This ordering - might change as the content within the Handbook is reorganised; - this sort of reorganistion should not (generally) include the - need to rename files (unless entire chapters are being promoted - or demoted within the hierarchy).</para> - </important> - - <para>Each <filename>chapter.sgml</filename> file will not be a - complete SGML document. In particular, they will not have their - own DOCTYPE lines at the start of the files.</para> - - <para>This is unfortunate as - it makes it impossible to treat these as generic SGML - files and simply convert them to HTML, RTF, PS, and other - formats in the same way the main Handbook is generated. This - <emphasis>would</emphasis> force you to rebuild the Handbook - every time you want to see the effect a change has had on just - one chapter.</para> - </sect4> - </sect3> - </sect2> - </sect1> -</chapter> - -<!-- - Local Variables: - mode: sgml - sgml-declaration: "../chapter.decl" - sgml-indent-data: t - sgml-omittag: nil - sgml-always-quote-attributes: t - sgml-parent-document: ("../book.sgml" "part" "chapter") - End: ---> - diff --git a/en_US.ISO_8859-1/books/fdp-primer/stylesheets/chapter.sgml b/en_US.ISO_8859-1/books/fdp-primer/stylesheets/chapter.sgml deleted file mode 100644 index 8a014549cd..0000000000 --- a/en_US.ISO_8859-1/books/fdp-primer/stylesheets/chapter.sgml +++ /dev/null @@ -1,81 +0,0 @@ -<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved. - - Redistribution and use in source (SGML DocBook) and 'compiled' forms - (SGML HTML, PDF, PostScript, RTF and so forth) with or without - modification, are permitted provided that the following conditions - are met: - - 1. Redistributions of source code (SGML DocBook) must retain the above - copyright notice, this list of conditions and the following - disclaimer as the first lines of this file unmodified. - - 2. Redistributions in compiled form (transformed to other DTDs, - converted to PDF, PostScript, RTF and other formats) must reproduce - the above copyright notice, this list of conditions and the - following disclaimer in the documentation and/or other materials - provided with the distribution. - - THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR - IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES - OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE - DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT, - INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES - (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR - SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) - HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, - STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN - ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE - POSSIBILITY OF SUCH DAMAGE. - - $FreeBSD$ ---> - -<chapter id="stylesheets"> - <title>* Stylesheets</title> - - <para>SGML says nothing about how a document should be displayed to the - user, or rendered on paper. To do that, various languages have been - developed to describe stylesheets, including DynaText, Panorama, SPICE, - JSSS, FOSI, CSS, and DSSSL.</para> - - <para>For DocBook, we are using stylesheets written in DSSSL. For HTML we - are using CSS.</para> - - <sect1> - <title>* DSSSL</title> - - <para>The Documentation Project uses a slightly customised version of - Norm Walsh's modular DocBook stylesheets.</para> - - <para>These can be found in - <filename>textproc/dsssl-docbook-modular</filename>.</para> - - <para>The modified stylesheets are not in the ports system. Instead they - are part of the Documentation Project source repository, and can be - found in <filename>doc/share/sgml/freebsd.dsl</filename>. It is well - commented, and pending completion of this section you are encouraged to - examine that file to see how some of the available options in the - standard stylesheets have been configured in order to customise the - output for the FreeBSD Documentation Project. That file also contains - examples showing how to extend the elements that the stylesheet - understands, which is how the FreeBSD specific elements have been - formatted.</para> - </sect1> - - <sect1> - <title>* CSS</title> - - <para></para> - </sect1> -</chapter> - -<!-- - Local Variables: - mode: sgml - sgml-declaration: "../chapter.decl" - sgml-indent-data: t - sgml-omittag: nil - sgml-always-quote-attributes: t - sgml-parent-document: ("../book.sgml" "part" "chapter") - End: ---> diff --git a/en_US.ISO_8859-1/books/fdp-primer/the-website/chapter.sgml b/en_US.ISO_8859-1/books/fdp-primer/the-website/chapter.sgml deleted file mode 100644 index 92502c7550..0000000000 --- a/en_US.ISO_8859-1/books/fdp-primer/the-website/chapter.sgml +++ /dev/null @@ -1,217 +0,0 @@ -<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved. - - Redistribution and use in source (SGML DocBook) and 'compiled' forms - (SGML HTML, PDF, PostScript, RTF and so forth) with or without - modification, are permitted provided that the following conditions - are met: - - 1. Redistributions of source code (SGML DocBook) must retain the above - copyright notice, this list of conditions and the following - disclaimer as the first lines of this file unmodified. - - 2. Redistributions in compiled form (transformed to other DTDs, - converted to PDF, PostScript, RTF and other formats) must reproduce - the above copyright notice, this list of conditions and the - following disclaimer in the documentation and/or other materials - provided with the distribution. - - THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR - IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES - OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE - DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT, - INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES - (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR - SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) - HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, - STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN - ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE - POSSIBILITY OF SUCH DAMAGE. - - $FreeBSD: doc/en_US.ISO_8859-1/books/fdp-primer/the-website/chapter.sgml,v 1.3 1999/09/06 06:52:43 peter Exp $ ---> - -<chapter id="the-website"> - <title>The Website</title> - - <sect1> - <title>Preparation</title> - - <para>Get 200MB free disk space. You will need the disk space for the - SGML tools, a subset of the CVS tree, temporary build space and the - installed web pages. If you aready have installed the SGML tools and - the CVS tree, you need only ~100MB free disk space.</para> - - <note> - <para>Make sure your documentation ports are up to date! When in - doubt, remove the old ports using &man.pkg.delete.1; command before - installing the port. For example, we currently depend on - jade-1.2 and if you have installed jade-1.1, please do</para> - - <screen>&prompt.root; <userinput>pkg_delete jade-1.1</userinput></screen> - </note> - - <para>Setup a CVS repository. You need the directories www, doc and - ports in the CVS tree (plus the CVSROOT of course). Please read the - CVSup introduction <ulink - url="http://www.freebsd.org/handbook/synching.html#CVSUP"> - http://www.freebsd.org/handbook/synching.html#CVSUP</ulink> how to - mirror a CVS tree or parts of a CVS tree.</para> - - <para>The essential cvsup collections are: <literal>www</literal>, - <literal>doc-all</literal>, <literal>cvs-base</literal>, and - <literal>ports-base</literal>.</para> - - <para>These collections require ~100MB free disk space.</para> - - <para>A full CVS tree - including <literal>src</literal>, - <literal>doc</literal>, <literal>www</literal>, and - <literal>ports</literal> - is currently 650MB large.</para> - </sect1> - - <sect1> - <title>Build the web pages from scratch</title> - - <procedure> - <step> - <para>Go to into a build directory with at least 60MB of free - space.</para> - - <screen>&prompt.root; <userinput>mkdir /var/tmp/webbuild</userinput> -&prompt.root; <userinput>cd /var/tmp/webuild</userinput></screen> - </step> - - <step> - <para>Checkout the SGML files from the CVS tree.</para> - - <screen>&prompt.root; <userinput>cvs -R co www doc</userinput></screen> - </step> - - <step><para>Change in to the <filename>www</filename> directory, and - run the &man.make.1; <maketarget>links</maketarget> target, to - create the necessary symbolic links.</para> - - <screen>&prompt.root; <userinput>cd www</userinput> -&prompt.root; <userinput>make links</userinput></screen> - </step> - - <step> - <para>Change in to the <filename>en</filename> directory, and run - the &man.make.1; <maketarget>all</maketarget> target, to create - the web pages.</para> - - <screen>&prompt.root; <userinput>cd en</userinput> -&prompt.root; <userinput>make all</userinput></screen> - </step> - </procedure> - </sect1> - - <sect1> - <title>Install the web pages into your web server</title> - - <procedure> - <step> - <para>If you have moved out of the <filename>en</filename> - directory, change back to it.</para> - - <screen>&prompt.root; <userinput>cd <replaceable>path</replaceable>/www/en</userinput></screen> - </step> - - <step> - <para>Run the &man.make.1; <maketarget>install</maketarget> target, - setting the <makevar>DESTDIR</makevar> variable to the name of the - directory you want to install the files to.</para> - - <screen>&prompt.root; <userinput>make DESTDIR=<replaceable>/usr/local/www</replaceable> install</userinput></screen> - </step> - - <step> - <para>If you have previously installed the web pages in to the same - directory the install process will not have deleted any old or - outdated pages. For example, if you build and install a new copy - of the site 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 -print0 | xargs -0 rm</userinput></screen> - </step> - </procedure> - </sect1> - - <sect1> - <title>Environment variables</title> - - <variablelist> - <varlistentry> - <term><envar>CVSROOT</envar></term> - - <listitem> - <para>Location of the CVS tree. Essential.</para> - - <screen><userinput>&prompt.root; CVSROOT=/home/ncvs; export CVSROOT</userinput></screen> - </listitem> - </varlistentry> - - <varlistentry> - <term><makevar>ENGLISH_ONLY</makevar></term> - - <listitem> - <para>If set and not empty, the makefiles will build and - install only the English documents. All translations will be - ignored. E.g.:</para> - - <screen>&prompt.root; <userinput>make ENGLISH_ONLY=YES all install</userinput></screen> - - <para>If you want unset the variable - <makevar>ENGLISH_ONLY</makevar> and build all pages, including - translations, set the variable <makevar>ENGLISH_ONLY</makevar> - to an empty value</para> - - <screen>&prompt.root; <userinput>make ENGLISH_ONLY="" all install clean</userinput></screen> - </listitem> - </varlistentry> - - <varlistentry> - <term><makevar>WEB_ONLY</makevar></term> - - <listitem> - <para>If set and not empty, the makefiles wil build and install - only the HTML pages from the www directory. All documents from - the doc directory (Handbook, FAQ, Tutorials) will be ignored. - E.g.:</para> - - <screen>&prompt.root; <userinput>make WEB_ONLY=YES all install</userinput></screen> - </listitem> - </varlistentry> - - <varlistentry> - <term><makevar>NOPORTSCVS</makevar></term> - - <listitem> - <para>If set, the makefiles will not checkout files from the ports - cvs repository. Instead, it will copy the files from - <filename>/usr/ports</filename> (or where the variable - <envar>PORTSBASE</envar> points to).</para> - </listitem> - </varlistentry> - </variablelist> - - <para><envar>CVSROOT</envar> is an environment variable. You must set it - on the commandline or in your dot files (~/.profile).</para> - - <para><makevar>WEB_ONLY</makevar>, <makevar>ENGLISH_ONLY</makevar> and - <makevar>NOPORTSCVS</makevar> are makefile variables. You can set the - variables in <filename>/etc/make.conf</filename>, - <filename>Makefile.inc</filename> or as environment variables on the - commandline or in your dot files.</para> - </sect1> -</chapter> - -<!-- - Local Variables: - mode: sgml - sgml-declaration: "../chapter.decl" - sgml-indent-data: t - sgml-omittag: nil - sgml-always-quote-attributes: t - sgml-parent-document: ("../book.sgml" "part" "chapter") - End: ---> diff --git a/en_US.ISO_8859-1/books/fdp-primer/tools/chapter.sgml b/en_US.ISO_8859-1/books/fdp-primer/tools/chapter.sgml deleted file mode 100644 index e676431422..0000000000 --- a/en_US.ISO_8859-1/books/fdp-primer/tools/chapter.sgml +++ /dev/null @@ -1,284 +0,0 @@ -<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved. - - Redistribution and use in source (SGML DocBook) and 'compiled' forms - (SGML, HTML, PDF, PostScript, RTF and so forth) with or without - modification, are permitted provided that the following conditions - are met: - - 1. Redistributions of source code (SGML DocBook) must retain the above - copyright notice, this list of conditions and the following - disclaimer as the first lines of this file unmodified. - - 2. Redistributions in compiled form (transformed to other DTDs, - converted to PDF, PostScript, RTF and other formats) must reproduce - the above copyright notice, this list of conditions and the - following disclaimer in the documentation and/or other materials - provided with the distribution. - - THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR - IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES - OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE - DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT, - INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES - (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR - SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) - HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, - STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN - ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE - POSSIBILITY OF SUCH DAMAGE. - - $FreeBSD: doc/en_US.ISO_8859-1/books/fdp-primer/tools/chapter.sgml,v 1.11 2001/03/13 23:11:25 dd Exp $ ---> - -<chapter id="tools"> - <title>Tools</title> - - <para>The FDP uses a number of different software tools to help - manage the FreeBSD documentation, convert it to different output - formats, and so on. You will need to use these tools yourself if - you are to work with the FreeBSD documentation.</para> - - <para>All these tools are available as FreeBSD Ports and Packages, - greatly simplifying the work you have to do to install - them.</para> - - <para>You will need to install these tools before you work through - any of the examples in later chapters. The actual usage of these - tools is covered in later chapters.</para> - - <important> - <title>Use <filename>textproc/docproj</filename> if possible</title> - - <para>You can save yourself a lot of time if you install the - <filename>textproc/docproj</filename> port. This is a - <emphasis>meta-port</emphasis> which does not contain any software - itself. Instead, it depends on various other ports being installed - correctly. Installing this port <emphasis>should</emphasis> - automatically download and install all of the packages listed in this - chapter that you need.</para> - - <para>One of the packages that you might need is the JadeTeX macro set. - In turn, this macro set requires that TeX is installed. TeX is a large - package, and you only need it if you want to produce Postscript or PDF - output.</para> - - <para>To save yourself time and space you must specify whether or not you - want JadeTeX (and therefore TeX) installed when you install this port. - Either do; - - <screen>&prompt.root; <userinput>make JADETEX=yes install</userinput></screen> - - or - - <screen>&prompt.root; <userinput>make JADETEX=no install</userinput></screen> - - as necessary.</para> - </important> - - <sect1> - <title>Mandatory tools</title> - - <sect2> - <title>Software</title> - - <para>These programs are required before you can usefully work with - the FreeBSD documentation. They are all included in - <filename>textproc/docproj</filename>.</para> - - <variablelist> - <varlistentry> - <term><application>SP</application> - (<filename>textproc/sp</filename>)</term> - - <listitem> - <para>A suite of applications, including a validating SGML parser, - and an SGML normaliser.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><application>Jade</application> - (<filename>textproc/jade</filename>)</term> - - <listitem> - <para>A DSSSL implementation. Used for converting marked up - documents to other formats, including HTML and TeX.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><application>Tidy</application> - (<filename>www/tidy</filename>)</term> - - <listitem> - <para>An HTML 'pretty printer', used to reformat some of the - automatically generated HTML so that it is easier to - follow.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><application>Links</application> - (<filename>www/links</filename>)</term> - - <listitem> - <para>A text-mode WWW browser, &man.links.1; can also convert - HTML files to plain text.</para> - </listitem> - </varlistentry> - </variablelist> - </sect2> - - <sect2> - <title>DTDs and Entities</title> - - <para>These are the DTDs and entity sets used by the FDP. They need to - be installed before you can work with any of the documentation.</para> - - <variablelist> - <varlistentry> - <term>HTML DTD (<filename>textproc/html</filename>)</term> - - <listitem> - <para>HTML is the markup language of choice for the World Wide - Web, and is used throughout the FreeBSD web site.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>LinuxDoc DTD (<filename>textproc/linuxdoc</filename>)</term> - - <listitem> - <para>Some FreeBSD documentation is marked up in LinuxDoc. The - FDP is actively migrating from LinuxDoc to DocBook.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>DocBook DTD (<filename>textproc/docbook</filename>)</term> - - <listitem> - <para>DocBook is designed for marking up technical documentation, - and the FDP is migrating from LinuxDoc to DocBook. At the time - of writing, this document and the FreeBSD Handbook are marked - up in DocBook.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>ISO 8879 entities - (<filename>textproc/iso8879</filename>)</term> - - <listitem> - <para>19 of the ISO 8879:1986 character entity sets used by many - DTDs. Includes named mathematical symbols, additional - characters in the 'latin' character set (accents, diacriticals, - and so on), and greek symbols.</para> - </listitem> - </varlistentry> - </variablelist> - </sect2> - - <sect2> - <title>Stylesheets</title> - - <para>The stylesheets are used when converting and formatting the - documentation for display on screen, printing, and so on.</para> - - <variablelist> - <varlistentry> - <term>Modular DocBook Stylesheets - (<filename>textproc/dsssl-docbook-modular</filename>)</term> - - <listitem> - <para>The Modular DocBook Stylesheets are used when converting - documentation marked up in DocBook to other formats, such as - HTML or RTF.</para> - </listitem> - </varlistentry> - </variablelist> - </sect2> - </sect1> - - <sect1> - <title>Optional tools</title> - - <para>You do not need to have any of the following installed. However, - you may find it easier to work with the documentation if you do, and - they may give you more flexibility in the output formats that can be - generated.</para> - - <sect2> - <title>Software</title> - - <variablelist> - <varlistentry> - <term><application>JadeTeX</application> and - <application>teTeX</application> - (<filename>print/jadetex</filename> and - <filename>print/teTeX</filename>)</term> - - <listitem> - <para><application>Jade</application> and - <application>teTeX</application> are used to convert DocBook - documents to DVI, Postscript, and PDF formats. The - <application>JadeTeX</application> macros are needed in order to - do this.</para> - - <para>If you do not intend to convert your documentation to one of - these formats (i.e., HTML, plain text, and RTF are sufficient) - then you do not need to install - <application>JadeTeX</application> and - <application>teTeX</application>. This can be a significant - space and time saver, as <application>teTeX</application> is - over 30MB in size.</para> - - <important> - <para>If you decide to install - <application>JadeTeX</application> and - <application>teTeX</application> then you will need to - configure <application>teTeX</application> after - <application>JadeTeX</application> has been installed. - <filename>print/jadetex/pkg-message</filename> contains - detailed instructions explaining what you need to do.</para> - </important> - </listitem> - </varlistentry> - - <varlistentry> - <term><application>Emacs</application> or - <application>xemacs</application> - (<filename>editors/emacs</filename> or - <filename>editors/xemacs</filename>)</term> - - <listitem> - <para>Both these editors include a special mode for editing - documents marked up according to an SGML DTD. This mode - includes commands to reduce the amount of typing you need, and - help reduce the possibility of errors.</para> - - <para>You do not need to use them; any text editor can be used to - edit marked up documents. You may find they make you more - efficient.</para> - </listitem> - </varlistentry> - </variablelist> - - <para>If anyone has recommendations for other software that is useful - when manipulating SGML documents, please let Nik Clayton - (<email>nik@FreeBSD.org</email>) know, so they can be added to this - list.</para> - </sect2> - </sect1> -</chapter> - -<!-- - Local Variables: - mode: sgml - sgml-declaration: "../chapter.decl" - sgml-indent-data: t - sgml-omittag: nil - sgml-always-quote-attributes: t - sgml-parent-document: ("../book.sgml" "part" "chapter") - End: ---> diff --git a/en_US.ISO_8859-1/books/fdp-primer/translations/chapter.sgml b/en_US.ISO_8859-1/books/fdp-primer/translations/chapter.sgml deleted file mode 100644 index 80b6315ef9..0000000000 --- a/en_US.ISO_8859-1/books/fdp-primer/translations/chapter.sgml +++ /dev/null @@ -1,480 +0,0 @@ -<!-- Copyright (c) 1999 Nik Clayton, All rights reserved. - - Redistribution and use in source (SGML DocBook) and 'compiled' forms - (SGML HTML, PDF, PostScript, RTF and so forth) with or without - modification, are permitted provided that the following conditions - are met: - - 1. Redistributions of source code (SGML DocBook) must retain the above - copyright notice, this list of conditions and the following - disclaimer as the first lines of this file unmodified. - - 2. Redistributions in compiled form (transformed to other DTDs, - converted to PDF, PostScript, RTF and other formats) must reproduce - the above copyright notice, this list of conditions and the - following disclaimer in the documentation and/or other materials - provided with the distribution. - - THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR - IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES - OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE - DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT, - INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES - (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR - SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) - HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, - STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN - ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE - POSSIBILITY OF SUCH DAMAGE. - - $FreeBSD: doc/en_US.ISO_8859-1/books/fdp-primer/translations/chapter.sgml,v 1.6 2000/08/03 23:20:48 ben Exp $ ---> - -<chapter id="translations"> - <title>Translations</title> - - <para>This is the FAQ for people translating the FreeBSD documentation - (FAQ, Handbook, tutorials, man 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 maintainer is Nik Clayton - <email>nik@FreeBSD.org</email>.</para> - - <qandaset> - <qandaentry> - <question> - <para>Why a FAQ?</para> - </question> - - <answer> - <para>More and more people are approaching the freebsd-doc mailing - list and volunteering to translate FreeBSD documentation to other - languages. This FAQ aims to answer their questions so they can start - translating documentation as quickly as possible.</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>What do <phrase>i18n</phrase> and <phrase>l10n</phrase> - mean?</para> - </question> - - <answer> - <para><phrase>i18n</phrase> means - <phrase>internationalisation</phrase> and <phrase>l10n</phrase> - means <phrase>localisation</phrase>. They are just a convenient - shorthand.</para> - - <para><phrase>i18n</phrase> can be read as “i” followed by - 18 letters, followed by “n”. Similarly, - <phrase>l10n</phrase> is “l” followed by 10 letters, - followed by “n”.</para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>Is there a mailing list for translators?</para> - </question> - - <answer> - <para>Yes, <email>freebsd-translate@ngo.org.uk</email>. Subscribe by - sending a message to - <email>freebsd-translate-request@ngo.org.uk</email> with the word - <literal>subscribe</literal> in the body of the message.</para> - - <para>You will receive a reply asking you to confirm your subscription - (in exactly the same manner as the the FreeBSD lists at <hostid - role="domainname">FreeBSD.org</hostid>).</para> - - <para>The primary language of the mailing list is English. However, - posts in other languages will be accepted. The mailing list is not - moderated, but you need to be a member of the list before you can - post to it.</para> - - <para>The mailing list is archived, but they are not currently - searchable. Sending the message <literal>help</literal> to - <email>majordomo@ngo.org.uk</email> will send back instructions on - how to access the archive.</para> - - <para>It is expected that the mailing list will transfer to <hostid - role="domainname">FreeBSD.org</hostid> and therefore become - <emphasis>official</emphasis> in the near future.</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 CVS repository (at least the documentation part) either - using <application>CTM</application> or - <application>CVSup</application>. The "Staying current with FreeBSD" - chapter in the Handbook explains how to use these - applications.</para> - - <para>You should be comfortable using <application>CVS</application>. - This will allow you to see what has changed between different - versions of the files that make up the documentation.</para> - - <para>[XXX To Do -- write a tutorial that shows how to use CVSup to - get just the documentation, check it out, and see what's changed - between two arbitrary revisions]</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 <ulink - url="http://www.FreeBSD.org/docproj/translations.html">Documentation - Project translations page</ulink> lists the translation efforts - that are currently known about. If others are already working - on translating documentation to your language, please don't - 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 - <email>freebsd-doc@FreeBSD.org</email> in case someone else is - thinking of doing a translation, but hasn't 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 “FreeBSD - <replaceable>your-language-here</replaceable> Documentation - Translation Project”. Welcome aboard.</para> - - <para>First, decide whether or not you've 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 publicise your work and - coordinate any volunteers that might want to help you.</para> - - <para>Write an e-mail 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>You should subscribe to the - <email>freebsd-translate@ngo.org.uk</email> mailing list (as - described earlier).</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 e-mail - 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've 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'm the only person working on translating to this language, how - do I submit my translation?</para> - - <para>or</para> - - <para>We're 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 organised properly. This - means that it should drop in to the existing documentation tree and - build straight away.</para> - - <para>Currently, the FreeBSD documentation is stored in a top level - directory called <filename>doc/</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>doc/ - sv_SE.ISO_8859-1/ - Makefile - books/ - faq/ - Makefile - book.sgml</programlisting> - - <para><literal>sv_SE.ISO_8859-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</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 e-mail Nik Clayton - <email>nik@FreeBSD.org</email>, and arrange to e-mail the files - when it is convenient.</para> - - <para>Either way, you should use &man.send-pr.1; 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 - Nik Clayton <email>nik@FreeBSD.org</email>) 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.ISO_8859-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 try and 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's 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 - and 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 &man.send-pr.1;) 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> - - <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 <filename>textproc/iso8879</filename>.</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 “e” with an acute accent</seg> - </seglistitem> - - <seglistitem> - <seg>&Eacute;</seg> - <seg>É</seg> - <seg>Large “E” with an acute accent</seg> - </seglistitem> - - <seglistitem> - <seg>&uuml;</seg> - <seg>ü</seg> - <seg>Small “u” with an umlaut</seg> - </seglistitem> - </segmentedlist> - - <para>After you have installed the iso8879 port, the files in - <filename>/usr/local/share/sgml/iso8879</filename> contain the - complete list.</para> - </question> - </qandaentry> - - <qandaentry> - <question> - <para>Addressing the reader</para> - </question> - - <answer> - <para>In the English documents, the reader is addressed as - “you”, 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: doc/en_US.ISO_8859-1/books/fdp-primer/translations/chapter.sgml,v 1.5 2000/07/07 18:38:38 dannyboy Exp $ ---></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 - CVS, 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: doc/es_ES.ISO_8859-1/books/fdp-primer/translations/chapter.sgml,v 1.3 1999/06/24 19:12:32 jesusr Exp $ - Original revision: 1.11 ---></programlisting> - </answer> - </qandaentry> - </qandaset> -</chapter> - -<!-- - Local Variables: - mode: sgml - sgml-declaration: "../chapter.decl" - sgml-indent-data: t - sgml-omittag: nil - sgml-always-quote-attributes: t - sgml-parent-document: ("../book.sgml" "part" "chapter") - End: ---> diff --git a/en_US.ISO_8859-1/books/fdp-primer/writing-style/chapter.sgml b/en_US.ISO_8859-1/books/fdp-primer/writing-style/chapter.sgml deleted file mode 100644 index 3e78167d13..0000000000 --- a/en_US.ISO_8859-1/books/fdp-primer/writing-style/chapter.sgml +++ /dev/null @@ -1,318 +0,0 @@ -<!-- Copyright (c) 1998 Nik Clayton, All rights reserved. - - Redistribution and use in source (SGML DocBook) and 'compiled' forms - (SGML HTML, PDF, PostScript, RTF and so forth) with or without - modification, are permitted provided that the following conditions - are met: - - 1. Redistributions of source code (SGML DocBook) must retain the above - copyright notice, this list of conditions and the following - disclaimer as the first lines of this file unmodified. - - 2. Redistributions in compiled form (transformed to other DTDs, - converted to PDF, PostScript, RTF and other formats) must reproduce - the above copyright notice, this list of conditions and the - following disclaimer in the documentation and/or other materials - provided with the distribution. - - THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR - IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES - OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE - DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT, - INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES - (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR - SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) - HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, - STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN - ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE - POSSIBILITY OF SUCH DAMAGE. - - $FreeBSD: doc/en_US.ISO_8859-1/books/fdp-primer/writing-style/chapter.sgml,v 1.11 2001/04/09 00:33:47 dd Exp $ ---> - -<chapter id="writing-style"> - <title>Writing style</title> - - <para>In order to promote consistency between the myriad authors of the - FreeBSD documentation, some guidelines have been drawn up for authors to - follow.</para> - - <variablelist> - <varlistentry> - <term>Do not use contractions</term> - - <listitem> - <para>Do not use contractions. Always spell the phrase out in full. - “Don't use contractions” would be 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. Seperate the last item from the others with - a comma and the word “and”.</para> - - <para>For example, look at the following:</para> - - <blockquote> - <para>This is a list of one, two and three items.</para> - </blockquote> - - <para>Is this a list of three items, “one”, - “two”, and “three”, or a list of two items, - “one” and “two and three”?</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>Try not to use redundant phrases. In particular, “the - command”, “the file”, and “man - command” are probably redundant.</para> - - <para>These two examples show this for commands. The second example - is preferred.</para> - - <informalexample> - <para>Use the command <command>cvsup</command> to update your - sources</para> - </informalexample> - - <informalexample> - <para>Use <command>cvsup</command> to update your sources</para> - </informalexample> - - <para>These two examples show this for filenames. The second example - is preferred.</para> - - <informalexample> - <para>… in the filename - <filename>/etc/rc.local</filename>…</para> - </informalexample> - - <informalexample> - <para>… in - <filename>/etc/rc.local</filename>…</para> - </informalexample> - - <para>These two examples show this for manual references. The second - example is preferred (the second example uses - <sgmltag>citerefentry</sgmltag>).</para> - - <informalexample> - <para>See <command>man csh</command> for more - information.</para> - </informalexample> - - <informalexample> - <para>See &man.csh.1;</para> - </informalexample> - </listitem> - </varlistentry> - <varlistentry> - <term>Two spaces at the end of sentences</term> - - <listitem> - <para>Always use two spaces at the end of sentences, as this - improves readability, and eases use of tools such as - <application>emacs</application>.</para> - - <para>While it may be argued that a capital letter following - a period denotes a new sentence, this is not the case, especially - in name usage. <quote>Jordan K. Hubbard</quote> is a good - example; it has a capital <literal>H</literal> following a - period and a space, and there certainly isn't a new sentence - there.</para> - </listitem> - </varlistentry> - </variablelist> - - <para>For more information about writing style, see <ulink - url="http://www.bartleby.com/141/index.html">Elements of - Style</ulink>, by William Strunk.</para> - - <sect1> - <title>Style guide</title> - - <para>To keep the source for the Handbook consistent when many different - people are editing it, please follow these style conventions.</para> - - <sect2> - <title>Letter case</title> - - <para>Tags are entered in lower case, <literal><para></literal>, - <emphasis>not</emphasis> <literal><PARA></literal>.</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> - <title>Indentation</title> - - <para>Each file starts with indentation set at column 0, - <emphasis>regardless</emphasis> of the indentation level of the file - which might contain this one.</para> - - <para>Every start tag increases the indentation level by 2 spaces, and - every end tag decreases the indentation level by 2 spaces. Replace - as many leading spaces with tabs as appropriate. 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 something - like:</para> - - <programlisting><![ CDATA [+--- This is column 0 -V -<chapter> - <title>...</title> - - <sect1> - <title>...</title> - - <sect2> - <title>Indentation</title> - - <para>Each file starts with indentation set at column 0, - <emphasis>regardless</emphasis> of the indentation level of the file - which might contain this one.</para> - - <para>Every start tag increases the indentation level by 2 spaces, and - every end tag decreases the indentation level by 2 spaces. Content - within elements should be indented by two spaces if the content runs - over more than one line.</para> - - ... - </sect2> - </sect1> -</chapter>]]></programlisting> - - <para>If you use <application>Emacs</application> or - <application>Xemacs</application> to edit the files then - <literal>sgml-mode</literal> should be loaded automatically, and the - Emacs local variables at the bottom of each file should enforce these - styles.</para> - </sect2> - - <sect2> - <title>Tag style</title> - - <sect3> - <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><![ CDATA [<article> - <articleinfo> - <title>NIS</title> - - <pubdate>October 1999</pubdata> - - <abstract> - <para>... - ... - ...</para> - </abstract> - </articleinfo> - - <sect1> - <title>...</title> - - <para>...</para> - </sect1> - - <sect1> - <title>...</title> - - <para>...</para> - </sect1> -</article>]]></programlisting> - </informalexample> - </sect3> - - <sect3> - <title>Separating tags</title> - - <para>Tags like <sgmltag>itemizedlist</sgmltag> which will - always have further tags inside them, and in fact don't take - character data themselves, are always on a line by - themselves.</para> - - <para>Tags like <sgmltag>para</sgmltag> and - <sgmltag>term</sgmltag> don't 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> - <title>White space changes</title> - - <para>When committing changes, <emphasis>do not commit changes to the - content at the same time as changes to the - formatting</emphasis>.</para> - - <para>This is so that the teams that convert the Handbook to other - languages can quickly see what content has actually changed in your - commit, without having to decide whether a line has changed because of - the content, or just because it has been refilled.</para> - - <para>For example, if you have added two sentences to a paragraph, such - that the line lengths on the paragraph now go over 80 columns, first - commit your change with the too-long line lengths. Then fix the line - wrapping, and commit this second change. In the commit message for - the second change, be sure to indicate that this is a whitespace-only - change, and that the translation team can ignore it.</para> - </sect2> - </sect1> -</chapter> - -<!-- - Local Variables: - mode: sgml - sgml-declaration: "../chapter.decl" - sgml-indent-data: t - sgml-omittag: nil - sgml-always-quote-attributes: t - sgml-parent-document: ("../book.sgml" "part" "chapter") - End: ---> - |