diff --git a/en_US.ISO8859-1/books/fdp-primer/Makefile b/en_US.ISO8859-1/books/fdp-primer/Makefile index ec34c30d36..054b703417 100644 --- a/en_US.ISO8859-1/books/fdp-primer/Makefile +++ b/en_US.ISO8859-1/books/fdp-primer/Makefile @@ -1,41 +1,40 @@ # -# $Id: Makefile,v 1.5 1999-08-29 00:02:22 jhb Exp $ +# $Id: Makefile,v 1.6 1999-09-03 17:22:40 nik Exp $ # # Build the FreeBSD Documentation Project Primer. # MAINTAINER=nik@FreeBSD.org DOC?= book FORMATS?= html-split html INSTALL_COMPRESSED?= gz INSTALL_ONLY_COMPRESSED?= # # SRCS lists the individual SGML files that make up the document. Changes # to any of these files will force a rebuild # # SGML content SRCS= book.sgml SRCS+= overview/chapter.sgml SRCS+= psgml-mode/chapter.sgml SRCS+= see-also/chapter.sgml SRCS+= sgml-markup/chapter.sgml SRCS+= sgml-primer/chapter.sgml SRCS+= stylesheets/chapter.sgml -SRCS+= the-faq/chapter.sgml -SRCS+= the-handbook/chapter.sgml +SRCS+= structure/chapter.sgml SRCS+= the-website/chapter.sgml SRCS+= tools/chapter.sgml SRCS+= translations/chapter.sgml SRCS+= writing-style/chapter.sgml # Entities SRCS+= chapters.ent -DOC_PREFIX?= ../../.. +DOC_PREFIX?= ${.CURDIR}/../../.. -.include "${DOC_PREFIX}/share/mk/docproj.docbook.mk" +.include "${DOC_PREFIX}/share/mk/doc.project.mk" diff --git a/en_US.ISO8859-1/books/fdp-primer/book.sgml b/en_US.ISO8859-1/books/fdp-primer/book.sgml index 57c3e91fa2..877a39e0f1 100644 --- a/en_US.ISO8859-1/books/fdp-primer/book.sgml +++ b/en_US.ISO8859-1/books/fdp-primer/book.sgml @@ -1,281 +1,280 @@ %man; %chapters; ]> FreeBSD Documentation Project Primer for New Contributors Nik Clayton
nik@FreeBSD.org
 1998 1999 Nik Clayton - $Date: 1999-08-29 16:08:38 $ + $Date: 1999-09-03 17:22:39 $ - $Id: book.sgml,v 1.6 1999-08-29 16:08:38 jhb Exp $ + $Id: book.sgml,v 1.7 1999-09-03 17:22:39 nik Exp $ Redistribution and use in source (SGML DocBook) and 'compiled' forms (SGML, HTML, PDF, PostScript, RTF and so forth) with or without modification, are permitted provided that the following conditions are met: Redistributions of source code (SGML DocBook) must retain the above copyright notice, this list of conditions and the following disclaimer as the first lines of this file unmodified. Redistributions in compiled form (transformed to other DTDs, converted to PDF, PostScript, RTF and other formats) must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. Thank you for becoming a part of the FreeBSD Documentation Project. Your contribution is extremely valuable. This primer covers everything you will need to know in order to start contributing to the FreeBSD Documentation Project, from the tools and software you will be using (both mandatory and recommended) to the philosophy behind the Documentation Project. This document is a work in progress, and is not complete. Sections that are known to be incomplete are indicated with a * in their name. Preface Shell Prompts The following table shows the default system prompt and superuser prompt. The examples will use this prompt to indicate which user you should be running the example as. User Prompt Normal user &prompt.user; root &prompt.root; Typographic Conventions The following table describes the typographic conventions used in this book. Meaning Examples The name of commands, files, and directories. On screen computer output. Edit your .login file.Use ls -a to list all files.You have mail. What you type, when contrasted with on-screen computer output. &prompt.user; su Password: Manual page references. Use su 1 to change user names. User and group names Only root can do this. Emphasis You must do this. Command line variables; replace with the real name or variable. To delete a file, type rm filename Environment variables $HOME is your home directory. Notes, warnings, and examples Within the text appear notes, warnings, and examples. Notes are represented like this, and contain information that you should take note of, as it may affect what you do. Warnings are represented like this, and contain information warning you about possible damage if you do not follow the instructions. This damage may be physical, to your hardware or to you, or it may be non-physical, such as the inadvertant deletion of important files. A sample example Examples are represented like this, and typically contain examples you should walk through, or show you what the results of a particular action should be. Acknowledgments My thanks to Sue Blake, Patrick Durusau, Jon Hamilton, Peter Flynn, and Christopher Maden, who took the time to read early drafts of this document and offer many valuable comments and criticisms. &chap.overview; &chap.tools; &chap.sgml-primer; &chap.sgml-markup; &chap.stylesheets; - &chap.the-faq; - &chap.the-handbook; + &chap.structure; &chap.the-website; &chap.translations; &chap.writing-style; &chap.psgml-mode; &chap.see-also; diff --git a/en_US.ISO8859-1/books/fdp-primer/chapters.ent b/en_US.ISO8859-1/books/fdp-primer/chapters.ent index 3375e0085d..0983076bf3 100644 --- a/en_US.ISO8859-1/books/fdp-primer/chapters.ent +++ b/en_US.ISO8859-1/books/fdp-primer/chapters.ent @@ -1,23 +1,22 @@ - - + diff --git a/en_US.ISO8859-1/books/fdp-primer/structure/chapter.sgml b/en_US.ISO8859-1/books/fdp-primer/structure/chapter.sgml new file mode 100644 index 0000000000..0fcb999857 --- /dev/null +++ b/en_US.ISO8859-1/books/fdp-primer/structure/chapter.sgml @@ -0,0 +1,299 @@ + + + + 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 + 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.ISO8859-1/books/fdp-primer/writing-style/chapter.sgml b/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.sgml index c1e9fbde52..fb6746f935 100644 --- a/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.sgml +++ b/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.sgml @@ -1,143 +1,231 @@ Writing style In order to promote consistency between the myriad authors of the FreeBSD documentation, some guidelines have been drawn up for authors to follow. Do not use contractions Do not use contractions. Always spell the phrase out in full. “Don't use contractions” would be wrong. Avoiding contractions makes for a more formal tone, is more precise, and slightly easier for translators. Use the serial comma In a list of items within a paragraph, seperate each item from the others with a comma. Seperate the last item from the others with a comma and the word “and”. For example, look at the following quote;
