os/doc
3
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

My primer for people new to the Doc. Proj. Incomplete, but should be

Browse source 
enough for most people, and gets it into the repository, making it
easier for others to add to as necessary.

This has not (yet) been turned on in the upper level Makefile or
listed on the web site yet, I want to get some more feedback
from readers first.  It should be "made visible" later this week.
This commit is contained in:
Nik Clayton 1999-04-20 20:59:59 +00:00
parent 8bdee18bd8
commit c4ab126805
Notes: svn2git 2020-12-08 03:00:23 +00:00 
svn path=/head/; revision=4718
43 changed files with 15417 additions and 0 deletions
en/tutorials/docproj-primer
Makefilebook.sgmlchapter.declchapters.ent
overview
chapter.sgml
psgml-mode
chapter.sgml
see-also
chapter.sgml
sgml-markup
chapter.sgml
sgml-primer
chapter.sgml
stylesheets
chapter.sgml
the-faq
chapter.sgml
the-handbook
chapter.sgml
the-website
chapter.sgml
tools
chapter.sgml
writing-style
chapter.sgml
en_US.ISO8859-1/books/fdp-primer
Makefilebook.sgmlchapter.declchapters.ent
overview
chapter.sgml
psgml-mode
chapter.sgml
see-also
chapter.sgml
sgml-markup
chapter.sgml
sgml-primer
chapter.sgml
stylesheets
chapter.sgml
the-website
chapter.sgml
tools
chapter.sgml
writing-style
chapter.sgml
en_US.ISO_8859-1/books/fdp-primer
Makefilebook.sgmlchapter.declchapters.ent
overview
chapter.sgml
psgml-mode
chapter.sgml
see-also
chapter.sgml
sgml-markup
chapter.sgml
sgml-primer
chapter.sgml
stylesheets
chapter.sgml
the-faq
chapter.sgml
the-handbook
chapter.sgml
the-website
chapter.sgml
tools
chapter.sgml
writing-style
chapter.sgml

38
en/tutorials/docproj-primer/Makefile Normal file
View file

@ -0,0 +1,38 @@
#
# $Id: Makefile,v 1.1 1999-04-20 20:59:49 nik Exp $
#
# Build the FreeBSD Documentation Project Primer.
#
MAINTAINER=nik@FreeBSD.ORG
DOC?= book
FORMATS?= html-split
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+= the-faq/chapter.sgml
SRCS+= the-handbook/chapter.sgml
SRCS+= the-website/chapter.sgml
SRCS+= tools/chapter.sgml
SRCS+= writing-style/chapter.sgml
# Entities
SRCS+= chapters.ent
.include "../../../share/mk/docproj.docbook.mk"

278
en/tutorials/docproj-primer/book.sgml Normal file
View file

@ -0,0 +1,278 @@
<!-- 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.
-->
<!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook V3.0-Based Extension//EN" [
<!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN">
%man;
<!ENTITY % chapters SYSTEM "chapters.ent"> %chapters;
]>
<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>
<holder role="mailto:nik@FreeBSD.ORG">Nik Clayton</holder>
</copyright>
<pubdate role="rcs">$Date: 1999-04-20 20:59:49 $</pubdate>
<releaseinfo>$ID$</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, 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>
<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.sgml-primer;
&chap.tools;
&chap.sgml-markup;
&chap.stylesheets;
&chap.the-faq;
&chap.the-handbook;
&chap.the-website;
&chap.writing-style;
&chap.psgml-mode;
&chap.see-also;
</book>
<!--
Local Variables:
mode: sgml
sgml-indent-data: t
sgml-omittag: nil
sgml-always-quote-attributes: t
End:
-->

1
en/tutorials/docproj-primer/chapter.decl Normal file
View file

@ -0,0 +1 @@
<!DOCTYPE chapter PUBLIC "-//FreeBSD//DTD DocBook V3.0-Based Extension//EN">

22
en/tutorials/docproj-primer/chapters.ent Normal file
View file

@ -0,0 +1,22 @@
<!--
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.
$Id: chapters.ent,v 1.1 1999-04-20 20:59:49 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.the-faq SYSTEM "the-faq/chapter.sgml">
<!ENTITY chap.the-handbook SYSTEM "the-handbook/chapter.sgml">
<!ENTITY chap.the-website SYSTEM "the-website/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">

89
en/tutorials/docproj-primer/overview/chapter.sgml Normal file
View file

@ -0,0 +1,89 @@
<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved.
Redistribution and use in source (SGML DocBook) and 'compiled' forms
(SGML HTML, PDF, PostScript, RTF and so forth) with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code (SGML DocBook) must retain the above
copyright notice, this list of conditions and the following
disclaimer as the first lines of this file unmodified.
2. Redistributions in compiled form (transformed to other DTDs,
converted to PDF, PostScript, RTF and other formats) must reproduce
the above copyright notice, this list of conditions and the
following disclaimer in the documentation and/or other materials
provided with the distribution.
THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT,
INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
-->
<chapter id="overview">
<title>Overview</title>
<para>Welcome to the FreeBSD Documentation Project, and thank you for
volunteering. One of the keys to the success of a project such as FreeBSD
is the availability of good quality documentation, and your contribution
will help that success.</para>
<para>After you have read this primer you should;</para>
<itemizedlist>
<listitem>
<para>Have an understanding of the text formats used by the
Documentation Project, and why they were chosen.</para>
</listitem>
<listitem>
<para>Be able to read and understand the source code for the Handbook,
FAQ, and website, and follow how they are converted into HTML,
PostScript, and other formats.</para>
</listitem>
<listitem>
<para>Be able to make changes to the documentation, test them, and
either contribute them back to the project or (if you have commit
privileges) commit them.</para>
</listitem>
</itemizedlist>
<para>This primer assumes that you already understand;</para>
<itemizedlist>
<listitem>
<para>How to maintain an up-to-date copy of the FreeBSD CVS tree using
CVS and one of CVSup or CTM, and how to check out particular versions
of files.</para>
<para>Alternatively, how to retrieve versions of files using the
<application>CVSWeb</application> interface.</para>
</listitem>
<listitem>
<para>How to use the ports system to download and install new
software.</para>
</listitem>
</itemizedlist>
</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:
-->

148
en/tutorials/docproj-primer/psgml-mode/chapter.sgml Normal file
View file

