aboutsummaryrefslogtreecommitdiff
path: root/en_US.ISO8859-1/books/fdp-primer
diff options
context:
space:
mode:
authorNik Clayton <nik@FreeBSD.org>1999-09-03 17:22:43 +0000
committerNik Clayton <nik@FreeBSD.org>1999-09-03 17:22:43 +0000
commit30bff5e9ff2cc964f1ad4e8caceed06eb0f438bd (patch)
treedd04fed7ed5d1bf52b92f9059bd3720980a3dc2c /en_US.ISO8859-1/books/fdp-primer
parent52eba2b89b15fbed08ea8cd187b155e4aa16b1a6 (diff)
downloaddoc-30bff5e9ff2cc964f1ad4e8caceed06eb0f438bd.tar.gz
doc-30bff5e9ff2cc964f1ad4e8caceed06eb0f438bd.zip
A new chapter that explains the structure of the doc/ tree and how
documentation is placed under it. Replaces the empty FAQ section and the only partly completed Handbook section. This is because the information in here applies to all the documentation under doc/, not just the Handbook. Move the style guide information out of the-handbook/chapter.sgml and in to writing-style/chapter.sgml. It doesn't really belong here either, but we don't have a general style chapter (yet). Update Makefile to know about this, and use the doc.project.mk file. Update book.sgml to know about the new chapter. Remove the old chapters.
Notes
Notes: svn path=/head/; revision=5510
Diffstat (limited to 'en_US.ISO8859-1/books/fdp-primer')
-rw-r--r--en_US.ISO8859-1/books/fdp-primer/Makefile9
-rw-r--r--en_US.ISO8859-1/books/fdp-primer/book.sgml9
-rw-r--r--en_US.ISO8859-1/books/fdp-primer/chapters.ent5
-rw-r--r--en_US.ISO8859-1/books/fdp-primer/structure/chapter.sgml299
-rw-r--r--en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.sgml90
5 files changed, 398 insertions, 14 deletions
diff --git a/en_US.ISO8859-1/books/fdp-primer/Makefile b/en_US.ISO8859-1/books/fdp-primer/Makefile
index ec34c30d36..054b703417 100644
--- a/en_US.ISO8859-1/books/fdp-primer/Makefile
+++ b/en_US.ISO8859-1/books/fdp-primer/Makefile
@@ -1,5 +1,5 @@
#
-# $Id: Makefile,v 1.5 1999-08-29 00:02:22 jhb Exp $
+# $Id: Makefile,v 1.6 1999-09-03 17:22:40 nik Exp $
#
# Build the FreeBSD Documentation Project Primer.
#
@@ -26,8 +26,7 @@ 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+= structure/chapter.sgml
SRCS+= the-website/chapter.sgml
SRCS+= tools/chapter.sgml
SRCS+= translations/chapter.sgml
@@ -36,6 +35,6 @@ SRCS+= writing-style/chapter.sgml
# Entities
SRCS+= chapters.ent
-DOC_PREFIX?= ../../..
+DOC_PREFIX?= ${.CURDIR}/../../..
-.include "${DOC_PREFIX}/share/mk/docproj.docbook.mk"
+.include "${DOC_PREFIX}/share/mk/doc.project.mk"
diff --git a/en_US.ISO8859-1/books/fdp-primer/book.sgml b/en_US.ISO8859-1/books/fdp-primer/book.sgml
index 57c3e91fa2..877a39e0f1 100644
--- a/en_US.ISO8859-1/books/fdp-primer/book.sgml
+++ b/en_US.ISO8859-1/books/fdp-primer/book.sgml
@@ -27,7 +27,7 @@
ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
- $Id: book.sgml,v 1.6 1999-08-29 16:08:38 jhb Exp $
+ $Id: book.sgml,v 1.7 1999-09-03 17:22:39 nik Exp $
-->
<!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN" [
@@ -56,9 +56,9 @@
<holder role="mailto:nik@FreeBSD.org">Nik Clayton</holder>
</copyright>
- <pubdate role="rcs">$Date: 1999-08-29 16:08:38 $</pubdate>
+ <pubdate role="rcs">$Date: 1999-09-03 17:22:39 $</pubdate>
- <releaseinfo>$Id: book.sgml,v 1.6 1999-08-29 16:08:38 jhb Exp $</releaseinfo>
+ <releaseinfo>$Id: book.sgml,v 1.7 1999-09-03 17:22:39 nik Exp $</releaseinfo>
<legalnotice>
<para>Redistribution and use in source (SGML DocBook) and 'compiled'
@@ -261,8 +261,7 @@ Password:</screen></entry>
&chap.sgml-primer;
&chap.sgml-markup;
&chap.stylesheets;
- &chap.the-faq;
- &chap.the-handbook;
+ &chap.structure;
&chap.the-website;
&chap.translations;
&chap.writing-style;
diff --git a/en_US.ISO8859-1/books/fdp-primer/chapters.ent b/en_US.ISO8859-1/books/fdp-primer/chapters.ent
index 3375e0085d..0983076bf3 100644
--- a/en_US.ISO8859-1/books/fdp-primer/chapters.ent
+++ b/en_US.ISO8859-1/books/fdp-primer/chapters.ent
@@ -6,7 +6,7 @@
Chapters should be listed in the order in which they are referenced.
- $Id: chapters.ent,v 1.2 1999-07-14 22:31:29 nik Exp $
+ $Id: chapters.ent,v 1.3 1999-09-03 17:22:39 nik Exp $
-->
<!ENTITY chap.overview SYSTEM "overview/chapter.sgml">
@@ -14,8 +14,7 @@
<!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.structure SYSTEM "structure/chapter.sgml">
<!ENTITY chap.the-website SYSTEM "the-website/chapter.sgml">
<!ENTITY chap.translations SYSTEM "translations/chapter.sgml">
<!ENTITY chap.writing-style SYSTEM "writing-style/chapter.sgml">
diff --git a/en_US.ISO8859-1/books/fdp-primer/structure/chapter.sgml b/en_US.ISO8859-1/books/fdp-primer/structure/chapter.sgml
new file mode 100644
index 0000000000..0fcb999857
--- /dev/null
+++ b/en_US.ISO8859-1/books/fdp-primer/structure/chapter.sgml
@@ -0,0 +1,299 @@
+<!-- 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.
+
+ $Id: chapter.sgml,v 1.1 1999-09-03 17:22:38 nik Exp $
+-->
+
+<chapter id="structure">
+ <title>Structuring documents under <filename>doc/</filename></title>
+
+ <para>The <filename>doc/</filename> tree is organised in a particular
+ fashion, and the documents that are part of the FDP are in turn organised
+ in a particular fashion. The aim is to make it simple to add new
+ documentation in to the tree and;</para>
+
+ <orderedlist>
+ <listitem>
+ <para>be easy to automate converting the document to other formats</para>
+ </listitem>
+
+ <listitem>
+ <para>promote consistency between the different documentation
+ organisations, to make it easier to switch between working on
+ different documents</para>
+ </listitem>
+
+ <listitem>
+ <para>make it easy to decide where in the tree new documentation should
+ be placed</para>
+ </listitem>
+ </orderedlist>
+
+ <para>In addition, the documentation tree has to accommodate documentation
+ that could be in many different languages and in many different
+ encodings. It is important that the structure of the documentation tree
+ does not enforce any particular defaults or cultural preferences.</para>
+
+ <sect1>
+ <title>The top level, <filename>doc/</filename></title>
+
+ <para>There are two types of directory under <filename>doc/</filename>,
+ each with very specific directory names and meanings.</para>
+
+ <segmentedlist>
+ <seglistitem>
+ <seg><filename>share/</filename></seg>
+
+ <seg>Contains files that are not specific to the various translations
+ and encodings of the documentation. Contains subdirectories to
+ further categorise the information. For example, the files that
+ comprise the &man.make.1; infrastructure are in
+ <filename>share/mk</filename>, while the additional SGML support
+ files (such as the FreeBSD extended DocBook DTD) are in
+ <filename>share/sgml</filename>.</seg>
+ </seglistitem>
+
+ <seglistitem>
+ <seg><filename><replaceable>lang</replaceable>.<replaceable>encoding</replaceable>/</filename></seg>
+
+ <seg>One directory exists for each available translation and encoding
+ of the documentation, for example
+ <filename>en_US.ISO_8859-1/</filename> and
+ <filename>zh_TW.Big5/</filename>. The names are long, but by fully
+ specifying the language and encoding we prevent any future headaches
+ should a translation team want to provide the documentation in the
+ same language but in more than one encoding. This also completely
+ isolates us from any problems that might be caused by a switch to
+ Unicode.</seg>
+ </seglistitem>
+ </segmentedlist>
+ </sect1>
+
+ <sect1>
+ <title>The
+ <filename><replaceable>lang</replaceable>.<replaceable>encoding</replaceable>/</filename> directories</title>
+
+ <para>These directories contain the documents themselves. The
+ documentation is split in to up to three more categories at this
+ level, indicated by the different directory names.</para>
+
+ <segmentedlist>
+ <seglistitem>
+ <seg><filename>articles</filename></seg>
+
+ <seg>Documentation marked up as a DocBook <sgmltag>article</sgmltag>
+ (or equivalent). Reasonably short, and broken up in to sections.
+ Normally only available as one HTML file.</seg>
+ </seglistitem>
+
+ <seglistitem>
+ <seg><filename>books</filename></seg>
+
+ <seg>Documentation marked up as a DocBook <sgmltag>book</sgmltag> (or
+ equivalent). Book length, and broken up in to chapters. Normally
+ available as both one large HTML file (for people with fast
+ connections, or who want to print it easily from their browser) and
+ as a collection of linked, smaller files.</seg>
+ </seglistitem>
+
+ <seglistitem>
+ <seg><filename>man</filename></seg>
+
+ <seg>For translations of the system manual pages. This directory will
+ contain one or more
+ <filename>man<replaceable>n</replaceable></filename> directories,
+ corresponding to the sections that have been translated.</seg>
+ </seglistitem>
+ </segmentedlist>
+
+ <para>Not every
+ <filename><replaceable>lang</replaceable>.<replaceable>encoding</replaceable></filename> directory will contain all of these directories. It depends
+ on much translation has been accomplished by that translation
+ team.</para>
+ </sect1>
+
+ <sect1>
+ <title>Document specific information</title>
+
+ <para>This section contains specific notes about particular documents
+ managed by the FDP.</para>
+
+ <sect2>
+ <title>The Handbook</title>
+
+ <subtitle><filename>books/handbook/</filename></subtitle>
+
+ <para>The Handbook is written to comply with the FreeBSD DocBook
+ extended DTD.</para>
+
+ <para>The Handbook is organised as a DocBook <sgmltag>book</sgmltag>.
+ It is then divided into <sgmltag>part</sgmltag>s, each of which may
+ contain several <sgmltag>chapter</sgmltag>s.
+ <sgmltag>chapter</sgmltag>s are further subdivided into sections
+ (<sgmltag>sect1</sgmltag>) and subsections (<sgmltag>sect2</sgmltag>,
+ <sgmltag>sect3</sgmltag>) and so on.</para>
+
+ <sect3>
+ <title>Physical organisation</title>
+
+ <para>There are a number of files and directories within the
+ <filename>handbook</filename> directory.</para>
+
+ <note>
+ <para>The Handbook's organisation may change over time, and this
+ document may lag in detailing the organisational changes. If you
+ have any questions about how the Handbook is organised, please
+ contact the FreeBSD Documentation Project,
+ <email>freebsd-doc@FreeBSD.org</email>.</para>
+ </note>
+
+ <sect4>
+ <title><filename>Makefile</filename></title>
+
+ <para>The <filename>Makefile</filename> defines some variables that
+ affect how the SGML source is converted to other formats, and
+ lists the various source files that make up the Handbook. It then
+ includes the standard <filename>doc.project.mk</filename> file, to
+ bring in the rest of the code that handles converting documents
+ from one format to another.</para>
+ </sect4>
+
+ <sect4>
+ <title><filename>book.sgml</filename></title>
+
+ <para>This is the top level document in the Handbook. It contains
+ the Handbook's <link
+ linkend="sgml-primer-doctype-declaration">DOCTYPE
+ declaration</link>, as well as the elements that describe the
+ Handbook's structure.</para>
+
+ <para><filename>book.sgml</filename> uses <link
+ linkend="sgml-primer-parameter-entities">parameter
+ entities</link> to load in the files with the
+ <filename>.ent</filename> extension. These files (described later)
+ then define <link linkend="sgml-primer-general-entities">general
+ entities</link> that are used throughout the rest of the
+ Handbook.</para>
+ </sect4>
+
+ <sect4>
+ <title><filename><replaceable>directory</replaceable>/chapter.sgml</filename></title>
+
+ <para>Each chapter in the Handbook is stored in a file called
+ <filename>chapter.sgml</filename> in a separate directory from the
+ other chapters. Each directory is named after the value of the
+ <literal>id</literal> attribute on the <sgmltag>chapter</sgmltag>
+ element.</para>
+
+ <para>For example, if one of the chapter files contains:</para>
+
+ <programlisting><![ CDATA [
+<chapter id="kernelconfiguration">
+...
+</chapter>]]></programlisting>
+
+ <para>then it will be called <filename>chapter.sgml</filename> in
+ the <filename>kernelconfiguration</filename> directory. In
+ general, the entire contents of the chapter will be held in this
+ file.</para>
+
+ <para>When the HTML version of the Handbook is produced, this will
+ yield <filename>kernelconfiguration.html</filename>. This is
+ because of the <literal>id</literal> value, and is not related to
+ the name of the directory.</para>
+
+ <para>In earlier versions of the Handbook the files were stored in
+ the same directory as <filename>book.sgml</filename>, and named
+ after the value of the <literal>id</literal> attribute on the
+ file's <sgmltag>chapter</sgmltag> element. Moving them in to
+ separate directories prepares for future plans for the Handbook.
+ Specifically, it will soon be possible to include images in each
+ chapter. It makes more sense for each image to be stored in a
+ directory with the text for the chapter than to try and keep the
+ text for all the chapters, and all the images, in one large
+ directory. Namespace collisions would be inevitable, and it is
+ easier to work with several directories with a few files in them
+ than it is to work with one directory that has many files in
+ it.</para>
+
+ <para>A brief look will show that there are many directories with
+ individual <filename>chapter.sgml</filename> files, including
+ <filename>basics/chapter.sgml</filename>,
+ <filename>introduction/chapter.sgml</filename>, and
+ <filename>printing/chapter.sgml</filename>.</para>
+
+ <important>
+ <para>Chapters and/or directories should not be named in a fashion
+ that reflects their ordering within the Handbook. This ordering
+ might change as the content within the Handbook is reorganised;
+ this sort of reorganistion should not (generally) include the
+ need to rename files (unless entire chapters are being promoted
+ or demoted within the hierarchy).</para>
+ </important>
+
+ <para>Each <filename>chapter.sgml</filename> file will not be a
+ complete SGML document. In particular, they will not have their
+ own DOCTYPE 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>
+ </sect4>
+ </sect3>
+ </sect2>
+ </sect1>
+</chapter>
+
+<!--
+ Local Variables:
+ mode: sgml
+ sgml-declaration: "../chapter.decl"
+ sgml-indent-data: t
+ sgml-omittag: nil
+ sgml-always-quote-attributes: t
+ sgml-parent-document: ("../book.sgml" "part" "chapter")
+ End:
+-->
+
diff --git a/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.sgml b/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.sgml
index c1e9fbde52..fb6746f935 100644
--- a/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.sgml
+++ b/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.sgml
@@ -27,7 +27,7 @@
ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
- $Id: chapter.sgml,v 1.3 1999-07-30 21:09:07 nik Exp $
+ $Id: chapter.sgml,v 1.4 1999-09-03 17:22:43 nik Exp $
-->
<chapter id="writing-style">
@@ -128,6 +128,94 @@
<para>For more information about writing style, see <ulink
url="http://www.columbia.edu/acis/bartleby/strunk/">Elements of
Style</ulink>, by William Strunk.</para>
+
+ <sect1>
+ <title>Style guide</title>
+
+ <para>To keep the source for the Handbook consistent when many different
+ people are editing it, please follow these style conventions.</para>
+
+ <sect2>
+ <title>Letter case</title>
+
+ <para>Tags are entered in lower case, <literal>&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>
</chapter>
<!--