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 d0c899ed46..6b42003e89 100644 --- a/en_US.ISO8859-1/books/fdp-primer/structure/chapter.sgml +++ b/en_US.ISO8859-1/books/fdp-primer/structure/chapter.sgml @@ -1,299 +1,287 @@ Structuring documents under <filename>doc/</filename> The doc/ tree is organised in a particular fashion, and the documents that are part of the FDP are in turn organised in a particular fashion. The aim is to make it simple to add new documentation in to the tree and; be easy to automate converting the document to other formats promote consistency between the different documentation organisations, to make it easier to switch between working on different documents 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. The top level, <filename>doc/</filename> There are two types of directory under doc/, each with very specific directory names and meanings. share/ Contains files that are not specific to the various translations and encodings of the documentation. Contains subdirectories to further categorise 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 en_US.ISO_8859-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. The <filename><replaceable>lang</replaceable>.<replaceable>encoding</replaceable>/</filename> directories These directories contain the documents themselves. The documentation is split in to up to three more categories at this level, indicated by the different directory names. articles Documentation marked up as a DocBook article (or equivalent). Reasonably short, and broken up in to sections. Normally only available as one HTML file. books Documentation marked up as a DocBook book (or equivalent). Book length, and broken up in to chapters. Normally available as both one large HTML file (for people with fast connections, or who want to print it easily from their 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. Not every lang.encoding directory will contain all of these directories. It depends on much translation has been accomplished by that translation team. Document specific information This section contains specific notes about particular documents managed by the FDP. The Handbook books/handbook/ The Handbook is written to comply with the FreeBSD DocBook extended DTD. The Handbook is organised 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 organisation There are a number of files and directories within the handbook directory. The Handbook's organisation may change over time, and this document may lag in detailing the organisational changes. If you have any questions about how the Handbook is organised, please contact the FreeBSD Documentation Project, freebsd-doc@FreeBSD.org. <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. <filename>book.sgml</filename> 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. book.sgml uses parameter entities to load in the files with the .ent extension. These files (described later) then define general entities that are used throughout the rest of the Handbook. <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 element. For example, if one of the chapter files contains: ... ]]> then it will be called chapter.sgml in the kernelconfiguration 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 kernelconfiguration.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. Moving them in to separate directories prepares for future plans for the Handbook. Specifically, it will soon be possible to include images in each chapter. It makes more sense for each image to be stored in a directory with the text for the chapter than to try and keep the text for all the chapters, and all the images, in one large directory. 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 reorganised; this sort of reorganistion 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 line at the start of the file. - This is unfortunate for two reasons; - - - - It makes it impossible to treat these as generic SGML + 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 as had on just one chapter. - - - - Emacs' sgml-mode can not use it to - determine the DTD to use, losing useful benefits of - sgml-mode (element completion, automatic - validation, and so on). - - diff --git a/en_US.ISO_8859-1/books/fdp-primer/structure/chapter.sgml b/en_US.ISO_8859-1/books/fdp-primer/structure/chapter.sgml index d0c899ed46..6b42003e89 100644 --- a/en_US.ISO_8859-1/books/fdp-primer/structure/chapter.sgml +++ b/en_US.ISO_8859-1/books/fdp-primer/structure/chapter.sgml @@ -1,299 +1,287 @@ Structuring documents under <filename>doc/</filename> The doc/ tree is organised in a particular fashion, and the documents that are part of the FDP are in turn organised in a particular fashion. The aim is to make it simple to add new documentation in to the tree and; be easy to automate converting the document to other formats promote consistency between the different documentation organisations, to make it easier to switch between working on different documents 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. The top level, <filename>doc/</filename> There are two types of directory under doc/, each with very specific directory names and meanings. share/ Contains files that are not specific to the various translations and encodings of the documentation. Contains subdirectories to further categorise 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 en_US.ISO_8859-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. The <filename><replaceable>lang</replaceable>.<replaceable>encoding</replaceable>/</filename> directories These directories contain the documents themselves. The documentation is split in to up to three more categories at this level, indicated by the different directory names. articles Documentation marked up as a DocBook article (or equivalent). Reasonably short, and broken up in to sections. Normally only available as one HTML file. books Documentation marked up as a DocBook book (or equivalent). Book length, and broken up in to chapters. Normally available as both one large HTML file (for people with fast connections, or who want to print it easily from their 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. Not every lang.encoding directory will contain all of these directories. It depends on much translation has been accomplished by that translation team. Document specific information This section contains specific notes about particular documents managed by the FDP. The Handbook books/handbook/ The Handbook is written to comply with the FreeBSD DocBook extended DTD. The Handbook is organised 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 organisation There are a number of files and directories within the handbook directory. The Handbook's organisation may change over time, and this document may lag in detailing the organisational changes. If you have any questions about how the Handbook is organised, please contact the FreeBSD Documentation Project, freebsd-doc@FreeBSD.org. <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. <filename>book.sgml</filename> 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. book.sgml uses parameter entities to load in the files with the .ent extension. These files (described later) then define general entities that are used throughout the rest of the Handbook. <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 element. For example, if one of the chapter files contains: ... ]]> then it will be called chapter.sgml in the kernelconfiguration 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 kernelconfiguration.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. Moving them in to separate directories prepares for future plans for the Handbook. Specifically, it will soon be possible to include images in each chapter. It makes more sense for each image to be stored in a directory with the text for the chapter than to try and keep the text for all the chapters, and all the images, in one large directory. 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 reorganised; this sort of reorganistion 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 line at the start of the file. - This is unfortunate for two reasons; - - - - It makes it impossible to treat these as generic SGML + 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 as had on just one chapter. - - - - Emacs' sgml-mode can not use it to - determine the DTD to use, losing useful benefits of - sgml-mode (element completion, automatic - validation, and so on). - -