@ -0,0 +1,148 @@
<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved.
Redistribution and use in source (SGML DocBook) and 'compiled' forms
(SGML HTML, PDF, PostScript, RTF and so forth) with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code (SGML DocBook) must retain the above
copyright notice, this list of conditions and the following
disclaimer as the first lines of this file unmodified.
2. Redistributions in compiled form (transformed to other DTDs,
converted to PDF, PostScript, RTF and other formats) must reproduce
the above copyright notice, this list of conditions and the
following disclaimer in the documentation and/or other materials
provided with the distribution.
THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT,
INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
-->
<chapter 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 <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:
-->

119
en/tutorials/docproj-primer/see-also/chapter.sgml Normal file
View file

@ -0,0 +1,119 @@
<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved.
Redistribution and use in source (SGML DocBook) and 'compiled' forms
(SGML HTML, PDF, PostScript, RTF and so forth) with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code (SGML DocBook) must retain the above
copyright notice, this list of conditions and the following
disclaimer as the first lines of this file unmodified.
2. Redistributions in compiled form (transformed to other DTDs,
converted to PDF, PostScript, RTF and other formats) must reproduce
the above copyright notice, this list of conditions and the
following disclaimer in the documentation and/or other materials
provided with the distribution.
THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT,
INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
-->
<chapter 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&amp;id=SG">http://etext.virginia.edu/bin/tei-tocs?div=DIV1&amp;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
organisation</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.oreilly.com/davenport/">The Davenport
Group</ulink>, maintainers of the DocBook DTD</para>
</listitem>
</itemizedlist>
</sect1>
<sect1>
<title>The Linux Documentation Project</title>
<itemizedlist>
<listitem>
<para><ulink url="http://metalab.unc.edu/LDP/">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:
-->

2210
en/tutorials/docproj-primer/sgml-markup/chapter.sgml Normal file
View file

File diff suppressed because it is too large Load diff

1554
en/tutorials/docproj-primer/sgml-primer/chapter.sgml Normal file
View file

File diff suppressed because it is too large Load diff

68
en/tutorials/docproj-primer/stylesheets/chapter.sgml Normal file
View file

@ -0,0 +1,68 @@
<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved.
Redistribution and use in source (SGML DocBook) and 'compiled' forms
(SGML HTML, PDF, PostScript, RTF and so forth) with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code (SGML DocBook) must retain the above
copyright notice, this list of conditions and the following
disclaimer as the first lines of this file unmodified.
2. Redistributions in compiled form (transformed to other DTDs,
converted to PDF, PostScript, RTF and other formats) must reproduce
the above copyright notice, this list of conditions and the
following disclaimer in the documentation and/or other materials
provided with the distribution.
THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT,
INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
-->
<chapter 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>
</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:
-->

47
en/tutorials/docproj-primer/the-faq/chapter.sgml Normal file
View file

@ -0,0 +1,47 @@
<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved.
Redistribution and use in source (SGML DocBook) and 'compiled' forms
(SGML HTML, PDF, PostScript, RTF and so forth) with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code (SGML DocBook) must retain the above
copyright notice, this list of conditions and the following
disclaimer as the first lines of this file unmodified.
2. Redistributions in compiled form (transformed to other DTDs,
converted to PDF, PostScript, RTF and other formats) must reproduce
the above copyright notice, this list of conditions and the
following disclaimer in the documentation and/or other materials
provided with the distribution.
THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT,
INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
-->
<chapter id="the-faq">
<title>* The FAQ</title>
<para></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:
-->

280
en/tutorials/docproj-primer/the-handbook/chapter.sgml Normal file
View file

@ -0,0 +1,280 @@
<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved.
Redistribution and use in source (SGML DocBook) and 'compiled' forms
(SGML HTML, PDF, PostScript, RTF and so forth) with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code (SGML DocBook) must retain the above
copyright notice, this list of conditions and the following
disclaimer as the first lines of this file unmodified.
2. Redistributions in compiled form (transformed to other DTDs,
converted to PDF, PostScript, RTF and other formats) must reproduce
the above copyright notice, this list of conditions and the
following disclaimer in the documentation and/or other materials
provided with the distribution.
THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT,
INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
-->
<chapter id="the-handbook">
<title>* The Handbook</title>
<sect1>
<title>Logical structure</title>
<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>
</sect1>
<sect1>
<title>Physical organisation</title>
<para>The Handbook (and its translations) are in the
<filename>doc/<replaceable>language</replaceable>/handbook</filename>
subdirectory of the main CVS
repository. <replaceable>language</replaceable> corresponds to the ISO
language code for that translation, <literal>en</literal> for English,
<literal>ja</literal> for Japanese, and so on.</para>
<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>doc@FreeBSD.ORG</email>.</para>
</note>
<sect2>
<title><filename>Makefile</filename></title>
<para>The <filename>Makefile</filename> defines the rules that are used
to convert the Handbook from its source form (DocBook) to a number of
other target formats (including HTML, PostScript, and plain
text).</para>
<para>A more detailed description of the <filename>Makefile</filename>
is in <xref linkend="the-handbook-converting">.</para>
</sect2>
<sect2>
<title><filename>handbook.sgml</filename></title>
<para>This is the top level document in the Handbook. It contains the
Handbook's <link linkend="doctype-declaration">DOCTYPE
declaration</link>, as well as the elements that describe the
Handbook's structure.</para>
<para><filename>handbook.sgml</filename> uses <link
linkend="parameter-entities">parameter entities</link> to load in
the files with the <filename>.ent</filename> extension. These files
(described later) then define <link linkend="general-entities">general
entities</link> that are used throughout the rest of the
Handbook.</para>
</sect2>
<sect2>
<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>handbook.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
line at the start of the file.</para>
<para>This is unfortunate for two reasons;</para>
<itemizedlist>
<listitem>
<para>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 as had on just one
chapter.</para>
</listitem>
<listitem>
<para>Emacs' <literal>sgml-mode</literal> can not use it to
determine the DTD to use, losing useful benefits of
<literal>sgml-mode</literal> (element completion, automatic
validation, and so on).</para>
</listitem>
</itemizedlist>
</sect2>
</sect1>
<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>&lt;para&gt;</literal>,
<emphasis>not</emphasis> <literal>&lt;PARA&gt;</literal>.</para>
<para>Text that appears in SGML contexts is generally written in upper
case, <literal>&lt!ENTITY&hellip;&gt;</literal>, and
<literal>&lt;!DOCTYPE&hellip;&gt;</literal>, <emphasis>not</emphasis>
<literal>&lt;!entity&hellip;&gt;</literal> and
<literal>&lt;!doctype&hellip;&gt;</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. 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>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 sentances 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>
<sect1 id="the-handbook-converting">
<title>Converting the Handbook to other formats</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:
-->

