Date: Mon, 21 May 2012 14:21:17 +0000 (UTC) From: Warren Block <wblock@FreeBSD.org> To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r38868 - head/en_US.ISO8859-1/books/fdp-primer/structure Message-ID: <201205211421.q4LELHLh061406@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
Author: wblock Date: Mon May 21 14:21:16 2012 New Revision: 38868 URL: http://svn.freebsd.org/changeset/doc/38868 Log: Whitespace-only fixes, wrap long lines and correct indentation. Translators, please ignore. Modified: head/en_US.ISO8859-1/books/fdp-primer/structure/chapter.sgml Modified: head/en_US.ISO8859-1/books/fdp-primer/structure/chapter.sgml ============================================================================== --- head/en_US.ISO8859-1/books/fdp-primer/structure/chapter.sgml Mon May 21 13:11:29 2012 (r38867) +++ head/en_US.ISO8859-1/books/fdp-primer/structure/chapter.sgml Mon May 21 14:21:16 2012 (r38868) @@ -33,14 +33,15 @@ <chapter id="structure"> <title>Structuring Documents Under <filename>doc/</filename></title> - <para>The <filename>doc/</filename> tree is organized in a particular - fashion, and the documents that are part of the FDP are in turn organized - in a particular fashion. The aim is to make it simple to add new - documentation into the tree and:</para> + <para>The <filename>doc/</filename> tree is organized in a + particular fashion, and the documents that are part of the FDP are + in turn organized in a particular fashion. The aim is to make it + simple to add new documentation into the tree and:</para> <orderedlist> <listitem> - <para>Make it easy to automate converting the document to other formats.</para> + <para>Make it easy to automate converting the document to other + formats.</para> </listitem> <listitem> @@ -50,21 +51,23 @@ </listitem> <listitem> - <para>Make it easy to decide where in the tree new documentation should - be placed.</para> + <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> + <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 id="structure-top"> <title>The Top Level, <filename>doc/</filename></title> - <para>There are two types of directory under <filename>doc/</filename>, - each with very specific directory names and meanings.</para> + <para>There are two types of directory under + <filename>doc/</filename>, each with very specific directory + names and meanings.</para> <segmentedlist> <segtitle>Directory</segtitle> @@ -73,39 +76,41 @@ <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 categorize 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 + + <seg>Contains files that are not specific to the various + translations and encodings of the documentation. Contains + subdirectories to further categorize the information. For + example, the files that comprise the &man.make.1; + infrastructure are in <filename>share/mk</filename>, while + the additional 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 + + <seg>One directory exists for each available translation and + encoding of the documentation, for example <filename>en_US.ISO8859-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> + <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 id="structure-locale"> <title>The - <filename><replaceable>lang</replaceable>.<replaceable>encoding</replaceable>/</filename> Directories</title> + <filename><replaceable>lang</replaceable>.<replaceable>encoding</replaceable>/</filename> + Directories</title> <para>These directories contain the documents themselves. The - documentation is split into up to three more categories at this - level, indicated by the different directory names.</para> + documentation is split into up to three more categories at + this level, indicated by the different directory names.</para> <segmentedlist> <segtitle>Directory</segtitle> @@ -114,43 +119,47 @@ <seglistitem> <seg><filename>articles</filename></seg> - - <seg>Documentation marked up as a DocBook <sgmltag>article</sgmltag> - (or equivalent). Reasonably short, and broken up into sections. - Normally only available as one HTML file.</seg> + + <seg>Documentation marked up as a DocBook + <sgmltag>article</sgmltag> (or equivalent). Reasonably + short, and broken up into sections. Normally only available + as one HTML file.</seg> </seglistitem> - + <seglistitem> <seg><filename>books</filename></seg> - - <seg>Documentation marked up as a DocBook <sgmltag>book</sgmltag> (or - equivalent). Book length, and broken up into chapters. Normally - available as both one large HTML file (for people with fast - connections, or who want to print it easily from a browser) and - as a collection of linked, smaller files.</seg> + + <seg>Documentation marked up as a DocBook + <sgmltag>book</sgmltag> (or equivalent). Book length, and + broken up into chapters. Normally available as both one + large HTML file (for people with fast connections, or who + want to print it easily from a browser) and as a collection + of linked, smaller files.</seg> </seglistitem> <seglistitem> <seg><filename>man</filename></seg> - - <seg>For translations of the system manual pages. This directory will - contain one or more - <filename>man<replaceable>n</replaceable></filename> directories, - corresponding to the sections that have been translated.</seg> + + <seg>For translations of the system manual pages. This + directory will contain one or more + <filename>man<replaceable>n</replaceable></filename> + directories, corresponding to the sections that have been + translated.</seg> </seglistitem> </segmentedlist> <para>Not every - <filename><replaceable>lang</replaceable>.<replaceable>encoding</replaceable></filename> directory will contain all of these directories. It depends - on how much translation has been accomplished by that translation + <filename><replaceable>lang</replaceable>.<replaceable>encoding</replaceable></filename> + directory will contain all of these directories. It depends on + how much translation has been accomplished by that translation team.</para> </sect1> - + <sect1 id="structure-document"> <title>Document Specific Information</title> - <para>This section contains specific notes about particular documents - managed by the FDP.</para> + <para>This section contains specific notes about particular + documents managed by the FDP.</para> <sect2> <title>The Handbook</title> @@ -159,52 +168,55 @@ <para>The Handbook is written to comply with the FreeBSD DocBook extended DTD.</para> - - <para>The Handbook is organized 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>, + + <para>The Handbook is organized 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 Organization</title> - + <para>There are a number of files and directories within the <filename>handbook</filename> directory.</para> <note> - <para>The Handbook's organization may change over time, and this - document may lag in detailing the organizational changes. If you - have any questions about how the Handbook is organized, please - contact the &a.doc;.</para> + <para>The Handbook's organization may change over time, and + this document may lag in detailing the organizational + changes. If you have any questions about how the Handbook + is organized, please contact the &a.doc;.</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> + + <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 + + <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> + 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 + <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> @@ -212,69 +224,75 @@ <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> + <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> - + <para>For example, if one of the chapter files + contains:</para> + <programlisting><![ CDATA [ <chapter id="kernelconfig"> ... </chapter>]]></programlisting> - <para>Then it will be called <filename>chapter.sgml</filename> in - the <filename>kernelconfig</filename> directory. In - general, the entire contents of the chapter will be held in this + <para>Then it will be called + <filename>chapter.sgml</filename> in the + <filename>kernelconfig</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>kernelconfig.html</filename>. This is - because of the <literal>id</literal> value, and is not related to - the name of the directory.</para> - - <para>In earlier versions of the Handbook the files were stored in - the same directory as <filename>book.sgml</filename>, and named - after the value of the <literal>id</literal> attribute on the - file's <sgmltag>chapter</sgmltag> element. - Now, it is possible to include images in each - chapter. Images for each Handbook chapter are stored within - <filename class="directory">share/images/books/handbook</filename>. - Note that localized version of these images should be placed in the same - directory as the SGML sources for each chapter. - 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>, + + <para>When the HTML version of the Handbook is produced, + this will yield <filename>kernelconfig.html</filename>. + This is because of the <literal>id</literal> value, and is + not related to the name of the directory.</para> + + <para>In earlier versions of the Handbook the files were + stored in the same directory as + <filename>book.sgml</filename>, and named after the value + of the <literal>id</literal> attribute on the file's + <sgmltag>chapter</sgmltag> element. Now, it is possible + to include images in each chapter. Images for each + Handbook chapter are stored within <filename + class="directory">share/images/books/handbook</filename>. + Note that localized version of these images should be + placed in the same directory as the SGML sources for each + chapter. 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 reorganized; - this sort of reorganization should not (generally) include the - need to rename files (unless entire chapters are being promoted - or demoted within the hierarchy).</para> + <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 reorganized; this sort of + reorganization should not (generally) include the need + to rename files (unless entire chapters are being + promoted or demoted within the hierarchy).</para> </important> - - <para>Each <filename>chapter.sgml</filename> file will not be a - complete SGML document. In particular, they will not have their - own DOCTYPE lines at the start of the files.</para> - - <para>This is unfortunate as - it makes it impossible to treat these as generic SGML - files and simply convert them to HTML, RTF, PS, and other - formats in the same way the main Handbook is generated. This - <emphasis>would</emphasis> force you to rebuild the Handbook - every time you want to see the effect a change has had on just - one chapter.</para> + + <para>Each <filename>chapter.sgml</filename> file will not + be a complete SGML document. In particular, they will not + have their own DOCTYPE lines at the start of the + files.</para> + + <para>This is unfortunate as it makes it impossible to treat + these as generic SGML files and simply convert them to + HTML, RTF, PS, and other formats in the same way the main + Handbook is generated. This <emphasis>would</emphasis> + force you to rebuild the Handbook every time you want to + see the effect a change has had on just one + chapter.</para> </sect4> </sect3> </sect2>
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201205211421.q4LELHLh061406>