This is a list of one, two and three items.
Is this a list of three items, “one”, “two”, and “three”, or a list of two items, “one” and “two and three”? It is better to be explicit and include a serial comma;
This is a list of one, two, and three items.
Avoid redundant phrases Try not to use redundant phrases. In particular, “the command”, “the file”, and “man command” are probably redundant. These two examples show this for commands. The second example is preferred. Use the command cvsup to update your sources Use cvsup to update your sources These two examples show this for filenames. The second example is preferred. … in the filename /etc/rc.local… … in /etc/rc.local… These two examples show this for manual references. The second example is preferred (the second example uses citerefentry). See man csh for more information. See &man.csh.1; For more information about writing style, see Elements of Style, by William Strunk. + + + Style guide + + To keep the source for the Handbook consistent when many different + people are editing it, please follow these style conventions. + + + Letter case + + Tags are entered in lower case, <para>, + not <PARA>. + + Text that appears in SGML contexts is generally written in upper + case, <!ENTITY…>, and + <!DOCTYPE…>, not + <!entity…> and + <!doctype…>. + + + + Indentation + + Each file starts with indentation set at column 0, + regardless of the indentation level of the file + which might contain this one. + + Every start tag increases the indentation level by 2 spaces, and + every end tag decreases the indentation level by 2 spaces. Content + within elements should be indented by two spaces if the content runs + over more than one line. + + For example, the source for this section looks something + like; + + + + ... + + + ... + + + Indentation + + Each file starts with indentation set at column 0, + regardless of the indentation level of the file + which might contain this one. + + Every start tag increases the indentation level by 2 spaces, and + every end tag decreases the indentation level by 2 spaces. Content + within elements should be indented by two spaces if the content runs + over more than one line. + + ... + + +]]> + + If you use Emacs or + Xemacs to edit the files then + sgml-mode should be loaded automatically, and the + Emacs local variables at the bottom of each file should enforce these + styles. + + + + White space changes + + When committing changes, do not commit changes to the + content at the same time as changes to the + formatting. + + This is so that the teams that convert the Handbook to other + languages can quickly see what content has actually changed in your + commit, without having to decide whether a line has changed because of + the content, or just because it has been refilled. + + For example, if you have added two sentances to a paragraph, such + that the line lengths on the paragraph now go over 80 columns, first + commit your change with the too-long line lengths. Then fix the line + wrapping, and commit this second change. In the commit message for + the second change, be sure to indicate that this is a whitespace-only + change, and that the translation team can ignore it. + + diff --git a/en_US.ISO_8859-1/books/fdp-primer/Makefile b/en_US.ISO_8859-1/books/fdp-primer/Makefile index ec34c30d36..054b703417 100644 --- a/en_US.ISO_8859-1/books/fdp-primer/Makefile +++ b/en_US.ISO_8859-1/books/fdp-primer/Makefile @@ -1,41 +1,40 @@ # -# $Id: Makefile,v 1.5 1999-08-29 00:02:22 jhb Exp $ +# $Id: Makefile,v 1.6 1999-09-03 17:22:40 nik Exp $ # # Build the FreeBSD Documentation Project Primer. # MAINTAINER=nik@FreeBSD.org DOC?= book FORMATS?= html-split html INSTALL_COMPRESSED?= gz INSTALL_ONLY_COMPRESSED?= # # SRCS lists the individual SGML files that make up the document. Changes # to any of these files will force a rebuild # # SGML content SRCS= book.sgml SRCS+= overview/chapter.sgml SRCS+= psgml-mode/chapter.sgml SRCS+= see-also/chapter.sgml SRCS+= sgml-markup/chapter.sgml SRCS+= sgml-primer/chapter.sgml SRCS+= stylesheets/chapter.sgml -SRCS+= the-faq/chapter.sgml -SRCS+= the-handbook/chapter.sgml +SRCS+= structure/chapter.sgml SRCS+= the-website/chapter.sgml SRCS+= tools/chapter.sgml SRCS+= translations/chapter.sgml SRCS+= writing-style/chapter.sgml # Entities SRCS+= chapters.ent -DOC_PREFIX?= ../../.. +DOC_PREFIX?= ${.CURDIR}/../../.. -.include "${DOC_PREFIX}/share/mk/docproj.docbook.mk" +.include "${DOC_PREFIX}/share/mk/doc.project.mk" diff --git a/en_US.ISO_8859-1/books/fdp-primer/book.sgml b/en_US.ISO_8859-1/books/fdp-primer/book.sgml index 57c3e91fa2..877a39e0f1 100644 --- a/en_US.ISO_8859-1/books/fdp-primer/book.sgml +++ b/en_US.ISO_8859-1/books/fdp-primer/book.sgml @@ -1,281 +1,280 @@ %man; %chapters; ]> FreeBSD Documentation Project Primer for New Contributors Nik Clayton
nik@FreeBSD.org
 1998 1999 Nik Clayton - $Date: 1999-08-29 16:08:38 $ + $Date: 1999-09-03 17:22:39 $ - $Id: book.sgml,v 1.6 1999-08-29 16:08:38 jhb Exp $ + $Id: book.sgml,v 1.7 1999-09-03 17:22:39 nik Exp $ Redistribution and use in source (SGML DocBook) and 'compiled' forms (SGML, HTML, PDF, PostScript, RTF and so forth) with or without modification, are permitted provided that the following conditions are met: Redistributions of source code (SGML DocBook) must retain the above copyright notice, this list of conditions and the following disclaimer as the first lines of this file unmodified. Redistributions in compiled form (transformed to other DTDs, converted to PDF, PostScript, RTF and other formats) must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. Thank you for becoming a part of the FreeBSD Documentation Project. Your contribution is extremely valuable. This primer covers everything you will need to know in order to start contributing to the FreeBSD Documentation Project, from the tools and software you will be using (both mandatory and recommended) to the philosophy behind the Documentation Project. This document is a work in progress, and is not complete. Sections that are known to be incomplete are indicated with a * in their name. Preface Shell Prompts The following table shows the default system prompt and superuser prompt. The examples will use this prompt to indicate which user you should be running the example as. User Prompt Normal user &prompt.user; root &prompt.root; Typographic Conventions The following table describes the typographic conventions used in this book. Meaning Examples The name of commands, files, and directories. On screen computer output. Edit your .login file.Use ls -a to list all files.You have mail. What you type, when contrasted with on-screen computer output. &prompt.user; su Password: Manual page references. Use su 1 to change user names. User and group names Only root can do this. Emphasis You must do this. Command line variables; replace with the real name or variable. To delete a file, type rm filename Environment variables $HOME is your home directory. Notes, warnings, and examples Within the text appear notes, warnings, and examples. Notes are represented like this, and contain information that you should take note of, as it may affect what you do. Warnings are represented like this, and contain information warning you about possible damage if you do not follow the instructions. This damage may be physical, to your hardware or to you, or it may be non-physical, such as the inadvertant deletion of important files. A sample example Examples are represented like this, and typically contain examples you should walk through, or show you what the results of a particular action should be. Acknowledgments My thanks to Sue Blake, Patrick Durusau, Jon Hamilton, Peter Flynn, and Christopher Maden, who took the time to read early drafts of this document and offer many valuable comments and criticisms. &chap.overview; &chap.tools; &chap.sgml-primer; &chap.sgml-markup; &chap.stylesheets; - &chap.the-faq; - &chap.the-handbook; + &chap.structure; &chap.the-website; &chap.translations; &chap.writing-style; &chap.psgml-mode; &chap.see-also; diff --git a/en_US.ISO_8859-1/books/fdp-primer/chapters.ent b/en_US.ISO_8859-1/books/fdp-primer/chapters.ent index 3375e0085d..0983076bf3 100644 --- a/en_US.ISO_8859-1/books/fdp-primer/chapters.ent +++ b/en_US.ISO_8859-1/books/fdp-primer/chapters.ent @@ -1,23 +1,22 @@ - - + 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 new file mode 100644 index 0000000000..0fcb999857 --- /dev/null +++ b/en_US.ISO_8859-1/books/fdp-primer/structure/chapter.sgml @@ -0,0 +1,299 @@ + + + + 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 + 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/the-faq/chapter.sgml b/en_US.ISO_8859-1/books/fdp-primer/the-faq/chapter.sgml deleted file mode 100644 index 664c9bbf5e..0000000000 --- a/en_US.ISO_8859-1/books/fdp-primer/the-faq/chapter.sgml +++ /dev/null @@ -1,49 +0,0 @@ - - - - * The FAQ - - - - - - diff --git a/en_US.ISO_8859-1/books/fdp-primer/the-handbook/chapter.sgml b/en_US.ISO_8859-1/books/fdp-primer/the-handbook/chapter.sgml deleted file mode 100644 index c494990ff9..0000000000 --- a/en_US.ISO_8859-1/books/fdp-primer/the-handbook/chapter.sgml +++ /dev/null @@ -1,282 +0,0 @@ - - - - * The Handbook - - - Logical structure - - 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 - - The Handbook (and its translations) are in the - doc/language/handbook - subdirectory of the main CVS - repository. language corresponds to the ISO - language code for that translation, en for English, - ja for Japanese, and so on. - - 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 the rules that are used - to convert the Handbook from its source form (DocBook) to a number of - other target formats (including HTML, PostScript, and plain - text). - - A more detailed description of the Makefile - is in . - - - - <filename>handbook.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. - - handbook.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 handbook.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 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). - - - - - - - Style guide - - To keep the source for the Handbook consistent when many different - people are editing it, please follow these style conventions. - - - Letter case - - Tags are entered in lower case, <para>, - not <PARA>. - - Text that appears in SGML contexts is generally written in upper - case, <!ENTITY…>, and - <!DOCTYPE…>, not - <!entity…> and - <!doctype…>. - - - - Indentation - - Each file starts with indentation set at column 0, - regardless of the indentation level of the file - which might contain this one. - - Every start tag increases the indentation level by 2 spaces, and - every end tag decreases the indentation level by 2 spaces. Content - within elements should be indented by two spaces if the content runs - over more than one line. - - For example, the source for this section looks something - like; - - - - ... - - - ... - - - Indentation - - Each file starts with indentation set at column 0, - regardless of the indentation level of the file - which might contain this one. - - Every start tag increases the indentation level by 2 spaces, and - every end tag decreases the indentation level by 2 spaces. Content - within elements should be indented by two spaces if the content runs - over more than one line. - - ... - - -]]> - - If you use Emacs or - Xemacs to edit the files then - sgml-mode should be loaded automatically, and the - Emacs local variables at the bottom of each file should enforce these - styles. - - - - White space changes - - When committing changes, do not commit changes to the - content at the same time as changes to the - formatting. - - This is so that the teams that convert the Handbook to other - languages can quickly see what content has actually changed in your - commit, without having to decide whether a line has changed because of - the content, or just because it has been refilled. - - For example, if you have added two sentances to a paragraph, such - that the line lengths on the paragraph now go over 80 columns, first - commit your change with the too-long line lengths. Then fix the line - wrapping, and commit this second change. In the commit message for - the second change, be sure to indicate that this is a whitespace-only - change, and that the translation team can ignore it. - - - - - Converting the Handbook to other formats - - - - - - - diff --git a/en_US.ISO_8859-1/books/fdp-primer/writing-style/chapter.sgml b/en_US.ISO_8859-1/books/fdp-primer/writing-style/chapter.sgml index c1e9fbde52..fb6746f935 100644 --- a/en_US.ISO_8859-1/books/fdp-primer/writing-style/chapter.sgml +++ b/en_US.ISO_8859-1/books/fdp-primer/writing-style/chapter.sgml @@ -1,143 +1,231 @@ Writing style In order to promote consistency between the myriad authors of the FreeBSD documentation, some guidelines have been drawn up for authors to follow. Do not use contractions Do not use contractions. Always spell the phrase out in full. “Don't use contractions” would be wrong. Avoiding contractions makes for a more formal tone, is more precise, and slightly easier for translators. Use the serial comma In a list of items within a paragraph, seperate each item from the others with a comma. Seperate the last item from the others with a comma and the word “and”. For example, look at the following quote;