47
en/tutorials/docproj-primer/the-website/chapter.sgml Normal file
View file

@ -0,0 +1,47 @@
<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved.
Redistribution and use in source (SGML DocBook) and 'compiled' forms
(SGML HTML, PDF, PostScript, RTF and so forth) with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code (SGML DocBook) must retain the above
copyright notice, this list of conditions and the following
disclaimer as the first lines of this file unmodified.
2. Redistributions in compiled form (transformed to other DTDs,
converted to PDF, PostScript, RTF and other formats) must reproduce
the above copyright notice, this list of conditions and the
following disclaimer in the documentation and/or other materials
provided with the distribution.
THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT,
INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
-->
<chapter id="the-website">
<title>* The Website</title>
<para></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:
-->

210
en/tutorials/docproj-primer/tools/chapter.sgml Normal file
View file

@ -0,0 +1,210 @@
<chapter id="tools">
<title>* Tools</title>
<para>The Documentation Project uses a number of tools to assist in the
production of documentation. You will need to install some or all of these
tools before you will be able to make changes.</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 that are missing from your system.</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>Software</title>
<para>The project uses the following applications;</para>
<variablelist>
<varlistentry>
<term><application>Jade</application> and
<application>SP</application></term>
<listitem>
<para>These are two application suites by James Clark, who has
produced many useful SGML-processing applications.
<application>Jade</application> is &ldquo;James' DSSSL
Engine&rdquo;, a system that takes SGML documentation and a DSSSL
stylesheet and produces converted output.
<application>SP</application> contains a number of useful
applications to manipulate, normalise, and interrogate SGML
documents.</para>
<para>Don't be concerned if these terms are unfamliar to you.</para>
<para>They can be found in the ports system as
<filename>textproc/jade</filename> and
<filename>textproc/sp</filename> respectively.</para>
<note>
<para>Installed as part of
<filename>textproc/docproj</filename>.</para>
</note>
</listitem>
</varlistentry>
<varlistentry>
<term><application>teTeX</application></term>
<listitem>
<para><application>teTeX</application> is a distrubution of the TeX
typesetting system, and is used (in conjunction with Jade) to
produce the Postscript and PDF output formats.</para>
<para>v0.9 of <application>teTeX</application> is required, which is
currently in the ports collection as
<filename>print/teTeX-beta</filename>.</para>
<note>
<para>Might be installed as part of
<filename>textproc/docproj</filename>, depending on the
<makevar>JADETEX</makevar> setting.</para>
</note>
</listitem>
</varlistentry>
<varlistentry>
<term><application>Emacs</application> or
<application>Xemacs</application></term>
<listitem>
<para>Neither of these programs is required. However, both of them
feature PSGML-MODE, a useful extension when dealing with SGML
documents that can reduce the amount of typing you need to do, and
remove some of the more obvious errors.</para>
<para>They can be found in <filename>editor/emacs20</filename> and
<filename>editor/xemacs20</filename>.</para>
<note>
<para>Not installed as part of
<filename>textproc/docproj</filename>.</para>
</note>
</listitem>
</varlistentry>
</variablelist>
</sect1>
<sect1>
<title>Document Type Definitions (DTDs)</title>
<para>The project uses the following DTDs;</para>
<variablelist>
<varlistentry>
<term>HTML</term>
<listitem>
<para>HTML, the HyperText Markup Language, is the markup language of
choice on the World Wide Web. More information can be found at
&lt;URL:<ulink
url="http://www.w3.org/">http://www.w3.org/</ulink>&gt;.</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> category.</para>
<note>
<para>Installed as part of
<filename>textproc/docproj</filename>.</para>
</note>
</listitem>
</varlistentry>
<varlistentry>
<term>LinuxDoc</term>
<listitem>
<para>LinuxDoc is an adaptation of the QWERTZ DTD, first adopted by
the <ulink url="http://sunsite.unc.edu/LDP/">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>
<note>
<para>Installed as part of
<filename>textproc/docproj</filename>.</para>
</note>
</listitem>
</varlistentry>
<varlistentry>
<term>DocBook</term>
<listitem>
<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, it
contains XXX</para>
<note>
<para>Installed as part of
<filename>textproc/docproj</filename>.</para>
</note>
</listitem>
</varlistentry>
</variablelist>
</sect1>
<sect1>
<title>DSSSL Stylesheets</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>
<note>
<para>Installed as part of <filename>textproc/docproj</filename>.</para>
</note>
</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:
-->

137
en/tutorials/docproj-primer/writing-style/chapter.sgml Normal file
View file

@ -0,0 +1,137 @@
<!-- Copyright (c) 1998 Nik Clayton, All rights reserved.
Redistribution and use in source (SGML DocBook) and 'compiled' forms
(SGML HTML, PDF, PostScript, RTF and so forth) with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code (SGML DocBook) must retain the above
copyright notice, this list of conditions and the following
disclaimer as the first lines of this file unmodified.
2. Redistributions in compiled form (transformed to other DTDs,
converted to PDF, PostScript, RTF and other formats) must reproduce
the above copyright notice, this list of conditions and the
following disclaimer in the documentation and/or other materials
provided with the distribution.
THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT,
INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
-->
<chapter 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.
&ldquo;Don't use contractions&rdquo; would be wrong.</para>
<para>Avoiding contractions makes for a more formal tone, is more
precise, and slightly easier for translators.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Use the serial comma</term>
<listitem>
<para>In a list of items within a paragraph, seperate each item from
the others with a comma. Seperate the last item from the others with
a comma and the word &ldquo;and&rdquo;.</para>
<para>For example, look at the following quote;</para>
<blockquote>
<para>This is a list of one, two and three items.</para>
</blockquote>
<para>Is this a list of three items, &ldquo;one&rdquo;,
&ldquo;two&rdquo;, and &ldquo;three&rdquo;, or a list of two items,
&ldquo;one&rdquo; and &ldquo;two and three&rdquo;?</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, &ldquo;the
command&rdquo;, &ldquo;the file&rdquo;, and &ldquo;man
command&rdquo; 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>&hellip; in the filename
<filename>/etc/rc.local</filename>&hellip;</para>
</informalexample>
<informalexample>
<para>&hellip; in
<filename>/etc/rc.local</filename>&hellip;</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>
</variablelist>
</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:
-->

