From 3e5623c655d903c2d84c0f173f46af8399fb580e Mon Sep 17 00:00:00 2001 From: Warren Block Date: Mon, 21 May 2012 14:21:16 +0000 Subject: [PATCH] Whitespace-only fixes, wrap long lines and correct indentation. Translators, please ignore. --- .../books/fdp-primer/structure/chapter.sgml | 276 ++++++++++-------- 1 file changed, 147 insertions(+), 129 deletions(-) diff --git a/en_US.ISO8859-1/books/fdp-primer/structure/chapter.sgml b/en_US.ISO8859-1/books/fdp-primer/structure/chapter.sgml index 8acf6ce73f..0b7089b06f 100644 --- a/en_US.ISO8859-1/books/fdp-primer/structure/chapter.sgml +++ b/en_US.ISO8859-1/books/fdp-primer/structure/chapter.sgml @@ -33,14 +33,15 @@ Structuring Documents Under <filename>doc/</filename> - The doc/ 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: + The doc/ 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: - Make it easy to automate converting the document to other formats. + Make it easy to automate converting the document to other + formats. @@ -50,21 +51,23 @@ - Make it easy to decide where in the tree new documentation should - be placed. + Make it easy to decide where in the tree new documentation + should be placed. - 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. + 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. The Top Level, <filename>doc/</filename> - There are two types of directory under doc/, - each with very specific directory names and meanings. + There are two types of directory under + doc/, each with very specific directory + names and meanings. Directory @@ -73,39 +76,41 @@ 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 SGML support - files (such as the FreeBSD extended DocBook DTD) are in + + 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 SGML support files (such as the FreeBSD + extended DocBook DTD) are in share/sgml. lang.encoding/ - - One directory exists for each available translation and encoding - of the documentation, for example + + 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 - 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. + zh_TW.Big5/. 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. The - <filename><replaceable>lang</replaceable>.<replaceable>encoding</replaceable>/</filename> Directories + lang.encoding/ + Directories 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. + documentation is split into up to three more categories at + this level, indicated by the different directory names. Directory @@ -114,43 +119,47 @@ articles - - Documentation marked up as a DocBook article - (or equivalent). Reasonably short, and broken up into sections. - Normally only available as one HTML file. + + Documentation marked up as a DocBook + article (or equivalent). Reasonably + short, and broken up into sections. Normally only available + as one HTML file. - + books - - Documentation marked up as a DocBook book (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. + + Documentation marked up as a DocBook + book (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. 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. + + For translations of the system manual pages. This + 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 directories. It depends - on how much translation has been accomplished by that translation + lang.encoding + directory will contain all of these directories. It depends on + how much translation has been accomplished by that translation team. - + Document Specific Information - This section contains specific notes about particular documents - managed by the FDP. + This section contains specific notes about particular + documents managed by the FDP. The Handbook @@ -159,52 +168,55 @@ The Handbook is written to comply with the FreeBSD DocBook extended DTD. - - The Handbook is organized as a DocBook book. - It is then divided into parts, each of which may - contain several chapters. - chapters are further subdivided into sections - (sect1) and subsections (sect2, + + The Handbook is organized as a DocBook + book. It is then divided into + parts, each of which may contain several + chapters. chapters are + further subdivided into sections (sect1) + and subsections (sect2, sect3) and so on. - + Physical Organization - + There are a number of files and directories within the handbook directory. - 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;. + 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;. - + <filename>Makefile</filename> - - The Makefile 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 doc.project.mk file, to - bring in the rest of the code that handles converting documents - from one format to another. + + The Makefile 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 + doc.project.mk file, to bring in the + rest of the code that handles converting documents from + one format to another. <filename>book.sgml</filename> - - This is the top level document in the Handbook. It contains - the Handbook's This is the top level document in the Handbook. It + contains the Handbook's DOCTYPE - declaration, as well as the elements that describe the - Handbook's structure. + declaration, as well as the elements that + describe the Handbook's structure. book.sgml uses parameter entities to load in the files with the - .ent extension. These files (described later) - then define general + .ent extension. These files + (described later) then define general entities that are used throughout the rest of the Handbook. @@ -212,69 +224,75 @@ <filename><replaceable>directory</replaceable>/chapter.sgml</filename> - Each chapter in the Handbook is stored in a file called - chapter.sgml in a separate directory from the - other chapters. Each directory is named after the value of the - id attribute on the chapter + Each chapter in the Handbook is stored in a file + called chapter.sgml in a separate + directory from the other chapters. Each directory is + named after the value of the id + attribute on the chapter element. - For example, if one of the chapter files contains: - + For example, if one of the chapter files + contains: + ... ]]> - Then it will be called chapter.sgml in - the kernelconfig directory. In - general, the entire contents of the chapter will be held in this + Then it will be called + chapter.sgml in the + kernelconfig directory. In general, + the entire contents of the chapter will be held in this file. - - When the HTML 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 book.sgml, and named - after the value of the id attribute on the - file's chapter element. - Now, it is possible to include images in each - chapter. Images for each Handbook chapter are stored within - share/images/books/handbook. - 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. + When the HTML 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. - A brief look will show that there are many directories with - individual chapter.sgml files, including - basics/chapter.sgml, + In earlier versions of the Handbook the files were + stored in the same directory as + book.sgml, and named after the value + of the id attribute on the file's + chapter element. Now, it is possible + to include images in each chapter. Images for each + Handbook chapter are stored within share/images/books/handbook. + 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. + + A brief look will show that there are many directories + with individual chapter.sgml files, + including basics/chapter.sgml, introduction/chapter.sgml, and printing/chapter.sgml. - + - 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). + 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). - - Each chapter.sgml file will not be a - complete SGML document. In particular, they will not have their - own DOCTYPE lines at the start of the files. - - 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 - would force you to rebuild the Handbook - every time you want to see the effect a change has had on just - one chapter. + + Each chapter.sgml file will not + be a complete SGML document. In particular, they will not + have their own DOCTYPE lines at the start of the + files. + + 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 would + force you to rebuild the Handbook every time you want to + see the effect a change has had on just one + chapter.