This is a list of one, two and three items.
Is this a list of three items, “one”, “two”, and “three”, or a list of two items, “one” and “two and three”? It is better to be explicit and include a serial comma;
This is a list of one, two, and three items.
Avoid redundant phrases Try not to use redundant phrases. In particular, “the command”, “the file”, and “man command” are probably redundant. These two examples show this for commands. The second example is preferred. Use the command cvsup to update your sources Use cvsup to update your sources These two examples show this for filenames. The second example is preferred. … in the filename /etc/rc.local… … in /etc/rc.local… These two examples show this for manual references. The second example is preferred (the second example uses citerefentry). See man csh for more information. See &man.csh.1; For more information about writing style, see Elements of Style, by William Strunk. + + + Style guide + + To keep the source for the Handbook consistent when many different + people are editing it, please follow these style conventions. + + + Letter case + + Tags are entered in lower case, <para>, + not <PARA>. + + Text that appears in SGML contexts is generally written in upper + case, <!ENTITY…>, and + <!DOCTYPE…>, not + <!entity…> and + <!doctype…>. + + + + Indentation + + Each file starts with indentation set at column 0, + regardless of the indentation level of the file + which might contain this one. + + Every start tag increases the indentation level by 2 spaces, and + every end tag decreases the indentation level by 2 spaces. Content + within elements should be indented by two spaces if the content runs + over more than one line. + + For example, the source for this section looks something + like; + + + + ... + + + ... + + + Indentation + + Each file starts with indentation set at column 0, + regardless of the indentation level of the file + which might contain this one. + + Every start tag increases the indentation level by 2 spaces, and + every end tag decreases the indentation level by 2 spaces. Content + within elements should be indented by two spaces if the content runs + over more than one line. + + ... + + +]]> + + If you use Emacs or + Xemacs to edit the files then + sgml-mode should be loaded automatically, and the + Emacs local variables at the bottom of each file should enforce these + styles. + + + + White space changes + + When committing changes, do not commit changes to the + content at the same time as changes to the + formatting. + + This is so that the teams that convert the Handbook to other + languages can quickly see what content has actually changed in your + commit, without having to decide whether a line has changed because of + the content, or just because it has been refilled. + + For example, if you have added two sentances to a paragraph, such + that the line lengths on the paragraph now go over 80 columns, first + commit your change with the too-long line lengths. Then fix the line + wrapping, and commit this second change. In the commit message for + the second change, be sure to indicate that this is a whitespace-only + change, and that the translation team can ignore it. + +