38
en_US.ISO8859-1/books/fdp-primer/Makefile Normal file
View file

@ -0,0 +1,38 @@
#
# $Id: Makefile,v 1.1 1999-04-20 20:59:49 nik Exp $
#
# Build the FreeBSD Documentation Project Primer.
#
MAINTAINER=nik@FreeBSD.ORG
DOC?= book
FORMATS?= html-split
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+= the-faq/chapter.sgml
SRCS+= the-handbook/chapter.sgml
SRCS+= the-website/chapter.sgml
SRCS+= tools/chapter.sgml
SRCS+= writing-style/chapter.sgml
# Entities
SRCS+= chapters.ent
.include "../../../share/mk/docproj.docbook.mk"

278
en_US.ISO8859-1/books/fdp-primer/book.sgml Normal file
View file

@ -0,0 +1,278 @@
<!-- 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.
-->
<!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook V3.0-Based Extension//EN" [
<!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN">
%man;
<!ENTITY % chapters SYSTEM "chapters.ent"> %chapters;
]>
<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>
<holder role="mailto:nik@FreeBSD.ORG">Nik Clayton</holder>
</copyright>
<pubdate role="rcs">$Date: 1999-04-20 20:59:49 $</pubdate>
<releaseinfo>$ID$</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, 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>
<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.sgml-primer;
&chap.tools;
&chap.sgml-markup;
&chap.stylesheets;
&chap.the-faq;
&chap.the-handbook;
&chap.the-website;
&chap.writing-style;
&chap.psgml-mode;
&chap.see-also;
</book>
<!--
Local Variables:
mode: sgml
sgml-indent-data: t
sgml-omittag: nil
sgml-always-quote-attributes: t
End:
-->

1
en_US.ISO8859-1/books/fdp-primer/chapter.decl Normal file
View file

@ -0,0 +1 @@
<!DOCTYPE chapter PUBLIC "-//FreeBSD//DTD DocBook V3.0-Based Extension//EN">

22
en_US.ISO8859-1/books/fdp-primer/chapters.ent Normal file
View file

@ -0,0 +1,22 @@
<!--
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.
$Id: chapters.ent,v 1.1 1999-04-20 20:59:49 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.the-faq SYSTEM "the-faq/chapter.sgml">
<!ENTITY chap.the-handbook SYSTEM "the-handbook/chapter.sgml">
<!ENTITY chap.the-website SYSTEM "the-website/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">

89
en_US.ISO8859-1/books/fdp-primer/overview/chapter.sgml Normal file
View file

@ -0,0 +1,89 @@
<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved.
Redistribution and use in source (SGML DocBook) and 'compiled' forms
(SGML HTML, PDF, PostScript, RTF and so forth) with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code (SGML DocBook) must retain the above
copyright notice, this list of conditions and the following
disclaimer as the first lines of this file unmodified.
2. Redistributions in compiled form (transformed to other DTDs,
converted to PDF, PostScript, RTF and other formats) must reproduce
the above copyright notice, this list of conditions and the
following disclaimer in the documentation and/or other materials
provided with the distribution.
THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT,
INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
-->
<chapter id="overview">
<title>Overview</title>
<para>Welcome to the FreeBSD Documentation Project, and thank you for
volunteering. One of the keys to the success of a project such as FreeBSD
is the availability of good quality documentation, and your contribution
will help that success.</para>
<para>After you have read this primer you should;</para>
<itemizedlist>
<listitem>
<para>Have an understanding of the text formats used by the
Documentation Project, and why they were chosen.</para>
</listitem>
<listitem>
<para>Be able to read and understand the source code for the Handbook,
FAQ, and website, and follow how they are converted into HTML,
PostScript, and other formats.</para>
</listitem>
<listitem>
<para>Be able to make changes to the documentation, test them, and
either contribute them back to the project or (if you have commit
privileges) commit them.</para>
</listitem>
</itemizedlist>
<para>This primer assumes that you already understand;</para>
<itemizedlist>
<listitem>
<para>How to maintain an up-to-date copy of the FreeBSD CVS tree using
CVS and one of CVSup or CTM, and how to check out particular versions
of files.</para>
<para>Alternatively, how to retrieve versions of files using the
<application>CVSWeb</application> interface.</para>
</listitem>
<listitem>
<para>How to use the ports system to download and install new
software.</para>
</listitem>
</itemizedlist>
</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:
-->

148
en_US.ISO8859-1/books/fdp-primer/psgml-mode/chapter.sgml Normal file
View file

@ -0,0 +1,148 @@
<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved.
Redistribution and use in source (SGML DocBook) and 'compiled' forms
(SGML HTML, PDF, PostScript, RTF and so forth) with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code (SGML DocBook) must retain the above
copyright notice, this list of conditions and the following
disclaimer as the first lines of this file unmodified.
2. Redistributions in compiled form (transformed to other DTDs,
converted to PDF, PostScript, RTF and other formats) must reproduce
the above copyright notice, this list of conditions and the
following disclaimer in the documentation and/or other materials
provided with the distribution.
THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT,
INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
-->
<chapter 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 <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:
-->

119
en_US.ISO8859-1/books/fdp-primer/see-also/chapter.sgml Normal file
View file

@ -0,0 +1,119 @@
<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved.
Redistribution and use in source (SGML DocBook) and 'compiled' forms
(SGML HTML, PDF, PostScript, RTF and so forth) with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code (SGML DocBook) must retain the above
copyright notice, this list of conditions and the following
disclaimer as the first lines of this file unmodified.
2. Redistributions in compiled form (transformed to other DTDs,
converted to PDF, PostScript, RTF and other formats) must reproduce
the above copyright notice, this list of conditions and the
following disclaimer in the documentation and/or other materials
provided with the distribution.
THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT,
INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
-->
<chapter 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&amp;id=SG">http://etext.virginia.edu/bin/tei-tocs?div=DIV1&amp;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
organisation</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.oreilly.com/davenport/">The Davenport
Group</ulink>, maintainers of the DocBook DTD</para>
</listitem>
</itemizedlist>
</sect1>
<sect1>
<title>The Linux Documentation Project</title>
<itemizedlist>
<listitem>
<para><ulink url="http://metalab.unc.edu/LDP/">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:
-->

