diff options
Diffstat (limited to 'en_US.ISO_8859-1/books')
7 files changed, 398 insertions, 345 deletions
diff --git a/en_US.ISO_8859-1/books/fdp-primer/Makefile b/en_US.ISO_8859-1/books/fdp-primer/Makefile index ec34c30d36..054b703417 100644 --- a/en_US.ISO_8859-1/books/fdp-primer/Makefile +++ b/en_US.ISO_8859-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.ISO_8859-1/books/fdp-primer/book.sgml b/en_US.ISO_8859-1/books/fdp-primer/book.sgml index 57c3e91fa2..877a39e0f1 100644 --- a/en_US.ISO_8859-1/books/fdp-primer/book.sgml +++ b/en_US.ISO_8859-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.ISO_8859-1/books/fdp-primer/chapters.ent b/en_US.ISO_8859-1/books/fdp-primer/chapters.ent index 3375e0085d..0983076bf3 100644 --- a/en_US.ISO_8859-1/books/fdp-primer/chapters.ent +++ b/en_US.ISO_8859-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.ISO_8859-1/books/fdp-primer/structure/chapter.sgml b/en_US.ISO_8859-1/books/fdp-primer/structure/chapter.sgml new file mode 100644 index 0000000000..0fcb999857 --- /dev/null +++ b/en_US.ISO_8859-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.ISO_8859-1/books/fdp-primer/the-faq/chapter.sgml b/en_US.ISO_8859-1/books/fdp-primer/the-faq/chapter.sgml deleted file mode 100644 index 664c9bbf5e..0000000000 --- a/en_US.ISO_8859-1/books/fdp-primer/the-faq/chapter.sgml +++ /dev/null @@ -1,49 +0,0 @@ -<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved. - - Redistribution and use in source (SGML DocBook) and 'compiled' forms - (SGML HTML, PDF, PostScript, RTF and so forth) with or without - modification, are permitted provided that the following conditions - are met: - - 1. Redistributions of source code (SGML DocBook) must retain the above - copyright notice, this list of conditions and the following - disclaimer as the first lines of this file unmodified. - - 2. Redistributions in compiled form (transformed to other DTDs, - converted to PDF, PostScript, RTF and other formats) must reproduce - the above copyright notice, this list of conditions and the - following disclaimer in the documentation and/or other materials - provided with the distribution. - - THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR - IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES - OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE - DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT, - INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES - (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR - SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) - HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, - STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN - ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE - POSSIBILITY OF SUCH DAMAGE. - - $Id: chapter.sgml,v 1.2 1999-07-14 19:20:30 nik Exp $ ---> - -<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: ---> - diff --git a/en_US.ISO_8859-1/books/fdp-primer/the-handbook/chapter.sgml b/en_US.ISO_8859-1/books/fdp-primer/the-handbook/chapter.sgml deleted file mode 100644 index c494990ff9..0000000000 --- a/en_US.ISO_8859-1/books/fdp-primer/the-handbook/chapter.sgml +++ /dev/null @@ -1,282 +0,0 @@ -<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved. - - Redistribution and use in source (SGML DocBook) and 'compiled' forms - (SGML HTML, PDF, PostScript, RTF and so forth) with or without - modification, are permitted provided that the following conditions - are met: - - 1. Redistributions of source code (SGML DocBook) must retain the above - copyright notice, this list of conditions and the following - disclaimer as the first lines of this file unmodified. - - 2. Redistributions in compiled form (transformed to other DTDs, - converted to PDF, PostScript, RTF and other formats) must reproduce - the above copyright notice, this list of conditions and the - following disclaimer in the documentation and/or other materials - provided with the distribution. - - THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR - IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES - OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE - DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT, - INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES - (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR - SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) - HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, - STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN - ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE - POSSIBILITY OF SUCH DAMAGE. - - $Id: chapter.sgml,v 1.6 1999-08-29 16:08:43 jhb Exp $ ---> - -<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>freebsd-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="sgml-primer-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="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> - </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><para></literal>, - <emphasis>not</emphasis> <literal><PARA></literal>.</para> - - <para>Text that appears in SGML contexts is generally written in upper - case, <literal><!ENTITY…></literal>, and - <literal><!DOCTYPE…></literal>, <emphasis>not</emphasis> - <literal><!entity…></literal> and - <literal><!doctype…></literal>.</para> - </sect2> - - <sect2> - <title>Indentation</title> - - <para>Each file starts with indentation set at column 0, - <emphasis>regardless</emphasis> of the indentation level of the file - which might contain this one.</para> - - <para>Every start tag increases the indentation level by 2 spaces, and - every end tag decreases the indentation level by 2 spaces. 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: ---> - diff --git a/en_US.ISO_8859-1/books/fdp-primer/writing-style/chapter.sgml b/en_US.ISO_8859-1/books/fdp-primer/writing-style/chapter.sgml index c1e9fbde52..fb6746f935 100644 --- a/en_US.ISO_8859-1/books/fdp-primer/writing-style/chapter.sgml +++ b/en_US.ISO_8859-1/books/fdp-primer/writing-style/chapter.sgml @@ -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><para></literal>, + <emphasis>not</emphasis> <literal><PARA></literal>.</para> + + <para>Text that appears in SGML contexts is generally written in upper + case, <literal><!ENTITY…></literal>, and + <literal><!DOCTYPE…></literal>, <emphasis>not</emphasis> + <literal><!entity…></literal> and + <literal><!doctype…></literal>.</para> + </sect2> + + <sect2> + <title>Indentation</title> + + <para>Each file starts with indentation set at column 0, + <emphasis>regardless</emphasis> of the indentation level of the file + which might contain this one.</para> + + <para>Every start tag increases the indentation level by 2 spaces, and + every end tag decreases the indentation level by 2 spaces. 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> <!-- |