Date: Thu, 18 Jul 2013 00:21:38 +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: r42309 - head/en_US.ISO8859-1/books/fdp-primer/structure Message-ID: <201307180021.r6I0LcRM094168@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
Author: wblock Date: Thu Jul 18 00:21:37 2013 New Revision: 42309 URL: http://svnweb.freebsd.org/changeset/doc/42309 Log: Edit, update, and simplify the structure chapter. Reviewed by: bps and Allan Jude on IRC 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 Wed Jul 17 23:27:59 2013 (r42308) +++ head/en_US.ISO8859-1/books/fdp-primer/structure/chapter.xml Thu Jul 18 00:21:37 2013 (r42309) @@ -32,12 +32,10 @@ --> <chapter id="structure"> - <title>Structuring Documents Under <filename>doc/</filename></title> + <title>Documentation Directory Structure</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>Files and directories in the <filename class="directory">doc/</filename> tree follow a structure + meant to:</para> <orderedlist> <listitem> @@ -58,50 +56,57 @@ </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 + 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>doc/</filename></title> + <title>The Top Level, <filename class="directory">doc/</filename></title> <para>There are two types of directory under - <filename>doc/</filename>, each with very specific directory + <filename class="directory">doc/</filename>, each with very specific directory names and meanings.</para> - <segmentedlist> - <segtitle>Directory</segtitle> + <informaltable pgwide="1" frame="none"> + <tgroup cols="2"> + <thead> + <row> + <entry>Directory</entry> + <entry>Usage</entry> + </row> + </thead> + + <tbody> + <row> + <entry valign="top"><filename class="directory">share</filename></entry> - <segtitle>Meaning</segtitle> - - <seglistitem> - <seg><filename>share/</filename></seg> - - <seg>Contains files that are not specific to the various + <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>share/mk</filename>, while - the additional XML support files (such as the FreeBSD - extended DocBook DTD) are in - <filename>share/xml</filename>.</seg> - </seglistitem> + 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> - <seglistitem> - <seg><filename><replaceable>lang</replaceable>.<replaceable>encoding</replaceable>/</filename></seg> + <row> + <entry valign="top"><filename class="directory"><replaceable>lang</replaceable>.<replaceable>encoding</replaceable></filename></entry> - <seg>One directory exists for each available translation and + <entry>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 + <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 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> + 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> + </informaltable> </sect1> <sect1 id="structure-locale"> @@ -113,51 +118,58 @@ documentation is split into up to three more categories at this level, indicated by the different directory names.</para> - <segmentedlist> - <segtitle>Directory</segtitle> - - <segtitle>Contents</segtitle> - - <seglistitem> - <seg><filename>articles</filename></seg> + <informaltable pgwide="1" frame="none"> + <tgroup cols="2"> + <thead> + <row> + <entry>Directory</entry> + <entry>Usage</entry> + </row> + </thead> + + <tbody> + <row> + <entry valign="top"><filename class="directory">articles</filename></entry> - <seg>Documentation marked up as a DocBook + <entry>Documentation marked up as a DocBook <sgmltag>article</sgmltag> (or equivalent). Reasonably short, and broken up into sections. Normally only available - as one XHTML file.</seg> - </seglistitem> + as one <acronym>XHTML</acronym> file.</entry> + </row> - <seglistitem> - <seg><filename>books</filename></seg> + <row> + <entry valign="top"><filename>books</filename></entry> - <seg>Documentation marked up as a DocBook + <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 XHTML file (for people with fast connections, or who + 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.</seg> - </seglistitem> + of linked, smaller files.</entry> + </row> - <seglistitem> - <seg><filename>man</filename></seg> + <row> + <entry valign="top"><filename class="directory">man</filename></entry> - <seg>For translations of the system manual pages. This + <entry>For translations of the system manual pages. This directory will contain one or more - <filename>man<replaceable>n</replaceable></filename> + <filename class="directory">man<replaceable>n</replaceable></filename> directories, corresponding to the sections that have been - translated.</seg> - </seglistitem> - </segmentedlist> + translated.</entry> + </row> + </tbody> + </tgroup> + </informaltable> <para>Not every - <filename><replaceable>lang</replaceable>.<replaceable>encoding</replaceable></filename> - directory will contain all of these directories. It depends on + <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"> - <title>Document Specific Information</title> + <title>Document-Specific Information</title> <para>This section contains specific notes about particular documents managed by the FDP.</para> @@ -167,12 +179,12 @@ <subtitle><filename>books/handbook/</filename></subtitle> - <para>The Handbook is written to comply with the FreeBSD DocBook + <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>. It is then divided into - <sgmltag>part</sgmltag>s, each of which may contain several + <sgmltag>book</sgmltag>. The book is divided into + <sgmltag>part</sgmltag>s, each of which contains several <sgmltag>chapter</sgmltag>s. <sgmltag>chapter</sgmltag>s are further subdivided into sections (<sgmltag>sect1</sgmltag>) and subsections (<sgmltag>sect2</sgmltag>, @@ -187,18 +199,18 @@ <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> + 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 XML source is converted to + 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> file, to bring in the + <filename>doc.project.mk</filename>, to bring in the rest of the code that handles converting documents from one format to another.</para> </sect4> @@ -223,7 +235,7 @@ </sect4> <sect4> - <title><filename><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 @@ -235,10 +247,9 @@ <para>For example, if one of the chapter files contains:</para> - <programlisting><![CDATA[ -<chapter id="kernelconfig"> + <programlisting><sgmltag class="starttag">chapter id="kernelconfig"</sgmltag> ... -</chapter>]]></programlisting> +<sgmltag class="endtag">chapter</sgmltag></programlisting> <para>Then it will be called <filename>chapter.xml</filename> in the @@ -246,12 +257,12 @@ the entire contents of the chapter will be held in this file.</para> - <para>When the XHTML version of the Handbook is produced, + <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 + <para>In earlier versions of the Handbook, the files were stored in the same directory as <filename>book.xml</filename>, and named after the value of the <literal>id</literal> attribute on the file's @@ -259,8 +270,8 @@ 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 XML sources for each + 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 @@ -273,27 +284,19 @@ <filename>printing/chapter.xml</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>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 + renaming files, unless entire chapters are being + promoted or demoted within the hierarchy.</para> </important> - <para>Each <filename>chapter.xml</filename> file will not - be a complete XML 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 XML 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>The <filename>chapter.xml</filename> files are not + complete <acronym>XML</acronym> documents. They cannot be + individually rendered to output formats, but must be built + as part of the Handbook.</para> </sect4> </sect3> </sect2>
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201307180021.r6I0LcRM094168>