2210
en_US.ISO8859-1/books/fdp-primer/sgml-markup/chapter.sgml Normal file
View file

File diff suppressed because it is too large Load diff

1554
en_US.ISO8859-1/books/fdp-primer/sgml-primer/chapter.sgml Normal file
View file

File diff suppressed because it is too large Load diff

68
en_US.ISO8859-1/books/fdp-primer/stylesheets/chapter.sgml Normal file
View file

@ -0,0 +1,68 @@
<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved.
Redistribution and use in source (SGML DocBook) and 'compiled' forms
(SGML HTML, PDF, PostScript, RTF and so forth) with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code (SGML DocBook) must retain the above
copyright notice, this list of conditions and the following
disclaimer as the first lines of this file unmodified.
2. Redistributions in compiled form (transformed to other DTDs,
converted to PDF, PostScript, RTF and other formats) must reproduce
the above copyright notice, this list of conditions and the
following disclaimer in the documentation and/or other materials
provided with the distribution.
THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT,
INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
-->
<chapter 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>
</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:
-->

47
en_US.ISO8859-1/books/fdp-primer/the-website/chapter.sgml Normal file
View file

@ -0,0 +1,47 @@
<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved.
Redistribution and use in source (SGML DocBook) and 'compiled' forms
(SGML HTML, PDF, PostScript, RTF and so forth) with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code (SGML DocBook) must retain the above
copyright notice, this list of conditions and the following
disclaimer as the first lines of this file unmodified.
2. Redistributions in compiled form (transformed to other DTDs,
converted to PDF, PostScript, RTF and other formats) must reproduce
the above copyright notice, this list of conditions and the
following disclaimer in the documentation and/or other materials
provided with the distribution.
THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT,
INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
-->
<chapter id="the-website">
<title>* The Website</title>
<para></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:
-->

210
en_US.ISO8859-1/books/fdp-primer/tools/chapter.sgml Normal file
View file

@ -0,0 +1,210 @@
<chapter id="tools">
<title>* Tools</title>
<para>The Documentation Project uses a number of tools to assist in the
production of documentation. You will need to install some or all of these
tools before you will be able to make changes.</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 that are missing from your system.</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>Software</title>
<para>The project uses the following applications;</para>
<variablelist>
<varlistentry>
<term><application>Jade</application> and
<application>SP</application></term>
<listitem>
<para>These are two application suites by James Clark, who has
produced many useful SGML-processing applications.
<application>Jade</application> is &ldquo;James' DSSSL
Engine&rdquo;, a system that takes SGML documentation and a DSSSL
stylesheet and produces converted output.
<application>SP</application> contains a number of useful
applications to manipulate, normalise, and interrogate SGML
documents.</para>
<para>Don't be concerned if these terms are unfamliar to you.</para>
<para>They can be found in the ports system as
<filename>textproc/jade</filename> and
<filename>textproc/sp</filename> respectively.</para>
<note>
<para>Installed as part of
<filename>textproc/docproj</filename>.</para>
</note>
</listitem>
</varlistentry>
<varlistentry>
<term><application>teTeX</application></term>
<listitem>
<para><application>teTeX</application> is a distrubution of the TeX
typesetting system, and is used (in conjunction with Jade) to
produce the Postscript and PDF output formats.</para>
<para>v0.9 of <application>teTeX</application> is required, which is
currently in the ports collection as
<filename>print/teTeX-beta</filename>.</para>
<note>
<para>Might be installed as part of
<filename>textproc/docproj</filename>, depending on the
<makevar>JADETEX</makevar> setting.</para>
</note>
</listitem>
</varlistentry>
<varlistentry>
<term><application>Emacs</application> or
<application>Xemacs</application></term>
<listitem>
<para>Neither of these programs is required. However, both of them
feature PSGML-MODE, a useful extension when dealing with SGML
documents that can reduce the amount of typing you need to do, and
remove some of the more obvious errors.</para>
<para>They can be found in <filename>editor/emacs20</filename> and
<filename>editor/xemacs20</filename>.</para>
<note>
<para>Not installed as part of
<filename>textproc/docproj</filename>.</para>
</note>
</listitem>
</varlistentry>
</variablelist>
</sect1>
<sect1>
<title>Document Type Definitions (DTDs)</title>
<para>The project uses the following DTDs;</para>
<variablelist>
<varlistentry>
<term>HTML</term>
<listitem>
<para>HTML, the HyperText Markup Language, is the markup language of
choice on the World Wide Web. More information can be found at
&lt;URL:<ulink
url="http://www.w3.org/">http://www.w3.org/</ulink>&gt;.</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> category.</para>
<note>
<para>Installed as part of
<filename>textproc/docproj</filename>.</para>
</note>
</listitem>
</varlistentry>
<varlistentry>
<term>LinuxDoc</term>
<listitem>
<para>LinuxDoc is an adaptation of the QWERTZ DTD, first adopted by
the <ulink url="http://sunsite.unc.edu/LDP/">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>
<note>
<para>Installed as part of
<filename>textproc/docproj</filename>.</para>
</note>
</listitem>
</varlistentry>
<varlistentry>
<term>DocBook</term>
<listitem>
<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, it
contains XXX</para>
<note>
<para>Installed as part of
<filename>textproc/docproj</filename>.</para>
</note>
</listitem>
</varlistentry>
</variablelist>
</sect1>
<sect1>
<title>DSSSL Stylesheets</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>
<note>
<para>Installed as part of <filename>textproc/docproj</filename>.</para>
</note>
</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:
-->

137
en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.sgml Normal file
View file

