From owner-svn-doc-all@FreeBSD.ORG Mon May 21 14:21:18 2012 Return-Path: Delivered-To: svn-doc-all@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [69.147.83.52]) by hub.freebsd.org (Postfix) with ESMTP id 3D747106564A; Mon, 21 May 2012 14:21:18 +0000 (UTC) (envelope-from wblock@FreeBSD.org) Received: from svn.freebsd.org (svn.freebsd.org [IPv6:2001:4f8:fff6::2c]) by mx1.freebsd.org (Postfix) with ESMTP id DEFCB8FC08; Mon, 21 May 2012 14:21:17 +0000 (UTC) Received: from svn.freebsd.org (localhost [127.0.0.1]) by svn.freebsd.org (8.14.4/8.14.4) with ESMTP id q4LELHm2061408; Mon, 21 May 2012 14:21:17 GMT (envelope-from wblock@svn.freebsd.org) Received: (from wblock@localhost) by svn.freebsd.org (8.14.4/8.14.4/Submit) id q4LELHLh061406; Mon, 21 May 2012 14:21:17 GMT (envelope-from wblock@svn.freebsd.org) Message-Id: <201205211421.q4LELHLh061406@svn.freebsd.org> From: Warren Block Date: Mon, 21 May 2012 14:21:17 +0000 (UTC) To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org X-SVN-Group: doc-head MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Cc: Subject: svn commit: r38868 - head/en_US.ISO8859-1/books/fdp-primer/structure X-BeenThere: svn-doc-all@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: "SVN commit messages for the entire doc trees \(except for " user" , " projects" , and " translations" \)" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Mon, 21 May 2012 14:21:18 -0000 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 @@ 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. - - A brief look will show that there are many directories with - individual chapter.sgml files, including - basics/chapter.sgml, + + 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. + + 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.