diff --git a/en_US.ISO8859-1/books/fdp-primer/structure/chapter.xml b/en_US.ISO8859-1/books/fdp-primer/structure/chapter.xml index c4ebeb7d60..b4974a9068 100644 --- a/en_US.ISO8859-1/books/fdp-primer/structure/chapter.xml +++ b/en_US.ISO8859-1/books/fdp-primer/structure/chapter.xml @@ -34,8 +34,9 @@ Documentation Directory Structure - Files and directories in the doc/ tree follow a structure - meant to: + Files and directories in the + doc/ tree follow a + structure meant to: @@ -56,17 +57,17 @@ 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. + documents in many different languages and encodings. It is + important that the documentation tree structure does not enforce + any particular defaults or cultural preferences. - The Top Level, <filename class="directory">doc/</filename> + The Top Level, + <filename class="directory">doc/</filename> There are two types of directory under - doc/, each with very specific directory - names and meanings. + doc/, each with very + specific directory names and meanings. @@ -79,30 +80,35 @@ - share + + share 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 share/mk, while - the additional XML support files (such as the &os; - extended DocBook DTD) are in - share/xml. + 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 + share/mk, while + the additional XML support files + (such as the &os; extended DocBook + DTD) are in share/xml. - lang.encoding + lang.encoding - One directory exists for each available translation and - encoding of the documentation, for example - en_US.ISO8859-1/ and - zh_TW.Big5/. 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. + One directory exists for each available translation + and encoding of the documentation, for example + en_US.ISO8859-1/ + and zh_TW.Big5/. + 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. @@ -129,43 +135,46 @@ - articles + + articles Documentation marked up as a DocBook - article (or equivalent). Reasonably - short, and broken up into sections. Normally only available - as one XHTML file. + article (or equivalent). Reasonably + short, and broken up into sections. Normally only + available as one XHTML file. books Documentation marked up as a DocBook - book (or equivalent). Book length, and - broken up into chapters. Normally available as both one - large XHTML file (for people with fast connections, or who - want to print it easily from a browser) and as a collection - of linked, smaller files. + book (or equivalent). Book length, + and broken up into chapters. Normally available as both + one large XHTML file (for people with + fast connections, or who want to print it easily from a + browser) and as a collection of linked, smaller + files. - man + + man For translations of the system manual pages. This - directory will contain one or more - mann - directories, corresponding to the sections that have been - translated. + directory will contain one or more mann + directories, corresponding to the sections that have + been translated. - Not every - lang.encoding - directory will contain all of these subdirectories. It depends on - how much translation has been accomplished by that translation - team. + Not every lang.encoding + directory will contain all of these subdirectories. It depends + on how much translation has been accomplished by that + translation team. @@ -179,8 +188,8 @@ books/handbook/ - The Handbook is written in DocBook XML using the &os; DocBook - extended DTD. + The Handbook is written in DocBook XML + using the &os; DocBook extended DTD. The Handbook is organized as a DocBook book. The book is divided into @@ -199,20 +208,20 @@ 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;. + changes. Post questions about Handbook organization to + &a.doc;. <filename>Makefile</filename> The Makefile defines some - variables that affect how the XML source is converted to - other formats, and lists the various source files that - make up the Handbook. It then includes the standard - doc.project.mk, to bring in the - rest of the code that handles converting documents from - one format to another. + variables that affect how the XML + source is converted to other formats, and lists the + various source files that make up the Handbook. It then + includes the standard doc.project.mk, + to bring in the rest of the code that handles converting + documents from one format to another. @@ -235,7 +244,8 @@ - <filename class="directory"><replaceable>directory</replaceable>/chapter.xml</filename> + <filename + class="directory"><replaceable>directory</replaceable>/chapter.xml</filename> Each chapter in the Handbook is stored in a file called chapter.xml in a separate @@ -257,10 +267,11 @@ the entire contents of the chapter will be held in this file. - When the XHTML version of the Handbook is produced, - this will yield kernelconfig.html. - This is because of the id value, and is - not related to the name of the directory. + When the XHTML version of the + Handbook is produced, this will yield + kernelconfig.html. This is because + of the id value, and is not related to + the name of the directory. In earlier versions of the Handbook, the files were stored in the same directory as @@ -271,11 +282,11 @@ Handbook chapter are stored within share/images/books/handbook. Note that the localized version of these images should be - placed in the same directory as the XML 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. + placed in the same directory as the XML + 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. A brief look will show that there are many directories with individual chapter.xml files, @@ -285,16 +296,15 @@ 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. The chapter.xml files are not - complete XML documents. They cannot be + complete XML documents. They cannot be individually rendered to output formats, but must be built as part of the Handbook.