@ -0,0 +1,137 @@
<!-- Copyright (c) 1998 Nik Clayton, All rights reserved.
Redistribution and use in source (SGML DocBook) and 'compiled' forms
(SGML HTML, PDF, PostScript, RTF and so forth) with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code (SGML DocBook) must retain the above
copyright notice, this list of conditions and the following
disclaimer as the first lines of this file unmodified.
2. Redistributions in compiled form (transformed to other DTDs,
converted to PDF, PostScript, RTF and other formats) must reproduce
the above copyright notice, this list of conditions and the
following disclaimer in the documentation and/or other materials
provided with the distribution.
THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT,
INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
-->
<chapter 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.
&ldquo;Don't use contractions&rdquo; would be wrong.</para>
<para>Avoiding contractions makes for a more formal tone, is more
precise, and slightly easier for translators.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Use the serial comma</term>
<listitem>
<para>In a list of items within a paragraph, seperate each item from
the others with a comma. Seperate the last item from the others with
a comma and the word &ldquo;and&rdquo;.</para>
<para>For example, look at the following quote;</para>
<blockquote>
<para>This is a list of one, two and three items.</para>
</blockquote>
<para>Is this a list of three items, &ldquo;one&rdquo;,
&ldquo;two&rdquo;, and &ldquo;three&rdquo;, or a list of two items,
&ldquo;one&rdquo; and &ldquo;two and three&rdquo;?</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, &ldquo;the
command&rdquo;, &ldquo;the file&rdquo;, and &ldquo;man
command&rdquo; 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>&hellip; in the filename
<filename>/etc/rc.local</filename>&hellip;</para>
</informalexample>
<informalexample>
<para>&hellip; in
<filename>/etc/rc.local</filename>&hellip;</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>
</variablelist>
</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:
-->

38
en_US.ISO_8859-1/books/fdp-primer/Makefile Normal file
View file

@ -0,0 +1,38 @@
#
# $Id: Makefile,v 1.1 1999-04-20 20:59:49 nik Exp $
#
# Build the FreeBSD Documentation Project Primer.
#
MAINTAINER=nik@FreeBSD.ORG
DOC?= book
FORMATS?= html-split
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+= the-faq/chapter.sgml
SRCS+= the-handbook/chapter.sgml
SRCS+= the-website/chapter.sgml
SRCS+= tools/chapter.sgml
SRCS+= writing-style/chapter.sgml
# Entities
SRCS+= chapters.ent
.include "../../../share/mk/docproj.docbook.mk"

278
en_US.ISO_8859-1/books/fdp-primer/book.sgml Normal file
View file

@ -0,0 +1,278 @@
<!-- 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.
-->
<!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook V3.0-Based Extension//EN" [
<!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN">
%man;
<!ENTITY % chapters SYSTEM "chapters.ent"> %chapters;
]>
<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>
<holder role="mailto:nik@FreeBSD.ORG">Nik Clayton</holder>
</copyright>
<pubdate role="rcs">$Date: 1999-04-20 20:59:49 $</pubdate>
<releaseinfo>$ID$</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, 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>
<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.sgml-primer;
&chap.tools;
&chap.sgml-markup;
&chap.stylesheets;
&chap.the-faq;
&chap.the-handbook;
&chap.the-website;
&chap.writing-style;
&chap.psgml-mode;
&chap.see-also;
</book>
<!--
Local Variables:
mode: sgml
sgml-indent-data: t
sgml-omittag: nil
sgml-always-quote-attributes: t
End:
-->

1
en_US.ISO_8859-1/books/fdp-primer/chapter.decl Normal file
View file

@ -0,0 +1 @@
<!DOCTYPE chapter PUBLIC "-//FreeBSD//DTD DocBook V3.0-Based Extension//EN">

22
en_US.ISO_8859-1/books/fdp-primer/chapters.ent Normal file
View file

@ -0,0 +1,22 @@
<!--
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.
$Id: chapters.ent,v 1.1 1999-04-20 20:59:49 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.the-faq SYSTEM "the-faq/chapter.sgml">
<!ENTITY chap.the-handbook SYSTEM "the-handbook/chapter.sgml">
<!ENTITY chap.the-website SYSTEM "the-website/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">

89
en_US.ISO_8859-1/books/fdp-primer/overview/chapter.sgml Normal file
View file

@ -0,0 +1,89 @@
<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved.
Redistribution and use in source (SGML DocBook) and 'compiled' forms
(SGML HTML, PDF, PostScript, RTF and so forth) with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code (SGML DocBook) must retain the above
copyright notice, this list of conditions and the following
disclaimer as the first lines of this file unmodified.
2. Redistributions in compiled form (transformed to other DTDs,
converted to PDF, PostScript, RTF and other formats) must reproduce
the above copyright notice, this list of conditions and the
following disclaimer in the documentation and/or other materials
provided with the distribution.
THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT,
INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
-->
<chapter id="overview">
<title>Overview</title>
<para>Welcome to the FreeBSD Documentation Project, and thank you for
volunteering. One of the keys to the success of a project such as FreeBSD
is the availability of good quality documentation, and your contribution
will help that success.</para>
<para>After you have read this primer you should;</para>
<itemizedlist>
<listitem>
<para>Have an understanding of the text formats used by the
Documentation Project, and why they were chosen.</para>
</listitem>
<listitem>
<para>Be able to read and understand the source code for the Handbook,
FAQ, and website, and follow how they are converted into HTML,
PostScript, and other formats.</para>
</listitem>
<listitem>
<para>Be able to make changes to the documentation, test them, and
either contribute them back to the project or (if you have commit
privileges) commit them.</para>
</listitem>
</itemizedlist>
<para>This primer assumes that you already understand;</para>
<itemizedlist>
<listitem>
<para>How to maintain an up-to-date copy of the FreeBSD CVS tree using
CVS and one of CVSup or CTM, and how to check out particular versions
of files.</para>
<para>Alternatively, how to retrieve versions of files using the
<application>CVSWeb</application> interface.</para>
</listitem>
<listitem>
<para>How to use the ports system to download and install new
software.</para>
</listitem>
</itemizedlist>
</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:
-->

148
en_US.ISO_8859-1/books/fdp-primer/psgml-mode/chapter.sgml Normal file
View file

@ -0,0 +1,148 @@
<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved.
Redistribution and use in source (SGML DocBook) and 'compiled' forms
(SGML HTML, PDF, PostScript, RTF and so forth) with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code (SGML DocBook) must retain the above
copyright notice, this list of conditions and the following
disclaimer as the first lines of this file unmodified.
2. Redistributions in compiled form (transformed to other DTDs,
converted to PDF, PostScript, RTF and other formats) must reproduce
the above copyright notice, this list of conditions and the
following disclaimer in the documentation and/or other materials
provided with the distribution.
THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT,
INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
-->
<chapter 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 <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:
-->

