Date: Thu, 18 Jul 2013 00:31:46 +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: r42310 - head/en_US.ISO8859-1/books/fdp-primer/structure Message-ID: <201307180031.r6I0Vksf097200@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
Author: wblock Date: Thu Jul 18 00:31:45 2013 New Revision: 42310 URL: http://svnweb.freebsd.org/changeset/doc/42310 Log: Whitespace-only fixes. Translators, please ignore. Modified: head/en_US.ISO8859-1/books/fdp-primer/structure/chapter.xml Modified: head/en_US.ISO8859-1/books/fdp-primer/structure/chapter.xml ============================================================================== --- head/en_US.ISO8859-1/books/fdp-primer/structure/chapter.xml Thu Jul 18 00:21:37 2013 (r42309) +++ head/en_US.ISO8859-1/books/fdp-primer/structure/chapter.xml Thu Jul 18 00:31:45 2013 (r42310) @@ -34,8 +34,9 @@ <chapter id="structure"> <title>Documentation Directory Structure</title> - <para>Files and directories in the <filename class="directory">doc/</filename> tree follow a structure - meant to:</para> + <para>Files and directories in the + <filename class="directory">doc/</filename> tree follow a + structure meant to:</para> <orderedlist> <listitem> @@ -56,17 +57,17 @@ </orderedlist> <para>In addition, the documentation tree has to accommodate - documents in many different languages and - encodings. It is important that - the documentation tree structure does not enforce any particular defaults or - cultural preferences.</para> + documents in many different languages and encodings. It is + important that the documentation tree structure does not enforce + any particular defaults or cultural preferences.</para> <sect1 id="structure-top"> - <title>The Top Level, <filename class="directory">doc/</filename></title> + <title>The Top Level, + <filename class="directory">doc/</filename></title> <para>There are two types of directory under - <filename class="directory">doc/</filename>, each with very specific directory - names and meanings.</para> + <filename class="directory">doc/</filename>, each with very + specific directory names and meanings.</para> <informaltable pgwide="1" frame="none"> <tgroup cols="2"> @@ -79,30 +80,35 @@ <tbody> <row> - <entry valign="top"><filename class="directory">share</filename></entry> + <entry valign="top"> + <filename class="directory">share</filename></entry> <entry>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 class="directory">share/mk</filename>, while - the additional <acronym>XML</acronym> support files (such as the &os; - extended DocBook <acronym>DTD</acronym>) are in - <filename class="directory">share/xml</filename>.</entry> + 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 class="directory">share/mk</filename>, while + the additional <acronym>XML</acronym> support files + (such as the &os; extended DocBook + <acronym>DTD</acronym>) are in <filename + class="directory">share/xml</filename>.</entry> </row> <row> - <entry valign="top"><filename class="directory"><replaceable>lang</replaceable>.<replaceable>encoding</replaceable></filename></entry> + <entry valign="top"><filename + class="directory"><replaceable>lang</replaceable>.<replaceable>encoding</replaceable></filename></entry> - <entry>One directory exists for each available translation and - encoding of the documentation, for example - <filename class="directory">en_US.ISO8859-1/</filename> and - <filename class="directory">zh_TW.Big5/</filename>. The names are long, but - by fully specifying the language and encoding we prevent any - future headaches when a translation team wants to provide - documentation in the same language but in more than one - encoding. This also avoids - problems that might be caused by a future switch to Unicode.</entry> + <entry>One directory exists for each available translation + and encoding of the documentation, for example + <filename class="directory">en_US.ISO8859-1/</filename> + and <filename class="directory">zh_TW.Big5/</filename>. + The names are long, but by fully specifying the language + and encoding we prevent any future headaches when a + translation team wants to provide documentation in the + same language but in more than one encoding. This also + avoids problems that might be caused by a future switch + to Unicode.</entry> </row> </tbody> </tgroup> @@ -129,43 +135,46 @@ <tbody> <row> - <entry valign="top"><filename class="directory">articles</filename></entry> + <entry valign="top"> + <filename class="directory">articles</filename></entry> <entry>Documentation marked up as a DocBook - <sgmltag>article</sgmltag> (or equivalent). Reasonably - short, and broken up into sections. Normally only available - as one <acronym>XHTML</acronym> file.</entry> + <sgmltag>article</sgmltag> (or equivalent). Reasonably + short, and broken up into sections. Normally only + available as one <acronym>XHTML</acronym> file.</entry> </row> <row> <entry valign="top"><filename>books</filename></entry> <entry>Documentation marked up as a DocBook - <sgmltag>book</sgmltag> (or equivalent). Book length, and - broken up into chapters. Normally available as both one - large <acronym>XHTML</acronym> file (for people with fast connections, or who - want to print it easily from a browser) and as a collection - of linked, smaller files.</entry> + <sgmltag>book</sgmltag> (or equivalent). Book length, + and broken up into chapters. Normally available as both + one large <acronym>XHTML</acronym> file (for people with + fast connections, or who want to print it easily from a + browser) and as a collection of linked, smaller + files.</entry> </row> <row> - <entry valign="top"><filename class="directory">man</filename></entry> + <entry valign="top"> + <filename class="directory">man</filename></entry> <entry>For translations of the system manual pages. This - directory will contain one or more - <filename class="directory">man<replaceable>n</replaceable></filename> - directories, corresponding to the sections that have been - translated.</entry> + directory will contain one or more <filename + class="directory">man<replaceable>n</replaceable></filename> + directories, corresponding to the sections that have + been translated.</entry> </row> </tbody> </tgroup> </informaltable> - <para>Not every - <filename class="directory"><replaceable>lang</replaceable>.<replaceable>encoding</replaceable></filename> - directory will contain all of these subdirectories. It depends on - how much translation has been accomplished by that translation - team.</para> + <para>Not every <filename + class="directory"><replaceable>lang</replaceable>.<replaceable>encoding</replaceable></filename> + directory will contain all of these subdirectories. It depends + on how much translation has been accomplished by that + translation team.</para> </sect1> <sect1 id="structure-document"> @@ -179,8 +188,8 @@ <subtitle><filename>books/handbook/</filename></subtitle> - <para>The Handbook is written in DocBook <acronym>XML</acronym> using the &os; DocBook - extended DTD.</para> + <para>The Handbook is written in DocBook <acronym>XML</acronym> + using the &os; DocBook extended DTD.</para> <para>The Handbook is organized as a DocBook <sgmltag>book</sgmltag>. The book is divided into @@ -199,20 +208,20 @@ <note> <para>The Handbook's organization may change over time, and this document may lag in detailing the organizational - changes. Post questions about Handbook - organization to &a.doc;.</para> + changes. Post questions about Handbook organization to + &a.doc;.</para> </note> <sect4> <title><filename>Makefile</filename></title> <para>The <filename>Makefile</filename> defines some - variables that affect how the <acronym>XML</acronym> 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>, to bring in the - rest of the code that handles converting documents from - one format to another.</para> + variables that affect how the <acronym>XML</acronym> + 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>, + to bring in the rest of the code that handles converting + documents from one format to another.</para> </sect4> <sect4> @@ -235,7 +244,8 @@ </sect4> <sect4> - <title><filename class="directory"><replaceable>directory</replaceable>/chapter.xml</filename></title> + <title><filename + class="directory"><replaceable>directory</replaceable>/chapter.xml</filename></title> <para>Each chapter in the Handbook is stored in a file called <filename>chapter.xml</filename> in a separate @@ -257,10 +267,11 @@ the entire contents of the chapter will be held in this file.</para> - <para>When the <acronym>XHTML</acronym> 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>When the <acronym>XHTML</acronym> 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 @@ -271,11 +282,11 @@ Handbook chapter are stored within <filename class="directory">share/images/books/handbook</filename>. Note that the localized version of these images should be - placed in the same directory as the <acronym>XML</acronym> 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> + placed in the same directory as the <acronym>XML</acronym> + 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.xml</filename> files, @@ -285,16 +296,15 @@ <important> <para>Do not name chapters or directories after - their ordering within the - Handbook. This ordering can change as the content - within the Handbook is reorganized. - Reorganization should be possible without + their ordering within the Handbook. This ordering can + change as the content within the Handbook is + reorganized. Reorganization should be possible without renaming files, unless entire chapters are being promoted or demoted within the hierarchy.</para> </important> <para>The <filename>chapter.xml</filename> files are not - complete <acronym>XML</acronym> documents. They cannot be + complete <acronym>XML</acronym> documents. They cannot be individually rendered to output formats, but must be built as part of the Handbook.</para> </sect4>
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201307180031.r6I0Vksf097200>