From owner-svn-doc-head@FreeBSD.ORG Thu Jul 18 00:21:38 2013 Return-Path: Delivered-To: svn-doc-head@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [8.8.178.115]) by hub.freebsd.org (Postfix) with ESMTP id C36DB893; Thu, 18 Jul 2013 00:21:38 +0000 (UTC) (envelope-from wblock@FreeBSD.org) Received: from svn.freebsd.org (svn.freebsd.org [IPv6:2001:1900:2254:2068::e6a:0]) by mx1.freebsd.org (Postfix) with ESMTP id B4A4D6CC; Thu, 18 Jul 2013 00:21:38 +0000 (UTC) Received: from svn.freebsd.org ([127.0.1.70]) by svn.freebsd.org (8.14.7/8.14.7) with ESMTP id r6I0LcHl094169; Thu, 18 Jul 2013 00:21:38 GMT (envelope-from wblock@svn.freebsd.org) Received: (from wblock@localhost) by svn.freebsd.org (8.14.7/8.14.5/Submit) id r6I0LcRM094168; Thu, 18 Jul 2013 00:21:38 GMT (envelope-from wblock@svn.freebsd.org) Message-Id: <201307180021.r6I0LcRM094168@svn.freebsd.org> From: Warren Block Date: Thu, 18 Jul 2013 00:21:38 +0000 (UTC) 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 X-SVN-Group: doc-head MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-doc-head@freebsd.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: SVN commit messages for the doc tree for head List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Thu, 18 Jul 2013 00:21:38 -0000 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 @@ --> - Structuring Documents Under <filename>doc/</filename> + Documentation Directory Structure - 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: + Files and directories in the doc/ tree follow a structure + meant to: @@ -58,50 +56,57 @@ 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. - The Top Level, <filename>doc/</filename> + The Top Level, <filename class="directory">doc/</filename> There are two types of directory under - doc/, each with very specific directory + doc/, each with very specific directory names and meanings. - - Directory + + + + + Directory + Usage + + + + + + share - Meaning - - - share/ - - Contains files that are not specific to the various + 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 FreeBSD - extended DocBook DTD) are in - share/xml. - + 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 + 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 + 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. - - + 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. + + + + @@ -113,51 +118,58 @@ documentation is split into up to three more categories at this level, indicated by the different directory names. - - Directory - - Contents - - - articles + + + + + Directory + Usage + + + + + + articles - Documentation marked up as a DocBook + Documentation marked up as a DocBook article (or equivalent). Reasonably short, and broken up into sections. Normally only available - as one XHTML file. - + as one XHTML file. + - - books + + books - Documentation marked up as a DocBook + 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 + 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. - + of linked, smaller files. + - - man + + man - For translations of the system manual pages. This + For translations of the system manual pages. This directory will contain one or more - mann + mann directories, corresponding to the sections that have been - translated. - - + translated. + + + + Not every - lang.encoding - directory will contain all of these directories. It depends on + lang.encoding + directory will contain all of these subdirectories. It depends on how much translation has been accomplished by that translation team. - Document Specific Information + Document-Specific Information This section contains specific notes about particular documents managed by the FDP. @@ -167,12 +179,12 @@ books/handbook/ - The Handbook is written to comply with the FreeBSD DocBook + The Handbook is written in DocBook XML using the &os; DocBook extended DTD. The Handbook is organized as a DocBook - book. It is then divided into - parts, each of which may contain several + book. The book is divided into + parts, each of which contains several chapters. chapters are further subdivided into sections (sect1) and subsections (sect2, @@ -187,18 +199,18 @@ 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;. + 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 + 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 file, to bring in the + doc.project.mk, to bring in the rest of the code that handles converting documents from one format to another. @@ -223,7 +235,7 @@ - <filename><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 @@ -235,10 +247,9 @@ For example, if one of the chapter files contains: - + chapter id="kernelconfig" ... -]]> +chapter Then it will be called chapter.xml in the @@ -246,12 +257,12 @@ the entire contents of the chapter will be held in this file. - When the XHTML version of the Handbook is produced, + 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 + In earlier versions of the Handbook, the files were stored in the same directory as book.xml, and named after the value of the id attribute on the file's @@ -259,8 +270,8 @@ 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 XML sources for each + 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 @@ -273,27 +284,19 @@ printing/chapter.xml. - 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). + 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. - Each chapter.xml file will not - be a complete XML 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 XML 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. + The chapter.xml files are not + complete XML documents. They cannot be + individually rendered to output formats, but must be built + as part of the Handbook.