119
en_US.ISO_8859-1/books/fdp-primer/see-also/chapter.sgml Normal file
View file

@ -0,0 +1,119 @@
<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved.
Redistribution and use in source (SGML DocBook) and 'compiled' forms
(SGML HTML, PDF, PostScript, RTF and so forth) with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code (SGML DocBook) must retain the above
copyright notice, this list of conditions and the following
disclaimer as the first lines of this file unmodified.
2. Redistributions in compiled form (transformed to other DTDs,
converted to PDF, PostScript, RTF and other formats) must reproduce
the above copyright notice, this list of conditions and the
following disclaimer in the documentation and/or other materials
provided with the distribution.
THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT,
INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
-->
<chapter 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&amp;id=SG">http://etext.virginia.edu/bin/tei-tocs?div=DIV1&amp;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
organisation</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.oreilly.com/davenport/">The Davenport
Group</ulink>, maintainers of the DocBook DTD</para>
</listitem>
</itemizedlist>
</sect1>
<sect1>
<title>The Linux Documentation Project</title>
<itemizedlist>
<listitem>
<para><ulink url="http://metalab.unc.edu/LDP/">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:
-->

2210
en_US.ISO_8859-1/books/fdp-primer/sgml-markup/chapter.sgml Normal file
View file

File diff suppressed because it is too large Load diff

1554
en_US.ISO_8859-1/books/fdp-primer/sgml-primer/chapter.sgml Normal file
View file

File diff suppressed because it is too large Load diff

68
en_US.ISO_8859-1/books/fdp-primer/stylesheets/chapter.sgml Normal file
View file

@ -0,0 +1,68 @@
<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved.
Redistribution and use in source (SGML DocBook) and 'compiled' forms
(SGML HTML, PDF, PostScript, RTF and so forth) with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code (SGML DocBook) must retain the above
copyright notice, this list of conditions and the following
disclaimer as the first lines of this file unmodified.
2. Redistributions in compiled form (transformed to other DTDs,
converted to PDF, PostScript, RTF and other formats) must reproduce
the above copyright notice, this list of conditions and the
following disclaimer in the documentation and/or other materials
provided with the distribution.
THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT,
INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
-->
<chapter 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>
</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:
-->

47
en_US.ISO_8859-1/books/fdp-primer/the-faq/chapter.sgml Normal file
View file

@ -0,0 +1,47 @@
<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved.
Redistribution and use in source (SGML DocBook) and 'compiled' forms
(SGML HTML, PDF, PostScript, RTF and so forth) with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code (SGML DocBook) must retain the above
copyright notice, this list of conditions and the following
disclaimer as the first lines of this file unmodified.
2. Redistributions in compiled form (transformed to other DTDs,
converted to PDF, PostScript, RTF and other formats) must reproduce
the above copyright notice, this list of conditions and the
following disclaimer in the documentation and/or other materials
provided with the distribution.
THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT,
INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
-->
<chapter id="the-faq">
<title>* The FAQ</title>
<para></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:
-->

280
en_US.ISO_8859-1/books/fdp-primer/the-handbook/chapter.sgml Normal file
View file

@ -0,0 +1,280 @@
<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved.
Redistribution and use in source (SGML DocBook) and 'compiled' forms
(SGML HTML, PDF, PostScript, RTF and so forth) with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code (SGML DocBook) must retain the above
copyright notice, this list of conditions and the following
disclaimer as the first lines of this file unmodified.
2. Redistributions in compiled form (transformed to other DTDs,
converted to PDF, PostScript, RTF and other formats) must reproduce
the above copyright notice, this list of conditions and the
following disclaimer in the documentation and/or other materials
provided with the distribution.
THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT,
INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
-->
<chapter id="the-handbook">
<title>* The Handbook</title>
<sect1>
<title>Logical structure</title>
<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>
</sect1>
<sect1>
<title>Physical organisation</title>
<para>The Handbook (and its translations) are in the
<filename>doc/<replaceable>language</replaceable>/handbook</filename>
subdirectory of the main CVS
repository. <replaceable>language</replaceable> corresponds to the ISO
language code for that translation, <literal>en</literal> for English,
<literal>ja</literal> for Japanese, and so on.</para>
<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>doc@FreeBSD.ORG</email>.</para>
</note>
<sect2>
<title><filename>Makefile</filename></title>
<para>The <filename>Makefile</filename> defines the rules that are used
to convert the Handbook from its source form (DocBook) to a number of
other target formats (including HTML, PostScript, and plain
text).</para>
<para>A more detailed description of the <filename>Makefile</filename>
is in <xref linkend="the-handbook-converting">.</para>
</sect2>
<sect2>
<title><filename>handbook.sgml</filename></title>
<para>This is the top level document in the Handbook. It contains the
Handbook's <link linkend="doctype-declaration">DOCTYPE
declaration</link>, as well as the elements that describe the
Handbook's structure.</para>
<para><filename>handbook.sgml</filename> uses <link
linkend="parameter-entities">parameter entities</link> to load in
the files with the <filename>.ent</filename> extension. These files
(described later) then define <link linkend="general-entities">general
entities</link> that are used throughout the rest of the
Handbook.</para>
</sect2>
<sect2>
<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>handbook.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
line at the start of the file.</para>
<para>This is unfortunate for two reasons;</para>
<itemizedlist>
<listitem>
<para>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 as had on just one
chapter.</para>
</listitem>
<listitem>
<para>Emacs' <literal>sgml-mode</literal> can not use it to
determine the DTD to use, losing useful benefits of
<literal>sgml-mode</literal> (element completion, automatic
validation, and so on).</para>
</listitem>
</itemizedlist>
</sect2>
</sect1>
<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>&lt;para&gt;</literal>,
<emphasis>not</emphasis> <literal>&lt;PARA&gt;</literal>.</para>
<para>Text that appears in SGML contexts is generally written in upper
case, <literal>&lt!ENTITY&hellip;&gt;</literal>, and
<literal>&lt;!DOCTYPE&hellip;&gt;</literal>, <emphasis>not</emphasis>
<literal>&lt;!entity&hellip;&gt;</literal> and
<literal>&lt;!doctype&hellip;&gt;</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. 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>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 sentances 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>
<sect1 id="the-handbook-converting">
<title>Converting the Handbook to other formats</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:
-->

47
en_US.ISO_8859-1/books/fdp-primer/the-website/chapter.sgml Normal file
View file

@ -0,0 +1,47 @@
<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved.
Redistribution and use in source (SGML DocBook) and 'compiled' forms
(SGML HTML, PDF, PostScript, RTF and so forth) with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code (SGML DocBook) must retain the above
copyright notice, this list of conditions and the following
disclaimer as the first lines of this file unmodified.
2. Redistributions in compiled form (transformed to other DTDs,
converted to PDF, PostScript, RTF and other formats) must reproduce
the above copyright notice, this list of conditions and the
following disclaimer in the documentation and/or other materials
provided with the distribution.
THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT,
INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
-->
<chapter id="the-website">
<title>* The Website</title>
<para></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:
-->

210
en_US.ISO_8859-1/books/fdp-primer/tools/chapter.sgml Normal file
View file

@ -0,0 +1,210 @@
<chapter id="tools">
<title>* Tools</title>
<para>The Documentation Project uses a number of tools to assist in the
production of documentation. You will need to install some or all of these
tools before you will be able to make changes.</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 that are missing from your system.</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>Software</title>
<para>The project uses the following applications;</para>
<variablelist>
<varlistentry>
<term><application>Jade</application> and
<application>SP</application></term>
<listitem>
<para>These are two application suites by James Clark, who has
produced many useful SGML-processing applications.
<application>Jade</application> is &ldquo;James' DSSSL
Engine&rdquo;, a system that takes SGML documentation and a DSSSL
stylesheet and produces converted output.
<application>SP</application> contains a number of useful
applications to manipulate, normalise, and interrogate SGML
documents.</para>
<para>Don't be concerned if these terms are unfamliar to you.</para>
<para>They can be found in the ports system as
<filename>textproc/jade</filename> and
<filename>textproc/sp</filename> respectively.</para>
<note>
<para>Installed as part of
<filename>textproc/docproj</filename>.</para>
</note>
</listitem>
</varlistentry>
<varlistentry>
<term><application>teTeX</application></term>
<listitem>
<para><application>teTeX</application> is a distrubution of the TeX
typesetting system, and is used (in conjunction with Jade) to
produce the Postscript and PDF output formats.</para>
<para>v0.9 of <application>teTeX</application> is required, which is
currently in the ports collection as
<filename>print/teTeX-beta</filename>.</para>
<note>
<para>Might be installed as part of
<filename>textproc/docproj</filename>, depending on the
<makevar>JADETEX</makevar> setting.</para>
</note>
</listitem>
</varlistentry>
<varlistentry>
<term><application>Emacs</application> or
<application>Xemacs</application></term>
<listitem>
<para>Neither of these programs is required. However, both of them
feature PSGML-MODE, a useful extension when dealing with SGML
documents that can reduce the amount of typing you need to do, and
remove some of the more obvious errors.</para>
<para>They can be found in <filename>editor/emacs20</filename> and
<filename>editor/xemacs20</filename>.</para>
<note>
<para>Not installed as part of
<filename>textproc/docproj</filename>.</para>
</note>
</listitem>
</varlistentry>
</variablelist>
</sect1>
<sect1>
<title>Document Type Definitions (DTDs)</title>
<para>The project uses the following DTDs;</para>
<variablelist>
<varlistentry>
<term>HTML</term>
<listitem>
<para>HTML, the HyperText Markup Language, is the markup language of
choice on the World Wide Web. More information can be found at
&lt;URL:<ulink
url="http://www.w3.org/">http://www.w3.org/</ulink>&gt;.</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> category.</para>
<note>
<para>Installed as part of
<filename>textproc/docproj</filename>.</para>
</note>
</listitem>
</varlistentry>
<varlistentry>
<term>LinuxDoc</term>
<listitem>
<para>LinuxDoc is an adaptation of the QWERTZ DTD, first adopted by
the <ulink url="http://sunsite.unc.edu/LDP/">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>
<note>
<para>Installed as part of
<filename>textproc/docproj</filename>.</para>
</note>
</listitem>
</varlistentry>
<varlistentry>
<term>DocBook</term>
<listitem>
<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, it
contains XXX</para>
<note>
<para>Installed as part of
<filename>textproc/docproj</filename>.</para>
</note>
</listitem>
</varlistentry>
</variablelist>
</sect1>
<sect1>
<title>DSSSL Stylesheets</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>
<note>
<para>Installed as part of <filename>textproc/docproj</filename>.</para>
</note>
</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:
-->

137
en_US.ISO_8859-1/books/fdp-primer/writing-style/chapter.sgml Normal file
View file

@ -0,0 +1,137 @@
<!-- Copyright (c) 1998 Nik Clayton, All rights reserved.
Redistribution and use in source (SGML DocBook) and 'compiled' forms
(SGML HTML, PDF, PostScript, RTF and so forth) with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code (SGML DocBook) must retain the above
copyright notice, this list of conditions and the following
disclaimer as the first lines of this file unmodified.
2. Redistributions in compiled form (transformed to other DTDs,
converted to PDF, PostScript, RTF and other formats) must reproduce
the above copyright notice, this list of conditions and the
following disclaimer in the documentation and/or other materials
provided with the distribution.
THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT,
INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
-->
<chapter 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.
&ldquo;Don't use contractions&rdquo; would be wrong.</para>
<para>Avoiding contractions makes for a more formal tone, is more
precise, and slightly easier for translators.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Use the serial comma</term>
<listitem>
<para>In a list of items within a paragraph, seperate each item from
the others with a comma. Seperate the last item from the others with
a comma and the word &ldquo;and&rdquo;.</para>
<para>For example, look at the following quote;</para>
<blockquote>
<para>This is a list of one, two and three items.</para>
</blockquote>
<para>Is this a list of three items, &ldquo;one&rdquo;,
&ldquo;two&rdquo;, and &ldquo;three&rdquo;, or a list of two items,
&ldquo;one&rdquo; and &ldquo;two and three&rdquo;?</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, &ldquo;the
command&rdquo;, &ldquo;the file&rdquo;, and &ldquo;man
command&rdquo; 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>&hellip; in the filename
<filename>/etc/rc.local</filename>&hellip;</para>
</informalexample>
<informalexample>
<para>&hellip; in
<filename>/etc/rc.local</filename>&hellip;</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>
</variablelist>
</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:
-->