diff --git a/en_US.ISO8859-1/books/fdp-primer/overview/chapter.sgml b/en_US.ISO8859-1/books/fdp-primer/overview/chapter.sgml index 9ea5225913..ff994d5ac3 100644 --- a/en_US.ISO8859-1/books/fdp-primer/overview/chapter.sgml +++ b/en_US.ISO8859-1/books/fdp-primer/overview/chapter.sgml @@ -1,179 +1,179 @@ Overview Welcome to the FreeBSD Documentation Project. Good quality documentation is very important to the success of FreeBSD, and the FreeBSD Documentation Project (FDP) is how a lot of that documentation is produced. Your contributions are very valuable. This document's main purpose is to clearly explain how the FDP is organised, how to write and submit documentation to the FDP, and how to effectively use the tools available to you when writing documentation. Every one is welcome to join the FDP. There is no minimum - membership requirements, no quota of documentation you need to + membership requirement, no quota of documentation you need to produce per month. All you need to do is subscribe to the freebsd-doc@FreeBSD.org mailing list. After you have finished reading this document you should: Know which documentation is maintained by the FDP. Be able to read and understand the SGML source code for the documentation maintained by the FDP. Be able to make changes to the documentation. Be able to submit your changes back for review and eventual inclusion in the FreeBSD documentation. The FreeBSD Documentation Set The FDP is responsible for four categories of FreeBSD documentation. Manual pages The English language system manual pages are not written by the FDP, as they are part of the base system. However, the FDP can (and has) re-worded parts of existing manual pages to make them clearer, or to correct inaccuracies. The translation teams are responsible for translating the system manual pages in to different languages. These translations are kept within the FDP. FAQ The FAQ aims to address (in short question and answer format) questions that are asked, or should be asked, on the various mailing lists and newsgroups devoted to FreeBSD. The format does not permit long and comprehensive answers. Handbook The Handbook aims to be the comprehensive on-line resource and reference for FreeBSD users. Web site This is the main FreeBSD presence on the World Wide Web, visible at http://www.FreeBSD.org/ and many mirrors around the world. The web site is many people's first exposure to FreeBSD. These four groups of documentation are all available in the - FreeBSD CVS tree. This means that the logs and changes to these + FreeBSD CVS tree. This means that the logs of changes to these files are visible to anyone, and anyone can use a program such as CVSup or - CTM to keep their own local copies of + CTM to keep local copies of this documentation. In addition, many people have written tutorials or other web sites relating to FreeBSD. Some of these are stored in the CVS repository as well (where the author has agreed to this). In - other cases the author has decided to keep their documentation + other cases the author has decided to keep his documentation separate from the main FreeBSD repository. The FDP endeavours to provide links to as much of this documentation as possible. Before you start This document assumes that you already know: How to maintain an up-to-date local copy of the FreeBSD - documentation. Either by maintaining a local copy of the + documentation by maintaining a local copy of the FreeBSD CVS repository (using CVS and either CVSup or CTM) or by using CVSup to download just a checked-out copy. How to download and install new software using either the FreeBSD Ports system or &man.pkg.add.1;. diff --git a/en_US.ISO8859-1/books/fdp-primer/psgml-mode/chapter.sgml b/en_US.ISO8859-1/books/fdp-primer/psgml-mode/chapter.sgml index 79415582fa..8abcde6496 100644 --- a/en_US.ISO8859-1/books/fdp-primer/psgml-mode/chapter.sgml +++ b/en_US.ISO8859-1/books/fdp-primer/psgml-mode/chapter.sgml @@ -1,150 +1,150 @@ Using <literal>sgml-mode</literal> with <application>Emacs</application> Recent versions of Emacs or Xemacs (available from the ports collection) contain a very useful package called PSGML. Automatically - invoked when a file with .sgml extension is loaded, + invoked when a file with the .sgml extension is loaded, or by typing M-x sgml-mode, it is a major mode for dealing with SGML files, elements and attributes. An understanding of some of the commands provided by this mode can make working with SGML documents such as the Handbook much easier. C-c C-e Runs sgml-insert-element. You will be prompted for the name of the element to insert at the current point. You can use the TAB key to complete the element. Elements that are not valid at the current point will be disallowed. The start and end tags for the element will be inserted. If the element contains other, mandatory, elements then these will be inserted as well. C-c = Runs sgml-change-element-name. Place the point within an element and run this command. You will be prompted for the name of the element to change to. Both the start and end tags of the current element will be changed to the new element. C-c C-r Runs sgml-tag-region. Select some text (move to start of text, C-space, move to end of text, C-space) and then run this command. You will be prompted for the element to use. This element will then be inserted immediately before and after your marked region. C-c - Runs sgml-untag-element. Place the point within the start or end tag of an element you want to remove, and run this command. The element's start and end tags will be removed. C-c C-q Runs sgml-fill-element. Will recursively fill (i.e., reformat) content from the current element in. The filling will affect content in which whitespace is significant, such as within programlisting elements, so run this command with care. C-c C-a Runs sgml-edit-attributes. Opens a second buffer containing a list of all the attributes for the closest enclosing element, and their current values. Use TAB to navigate between attributes, C-k to remove an existing value and replace it with a new one, C-c to close this buffer and return to the main document. C-c C-v Runs sgml-validate. Prompts you to save the current document (if necessary) and then runs an SGML validator. The output from the validator is captured into a new buffer, and you can then navigate from one troublespot to the next, fixing markup errors as you go. Doubtless there are other useful functions of this mode, but those are the ones I use most often. diff --git a/en_US.ISO8859-1/books/fdp-primer/see-also/chapter.sgml b/en_US.ISO8859-1/books/fdp-primer/see-also/chapter.sgml index 9698df7b0b..9f8ac6dd06 100644 --- a/en_US.ISO8859-1/books/fdp-primer/see-also/chapter.sgml +++ b/en_US.ISO8859-1/books/fdp-primer/see-also/chapter.sgml @@ -1,121 +1,121 @@ See Also This document is deliberately not an exhaustive discussion of SGML, the DTDs listed, and the FreeBSD Documentation Project. For more information about these, you are encouraged to see the following web sites. The FreeBSD Documentation Project The FreeBSD Documentation Project web pages The FreeBSD Handbook SGML The SGML/XML web page, a comprehensive SGML resource Gentle introduction to SGML HTML The World Wide Web - organisation + Consortium The HTML 4.0 specification DocBook - The Davenport - Group, maintainers of the DocBook DTD + The DocBook + Technical Committee, maintainers of the DocBook DTD The Linux Documentation Project - The Linux Documentation + The Linux Documentation Project web pages diff --git a/en_US.ISO8859-1/books/fdp-primer/sgml-markup/chapter.sgml b/en_US.ISO8859-1/books/fdp-primer/sgml-markup/chapter.sgml index 0ac3f02504..ef88ad5fd1 100644 --- a/en_US.ISO8859-1/books/fdp-primer/sgml-markup/chapter.sgml +++ b/en_US.ISO8859-1/books/fdp-primer/sgml-markup/chapter.sgml @@ -1,2259 +1,2259 @@ SGML Markup This chapter describes the three markup languages you will encounter when you contribute to the FreeBSD documentation project. Each section describes the markup language, and details the markup that you are likely to want to use, or that is already in use. These markup languages contain a large number of elements, and it can be confusing sometimes to know which element to use for a particular situation. This section goes through the elements you are most likely to need, and gives examples of how you would use them. This is not an exhaustive list of elements, since that would just reiterate the documentation for each language. The aim of this section is to list those elements more likely to be useful to you. If you have a question about how best to markup a particular piece of content, please post it to the FreeBSD Documentation Project mailing list freebsd-doc@FreeBSD.org. Inline vs. block In the remainder of this document, when describing elements, inline means that the element can occur within a block element, and does not cause a line break. A block element, by comparison, will cause a line break (and other processing) when it is encountered. HTML HTML, the HyperText Markup Language, is the markup language of choice on the World Wide Web. More information can be found at <URL:http://www.w3.org/>. HTML is used to markup pages on the FreeBSD web site. It should not (generally) be used to mark up other documention, since DocBook offers a far richer set of elements to choose from. Consequently, you will normally only encounter HTML pages if you are writing for the web site. HTML has gone through a number of versions, 1, 2, 3.0, 3.2, and the latest, 4.0 (available in both strict and loose variants). The HTML DTDs are available from the ports collection in the textproc/html port. They are automatically installed as part of the textproc/docproj port. Formal Public Identifier (FPI) There are a number of HTML FPIs, depending upon the version (also known as the level) of HTML that you want to declare your document to be compliant with. The majority of HTML documents on the FreeBSD web site comply with the loose version of HTML 4.0. PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" Sectional elements An HTML document is normally split in to two sections. The first section, called the head, contains meta-information about the document, such as its title, the name of the author, the parent document, and so on. The second section, the body, contains the content that will be displayed to the user. These sections are indicated with head and body elements respectively. These elements are contained within the top-level html element. Normal HTML document structure <html> <head> <title>The document's title</title> </head> <body> … </body> </html> Block elements Headings HTML allows you to denote headings in your document, at up to six different levels. The largest and most prominent heading is h1, then h2, continuing down to h6. The element's content is the text of the heading. <sgmltag>h1</sgmltag>, <sgmltag>h2</sgmltag>, etc. Use: First section

This is the heading for the first section

This is the heading for the first sub-section

This is the heading for the second section

]]> Generally, an HTML page should have one first level heading (h1). This can contain many second level headings (h2), which can in turn contain many third level headings. Each hn element should have the same element, but one further up the hierarchy, preceeding it. Leaving gaps in the numbering is to be avoided. Bad ordering of <sgmltag>h<replaceable>n</replaceable></sgmltag> elements Use: First section

Sub-section

]]> Paragraphs HTML supports a single paragraph element, p. <sgmltag>p</sgmltag> Use: This is a paragraph. It can contain just about any other element.

]]> Block quotations A block quotation is an extended quotation from another document that should not appear within the current paragraph. <sgmltag>blockquote</sgmltag> Use: - A small excerpt from the US Constitution;

+ A small excerpt from the US Constitution:

We the People of the United States, in Order to form a more perfect Union, establish Justice, insure domestic Tranquility, provide for the common defence, promote the general Welfare, and secure the Blessings of Liberty to ourselves and our Posterity, do ordain and establish this Constitution for the United States of America.
]]> Lists You can present the user with three types of lists, ordered, unordered, and definition. Typically, each entry in an ordered list will be numbered, while - each entry in an unordered list will be proceeded by a bullet point. + each entry in an unordered list will be preceded by a bullet point. Definition lists are composed of two sections for each entry. The first section is the term being defined, and the second section is the definition of the term. Ordered lists are indicated by the ol element, unordered lists by the ul element, and definition lists by the dl element. Ordered and unordered lists contain listitems, indicated by the li element. A listitem can contain textual content, or it may be further wrapped in one or more p elements. Definition lists contain definition terms (dt) and definition descriptions (dd). A definition term can only contain inline elements. A definition description can contain other block elements. <sgmltag>ul</sgmltag> and <sgmltag>ol</sgmltag> Use: An unordered list. Listitems will probably be preceeded by bullets.

  • First item
  • Second item
  • Third item

An ordered list, with list items consisting of multiple paragraphs. Each item (note: not each paragraph) will be numbered.

  1. This is the first item. It only has one paragraph.

  2. This is the first paragraph of the second item.

    This is the second paragraph of the second item.

  3. This is the first and only paragraph of the third item.

]]> Definition lists with <sgmltag>dl</sgmltag> Use:
Term 1

Paragraph 1 of definition 1.

Paragraph 2 of definition 1.

Term 2

Paragraph 1 of definition 2.

Term 3
Paragraph 1 of definition 3. Note that the <p> element is not required in the single paragraph case.
]]> Pre-formatted text You can indicate that text should be shown to the user exactly as it is in the file. Typically, this means that the text is shown in a fixed font, multiple spaces are not merged in to one, and line breaks in the text are significant. In order to do this, wrap the content in the pre element. <sgmltag>pre</sgmltag> You could use pre to mark up an e-mail message; From: nik@FreeBSD.org To: freebsd-doc@FreeBSD.org Subject: New documentation available There's a new copy of my primer for contributers to the FreeBSD Documentation Project available at Comments appreciated. N]]> Tables Most text-mode browsers (such as Lynx) do not render tables particularly effectively. If you are relying on the tabular display of your content, you should consider using alternative markup to prevent confusion. Mark up tabular information using the table element. A table consists of one or more table rows (tr), each containing one or more cells of table data (td). Each cell can contain other block elements, such as paragraphs or lists. It can also contain another table (this nesting can repeat indefinitely). If the cell only contains one paragraph then you do not need to include the p element. Simple use of <sgmltag>table</sgmltag> Use: This is a simple 2x2 table.

Top left cell Top right cell
Bottom left cell Bottom right cell
]]> A cell can span multiple rows and columns. To indicate this, add the rowspan and/or colspan attributes, with values indicating the number of rows of columns that should be spanned. Using <literal>rowspan</literal> Use: One tall thin cell on the left, two short cells next to it on the right.

Long and thin
Top cell Bottom cell
]]> Using <literal>colspan</literal> Use: One long cell on top, two short cells below it.

Top cell
Bottom left cell Bottom right cell
]]> Using <literal>rowspan</literal> and <literal>colspan</literal> together Use: On a 3x3 grid, the top left block is a 2x2 set of cells merged in to one. The other cells are normal.

Top left large cell Top right cell
Middle right cell
Bottom left cell Bottom middle cell Bottom right cell
]]> In-line elements Emphasising information You have two levels of emphasis available in HTML, em and strong. em is for a normal level of emphasis and strong indicates stronger emphasis. Typically, em is rendered in italic and strong is rendered in bold. This is not always - the case however, and you should not rely on it. + the case, however, and you should not rely on it. <sgmltag>em</sgmltag> and <sgmltag>strong</sgmltag> Use: This has been emphasised, while this has been strongly emphasised.

]]> Bold and italics Because HTML includes presentational markup, you can also indicate that particular content should be rendered in bold or italic. The elements are b and i respectively. <sgmltag>b</sgmltag> and <sgmltag>i</sgmltag> This is in bold, while this is in italics.

]]> Indicating fixed pitch text If you have content that should be rendered in a fixed pitch (typewriter) typeface, use tt (for “teletype”). <sgmltag>tt</sgmltag> Use: This document was originally written by Nik Clayton, who can be reached by e-mail as nik@FreeBSD.org.

]]> Content size You can indicate that content should be shown in a larger or smaller font. There are three ways of doing this. Use big and small around the content you wish to change size. These tags can be nested, so <big><big>This is much bigger</big></big> is possible. Use font with the size attribute set to +1 or -1 respectively. This has the same effect as using big or small. However, the use of this approach is deprecated. Use font with the size attribute set to a number between 1 and 7. The default font size is 3. This approach is deprecated. <sgmltag>big</sgmltag>, <sgmltag>small</sgmltag>, and <sgmltag>font</sgmltag> The following fragments all do the same thing. This text is slightly smaller. But this text is slightly bigger.

This text is slightly smaller. But this text is slightly bigger

This text is slightly smaller. But this text is slightly bigger.

]]> Links Links are also in-line elements. Linking to other documents on the WWW In order to include a link to another document on the WWW you must know the URL of the document you want to link to. The link is indicated with a, and the href attribute contains the URL of the target document. The content of the element becomes the link, and is normally indicated to the user in some way (underlining, change of colour, different mouse cursor when over the link, and so on). Using <literal><a href="..."></literal> Use: More information is available at the FreeBSD web site.

]]> These links will take the user to the top of the chosen document. Linking to other parts of documents Linking to a point within another document (or within the same document) requires that the document author include anchors that you can link to. Anchors are indicated with a and the name attribute instead of href. Using <literal><a name="..."></literal> Use: This paragraph can be referenced in other links with the name para1.

]]> To link to a named part of a document, write a normal link to that document, but include the name of the anchor after a # symbol. Linking to a named part of another document Assume that the para1 example resides in a document called foo.html. More information can be found in the first paragraph of foo.html.

]]> If you are linking to a named anchor within the same document then you can omit the document's URL, and just include the name of the anchor (with the preceeding #). Linking to a named part of another document Assume that the para1 example resides in this document More information can be found in the first paragraph of this document.

]]> DocBook DocBook was designed by the Davenport Group to be a DTD for writing technical documentation. As such, and unlike LinuxDoc - and HTML, DocBook is very heavily orientated towards markup that + and HTML, DocBook is very heavily oriented towards markup that describes what something is, rather than describing how it should be presented. <literal>formal</literal> vs. <literal>informal</literal> Some elements may exist in two forms, formal and informal. Typically, the formal version of the element will consist of a title followed by the information version of the element. The informal version will not have a title. The DocBook DTD is available from the ports collection in the textproc/docbook port. It is automatically installed as part of the textproc/docproj port. FreeBSD extensions The FreeBSD Documentation Project has extended the DocBook DTD by adding some new elements. These elements serve to make some of the markup more precise. Where a FreeBSD specific element is listed below it is clearly marked. Throughout the rest of this document, the term “DocBook” is used to mean the FreeBSD extended DocBook DTD. There is nothing about these extensions that is FreeBSD specific, it was just felt that they were useful enhancements for this particular project. Should anyone from any of the other *nix camps (NetBSD, OpenBSD, Linux, …) be interested in collaborating on a standard DocBook extension set, please get in touch with Nik Clayton nik@FreeBSD.org. The FreeBSD extensions are not (currently) in the ports collection. It is a part of the Documentation Project source repository, and can be found in doc/share/sgml/freebsd.dtd. Formal Public Identifier (FPI) In compliance with the DocBook guidelines for writing FPIs for DocBook customisations, the FPI for the FreeBSD extended DocBook DTD is; PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN" Document structure DocBook allows you to structure your documentation in several ways. In the FreeBSD Documentation Project we are using two primary - types of DocBook document, the book, and the article. + types of DocBook document: the book and the article. A book is organised into chapters. This is a mandatory requirement. There may be parts between the book and the chapter to provide another layer of organisation. The Handbook is arranged in this way. A chapter may (or may not) contain one or more sections. These are indicated with the sect1 element. If a section contains another section then use the sect2 element, and so on, up to sect5. Chapters and sections contain the remainder of the content. An article is simpler than a book, and does not use chapters. Instead, the content of an article is organised into one or more sections, using the same sect1 (and sect2 and so on) elements that are used in books. Obviously, you should consider the nature of the documentation you are writing in order to decide whether it is best marked up as a book or an article. Articles are well suited to information that does not - need to be broken down in to several chapters, and that is, relatively + need to be broken down into several chapters, and that is, relatively speaking, quite short, at up to 20-25 pages of content. Books are - best suited to information that can be broken up in to several + best suited to information that can be broken up into several chapters, possibly with appendices and similar content as well. The FreeBSD tutorials are all marked up as articles, while this document, the FreeBSD FAQ, and the FreeBSD Handbook are all marked up as books. Starting a book The content of the book is contained within the book element. As well as containing structural markup, this element can contain elements that include additional information about the book. This is either meta-information, used for reference purposes, or additional content used to produce a title page. This additional information should be contained within bookinfo. Boilerplate <sgmltag>book</sgmltag> with <sgmltag>bookinfo</sgmltag> <book> <bookinfo> <title>Your title here</title> <author> <firstname>Your first name</firstname> <surname>Your surname</surname> <affiliation> <address><email>Your e-mail address</email></address> </affiliation> </author> <copyright> <year>1998</year> <holder role="mailto:your e-mail address">Your name</holder> </copyright> <pubdate role="rcs">$Date$</pubdate> <releaseinfo>$Id$</releaseinfo> <abstract> <para>Include an abstract of the book's contents here.</para> </abstract> </bookinfo> … </book> Starting an article The content of the article is contained within the article element. As well as containing structural markup, this element can contain elements that include additional information about the article. This is either meta-information, used for reference purposes, or additional content used to produce a title page. This additional information should be contained within artheader. Boilerplate <sgmltag>article</sgmltag> with <sgmltag>artheader</sgmltag> <article> <artheader> <title>Your title here</title> <author> <firstname>Your first name</firstname> <surname>Your surname</surname> <affiliation> <address><email>Your e-mail address</email></address> </affiliation> </author> <copyright> <year>1998</year> <holder role="mailto:your e-mail address">Your name</holder> </copyright> <pubdate role="rcs">$Date$</pubdate> <releaseinfo>$Id$</releaseinfo> <abstract> <para>Include an abstract of the article's contents here.</para> </abstract> </artheader> … </article> Indicating chapters Use chapter to mark up your chapters. Each chapter has a mandatory title. Articles do not contain chapters, they are reserved for books. A simple chapter The chapter's title ... ]]> - A chapter can not be empty, it must contain elements in addition + A chapter cannot be empty; it must contain elements in addition to title. If you need to include an empty chapter then just use an empty paragraph. Empty chapters This is an empty chapter ]]> Sections below chapters In books, chapters may (but do not need to) be broken up into sections, subsections, and so on. In articles, sections are the main structural element, and each article must contain at least one section. Use the sectn element. The n indicates the section number, which identifies the section level. The first sectn is sect1. You can have one or more of these in a chapter. They can contain one or more sect2 elements, and so on, down to sect5. Sections in chapters A sample chapter Some text in the chapter. First section (1.1) … Second section (1.2) First sub-section (1.2.1) First sub-sub-section (1.2.1.1) … Second sub-section (1.2.2) … ]]> This example includes section numbers in the section titles. You should not do this in your documents. Adding the section numbers is carried out the by the stylesheets (of which more later), and you do not need to manage them yourself. Subdividing using <sgmltag>part</sgmltag>s You can introduce another layer of organisation between book and chapter with one or - more parts. This can not be done in an + more parts. This cannot be done in an article. Introduction Overview ... What is FreeBSD? ... History ... ]]> Block elements Paragraphs - DocBook supports three types of paragraphs; + DocBook supports three types of paragraphs: formalpara, para, and simpara. Most of the time you will only need to use para. formalpara includes a title element, and simpara disallows some elements from within para. Stick with para. <sgmltag>para</sgmltag> Use: This is a paragraph. It can contain just about any other element. ]]> Appearance: This is a paragraph. It can contain just about any other element. Block quotations A block quotation is an extended quotation from another document that should not appear within the current paragraph. You will probably only need it infrequently. Blockquotes can optionally contain a title and an attribution (or they can be left untitled and unattributed). <sgmltag>blockquote</sgmltag> Use: A small excerpt from the US Constitution;
Preamble to the Constitution of the United States Copied from a web site somewhere We the People of the United States, in Order to form a more perfect Union, establish Justice, insure domestic Tranquility, provide for the common defence, promote the general Welfare, and secure the Blessings of Liberty to ourselves and our Posterity, do ordain and establish this Constitution for the United States of America.
]]> Appearance:
Preamble to the Constitution of the United States Copied from a web site somewhere We the People of the United States, in Order to form a more perfect Union, establish Justice, insure domestic Tranquility, provide for the common defence, promote the general Welfare, and secure the Blessings of Liberty to ourselves and our Posterity, do ordain and establish this Constitution for the United States of America.
Tips, notes, warnings, cautions, important information and sidebars. You may need to include extra information separate from the main body of the text. Typically this is “meta” information that the user should be aware of. Depending on the nature of the information, one of tip, note, warning, caution, and important should be used. Alternatively, if the information is related to the main text but is not one of the above, use sidebar. The circumstances in which to choose one of these elements over another is unclear. The DocBook documentation suggests; A Note is for information that should be heeded by all readers. An Important element is a variation on Note. A Caution is for information regarding possible data loss or software damage. A Warning is for information regarding possible hardware damage or injury to life or limb. <sgmltag>warning</sgmltag> Use: Installing FreeBSD may make you want to delete Windows from your harddisk. ]]> Installing FreeBSD may make you want to delete Windows from your harddisk. Lists and procedures You will often need to list pieces of information to the user, or present them with a number of steps that must be carried out in order to accomplish a particular goal. In order to do this, use itemizedlist, orderedlist, or procedureThere are other types of list element in DocBook, but we're not concerned with those at the moment. itemizedlist and - orderedlist are similar to the counterparts in + orderedlist are similar to their counterparts in HTML, ul and ol. Each one consists of one or more listitem elements, and each listitem contains one or more block elements. The listitem elements are analagous to - HTMLs li tags. However, unlike HTML they are + HTML's li tags. However, unlike HTML, they are required. procedure is slightly different. It consists of steps, which may in turn consists of more steps or substeps. Each step contains block elements. <sgmltag>itemizedlist</sgmltag>, <sgmltag>orderedlist</sgmltag>, and <sgmltag>procedure</sgmltag> Use: This is the first itemized item. This is the second itemized item. This is the first ordered item. This is the second ordered item. Do this. Then do this. And now do this. ]]> Appearance: This is the first itemized item. This is the second itemized item. This is the first ordered item. This is the second ordered item. Do this. Then do this. And now do this. Showing file samples If you want to show a fragment of a file (or perhaps a complete file) to the user, wrap it in the programlisting element. White space and line breaks within programlisting are significant. In particular, this means that the opening tag should appear on the same line as the first line of the output, and the closing tag should appear on the same line as the last line of the output, otherwise spurious blank lines may be included. <sgmltag>programlisting</sgmltag> Use: When you have finished, your program should look like this; #include <stdio.h> int main(void) { printf("hello, world\n"); }]]> Notice how the angle brackets in the #include line need to be referenced by their entities instead of being included literally. Appearance: When you have finished, your program should look like this; #include <stdio.h> int main(void) { printf("hello, world\n"); } There is a mechanism within DocBook for referring to sections of a previously occuring programlisting, called callouts (see programlistingco for more information). I don't fully understand (i.e., have never used) this feature, so can't document it here. For the mean time, you can include line numbers within the content, and then refer to them later on in your description. That will change, as soon as I find the time to understand and document callouts. Tables Unlike HTML, you do not need to use tables for layout purposes, as the stylesheet handles those issues for you. Instead, just use tables for marking up tabular data. In general terms (and see the DocBook documentation for more detail) a table (which can be either formal or informal) consists of a table element. This contains at least one tgroup element, which specifies (as an attribute) the number of columns in this table group. Within the tablegroup you can then have one thead element, which contains elements for the table headings (column headings), and one tbody which contains the body of the table. Both tgroup and thead contain row elements, which in turn contain entry elements. Each entry element specifies one cell in the table. <sgmltag>informaltable</sgmltag> Use: This is column head 1 This is column head 2 Row 1, column 1 Row 1, column 2 Row 2, column 1 Row 2, column 2 ]]> Appearance: This is column head 1 This is column head 2 Row 1, column 1 Row 1, column 2 Row 2, column 1 Row 2, column 2 If you don't want a border around the table the frame attribute can be added to the informaltable element with a value of none (i.e., <informaltable frame="none">). Tables where <literal>frame="none"</literal> Appearance: This is column head 1 This is column head 2 Row 1, column 1 Row 1, column 2 Row 2, column 1 Row 2, column 2 Examples for the user to follow A lot of the time you need to show examples for the user to follow. Typically, these will consist of dialogs with the computer; the user types in a command, the user gets a response back, they type in another command, and so on. A number of distinct elements and entities come in to play here. screen Everything the user sees in this example will be on the computer screen, so the next element is screen. Within screen, white space is significant. prompt, &prompt.root; and &prompt.user; Some of the things the user will be seeing on the screen are prompts from the computer (either from the OS, command shell, or application. These should be marked up using prompt. As a special case, the two shell prompts for the normal user and the root user have been provided as entities. Every time you want to indicate the user is at a shell prompt, use one of &prompt.root; and &prompt.user; as necessary. They do not need to be inside prompt. &prompt.root; and &prompt.user; are FreeBSD extensions to DocBook, and are not part of the original DTD. userinput When displaying text that the user should type in, wrap it in userinput tags. It will probably be displayed differently to the user. <sgmltag>screen</sgmltag>, <sgmltag>prompt</sgmltag>, and <sgmltag>userinput</sgmltag> Use: &prompt.user; ls -1 foo1 foo2 foo3 &prompt.user; ls -1 | grep foo2 foo2 &prompt.user; su Password: &prompt.root; cat foo2 This is the file called 'foo2']]> Appearance: &prompt.user; ls -1 foo1 foo2 foo3 &prompt.user; ls -1 | grep foo2 foo2 &prompt.user; su Password: &prompt.root; cat foo2 This is the file called 'foo2' Even though we are displaying the contents of the file foo2, it is not marked up as programlisting. Reserve programlisting for showing fragments of files outside the context of user actions. In-line elements Emphasising information When you want to emphasise a particular word or phrase, use emphasis. This may be presented as italic, or bold, or might be spoken differently with a text-to-speech system. There is no way to change the presentation of the emphasis within your document, no equivalent of HTML's b and i. If the information you are presenting is important then consider presenting it in important rather than emphasis. <sgmltag>emphasis</sgmltag> Use: FreeBSD is without doubt the premiere Unix like operating system for the Intel architecture.]]> Appearance: FreeBSD is without doubt the premiere Unix like operating system for the Intel architecture. Applications, commands, options, and cites You will frequently want to refer to both applications and commands when writing for the Handbook. The distinction between - them is simple; an application is the name for a suite (or possibly + them is simple: an application is the name for a suite (or possibly just 1) of programs that fulfil a particular task. A command is the name of a program that the user can run. In addition, you will occasionally need to list one or more of the options that a command might take. - Finally, you will often want to list a command with it's manual + Finally, you will often want to list a command with its manual section number, in the “command(number)” format so common in Unix manuals. Mark up application names with application. - When you want to list a command with it's manual section number + When you want to list a command with its manual section number (which should be most of the time) the DocBook element is citerefentry. This will contain a further two elements, refentrytitle and manvolnum. The content of refentrytitle is the name of the command, and the content of manvolnum is the manual page section. This can be cumbersome to write, and so a series of general entities have been created to make this easier. Each entity takes the form &man.manual-page.manual-section;. The file that contains these entities is in doc/share/sgml/man-refs.ent, and can be - referred to using this FPI; + referred to using this FPI: PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN" Therefore, the introduction to your documentation will probably - look like this; + look like this: <!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN" [ <!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"> %man; … ]> Use command when you want to include a command name “in-line” but present it as something the user should type in. Use option to mark up a command's options. This can be confusing, and sometimes the choice is not always clear. Hopefully this example makes it clearer. Applications, commands, and options. Use: Sendmail is the most widely used Unix mail application. Sendmail includes the sendmail 8 , &man.sendmail.8;, and &man.newaliases.8; programs. One of the command line parameters to sendmail 8 , , will display the current status of messages in the mail queue. Check this on the command line by running sendmail -bp.]]> Appearance: Sendmail is the most widely used Unix mail application. Sendmail includes the sendmail 8 , mailq 8 , and newaliases 8 programs. One of the command line parameters to sendmail 8 , , will display the current status of messages in the mail queue. Check this on the command line by running sendmail -bp. Notice how the &man.command.section; notation is easier to follow. Files, directories, extensions Whenever you wish to refer to the name of a file, a directory, or a file extension, use filename. <sgmltag>filename</sgmltag> Use: The SGML source for the Handbook in English can be found in /usr/doc/en/handbook/. The first file is called handbook.sgml in that directory. You should also see a Makefile and a number of files with a .ent extension.]]> Appearance: The SGML source for the Handbook in English can be found in /usr/doc/en/handbook/. The first file is called handbook.sgml in that directory. You should also see a Makefile and a number of files with a .ent extension. Devices FreeBSD extension These elements are part of the FreeBSD extension to DocBook, and do not exist in the original DocBook DTD. When referring to devices you have two choices. You can either refer to the device as it appears in /dev, or you can use the name of the device as it appears in the kernel. For this latter course, use devicename. Sometimes you will not have a choice. Some devices, such as networking cards, do not have entries in /dev, or the entries are markedly different from those entries. <sgmltag>devicename</sgmltag> Use: sio is used for serial communication in FreeBSD. sio manifests through a number of entries in /dev, including /dev/ttyd0 and /dev/cuaa0. By contrast, the networking devices, such as ed0 do not appear in /dev. In MS-DOS, the first floppy drive is referred to as a:. In FreeBSD it is /dev/fd0.]]> Appearance: sio is used for serial communication in FreeBSD. sio manifests through a number of entries in /dev, including /dev/ttyd0 and /dev/cuaa0. By contrast, the networking devices, such as ed0 do not appear in /dev. In MS-DOS, the first floppy drive is referred to as a:. In FreeBSD it is /dev/fd0. Hosts, domains, IP addresses, and so forth FreeBSD extension These elements are part of the FreeBSD extension to DocBook, and do not exist in the original DocBook DTD. You can markup identification information for networked computers (hosts) in several ways, depending on the nature of the information. All of them use hostid as the element, with the role attribute selecting the type of the marked up information. No role attribute, or role="hostname" With no role attribute (i.e., hostid...hostid the marked up information is the simple hostname, such as freefall or wcarchive. You can explicitly specify this with role="hostname". role="domainname" The text is a domain name, such as FreeBSD.org or ngo.org.uk. There is no hostname component. role="fqdn" The text is a Fully Qualified Domain Name, with both hostname and domain name parts. role="ipaddr" The text is an IP address, probably expressed as a dotted quad. role="netmask" The text is a network mask, which might be expressed as a dotted quad, a hexadecimal string, or as a / followed by a number. role="mac" The text is an ethernet MAC address, expressed as a series of 2 digit hexadecimal numbers seperated by colons. <sgmltag>hostid</sgmltag> and roles Use: The local machine can always be referred to by the name localhost, which will have the IP address 127.0.0.1. The FreeBSD.org domain contains a number of different hosts, including freefall.FreeBSD.org and bento.FreeBSD.org. When adding an IP alias to an interface (using ifconfig) always use a netmask of 255.255.255.255 (which can also be expressed as 0xffffffff. The MAC address uniquely identifies every network card in in existence. A typical MAC address looks like 08:00:20:87:ef:d0.]]> Appearance: The local machine can always be referred to by the name localhost, which will have the IP address 127.0.0.1. The FreeBSD.org domain contains a number of different hosts, including freefall.FreeBSD.org and bento.FreeBSD.org. When adding an IP alias to an interface (using ifconfig) always use a netmask of 255.255.255.255 (which can also be expressed as 0xffffffff. The MAC address uniquely identifies every network card in existence. A typical MAC address looks like 08:00:20:87:ef:d0. Usernames FreeBSD extension These elements are part of the FreeBSD extension to DocBook, and do not exist in the original DocBook DTD. When you need to refer to a specific username, such as root or bin, use username. <sgmltag>username</sgmltag> Use: To carry out most system administration functions you will need to be root.]]> Appearance: To carry out most system administration functions you will need to be root. Describing <filename>Makefile</filename>s FreeBSD extension These elements are part of the FreeBSD extension to DocBook, and do not exist in the original DocBook DTD. Two elements exist to describe parts of Makefiles, maketarget and makevar. maketarget identifies a build target exported by a Makefile that can be given as a parameter to make. makevar identifies a variable that can be set (in the environment, on the make command line, or within the Makefile) to influence the process. <sgmltag>maketarget</sgmltag> and <sgmltag>makevar</sgmltag> Use: Two common targets in a Makefile are all and clean. Typically, invoking all will rebuild the application, and invoking clean will remove the temporary files (.o for example) created by the build process. clean may be controlled by a number of variables, including CLOBBER and RECURSE.]]> Appearance: Two common targets in a Makefile are all and clean. Typically, invoking all will rebuild the application, and invoking clean will remove the temporary files (.o for example) created by the build process. clean may be controlled by a number of variables, including CLOBBER and RECURSE. Literal text You will often need to include “literal” text in the Handbook. This is text that is excerpted from another file, or which should be copied from the Handbook into another file verbatim. Some of the time, programlisting will be sufficient to denote this text. programlisting is not always appropriate, particularly when you want to include a portion of a file “in-line” with the rest of the paragraph. On these occasions, use literal. <sgmltag>literal</sgmltag> Use: The maxusers 10 line in the kernel configuration file determines the size of many system tables, and is a rough guide to how many simultaneous logins the system will support.]]> Appearance: The maxusers 10 line in the kernel configuration file determines the size of many system tables, and is a rough guide to how many simultaneous logins the system will support. Showing items that the user <emphasis>must</emphasis> fill in There will often be times when you want to show the user what to do, or refer to a file, or command line, or similar, where the user can not simply copy the examples that you provide, but must instead include some information themselves. replaceable is designed for this eventuality. Use it inside other elements to indicate parts of that element's content that the user must replace. <sgmltag>replaceable</sgmltag> Use: &prompt.user; man command ]]> Appearance: &prompt.user; man command replaceable can be used in many different elements, including literal. This example also shows that replaceable should only be wrapped around the content that the user is meant to provide. The other content should be left alone. Use: The maxusers n line in the kernel configuration file determines the size of many system tables, and is a rough guide to how many simultaneous logins the system will support. For a desktop workstation, 32 is a good value for n.]]> Appearance: The maxusers n line in the kernel configuration file determines the size of many system tables, and is a rough guide to how many simultaneous logins the system will support. For a desktop workstation, 32 is a good value for n. Links Links are also in-line elements. Linking to other parts of the same document Linking within the same document requires you to to specify where you are linking from (i.e., the text the user will click, or otherwise indicate, as the source of the link) and where you are linking to (the link's destination). Each element within DocBook has an attribute called id. You can place text in this attribute to uniquely name the element it is attached to. This value will be used when you specify the link source. Normally, you will only be linking to chapters or sections, so you would add the id attribute to these elements. <literal>id on chapters and sections</literal> Introduction This is the introduction. It contains a subsection, which is identified as well. Sub-sect 1 This is the subsection. ]]> Obviously, you should use more descriptive values. The values must be unique within the document (i.e., not just the file, but the document the file might be included in as well). Notice how the id for the subsection is constructed by appending text to the id of the chapter. This helps to ensure that they are unique. If you want to allow the user to jump into a specific portion of the document (possibly in the middle of a paragraph or an example), use anchor. This element has no content, but takes an id attribute. <sgmltag>anchor</sgmltag> This paragraph has an embedded link target in it. It won't show up in the document.]]> When you want to provide the user with a link they can activate (probably by clicking) to go to a section of the document that has an id attribute, you can use either xref or link. Both of these elements have a linkend attribute. The value of this attribute should be the value that you have used in a id attribute (it does not matter - if that value has not yet occured in your document, this will work + if that value has not yet occurred in your document; this will work for forward links as well as backward links). If you use xref then you have no control over the text of the link. It will be generated for you. Using <sgmltag>xref</sgmltag> Assume that this fragment appears somewhere in a document that includes the id example; More information can be found in . More specific information can be found in .]]> The text of the link will be generated automatically, and will look like (emphasised text indicates the text that will be the link);
More information can be found in Chapter One. More specific information can be found in the section called Sub-sect 1.
Notice how the text from the link is derived from the section title or the chapter number. This means that you can not use xref to link to an id attribute on an anchor element. The anchor has no content, so the xref can not generate the text for the link. If you want to control the text of the link then use link. This element wraps content, and the content will be used for the link. Using <sgmltag>link</sgmltag> Assume that this fragment appears somewhere in a document that includes the id example. More information can be found in the first chapter. More specific information can be found in FreeBSD home page instead.]]> Appearance: Of course, you could stop reading this document and go to the FreeBSD home page instead. * LinuxDoc LinuxDoc is an adaptation of the QWERTZ DTD, first adopted by the - Linux Documentation + Linux Documentation Project, and subsequently adopted by the FreeBSD Documentation Project. The LinuxDoc DTD contains primarily appearance related markup rather than content related markup (i.e., it describes what something looks like rather than what it is). Both the FreeBSD Documentation Project and the Linux Documentation Project are migrating from the LinuxDoc DTD to the DocBook DTD. The LinuxDoc DTD is available from the ports collection in the textproc/linuxdoc category. diff --git a/en_US.ISO8859-1/books/fdp-primer/sgml-primer/chapter.sgml b/en_US.ISO8859-1/books/fdp-primer/sgml-primer/chapter.sgml index da050c4242..58e81d90bf 100644 --- a/en_US.ISO8859-1/books/fdp-primer/sgml-primer/chapter.sgml +++ b/en_US.ISO8859-1/books/fdp-primer/sgml-primer/chapter.sgml @@ -1,1594 +1,1594 @@ SGML Primer The majority of FDP documentation is written in applications of SGML. This chapter explains exactly what that means, how to read and understand the source to the documentation, and the sort of SGML tricks you will see used in the documentation. Portions of this section were inspired by Mark Galassi's Get Going With DocBook. Overview Way back when, electronic text was simple to deal with. Admittedly, you had to know which character set your document was written in (ASCII, EBCDIC, or one of a number of others) but that was about it. Text was text, and what you saw really was what you got. No frills, no formatting, no intelligence. Inevitably, this was not enough. Once you have text in a machine-usable format, you expect machines to be able to use it and manipulate it intelligently. You would like to indicate that certain phrases should be emphasised, or added to a glossary, or be hyperlinks. You might want filenames to be shown in a “typewriter” style font for viewing on screen, but as “italics” when printed, or any of a myriad of other options for presentation. It was once hoped that Artificial Intelligence (AI) would make this easy. Your computer would read in the document and automatically identify key phrases, filenames, text that the reader should type in, examples, and more. Unfortunately, real life has not happened quite like that, and our computers require some assistance before they can meaningfully process our text. More precisely, they need help identifying what is what. You or I can look at
To remove /tmp/foo use &man.rm.1;. &prompt.user; rm /tmp/foo
and easily see which parts are filenames, which are commands to be typed in, which parts are references to manual pages, and so on. But the computer processing the document can not. For this we need markup. “Markup” is commonly used to describe “adding value” or “increasing cost”. The term takes on both these meanings when applied to text. Markup is additional text included in the document, distinguished from the document's content in some way, so that programs that process the document can read the markup and use it when making decisions about the document. Editors can hide the markup from the user, so the user is not distracted by it. The extra information stored in the markup adds value to the document. Adding the markup to the document must typically be done by a person—after all, if computers could recognise the text sufficiently well to add the markup then there would be no need to add it in the first place. This increases the cost (i.e., the effort required) to create the document. The previous example is actually represented in this document like this; To remove /tmp/foo use &man.rm.1;. rm /tmp/foo]]> As you can see, the markup is clearly separate from the content. Obviously, if you are going to use markup you need to define what your markup means, and how it should be interpreted. You will need a markup language that you can follow when marking up your documents. Of course, one markup language might not be enough. A markup language for technical documentation has very different requirements than a markup language that was to be used for cookery recipes. This, in turn, would be very different from a markup language used to describe poetry. What you really need is a first language that you use to write these other markup languages. A meta markup language. This is exactly what the Standard Generalised Markup Language (SGML) is. Many markup languages have been written in SGML, including the two most used by the FDP, HTML and DocBook. Each language definition is more properly called a Document Type Definition (DTD). The DTD specifies the name of the elements that can be used, what order they appear in (and whether some markup can be used inside other markup) and related information. A DTD is sometimes referred to as an application of SGML. A DTD is a complete specification of all the elements that are allowed to appear, the order in which they should appear, which elements are mandatory, which are optional, and so forth. This makes it possible to write an SGML parser which reads in both the DTD and a document which claims to conform to the DTD. The parser can then confirm whether or not all the elements required by the DTD are in the document in the right order, and whether there are any errors in the markup. This is normally referred to as validating the document. This processing simply confirms that the choice of elements, their ordering, and so on, conforms to that listed in the DTD. It does not check that you have used appropriate markup for the content. If you were to try and mark up all the filenames in your document as function names, the parser would not flag this as an error (assuming, of course, that your DTD defines elements for filenames and functions, and that they are allowed to appear in the same place). It is likely that most of your contributions to the Documentation Project will consist of content marked up in either HTML or DocBook, rather than alterations to the DTDs. For this reason this book will not touch on how to write a DTD. Elements, tags, and attributes All the DTDs written in SGML share certain characteristics. This is hardly surprising, as the philosophy behind SGML will inevitably show through. One of the most obvious manifestations of this philisophy is that of content and elements. Your documentation (whether it is a single web page, or a lengthy book) is considered to consist of content. This content is then divided (and further subdivided) into elements. The purpose of adding markup is to name and identify the boundaries of these elements for further processing. For example, consider a typical book. At the very top level, the book is itself an element. This “book” element obviously contains chapters, which can be considered to be elements in their own right. Each chapter will contain more elements, such as paragraphs, quotations, and footnotes. Each paragraph might contain further elements, identifying content that was direct speech, or the name of a character in the story. You might like to think of this as “chunking” content. At the very top level you have one chunk, the book. Look a little deeper, and you have more chunks, the individual chapters. These are chunked further into paragraphs, footnotes, character names, and so on. Notice how you can make this differentation between different elements of the content without resorting to any SGML terms. It really is surprisingly straightforward. You could do this with a highlighter pen and a printout of the book, using different colours to indicate different chunks of content. Of course, we do not have an electronic highlighter pen, so we need some other way of indicating which element each piece of content belongs to. In languages written in SGML (HTML, DocBook, et al) this is done by means of tags. A tag is used to identify where a particular element starts, and where the element ends. The tag is not part of the element itself. Because each DTD was normally written to mark up specific types of information, each one will recognise different elements, and will therefore have different names for the tags. For an element called element-name the start tag will normally look like <element-name>. The corresponding closing tag for this element is </element-name>. Using an element (start and end tags) HTML has an element for indicating that the content enclosed by the element is a paragraph, called p. This element has both start and end tags. This is a paragraph. It starts with the start tag for the 'p' element, and it will end with the end tag for the 'p' element.

This is another paragraph. But this one is much shorter.

]]> Not all elements require an end tag. Some elements have no content. For example, in HTML you can indicate that you want a horizontal line to appear in the document. Obviously, this line has no content, so just the start tag is required for this element. Using an element (start tag only) HTML has an element for indicating a horizontal rule, called hr. This element does not wrap content, so only has a start tag. This is a paragraph.

This is another paragraph. A horizontal rule separates this from the previous paragraph.

]]> If it is not obvious by now, elements can contain other elements. In the book example earlier, the book element contained all the chapter elements, which in turn contained all the paragraph elements, and so on. Elements within elements; <sgmltag>em</sgmltag> This is a simple paragraph where some of the words have been emphasised.

]]> The DTD will specify the rules detailing which elements can contain other elements, and exactly what they can contain. People often confuse the terms tags and elements, and use the terms as if they were interchangeable. They are not. An element is a conceptual part of your document. An element has a defined start and end. The tags mark where the element starts and end. When this document (or anyone else knowledgable about SGML) refers to “the <p> tag” they mean the literal text consisting of the three characters <, p, and >. But the phrase “the <p> element” refers to the whole element. This distinction is very subtle. But keep it in mind. Elements can have attributes. An attribute has a name and a value, and is used for adding extra information to the element. This might be information that indicates how the content should be rendered, or might be something that uniquely identifies that occurence of the element, or it might be something else. An element's attributes are written inside the start tag for that element, and take the form attribute-name="attribute-value". In sufficiently recent versions of HTML, the p element has an attribute called align, which suggests an alignment (justification) for the paragraph to the program displaying the HTML. The align attribute can take one of four defined values, left, center, right and justify. If the attribute is not specified then the default is left. Using an element with an attribute The inclusion of the align attribute on this paragraph was superfluous, since the default is left.

This may appear in the center.

]]> Some attributes will only take specific values, such as left or justify. Others will allow you to enter anything you want. If you need to include quotes (") within an attribute then use single quotes around the attribute value. Single quotes around attributes I'm on the right!

]]> Sometimes you do not need to use quotes around attribute values at all. However, the rules for doing this are subtle, and it is far simpler just to always quote your attribute values. For you to do… In order to run the examples in this document you will need to install some software on your system and ensure that an environment variable is set correctly. Download and install textproc/docproj from the FreeBSD ports system. This is a meta-port that should download and install all of the programs and supporting files that are used by the Documentation Project. Add lines to your shell startup files to set SGML_CATALOG_FILES. <filename>.profile</filename>, for &man.sh.1; and &man.bash.1; users SGML_ROOT=/usr/local/share/sgml SGML_CATALOG_FILES=${SGML_ROOT}/jade/catalog SGML_CATALOG_FILES=${SGML_ROOT}/iso8879/catalog:$SGML_CATALOG_FILES SGML_CATALOG_FILES=${SGML_ROOT}/html/catalog:$SGML_CATALOG_FILES SGML_CATALOG_FILES=${SGML_ROOT}/docbook/catalog:$SGML_CATALOG_FILES export SGML_CATALOG_FILES <filename>.login</filename>, for &man.csh.1; and &man.tcsh.1; users setenv SGML_ROOT /usr/local/share/sgml setenv SGML_CATALOG_FILES ${SGML_ROOT}/jade/catalog setenv SGML_CATALOG_FILES ${SGML_ROOT}/iso8879/catalog:$SGML_CATALOG_FILES setenv SGML_CATALOG_FILES ${SGML_ROOT}/html/catalog:$SGML_CATALOG_FILES setenv SGML_CATALOG_FILES ${SGML_ROOT}/docbook/catalog:$SGML_CATALOG_FILES Then either log out, and log back in again, or run those commands from the command line to set the variable values. Create example.sgml, and enter the following text; An example HTML file

This is a paragraph containing some text.

This paragraph contains some more text.

This paragraph might be right-justified.

]]> Try and validate this file using an SGML parser. Part of textproc/docproj is the &man.nsgmls.1; validating parser. Normally, &man.nsgmls.1; reads in a document marked up according to an SGML DTD and returns a copy of the document's Element Structure Information Set (ESIS, but that is not important right now). However, when &man.nsgmls.1; is given the parameter, &man.nsgmls.1; will suppress its normal output, and just print error messages. This makes it a useful way to check to see if your document is valid or not. Use &man.nsgmls.1; to check that your document is valid; &prompt.user; nsgmls -s example.sgml As you will see, &man.nsgmls.1; returns without displaying any output. This means that your document validated successfully. See what happens when required elements are omitted. Try removing the title and /title tags, and re-run the validation. &prompt.user; nsgmls -s example.sgml nsgmls:example.sgml:5:4:E: character data is not allowed here nsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished The error output from &man.nsgmls.1; is organised into colon-separated groups, or columns. Column Meaning 1 The name of the program generating the error. This will always be nsgmls. 2 The name of the file that contains the error. 3 Line number where the error appears. 4 Column number where the error appears. 5 A one letter code indicating the nature of the message. I indicates an informational message, W is for warnings, and E is for errors It is not always the fifth column either. nsgmls -sv displays nsgmls:I: SP version "1.3" (depending on the installed version). As you can see, this is an informational message. , and X is for cross-references. As you can see, these messages are errors. 6 The text of the error message. More information about errors from &man.nsgmls.1; is available in the Unofficial 'Kindler, Gentler HTML Validator' FAQ. ]]> Simply omitting the title tags has generated 2 different errors. The first error indicates that content (in this case, characters, rather than the start tag for an element) has occured where the SGML parser was expecting something else. In this case, the parser was expecting to see one of the start tags for elements that are valid inside head (such as title). The second error is because head elements must contain a title element. Because it does not &man.nsgmls.1; considers that the element has not been properly finished. However, the closing tag indicates that the element has been closed before it has been finished. Put the title element back in. The DOCTYPE declaration The beginning of each document that you write must specify the name of the DTD that the document conforms to. This is so that SGML parsers can determine the DTD and ensure that the document does conform to it. This information is generally expressed on one line, in the DOCTYPE declaration. A typical declaration for a document written to conform with version 4.0 of the HTML DTD looks like this; ]]> That line contains a number of different components. <! Is the indicator that indicates that this is an SGML declaration. This line is declaring the document type. DOCTYPE Shows that this is an SGML declaration for the document type. html Names the first element that will appear in the document. PUBLIC "-//W3C//DTD HTML 4.0//EN" Lists the Formal Public Identifier (FPI) for the DTD that this document conforms to. Your SGML parser will use this to find the correct DTD when processing this document. PUBLIC is not a part of the FPI, but indicates to the SGML processor how to find the DTD referenced in the FPI. Other ways of telling the SGML parser how to find the DTD are shown later. > Returns to the document. Formal Public Identifiers (FPIs) You don't need to know this, but it's useful background, and might help you debug problems when your SGML processor can't locate the DTD you are using. FPIs must follow a specific syntax. This syntax is as follows; "Owner//Keyword Description//Language" Owner This indicates the owner of the FPI. If this string starts with “ISO” then this is an ISO owned FPI. For example, the FPI "ISO 8879:1986//ENTITIES Greek Symbols//EN" lists ISO 8879:1986 as being the owner for the set of entities for greek symbols. ISO 8879:1986 is the ISO number for the SGML standard. Otherwise, this string will either look like -//Owner or +//Owner (notice the only difference is the leading + or -). If the string starts with - then the owner information is unregistered, with a + it identifies it as being registered. ISO 9070:1991 defines how registered names are generated; it might be derived from the number of an ISO publication, an ISBN code, or an organisation code assigned according to ISO 6523. In addition, a registration authority could be created in order to assign registered names. The ISO council delegated this to the American National Standards Institute (ANSI). Because the FreeBSD Project hasn't been registered the owner string is -//FreeBSD. And as you can see, the W3C are not a registered owner either. Keyword There are several keywords that indicate the type of information in the file. Some of the most common keywords are DTD, ELEMENT, ENTITIES, and TEXT. DTD is used only for DTD files, ELEMENT is usually used for DTD fragments that contain only entity or element declarations. TEXT is used for SGML content (text and tags). Description Any description you want to supply for the contents of this file. This may include version numbers or any short text that is meaningful to you and unique for the SGML system. Language This is an ISO two-character code that identifies the native language for the file. EN is used for English. <filename>catalog</filename> files If you use the syntax above and try and process this document using an SGML processor, the processor will need to have some way of turning the FPI into the name of the file on your computer that contains the DTD. In order to do this it can use a catalog file. A catalog file (typically called catalog) contains lines that map FPIs to filenames. For example, if the catalog file contained the line; PUBLIC "-//W3C//DTD HTML 4.0//EN" "4.0/strict.dtd" The SGML processor would know to look up the DTD from strict.dtd in the 4.0 subdirectory of whichever directory held the catalog file that contained that line. Look at the contents of /usr/local/share/sgml/html/catalog. This is the catalog file for the HTML DTDs that will have been installed as part of the textproc/docproj port. <envar>SGML_CATALOG_FILES</envar> In order to locate a catalog file, your SGML processor will need to know where to look. Many of them feature command line parameters for specifying the path to one or more catalogs. In addition, you can set SGML_CATALOG_FILES to point to the files. This environment variable should consist of a colon-separated list of catalog files (including their full path). Typically, you will want to include the following files; /usr/local/share/sgml/docbook/catalog /usr/local/share/sgml/html/catalog /usr/local/share/sgml/iso8879/catalog /usr/local/share/sgml/jade/catalog You should already have done this. Alternatives to FPIs Instead of using an FPI to indicate the DTD that the document conforms to (and therefore, which file on the system contains the DTD) you can explicitly specify the name of the file. - The syntax for this is slightly different; + The syntax for this is slightly different: ]]> The SYSTEM keyword indicates that the SGML processor should locate the DTD in a system specific fashion. This typically (but not always) means the DTD will be provided as a filename. Using FPIs is preferred for reasons of portability. You don't want to have to ship a copy of the DTD around with your document, and if you used the SYSTEM identifier then everyone would need to keep their DTDs in the same place. Escaping back to SGML Earlier in this primer I said that SGML is only used when writing a DTD. This is not strictly true. There is certain SGML syntax that you will want to be able to use within your documents. For example, comments can be included in your document, and will be ignored by the parser. Comments are entered using SGML syntax. Other uses for SGML syntax in your document will be shown later too. Obviously, you need some way of indicating to the SGML processor that the following content is not elements within the document, but is SGML that the parser should act upon. These sections are marked by <! ... > in your document. Everything between these delimiters is SGML syntax as you might find within a DTD. As you may just have realised, the DOCTYPE declaration is an example of SGML syntax that you need to include in your document… Comments Comments are an SGML construction, and are normally only valid inside a DTD. However, as shows, it is possible to use SGML syntax within your document. The delimiter for SGML comments is the string “--”. The first occurence of this string opens a comment, and the second closes it. SGML generic comment <!-- test comment --> ]]> Use 2 dashes There is a problem with producing the Postscript and PDF versions of this document. The above example probably shows just one hyphen symbol, - after the <! and before the >. You must use two -, not one. The Postscript and PDF versions have translated the two - in the original to a longer, more professional em-dash, and broken this example in the process. The HTML, plain text, and RTF versions of this document are not affected. ]]> If you have used HTML before you may have been shown different rules for comments. In particular, you may think that the string <!-- opens a comment, and it is only closed by -->. This is not the case. A lot of web browsers have broken HTML parsers, and will accept that as valid. However, the SGML parsers used by the Documentation Project are much stricter, and will reject documents that make that error. Errorneous SGML comments ]]> The SGML parser will treat this as though it were actually; <!THIS IS OUTSIDE THE COMMENT> This is not valid SGML, and may give confusing error messages. ]]> As the example suggests, do not write comments like that. ]]> That is a (slightly) better approach, but it still potentially confusing to people new to SGML. For you to do… Add some comments to example.sgml, and check that the file still validates using &man.nsgmls.1; Add some invalid comments to example.sgml, and see the error messages that &man.nsgmls.1; gives when it encounters an invalid comment. Entities Entities are a mechanism for assigning names to chunks of content. As an SGML parser processes your document, any entities it finds are replaced by the content of the entity. This is a good way to have re-usable, easily changeable chunks of content in your SGML documents. It is also the only way to include one marked up file inside another using SGML. There are two types of entities which can be used in two different situations; general entities and parameter entities. General Entities You can not use general entities in an SGML context (although you define them in one). They can only be used in your document. Contrast this with parameter entities. Each general entity has a name. When you want to reference a general entity (and therefore include whatever text it represents in your document), you write &entity-name;. For example, suppose you had an entity called current.version which expanded to the current version number of your product. You could write; The current version of our product is ¤t.version;.]]> When the version number changes you can simply change the definition of the value of the general entity and reprocess your document. You can also use general entities to enter characters that you could not otherwise include in an SGML document. For example, < and & can not normally appear in an SGML document. When the SGML parser sees the < symbol it assumes that a tag (either a start tag or an end tag) is about to appear, and when it sees the & symbol it assumes the next text will be the name of an entity. Fortunately, you can use the two general entities &lt; and &amp; whenever you need to include one or other of these A general entity can only be defined within an SGML context. Typically, this is done immediately after the DOCTYPE declaration. Defining general entities ]>]]> Notice how the DOCTYPE declaration has been extended by adding a square bracket at the end of the first line. The two entities are then defined over the next two lines, before the square bracket is closed, and then the DOCTYPE declaration is closed. The square brackets are necessary to indicate that we are extending the DTD indicated by the DOCTYPE declaration. Parameter entities Like general entities, parameter entities are used to assign names to reusable chunks of text. However, where as general entities can only be used within your document, parameter entities can only be used within an SGML context. Parameter entities are defined in a similar way to general entities. However, instead of using &entity-name; to refer to them, use %entity-name; Parameter entities use the Percent symbol. . The definition also includes the % between the ENTITY keyword and the name of the entity. Defining parameter entities ]>]]> This may not seem particularly useful. It will be. For you to do… Add a general entity to example.sgml. ]> An example HTML file

This is a paragraph containing some text.

This paragraph contains some more text.

This paragraph might be right-justified.

The current version of this document is: &version;

]]> Validate the document using &man.nsgmls.1; Load example.sgml into your web browser (you may need to copy it to example.html before your browser recognises it as an HTML document). Unless your browser is very advanced, you won't see the entity reference &version; replaced with the version number. Most web browsers have very simplistic parsers which do not handle proper SGML This is a shame. Imagine all the problems and hacks (such as Server Side Includes) that could be avoided if they did. . The solution is to normalise your document using an SGML normaliser. The normaliser reads in valid SGML and outputs equally valid SGML which has been transformed in some way. One of the ways in which the normaliser transforms the SGML is to expand all the entity references in the document, replacing the entities with the text that they represent. You can use &man.sgmlnorm.1; to do this. &prompt.user; sgmlnorm example.sgml > example.html You should find a normalised (i.e., entity references expanded) copy of your document in example.html, ready to load into your web browser. If you look at the output from &man.sgmlnorm.1; you will see that it does not include a DOCTYPE declaration at the start. To include this you need to use the option; &prompt.user; sgmlnorm -d example.sgml > example.html Using entities to include files Entities (both general and parameter) are particularly useful when used to include one file inside another. Using general entities to include files Suppose you have some content for an SGML book organised into files, one file per chapter, called chapter1.sgml, chapter2.sgml, and so forth, with a book.sgml file that will contain these chapters. In order to use the contents of these files as the values for your entities, you declare them with the SYSTEM keyword. This directs the SGML parser to use the contents of the named file as the value of the entity. Using general entities to include files ]> &chapter.1; &chapter.2; &chapter.3; ]]> When using general entities to include other files within a document, the files being included (chapter1.sgml, chapter2.sgml, and so on) must not start with a DOCTYPE declaration. This is a syntax error. Using parameter entities to include files Recall that parameter entities can only be used inside an SGML context. Why then would you want to include a file within an SGML context? You can use this to ensure that you can reuse your general entities. Suppose that you had many chapters in your document, and you reused these chapters in two different books, each book organising the chapters in a different fashion. You could list the entities at the top of each book, but this quickly becomes cumbersome to manage. Instead, place the general entity definitions inside one file, and use a parameter entity to include that file within your document. Using parameter entities to include files First, place your entity definitions in a separate file, called chapters.ent. This file contains the following; ]]> Now create a parameter entity to refer to the contents of the file. Then use the parameter entity to load the file into the document, which will then make all the general entities available for use. Then use the general entities as before; %chapters; ]> &chapter.1; &chapter.2; &chapter.3; ]]> For you to do… Use general entities to include files Create three files, para1.sgml, para2.sgml, and para3.sgml. Put content similar to the following in each file; This is the first paragraph.

]]> Edit example.sgml so that it looks like this; ]> An example HTML file

The current version of this document is: &version;

¶1; ¶2; ¶3; ]]> Produce example.html by normalising example.sgml. &prompt.user; sgmlnorm -d example.sgml > example.html Load example.html in to your web browser, and confirm that the paran.sgml files have been included in example.html. Use parameter entities to include files You must have taken the previous steps first. Edit example.sgml so that it looks like this; %entities; ]> An example HTML file

The current version of this document is: &version;

¶1; ¶2; ¶3; ]]> Create a new file, entities.sgml, with - this content; + this content: ]]> Produce example.html by normalising example.sgml. &prompt.user; sgmlnorm -d example.sgml > example.html Load example.html in to your web browser, and confirm that the paran.sgml files have been included in example.html. Marked sections SGML provides a mechanism to indicate that particular pieces of the document should be processed in a special way. These are termed “marked sections”. Structure of a marked section <![ KEYWORD [ Contents of marked section ]]> As you would expect, being an SGML construct, a marked section - starts <!. + starts with <!. The first square bracket begins to delimit the marked section. KEYWORD describes how this marked section should be processed by the parser. The second square bracket indicates that the content of the marked section starts here. The marked section is finished by closing the two square brackets, and then returning to the document context from the SGML context with > Marked section keywords <literal>CDATA</literal>, <literal>RCDATA</literal> These keywords denote the marked sections content model, and allow you to change it from the default. When an SGML parser is processing a document it keeps track of what is called the “content model”. Briefly, the content model describes what sort of content the parser is expecting to see, and what it will do with it when it finds it. The two content models you will probably find most useful are CDATA and RCDATA. CDATA is for “Character Data”. If the parser is in this content model then it is expecting to see characters, and characters only. In this model the < and & symbols lose their special status, and will be treated as ordinary characters. RCDATA is for “Entity references and character data” If the parser is in this content model then it is expecting to see characters and entities. < loses its special status, but & will still be treated as starting the beginning of a general entity. This is particularly useful if you are including some verbatim text that contains lots of < and & characters. While you could go through the text ensuring that every < is converted to a &lt; and every & is converted to a &amp;, it can be easier to mark the section as only containing CDATA. When the SGML parser encounters this it will ignore the < and & symbols embedded in the content. Using a CDATA marked section <para>Here is an example of how you would include some text that contained many &lt; and &amp; symbols. The sample text is a fragment of HTML. The surrounding text (<para> and <programlisting>) are from DocBook.</para> <programlisting> <![ CDATA [ This is a sample that shows you some of the elements within HTML. Since the angle brackets are used so many times, it's simpler to say the whole example is a CDATA marked section than to use the entity names for the left and right angle brackets throughout.

  • This is a listitem
  • This is a second listitem
  • This is a third listitem

This is the end of the example.

]]> ]]> </programlisting> If you look at the source for this document you will see this technique used throughout. <literal>INCLUDE</literal> and <literal>IGNORE</literal> If the keyword is INCLUDE then the contents of the marked section will be processed. If the keyword is IGNORE then the marked section is ignored and will not be processed. It will not appear in the output. Using <literal>INCLUDE</literal> and <literal>IGNORE</literal> in marked sections <![ INCLUDE [ This text will be processed and included. ]]> <![ IGNORE [ This text will not be processed or included. ]]> By itself, this isn't too useful. If you wanted to remove text from your document you could cut it out, or wrap it in comments. It becomes more useful when you realise you can use parameter entities to control this. Remember that parameter entities can only be used in SGML contexts, and the keyword of a marked section is an SGML context. For example, suppose that you produced a hard-copy version of some documentation and an electronic version. In the electronic version you wanted to include some extra content that wasn't to appear in the hard-copy. Create a parameter entity, and set it's value to INCLUDE. Write your document, using marked sections to delimit content that should only appear in the electronic version. In these marked sections use the parameter entity in place of the keyword. When you want to produce the hard-copy version of the document, change the parameter entity's value to IGNORE and reprocess the document. Using a parameter entity to control a marked section <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [ <!ENTITY % electronic.copy "INCLUDE"> ]]> ... <![ %electronic.copy [ This content should only appear in the electronic version of the document. ]]> When producing the hard-copy version, change the entity's definition to; <!ENTITY % electronic.copy "IGNORE"> On reprocessing the document, the marked sections that use %electronic.copy as their keyword will be ignored. For you to do… Create a new file, section.sgml, that contains the following; <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [ <!ENTITY % text.output "INCLUDE"> ]> <html> <head> <title>An example using marked sections</title> </head> <body> <p>This paragraph <![ CDATA [contains many < characters (< < < < <) so it is easier to wrap it in a CDATA marked section ]]></p> <![ IGNORE [ <p>This paragraph will definitely not be included in the output.</p> ]]> <![ [ <p>This paragraph might appear in the output, or it might not.</p> <p>Its appearance is controlled by the parameter entity.</p> ]]> </body> </html> Normalise this file using &man.sgmlnorm.1; and examine the output. Notice which paragraphs have appeared, which have disappeared, and what has happened to the content of the CDATA marked section. Change the definition of the text.output entity from INCLUDE to IGNORE. Re-normalise the file, and examine the output to see what has changed. Conclusion That is the conclusion of this SGML primer. For reasons of space and complexity several things have not been covered in depth (or at all). However, the previous sections cover enough SGML for you to be able to follow the organisation of the FDP documentation. 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 6b42003e89..f564b25e4d 100644 --- a/en_US.ISO8859-1/books/fdp-primer/structure/chapter.sgml +++ b/en_US.ISO8859-1/books/fdp-primer/structure/chapter.sgml @@ -1,287 +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; + documentation in to the tree and: - be easy to automate converting the document to other formats + make it 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 + documentation is split into 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. + (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 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 + 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. Not every lang.encoding directory will contain all of these directories. It depends - on much translation has been accomplished by that translation + 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. 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. + 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 as had on just + every time you want to see the effect a change has had on just one chapter. diff --git a/en_US.ISO8859-1/books/fdp-primer/tools/chapter.sgml b/en_US.ISO8859-1/books/fdp-primer/tools/chapter.sgml index b47420fdb0..5ec9dcb95e 100644 --- a/en_US.ISO8859-1/books/fdp-primer/tools/chapter.sgml +++ b/en_US.ISO8859-1/books/fdp-primer/tools/chapter.sgml @@ -1,284 +1,284 @@ Tools The FDP uses a number of different software tools to help manage the FreeBSD documentation, convert it to different output formats, and so on. You will need to use these tools yourself if you are to work with the FreeBSD documentation. All these tools are available as FreeBSD Ports and Packages, greatly simplifying the work you have to do to install them. You will need to install these tools before you work through any of the examples in later chapters. The actual usage of these - tools is covered in these later chapters. + tools is covered in later chapters. Use <filename>textproc/docproj</filename> if possible You can save yourself a lot of time if you install the textproc/docproj port. This is a meta-port which does not contain any software itself. Instead, it depends on various other ports being installed correctly. Installing this port should automatically download and install all of the packages listed in this - chapter that you need that are missing from your system. + chapter that you need. One of the packages that you might need is the JadeTeX macro set. In turn, this macro set requires that TeX is installed. TeX is a large package, and you only need it if you want to produce Postscript or PDF output. To save yourself time and space you must specify whether or not you want JadeTeX (and therefore TeX) installed when you install this port. Either do; &prompt.root; make JADETEX=yes install or &prompt.root; make JADETEX=no install as necessary. Mandatory tools Software These programs are required before you can usefully work with the FreeBSD documentation. They are all included in textproc/docproj. SP (textproc/sp) A suite of applications, including a validating SGML parser, and an SGML normaliser. Jade (textproc/jade) A DSSSL implementation. Used for converting marked up documents to other formats, including HTML and TeX. Tidy (www/tidy) An HTML 'pretty printer', used to reformat some of the automatically generated HTML so that it is easier to follow. Lynx (www/lynx-current) A text-mode WWW browser, &man.lynx.1; can also convert HTML files to plain text. DTDs and Entities These are the DTDs and entity sets used by the FDP. They need to be installed before you can work with any of the documentation. HTML DTD (textproc/html) HTML is the markup language of choice for the World Wide Web, and is used throughout the FreeBSD web site. LinuxDoc DTD (textproc/linuxdoc) Some FreeBSD documentation is marked up in LinuxDoc. The FDP is actively migrating from LinuxDoc to DocBook. DocBook DTD (textproc/docbook) DocBook is designed for marking up technical documentation, and the FDP is migrating from LinuxDoc to DocBook. At the time - of writing, this document, and the FreeBSD Handbook are marked + of writing, this document and the FreeBSD Handbook are marked up in DocBook. ISO 8879 entities (textproc/iso8879) 19 of the ISO 8879:1986 character entity sets used by many DTDs. Includes named mathematical symbols, additional characters in the 'latin' character set (accents, diacriticals, and so on), and greek symbols. Stylesheets The stylesheets are used when converting and formatting the documentation for display on screen, printing, and so on. Modular DocBook Stylesheets (textproc/dsssl-docbook-modular) The Modular DocBook Stylesheets are used when converting documentation marked up in DocBook to other formats, such as - HTML, or RTF. + HTML or RTF. Optional tools You do not need to have any of the following installed. However, you may find it easier to work with the documentation if you do, and they may give you more flexibility in the output formats that can be generated. Software JadeTeX and teTeX (print/jadetex and print/teTeX) Jade and teTeX are used to convert DocBook documents to DVI, Postscript, and PDF formats. The JadeTeX macros are needed in order to do this. If you do not intend to convert your documentation to one of these formats (i.e., HTML, plain text, and RTF are sufficient) then you do not need to install JadeTeX and teTeX. This can be a significant space and time saver, as teTeX is over 30MB in size. If you decide to install JadeTeX and teTeX then you will need to configure teTeX after JadeTeX has been installed. print/jadetex/pkg/MESSAGE contains detailed instructions explaining what you need to do. Emacs or xemacs (editors/emacs or editors/xemacs) Both these editors include a special mode for editing documents marked up according to an SGML DTD. This mode includes commands to reduce the amount of typing you need, and help reduce the possibility of errors. - You do not need to use them, any text editor can be used to + You do not need to use them; any text editor can be used to edit marked up documents. You may find they make you more efficient. If anyone has recommendations for other software that is useful when manipulating SGML documents, please let Nik Clayton (nik@FreeBSD.org) know, so they can be added to this list. diff --git a/en_US.ISO8859-1/books/fdp-primer/translations/chapter.sgml b/en_US.ISO8859-1/books/fdp-primer/translations/chapter.sgml index abc80c3879..2ceb9b0153 100644 --- a/en_US.ISO8859-1/books/fdp-primer/translations/chapter.sgml +++ b/en_US.ISO8859-1/books/fdp-primer/translations/chapter.sgml @@ -1,474 +1,474 @@ Translations This is the FAQ for people translating the FreeBSD documentation (FAQ, Handbook, tutorials, man pages, and others) to different languages. It is very heavily based on the translation FAQ from the FreeBSD German Documentation Project, originally written by Frank Gründer elwood@mc5sys.in-berlin.de and translated back to English by Bernd Warken bwarken@mayn.de. The FAQ maintainer is Nik Clayton nik@FreeBSD.org. Why a FAQ? More and more people are approaching the freebsd-doc mailing list and volunteering to translate FreeBSD documentation to other languages. This FAQ aims to answer their questions so they can start translating documentation as quickly as possible. What do i18n and l10n mean? i18n means internationalisation and l10n means localisation. They are just a convenient shorthand. i18n can be read as “i” followed by 18 letters, followed by “n”. Similarly, l10n is “l” followed by 10 letters, followed by “n”. Is there a mailing list for translators? Yes, freebsd-translate@ngo.org.uk. Subscribe by sending a message to freebsd-translate-request@ngo.org.uk with the word subscribe in the body of the message. You will receive a reply asking you to confirm your subscription (in exactly the same manner as the the FreeBSD lists at FreeBSD.org). The primary language of the mailing list is English. However, posts in other languages will be accepted. The mailing list is not moderated, but you need to be a member of the list before you can post to it. The mailing list is archived, but they are not currently searchable. Sending the message help to majordomo@ngo.org.uk will send back instructions on how to access the archive. It is expected that the mailing list will transfer to FreeBSD.org and therefore become official in the near future. Are more translators needed? Yes. The more people work on translation the faster it gets done, and the faster changes to the English documentation are mirrored in the translated documents. You do not have to be a professional translator to be able to help. What languages do I need to know? Ideally, you will have a good knowledge of written English, and obviously you will need to be fluent in the language you are translating to. English is not strictly necessary. For example, you could do a Hungarian translation of the FAQ from the Spanish translation. What software do I need to know? It is strongly recommended that you maintain a local copy of the FreeBSD CVS repository (at least the documentation part) either using CTM or CVSup. The "Staying current with FreeBSD" chapter in the Handbook explains how to use these applications. You should be comfortable using CVS. This will allow you to see what has changed between different versions of the files that make up the documentation. [XXX To Do -- write a tutorial that shows how to use CVSup to get just the documentation, check it out, and see what's changed between two arbitrary revisions] How do I find out who else might be translating to the same language? The Documentation Project translations page lists the translation efforts - that are currently known about. If someone else is already working + that are currently known about. If others are already working on translating documentation to your language, please don't duplicate their efforts. Instead, contact them to see how you can help. If no one is listed on that page as translating for your - language then send a message to + language, then send a message to freebsd-doc@FreeBSD.org in case someone else is thinking of doing a translation, but hasn't announced it yet. - No one else is translating to my language. What do I do? + No one else is translating to my language. What do I do? Congratulations, you have just started the “FreeBSD your-language-here Documentation Translation Project”. Welcome aboard. First, decide whether or not you've got the time to spare. Since you are the only person working on your language at the moment it is going to be your responsibility to publicise your work and coordinate any volunteers that might want to help you. Write an e-mail to the Documentation Project mailing list, announcing that you are going to translate the documentation, so the Documentation Project translations page can be maintained. You should subscribe to the freebsd-translate@ngo.org.uk mailing list (as described earlier). If there is already someone in your country providing FreeBSD - mirroring services you should contact them and ask if they can - provide some webspace for your project, and possibly an e-mail + mirroring services you should contact them and ask if you can + have some webspace for your project, and possibly an e-mail address or mailing list services. Then pick a document and start translating. It is best to start with something fairly small—either the FAQ, or one of the tutorials. I've translated some documentation, where do I send it? That depends. If you are already working with a translation team (such as the Japanese team, or the German team) then they will have their own procedures for handling submitted documentation, and these will be outlined on their web pages. If you are the only person working on a particular language (or you are responsible for a translation project and want to submit your changes back to the FreeBSD project) then you should send your translation to the FreeBSD project (see the next question). I'm the only person working on translating to this language, how do I submit my translation? or We're a translation team, and want to submit documentation that our members have translated for us? First, make sure your translation is organised properly. This means that it should drop in to the existing documentation tree and build straight away. Currently, the FreeBSD documentation is stored in a top level directory called doc/. Directories below this are named according to the language code they are written in, as defined in ISO639 (/usr/share/misc/iso639 on a version of FreeBSD newer than 20th January 1999). If your language can be encoded in different ways (for example, Chinese) then there should be directories below this, one for each encoding format you have provided. Finally, you should have directories for each document. For example, a hypothetical Swedish translation might look like doc/ sv/ Makefile FAQ/ Makefile *.sgml sv is the ISO639 code for Swedish. Note the two Makefiles, which will be used to build the documentation. There is no separate language code for Swedish, so there is no intermittent directory between the "sv" and "FAQ" directories This directory structure is going to change radically quite soon. Please see the on-going discussions on the freebsd-doc@FreeBSD.org mailing list for more information. . Use &man.tar.1; and &man.gzip.1; to compress up your documentation, and send it to the project. &prompt.user; cd doc &prompt.user; tar cf swedish-docs.tar sv &prompt.user; gzip -9 swedish-docs.tar Put swedish-docs.tar.gz somewhere. If you do not have access to your own webspace (perhaps your ISP does not let you have any) then you can e-mail Nik Clayton nik@FreeBSD.org, and arrange to e-mail the files when it is convenient. Either way, you should use &man.send-pr.1; to submit a report indicating that you have submitted the documentation. It would be very helpful if you could get other people to look over your translation and double check it first, since it is unlikely that the person committing it will be fluent in the language. Someone (probably the Documentation Project Manager, currently Nik Clayton nik@FreeBSD.org) will then take your translation and confirm that it builds. In particular, the following things will be looked at: - Do all your files use RCS strings (such as "ID"). + Do all your files use RCS strings (such as "ID")? Does make all in the - sv directory work correctly. + sv directory work correctly? - Does make install work correctly. + Does make install work correctly? If there are any problems then whoever is looking at the submission will get back to you to try and work them out. - If there are no problems then your translation will be committed + If there are no problems your translation will be committed as soon as possible. Can I include language or country specific text in my translation? We would prefer that you did not. For example, suppose that you are translating the Handbook to Korean, and want to include a section about retailers in Korea in your Handbook. There's no real reason why that information should not be in the English (or German, or Spanish, or Japanese, or …) versions as well. It is feasible that an English speaker in Korea might try and pick up a copy of FreeBSD whilst over there. It also helps increase FreeBSD's perceived presence around the globe, which is not a bad thing. If you have country specific information, please submit it as a change to the English Handbook (using &man.send-pr.1;) and then translate the change back to your language in the translated Handbook. Thanks. How should language specific characters be included? Non-ASCII characters in the documentation should be included using SGML entities. Briefly, these look like an ampersand (&), the name of the entity, and a semi-colon (;). The entity names are defined in ISO8879, which is in the ports tree as textproc/iso8879. A few examples include &eacute; é Small “e” with an acute accent &Eacute; É Large “E” with an acute accent &uuml; ü Small “u” with an umlaut After you have installed the iso8879 port, the files in /usr/local/share/sgml/iso8879 contain the complete list. Addressing the reader In the English documents, the reader is addressed as “you”, there is no formal/informal distinction as there is in some languages. If you are translating to a language which does distinguish, use whichever form is typically used in other technical documentation in your language. If in doubt, use a mildly polite form. Do I need to include any additional information in my translations? Yes. The header of the English version of each document will look something like this; ]]> The exact boilerplate may change, but it will always include an Id line and the phrase The FreeBSD Documentation Project. Your translated documents should include their own Id line, and change the FreeBSD Documentation Project line to The FreeBSD language Documentation Project. In addition, you should add a third line which indicates which revision of the English text this is based on. So, the Spanish version of this file might start ]]> diff --git a/en_US.ISO_8859-1/books/fdp-primer/overview/chapter.sgml b/en_US.ISO_8859-1/books/fdp-primer/overview/chapter.sgml index 9ea5225913..ff994d5ac3 100644 --- a/en_US.ISO_8859-1/books/fdp-primer/overview/chapter.sgml +++ b/en_US.ISO_8859-1/books/fdp-primer/overview/chapter.sgml @@ -1,179 +1,179 @@ Overview Welcome to the FreeBSD Documentation Project. Good quality documentation is very important to the success of FreeBSD, and the FreeBSD Documentation Project (FDP) is how a lot of that documentation is produced. Your contributions are very valuable. This document's main purpose is to clearly explain how the FDP is organised, how to write and submit documentation to the FDP, and how to effectively use the tools available to you when writing documentation. Every one is welcome to join the FDP. There is no minimum - membership requirements, no quota of documentation you need to + membership requirement, no quota of documentation you need to produce per month. All you need to do is subscribe to the freebsd-doc@FreeBSD.org mailing list. After you have finished reading this document you should: Know which documentation is maintained by the FDP. Be able to read and understand the SGML source code for the documentation maintained by the FDP. Be able to make changes to the documentation. Be able to submit your changes back for review and eventual inclusion in the FreeBSD documentation. The FreeBSD Documentation Set The FDP is responsible for four categories of FreeBSD documentation. Manual pages The English language system manual pages are not written by the FDP, as they are part of the base system. However, the FDP can (and has) re-worded parts of existing manual pages to make them clearer, or to correct inaccuracies. The translation teams are responsible for translating the system manual pages in to different languages. These translations are kept within the FDP. FAQ The FAQ aims to address (in short question and answer format) questions that are asked, or should be asked, on the various mailing lists and newsgroups devoted to FreeBSD. The format does not permit long and comprehensive answers. Handbook The Handbook aims to be the comprehensive on-line resource and reference for FreeBSD users. Web site This is the main FreeBSD presence on the World Wide Web, visible at http://www.FreeBSD.org/ and many mirrors around the world. The web site is many people's first exposure to FreeBSD. These four groups of documentation are all available in the - FreeBSD CVS tree. This means that the logs and changes to these + FreeBSD CVS tree. This means that the logs of changes to these files are visible to anyone, and anyone can use a program such as CVSup or - CTM to keep their own local copies of + CTM to keep local copies of this documentation. In addition, many people have written tutorials or other web sites relating to FreeBSD. Some of these are stored in the CVS repository as well (where the author has agreed to this). In - other cases the author has decided to keep their documentation + other cases the author has decided to keep his documentation separate from the main FreeBSD repository. The FDP endeavours to provide links to as much of this documentation as possible. Before you start This document assumes that you already know: How to maintain an up-to-date local copy of the FreeBSD - documentation. Either by maintaining a local copy of the + documentation by maintaining a local copy of the FreeBSD CVS repository (using CVS and either CVSup or CTM) or by using CVSup to download just a checked-out copy. How to download and install new software using either the FreeBSD Ports system or &man.pkg.add.1;. diff --git a/en_US.ISO_8859-1/books/fdp-primer/psgml-mode/chapter.sgml b/en_US.ISO_8859-1/books/fdp-primer/psgml-mode/chapter.sgml index 79415582fa..8abcde6496 100644 --- a/en_US.ISO_8859-1/books/fdp-primer/psgml-mode/chapter.sgml +++ b/en_US.ISO_8859-1/books/fdp-primer/psgml-mode/chapter.sgml @@ -1,150 +1,150 @@ Using <literal>sgml-mode</literal> with <application>Emacs</application> Recent versions of Emacs or Xemacs (available from the ports collection) contain a very useful package called PSGML. Automatically - invoked when a file with .sgml extension is loaded, + invoked when a file with the .sgml extension is loaded, or by typing M-x sgml-mode, it is a major mode for dealing with SGML files, elements and attributes. An understanding of some of the commands provided by this mode can make working with SGML documents such as the Handbook much easier. C-c C-e Runs sgml-insert-element. You will be prompted for the name of the element to insert at the current point. You can use the TAB key to complete the element. Elements that are not valid at the current point will be disallowed. The start and end tags for the element will be inserted. If the element contains other, mandatory, elements then these will be inserted as well. C-c = Runs sgml-change-element-name. Place the point within an element and run this command. You will be prompted for the name of the element to change to. Both the start and end tags of the current element will be changed to the new element. C-c C-r Runs sgml-tag-region. Select some text (move to start of text, C-space, move to end of text, C-space) and then run this command. You will be prompted for the element to use. This element will then be inserted immediately before and after your marked region. C-c - Runs sgml-untag-element. Place the point within the start or end tag of an element you want to remove, and run this command. The element's start and end tags will be removed. C-c C-q Runs sgml-fill-element. Will recursively fill (i.e., reformat) content from the current element in. The filling will affect content in which whitespace is significant, such as within programlisting elements, so run this command with care. C-c C-a Runs sgml-edit-attributes. Opens a second buffer containing a list of all the attributes for the closest enclosing element, and their current values. Use TAB to navigate between attributes, C-k to remove an existing value and replace it with a new one, C-c to close this buffer and return to the main document. C-c C-v Runs sgml-validate. Prompts you to save the current document (if necessary) and then runs an SGML validator. The output from the validator is captured into a new buffer, and you can then navigate from one troublespot to the next, fixing markup errors as you go. Doubtless there are other useful functions of this mode, but those are the ones I use most often. diff --git a/en_US.ISO_8859-1/books/fdp-primer/see-also/chapter.sgml b/en_US.ISO_8859-1/books/fdp-primer/see-also/chapter.sgml index 9698df7b0b..9f8ac6dd06 100644 --- a/en_US.ISO_8859-1/books/fdp-primer/see-also/chapter.sgml +++ b/en_US.ISO_8859-1/books/fdp-primer/see-also/chapter.sgml @@ -1,121 +1,121 @@ See Also This document is deliberately not an exhaustive discussion of SGML, the DTDs listed, and the FreeBSD Documentation Project. For more information about these, you are encouraged to see the following web sites. The FreeBSD Documentation Project The FreeBSD Documentation Project web pages The FreeBSD Handbook SGML The SGML/XML web page, a comprehensive SGML resource Gentle introduction to SGML HTML The World Wide Web - organisation + Consortium The HTML 4.0 specification DocBook - The Davenport - Group, maintainers of the DocBook DTD + The DocBook + Technical Committee, maintainers of the DocBook DTD The Linux Documentation Project - The Linux Documentation + The Linux Documentation Project web pages diff --git a/en_US.ISO_8859-1/books/fdp-primer/sgml-markup/chapter.sgml b/en_US.ISO_8859-1/books/fdp-primer/sgml-markup/chapter.sgml index 0ac3f02504..ef88ad5fd1 100644 --- a/en_US.ISO_8859-1/books/fdp-primer/sgml-markup/chapter.sgml +++ b/en_US.ISO_8859-1/books/fdp-primer/sgml-markup/chapter.sgml @@ -1,2259 +1,2259 @@ SGML Markup This chapter describes the three markup languages you will encounter when you contribute to the FreeBSD documentation project. Each section describes the markup language, and details the markup that you are likely to want to use, or that is already in use. These markup languages contain a large number of elements, and it can be confusing sometimes to know which element to use for a particular situation. This section goes through the elements you are most likely to need, and gives examples of how you would use them. This is not an exhaustive list of elements, since that would just reiterate the documentation for each language. The aim of this section is to list those elements more likely to be useful to you. If you have a question about how best to markup a particular piece of content, please post it to the FreeBSD Documentation Project mailing list freebsd-doc@FreeBSD.org. Inline vs. block In the remainder of this document, when describing elements, inline means that the element can occur within a block element, and does not cause a line break. A block element, by comparison, will cause a line break (and other processing) when it is encountered. HTML HTML, the HyperText Markup Language, is the markup language of choice on the World Wide Web. More information can be found at <URL:http://www.w3.org/>. HTML is used to markup pages on the FreeBSD web site. It should not (generally) be used to mark up other documention, since DocBook offers a far richer set of elements to choose from. Consequently, you will normally only encounter HTML pages if you are writing for the web site. HTML has gone through a number of versions, 1, 2, 3.0, 3.2, and the latest, 4.0 (available in both strict and loose variants). The HTML DTDs are available from the ports collection in the textproc/html port. They are automatically installed as part of the textproc/docproj port. Formal Public Identifier (FPI) There are a number of HTML FPIs, depending upon the version (also known as the level) of HTML that you want to declare your document to be compliant with. The majority of HTML documents on the FreeBSD web site comply with the loose version of HTML 4.0. PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" Sectional elements An HTML document is normally split in to two sections. The first section, called the head, contains meta-information about the document, such as its title, the name of the author, the parent document, and so on. The second section, the body, contains the content that will be displayed to the user. These sections are indicated with head and body elements respectively. These elements are contained within the top-level html element. Normal HTML document structure <html> <head> <title>The document's title</title> </head> <body> … </body> </html> Block elements Headings HTML allows you to denote headings in your document, at up to six different levels. The largest and most prominent heading is h1, then h2, continuing down to h6. The element's content is the text of the heading. <sgmltag>h1</sgmltag>, <sgmltag>h2</sgmltag>, etc. Use: First section

This is the heading for the first section

This is the heading for the first sub-section

This is the heading for the second section

]]> Generally, an HTML page should have one first level heading (h1). This can contain many second level headings (h2), which can in turn contain many third level headings. Each hn element should have the same element, but one further up the hierarchy, preceeding it. Leaving gaps in the numbering is to be avoided. Bad ordering of <sgmltag>h<replaceable>n</replaceable></sgmltag> elements Use: First section

Sub-section

]]> Paragraphs HTML supports a single paragraph element, p. <sgmltag>p</sgmltag> Use: This is a paragraph. It can contain just about any other element.

]]> Block quotations A block quotation is an extended quotation from another document that should not appear within the current paragraph. <sgmltag>blockquote</sgmltag> Use: - A small excerpt from the US Constitution;

+ A small excerpt from the US Constitution:

We the People of the United States, in Order to form a more perfect Union, establish Justice, insure domestic Tranquility, provide for the common defence, promote the general Welfare, and secure the Blessings of Liberty to ourselves and our Posterity, do ordain and establish this Constitution for the United States of America.
]]> Lists You can present the user with three types of lists, ordered, unordered, and definition. Typically, each entry in an ordered list will be numbered, while - each entry in an unordered list will be proceeded by a bullet point. + each entry in an unordered list will be preceded by a bullet point. Definition lists are composed of two sections for each entry. The first section is the term being defined, and the second section is the definition of the term. Ordered lists are indicated by the ol element, unordered lists by the ul element, and definition lists by the dl element. Ordered and unordered lists contain listitems, indicated by the li element. A listitem can contain textual content, or it may be further wrapped in one or more p elements. Definition lists contain definition terms (dt) and definition descriptions (dd). A definition term can only contain inline elements. A definition description can contain other block elements. <sgmltag>ul</sgmltag> and <sgmltag>ol</sgmltag> Use: An unordered list. Listitems will probably be preceeded by bullets.

  • First item
  • Second item
  • Third item

An ordered list, with list items consisting of multiple paragraphs. Each item (note: not each paragraph) will be numbered.

  1. This is the first item. It only has one paragraph.

  2. This is the first paragraph of the second item.

    This is the second paragraph of the second item.

  3. This is the first and only paragraph of the third item.

]]> Definition lists with <sgmltag>dl</sgmltag> Use:
Term 1

Paragraph 1 of definition 1.

Paragraph 2 of definition 1.

Term 2

Paragraph 1 of definition 2.

Term 3
Paragraph 1 of definition 3. Note that the <p> element is not required in the single paragraph case.
]]> Pre-formatted text You can indicate that text should be shown to the user exactly as it is in the file. Typically, this means that the text is shown in a fixed font, multiple spaces are not merged in to one, and line breaks in the text are significant. In order to do this, wrap the content in the pre element. <sgmltag>pre</sgmltag> You could use pre to mark up an e-mail message; From: nik@FreeBSD.org To: freebsd-doc@FreeBSD.org Subject: New documentation available There's a new copy of my primer for contributers to the FreeBSD Documentation Project available at Comments appreciated. N]]> Tables Most text-mode browsers (such as Lynx) do not render tables particularly effectively. If you are relying on the tabular display of your content, you should consider using alternative markup to prevent confusion. Mark up tabular information using the table element. A table consists of one or more table rows (tr), each containing one or more cells of table data (td). Each cell can contain other block elements, such as paragraphs or lists. It can also contain another table (this nesting can repeat indefinitely). If the cell only contains one paragraph then you do not need to include the p element. Simple use of <sgmltag>table</sgmltag> Use: This is a simple 2x2 table.

Top left cell Top right cell
Bottom left cell Bottom right cell
]]> A cell can span multiple rows and columns. To indicate this, add the rowspan and/or colspan attributes, with values indicating the number of rows of columns that should be spanned. Using <literal>rowspan</literal> Use: One tall thin cell on the left, two short cells next to it on the right.

Long and thin
Top cell Bottom cell
]]> Using <literal>colspan</literal> Use: One long cell on top, two short cells below it.

Top cell
Bottom left cell Bottom right cell
]]> Using <literal>rowspan</literal> and <literal>colspan</literal> together Use: On a 3x3 grid, the top left block is a 2x2 set of cells merged in to one. The other cells are normal.

Top left large cell Top right cell
Middle right cell
Bottom left cell Bottom middle cell Bottom right cell
]]> In-line elements Emphasising information You have two levels of emphasis available in HTML, em and strong. em is for a normal level of emphasis and strong indicates stronger emphasis. Typically, em is rendered in italic and strong is rendered in bold. This is not always - the case however, and you should not rely on it. + the case, however, and you should not rely on it. <sgmltag>em</sgmltag> and <sgmltag>strong</sgmltag> Use: This has been emphasised, while this has been strongly emphasised.

]]> Bold and italics Because HTML includes presentational markup, you can also indicate that particular content should be rendered in bold or italic. The elements are b and i respectively. <sgmltag>b</sgmltag> and <sgmltag>i</sgmltag> This is in bold, while this is in italics.

]]> Indicating fixed pitch text If you have content that should be rendered in a fixed pitch (typewriter) typeface, use tt (for “teletype”). <sgmltag>tt</sgmltag> Use: This document was originally written by Nik Clayton, who can be reached by e-mail as nik@FreeBSD.org.

]]> Content size You can indicate that content should be shown in a larger or smaller font. There are three ways of doing this. Use big and small around the content you wish to change size. These tags can be nested, so <big><big>This is much bigger</big></big> is possible. Use font with the size attribute set to +1 or -1 respectively. This has the same effect as using big or small. However, the use of this approach is deprecated. Use font with the size attribute set to a number between 1 and 7. The default font size is 3. This approach is deprecated. <sgmltag>big</sgmltag>, <sgmltag>small</sgmltag>, and <sgmltag>font</sgmltag> The following fragments all do the same thing. This text is slightly smaller. But this text is slightly bigger.

This text is slightly smaller. But this text is slightly bigger

This text is slightly smaller. But this text is slightly bigger.

]]> Links Links are also in-line elements. Linking to other documents on the WWW In order to include a link to another document on the WWW you must know the URL of the document you want to link to. The link is indicated with a, and the href attribute contains the URL of the target document. The content of the element becomes the link, and is normally indicated to the user in some way (underlining, change of colour, different mouse cursor when over the link, and so on). Using <literal><a href="..."></literal> Use: More information is available at the FreeBSD web site.

]]> These links will take the user to the top of the chosen document. Linking to other parts of documents Linking to a point within another document (or within the same document) requires that the document author include anchors that you can link to. Anchors are indicated with a and the name attribute instead of href. Using <literal><a name="..."></literal> Use: This paragraph can be referenced in other links with the name para1.

]]> To link to a named part of a document, write a normal link to that document, but include the name of the anchor after a # symbol. Linking to a named part of another document Assume that the para1 example resides in a document called foo.html. More information can be found in the first paragraph of foo.html.

]]> If you are linking to a named anchor within the same document then you can omit the document's URL, and just include the name of the anchor (with the preceeding #). Linking to a named part of another document Assume that the para1 example resides in this document More information can be found in the first paragraph of this document.

]]> DocBook DocBook was designed by the Davenport Group to be a DTD for writing technical documentation. As such, and unlike LinuxDoc - and HTML, DocBook is very heavily orientated towards markup that + and HTML, DocBook is very heavily oriented towards markup that describes what something is, rather than describing how it should be presented. <literal>formal</literal> vs. <literal>informal</literal> Some elements may exist in two forms, formal and informal. Typically, the formal version of the element will consist of a title followed by the information version of the element. The informal version will not have a title. The DocBook DTD is available from the ports collection in the textproc/docbook port. It is automatically installed as part of the textproc/docproj port. FreeBSD extensions The FreeBSD Documentation Project has extended the DocBook DTD by adding some new elements. These elements serve to make some of the markup more precise. Where a FreeBSD specific element is listed below it is clearly marked. Throughout the rest of this document, the term “DocBook” is used to mean the FreeBSD extended DocBook DTD. There is nothing about these extensions that is FreeBSD specific, it was just felt that they were useful enhancements for this particular project. Should anyone from any of the other *nix camps (NetBSD, OpenBSD, Linux, …) be interested in collaborating on a standard DocBook extension set, please get in touch with Nik Clayton nik@FreeBSD.org. The FreeBSD extensions are not (currently) in the ports collection. It is a part of the Documentation Project source repository, and can be found in doc/share/sgml/freebsd.dtd. Formal Public Identifier (FPI) In compliance with the DocBook guidelines for writing FPIs for DocBook customisations, the FPI for the FreeBSD extended DocBook DTD is; PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN" Document structure DocBook allows you to structure your documentation in several ways. In the FreeBSD Documentation Project we are using two primary - types of DocBook document, the book, and the article. + types of DocBook document: the book and the article. A book is organised into chapters. This is a mandatory requirement. There may be parts between the book and the chapter to provide another layer of organisation. The Handbook is arranged in this way. A chapter may (or may not) contain one or more sections. These are indicated with the sect1 element. If a section contains another section then use the sect2 element, and so on, up to sect5. Chapters and sections contain the remainder of the content. An article is simpler than a book, and does not use chapters. Instead, the content of an article is organised into one or more sections, using the same sect1 (and sect2 and so on) elements that are used in books. Obviously, you should consider the nature of the documentation you are writing in order to decide whether it is best marked up as a book or an article. Articles are well suited to information that does not - need to be broken down in to several chapters, and that is, relatively + need to be broken down into several chapters, and that is, relatively speaking, quite short, at up to 20-25 pages of content. Books are - best suited to information that can be broken up in to several + best suited to information that can be broken up into several chapters, possibly with appendices and similar content as well. The FreeBSD tutorials are all marked up as articles, while this document, the FreeBSD FAQ, and the FreeBSD Handbook are all marked up as books. Starting a book The content of the book is contained within the book element. As well as containing structural markup, this element can contain elements that include additional information about the book. This is either meta-information, used for reference purposes, or additional content used to produce a title page. This additional information should be contained within bookinfo. Boilerplate <sgmltag>book</sgmltag> with <sgmltag>bookinfo</sgmltag> <book> <bookinfo> <title>Your title here</title> <author> <firstname>Your first name</firstname> <surname>Your surname</surname> <affiliation> <address><email>Your e-mail address</email></address> </affiliation> </author> <copyright> <year>1998</year> <holder role="mailto:your e-mail address">Your name</holder> </copyright> <pubdate role="rcs">$Date$</pubdate> <releaseinfo>$Id$</releaseinfo> <abstract> <para>Include an abstract of the book's contents here.</para> </abstract> </bookinfo> … </book> Starting an article The content of the article is contained within the article element. As well as containing structural markup, this element can contain elements that include additional information about the article. This is either meta-information, used for reference purposes, or additional content used to produce a title page. This additional information should be contained within artheader. Boilerplate <sgmltag>article</sgmltag> with <sgmltag>artheader</sgmltag> <article> <artheader> <title>Your title here</title> <author> <firstname>Your first name</firstname> <surname>Your surname</surname> <affiliation> <address><email>Your e-mail address</email></address> </affiliation> </author> <copyright> <year>1998</year> <holder role="mailto:your e-mail address">Your name</holder> </copyright> <pubdate role="rcs">$Date$</pubdate> <releaseinfo>$Id$</releaseinfo> <abstract> <para>Include an abstract of the article's contents here.</para> </abstract> </artheader> … </article> Indicating chapters Use chapter to mark up your chapters. Each chapter has a mandatory title. Articles do not contain chapters, they are reserved for books. A simple chapter The chapter's title ... ]]> - A chapter can not be empty, it must contain elements in addition + A chapter cannot be empty; it must contain elements in addition to title. If you need to include an empty chapter then just use an empty paragraph. Empty chapters This is an empty chapter ]]> Sections below chapters In books, chapters may (but do not need to) be broken up into sections, subsections, and so on. In articles, sections are the main structural element, and each article must contain at least one section. Use the sectn element. The n indicates the section number, which identifies the section level. The first sectn is sect1. You can have one or more of these in a chapter. They can contain one or more sect2 elements, and so on, down to sect5. Sections in chapters A sample chapter Some text in the chapter. First section (1.1) … Second section (1.2) First sub-section (1.2.1) First sub-sub-section (1.2.1.1) … Second sub-section (1.2.2) … ]]> This example includes section numbers in the section titles. You should not do this in your documents. Adding the section numbers is carried out the by the stylesheets (of which more later), and you do not need to manage them yourself. Subdividing using <sgmltag>part</sgmltag>s You can introduce another layer of organisation between book and chapter with one or - more parts. This can not be done in an + more parts. This cannot be done in an article. Introduction Overview ... What is FreeBSD? ... History ... ]]> Block elements Paragraphs - DocBook supports three types of paragraphs; + DocBook supports three types of paragraphs: formalpara, para, and simpara. Most of the time you will only need to use para. formalpara includes a title element, and simpara disallows some elements from within para. Stick with para. <sgmltag>para</sgmltag> Use: This is a paragraph. It can contain just about any other element. ]]> Appearance: This is a paragraph. It can contain just about any other element. Block quotations A block quotation is an extended quotation from another document that should not appear within the current paragraph. You will probably only need it infrequently. Blockquotes can optionally contain a title and an attribution (or they can be left untitled and unattributed). <sgmltag>blockquote</sgmltag> Use: A small excerpt from the US Constitution;
Preamble to the Constitution of the United States Copied from a web site somewhere We the People of the United States, in Order to form a more perfect Union, establish Justice, insure domestic Tranquility, provide for the common defence, promote the general Welfare, and secure the Blessings of Liberty to ourselves and our Posterity, do ordain and establish this Constitution for the United States of America.
]]> Appearance:
Preamble to the Constitution of the United States Copied from a web site somewhere We the People of the United States, in Order to form a more perfect Union, establish Justice, insure domestic Tranquility, provide for the common defence, promote the general Welfare, and secure the Blessings of Liberty to ourselves and our Posterity, do ordain and establish this Constitution for the United States of America.
Tips, notes, warnings, cautions, important information and sidebars. You may need to include extra information separate from the main body of the text. Typically this is “meta” information that the user should be aware of. Depending on the nature of the information, one of tip, note, warning, caution, and important should be used. Alternatively, if the information is related to the main text but is not one of the above, use sidebar. The circumstances in which to choose one of these elements over another is unclear. The DocBook documentation suggests; A Note is for information that should be heeded by all readers. An Important element is a variation on Note. A Caution is for information regarding possible data loss or software damage. A Warning is for information regarding possible hardware damage or injury to life or limb. <sgmltag>warning</sgmltag> Use: Installing FreeBSD may make you want to delete Windows from your harddisk. ]]> Installing FreeBSD may make you want to delete Windows from your harddisk. Lists and procedures You will often need to list pieces of information to the user, or present them with a number of steps that must be carried out in order to accomplish a particular goal. In order to do this, use itemizedlist, orderedlist, or procedureThere are other types of list element in DocBook, but we're not concerned with those at the moment. itemizedlist and - orderedlist are similar to the counterparts in + orderedlist are similar to their counterparts in HTML, ul and ol. Each one consists of one or more listitem elements, and each listitem contains one or more block elements. The listitem elements are analagous to - HTMLs li tags. However, unlike HTML they are + HTML's li tags. However, unlike HTML, they are required. procedure is slightly different. It consists of steps, which may in turn consists of more steps or substeps. Each step contains block elements. <sgmltag>itemizedlist</sgmltag>, <sgmltag>orderedlist</sgmltag>, and <sgmltag>procedure</sgmltag> Use: This is the first itemized item. This is the second itemized item. This is the first ordered item. This is the second ordered item. Do this. Then do this. And now do this. ]]> Appearance: This is the first itemized item. This is the second itemized item. This is the first ordered item. This is the second ordered item. Do this. Then do this. And now do this. Showing file samples If you want to show a fragment of a file (or perhaps a complete file) to the user, wrap it in the programlisting element. White space and line breaks within programlisting are significant. In particular, this means that the opening tag should appear on the same line as the first line of the output, and the closing tag should appear on the same line as the last line of the output, otherwise spurious blank lines may be included. <sgmltag>programlisting</sgmltag> Use: When you have finished, your program should look like this; #include <stdio.h> int main(void) { printf("hello, world\n"); }]]> Notice how the angle brackets in the #include line need to be referenced by their entities instead of being included literally. Appearance: When you have finished, your program should look like this; #include <stdio.h> int main(void) { printf("hello, world\n"); } There is a mechanism within DocBook for referring to sections of a previously occuring programlisting, called callouts (see programlistingco for more information). I don't fully understand (i.e., have never used) this feature, so can't document it here. For the mean time, you can include line numbers within the content, and then refer to them later on in your description. That will change, as soon as I find the time to understand and document callouts. Tables Unlike HTML, you do not need to use tables for layout purposes, as the stylesheet handles those issues for you. Instead, just use tables for marking up tabular data. In general terms (and see the DocBook documentation for more detail) a table (which can be either formal or informal) consists of a table element. This contains at least one tgroup element, which specifies (as an attribute) the number of columns in this table group. Within the tablegroup you can then have one thead element, which contains elements for the table headings (column headings), and one tbody which contains the body of the table. Both tgroup and thead contain row elements, which in turn contain entry elements. Each entry element specifies one cell in the table. <sgmltag>informaltable</sgmltag> Use: This is column head 1 This is column head 2 Row 1, column 1 Row 1, column 2 Row 2, column 1 Row 2, column 2 ]]> Appearance: This is column head 1 This is column head 2 Row 1, column 1 Row 1, column 2 Row 2, column 1 Row 2, column 2 If you don't want a border around the table the frame attribute can be added to the informaltable element with a value of none (i.e., <informaltable frame="none">). Tables where <literal>frame="none"</literal> Appearance: This is column head 1 This is column head 2 Row 1, column 1 Row 1, column 2 Row 2, column 1 Row 2, column 2 Examples for the user to follow A lot of the time you need to show examples for the user to follow. Typically, these will consist of dialogs with the computer; the user types in a command, the user gets a response back, they type in another command, and so on. A number of distinct elements and entities come in to play here. screen Everything the user sees in this example will be on the computer screen, so the next element is screen. Within screen, white space is significant. prompt, &prompt.root; and &prompt.user; Some of the things the user will be seeing on the screen are prompts from the computer (either from the OS, command shell, or application. These should be marked up using prompt. As a special case, the two shell prompts for the normal user and the root user have been provided as entities. Every time you want to indicate the user is at a shell prompt, use one of &prompt.root; and &prompt.user; as necessary. They do not need to be inside prompt. &prompt.root; and &prompt.user; are FreeBSD extensions to DocBook, and are not part of the original DTD. userinput When displaying text that the user should type in, wrap it in userinput tags. It will probably be displayed differently to the user. <sgmltag>screen</sgmltag>, <sgmltag>prompt</sgmltag>, and <sgmltag>userinput</sgmltag> Use: &prompt.user; ls -1 foo1 foo2 foo3 &prompt.user; ls -1 | grep foo2 foo2 &prompt.user; su Password: &prompt.root; cat foo2 This is the file called 'foo2']]> Appearance: &prompt.user; ls -1 foo1 foo2 foo3 &prompt.user; ls -1 | grep foo2 foo2 &prompt.user; su Password: &prompt.root; cat foo2 This is the file called 'foo2' Even though we are displaying the contents of the file foo2, it is not marked up as programlisting. Reserve programlisting for showing fragments of files outside the context of user actions. In-line elements Emphasising information When you want to emphasise a particular word or phrase, use emphasis. This may be presented as italic, or bold, or might be spoken differently with a text-to-speech system. There is no way to change the presentation of the emphasis within your document, no equivalent of HTML's b and i. If the information you are presenting is important then consider presenting it in important rather than emphasis. <sgmltag>emphasis</sgmltag> Use: FreeBSD is without doubt the premiere Unix like operating system for the Intel architecture.]]> Appearance: FreeBSD is without doubt the premiere Unix like operating system for the Intel architecture. Applications, commands, options, and cites You will frequently want to refer to both applications and commands when writing for the Handbook. The distinction between - them is simple; an application is the name for a suite (or possibly + them is simple: an application is the name for a suite (or possibly just 1) of programs that fulfil a particular task. A command is the name of a program that the user can run. In addition, you will occasionally need to list one or more of the options that a command might take. - Finally, you will often want to list a command with it's manual + Finally, you will often want to list a command with its manual section number, in the “command(number)” format so common in Unix manuals. Mark up application names with application. - When you want to list a command with it's manual section number + When you want to list a command with its manual section number (which should be most of the time) the DocBook element is citerefentry. This will contain a further two elements, refentrytitle and manvolnum. The content of refentrytitle is the name of the command, and the content of manvolnum is the manual page section. This can be cumbersome to write, and so a series of general entities have been created to make this easier. Each entity takes the form &man.manual-page.manual-section;. The file that contains these entities is in doc/share/sgml/man-refs.ent, and can be - referred to using this FPI; + referred to using this FPI: PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN" Therefore, the introduction to your documentation will probably - look like this; + look like this: <!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN" [ <!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"> %man; … ]> Use command when you want to include a command name “in-line” but present it as something the user should type in. Use option to mark up a command's options. This can be confusing, and sometimes the choice is not always clear. Hopefully this example makes it clearer. Applications, commands, and options. Use: Sendmail is the most widely used Unix mail application. Sendmail includes the sendmail 8 , &man.sendmail.8;, and &man.newaliases.8; programs. One of the command line parameters to sendmail 8 , , will display the current status of messages in the mail queue. Check this on the command line by running sendmail -bp.]]> Appearance: Sendmail is the most widely used Unix mail application. Sendmail includes the sendmail 8 , mailq 8 , and newaliases 8 programs. One of the command line parameters to sendmail 8 , , will display the current status of messages in the mail queue. Check this on the command line by running sendmail -bp. Notice how the &man.command.section; notation is easier to follow. Files, directories, extensions Whenever you wish to refer to the name of a file, a directory, or a file extension, use filename. <sgmltag>filename</sgmltag> Use: The SGML source for the Handbook in English can be found in /usr/doc/en/handbook/. The first file is called handbook.sgml in that directory. You should also see a Makefile and a number of files with a .ent extension.]]> Appearance: The SGML source for the Handbook in English can be found in /usr/doc/en/handbook/. The first file is called handbook.sgml in that directory. You should also see a Makefile and a number of files with a .ent extension. Devices FreeBSD extension These elements are part of the FreeBSD extension to DocBook, and do not exist in the original DocBook DTD. When referring to devices you have two choices. You can either refer to the device as it appears in /dev, or you can use the name of the device as it appears in the kernel. For this latter course, use devicename. Sometimes you will not have a choice. Some devices, such as networking cards, do not have entries in /dev, or the entries are markedly different from those entries. <sgmltag>devicename</sgmltag> Use: sio is used for serial communication in FreeBSD. sio manifests through a number of entries in /dev, including /dev/ttyd0 and /dev/cuaa0. By contrast, the networking devices, such as ed0 do not appear in /dev. In MS-DOS, the first floppy drive is referred to as a:. In FreeBSD it is /dev/fd0.]]> Appearance: sio is used for serial communication in FreeBSD. sio manifests through a number of entries in /dev, including /dev/ttyd0 and /dev/cuaa0. By contrast, the networking devices, such as ed0 do not appear in /dev. In MS-DOS, the first floppy drive is referred to as a:. In FreeBSD it is /dev/fd0. Hosts, domains, IP addresses, and so forth FreeBSD extension These elements are part of the FreeBSD extension to DocBook, and do not exist in the original DocBook DTD. You can markup identification information for networked computers (hosts) in several ways, depending on the nature of the information. All of them use hostid as the element, with the role attribute selecting the type of the marked up information. No role attribute, or role="hostname" With no role attribute (i.e., hostid...hostid the marked up information is the simple hostname, such as freefall or wcarchive. You can explicitly specify this with role="hostname". role="domainname" The text is a domain name, such as FreeBSD.org or ngo.org.uk. There is no hostname component. role="fqdn" The text is a Fully Qualified Domain Name, with both hostname and domain name parts. role="ipaddr" The text is an IP address, probably expressed as a dotted quad. role="netmask" The text is a network mask, which might be expressed as a dotted quad, a hexadecimal string, or as a / followed by a number. role="mac" The text is an ethernet MAC address, expressed as a series of 2 digit hexadecimal numbers seperated by colons. <sgmltag>hostid</sgmltag> and roles Use: The local machine can always be referred to by the name localhost, which will have the IP address 127.0.0.1. The FreeBSD.org domain contains a number of different hosts, including freefall.FreeBSD.org and bento.FreeBSD.org. When adding an IP alias to an interface (using ifconfig) always use a netmask of 255.255.255.255 (which can also be expressed as 0xffffffff. The MAC address uniquely identifies every network card in in existence. A typical MAC address looks like 08:00:20:87:ef:d0.]]> Appearance: The local machine can always be referred to by the name localhost, which will have the IP address 127.0.0.1. The FreeBSD.org domain contains a number of different hosts, including freefall.FreeBSD.org and bento.FreeBSD.org. When adding an IP alias to an interface (using ifconfig) always use a netmask of 255.255.255.255 (which can also be expressed as 0xffffffff. The MAC address uniquely identifies every network card in existence. A typical MAC address looks like 08:00:20:87:ef:d0. Usernames FreeBSD extension These elements are part of the FreeBSD extension to DocBook, and do not exist in the original DocBook DTD. When you need to refer to a specific username, such as root or bin, use username. <sgmltag>username</sgmltag> Use: To carry out most system administration functions you will need to be root.]]> Appearance: To carry out most system administration functions you will need to be root. Describing <filename>Makefile</filename>s FreeBSD extension These elements are part of the FreeBSD extension to DocBook, and do not exist in the original DocBook DTD. Two elements exist to describe parts of Makefiles, maketarget and makevar. maketarget identifies a build target exported by a Makefile that can be given as a parameter to make. makevar identifies a variable that can be set (in the environment, on the make command line, or within the Makefile) to influence the process. <sgmltag>maketarget</sgmltag> and <sgmltag>makevar</sgmltag> Use: Two common targets in a Makefile are all and clean. Typically, invoking all will rebuild the application, and invoking clean will remove the temporary files (.o for example) created by the build process. clean may be controlled by a number of variables, including CLOBBER and RECURSE.]]> Appearance: Two common targets in a Makefile are all and clean. Typically, invoking all will rebuild the application, and invoking clean will remove the temporary files (.o for example) created by the build process. clean may be controlled by a number of variables, including CLOBBER and RECURSE. Literal text You will often need to include “literal” text in the Handbook. This is text that is excerpted from another file, or which should be copied from the Handbook into another file verbatim. Some of the time, programlisting will be sufficient to denote this text. programlisting is not always appropriate, particularly when you want to include a portion of a file “in-line” with the rest of the paragraph. On these occasions, use literal. <sgmltag>literal</sgmltag> Use: The maxusers 10 line in the kernel configuration file determines the size of many system tables, and is a rough guide to how many simultaneous logins the system will support.]]> Appearance: The maxusers 10 line in the kernel configuration file determines the size of many system tables, and is a rough guide to how many simultaneous logins the system will support. Showing items that the user <emphasis>must</emphasis> fill in There will often be times when you want to show the user what to do, or refer to a file, or command line, or similar, where the user can not simply copy the examples that you provide, but must instead include some information themselves. replaceable is designed for this eventuality. Use it inside other elements to indicate parts of that element's content that the user must replace. <sgmltag>replaceable</sgmltag> Use: &prompt.user; man command ]]> Appearance: &prompt.user; man command replaceable can be used in many different elements, including literal. This example also shows that replaceable should only be wrapped around the content that the user is meant to provide. The other content should be left alone. Use: The maxusers n line in the kernel configuration file determines the size of many system tables, and is a rough guide to how many simultaneous logins the system will support. For a desktop workstation, 32 is a good value for n.]]> Appearance: The maxusers n line in the kernel configuration file determines the size of many system tables, and is a rough guide to how many simultaneous logins the system will support. For a desktop workstation, 32 is a good value for n. Links Links are also in-line elements. Linking to other parts of the same document Linking within the same document requires you to to specify where you are linking from (i.e., the text the user will click, or otherwise indicate, as the source of the link) and where you are linking to (the link's destination). Each element within DocBook has an attribute called id. You can place text in this attribute to uniquely name the element it is attached to. This value will be used when you specify the link source. Normally, you will only be linking to chapters or sections, so you would add the id attribute to these elements. <literal>id on chapters and sections</literal> Introduction This is the introduction. It contains a subsection, which is identified as well. Sub-sect 1 This is the subsection. ]]> Obviously, you should use more descriptive values. The values must be unique within the document (i.e., not just the file, but the document the file might be included in as well). Notice how the id for the subsection is constructed by appending text to the id of the chapter. This helps to ensure that they are unique. If you want to allow the user to jump into a specific portion of the document (possibly in the middle of a paragraph or an example), use anchor. This element has no content, but takes an id attribute. <sgmltag>anchor</sgmltag> This paragraph has an embedded link target in it. It won't show up in the document.]]> When you want to provide the user with a link they can activate (probably by clicking) to go to a section of the document that has an id attribute, you can use either xref or link. Both of these elements have a linkend attribute. The value of this attribute should be the value that you have used in a id attribute (it does not matter - if that value has not yet occured in your document, this will work + if that value has not yet occurred in your document; this will work for forward links as well as backward links). If you use xref then you have no control over the text of the link. It will be generated for you. Using <sgmltag>xref</sgmltag> Assume that this fragment appears somewhere in a document that includes the id example; More information can be found in . More specific information can be found in .]]> The text of the link will be generated automatically, and will look like (emphasised text indicates the text that will be the link);
More information can be found in Chapter One. More specific information can be found in the section called Sub-sect 1.
Notice how the text from the link is derived from the section title or the chapter number. This means that you can not use xref to link to an id attribute on an anchor element. The anchor has no content, so the xref can not generate the text for the link. If you want to control the text of the link then use link. This element wraps content, and the content will be used for the link. Using <sgmltag>link</sgmltag> Assume that this fragment appears somewhere in a document that includes the id example. More information can be found in the first chapter. More specific information can be found in FreeBSD home page instead.]]> Appearance: Of course, you could stop reading this document and go to the FreeBSD home page instead. * LinuxDoc LinuxDoc is an adaptation of the QWERTZ DTD, first adopted by the - Linux Documentation + Linux Documentation Project, and subsequently adopted by the FreeBSD Documentation Project. The LinuxDoc DTD contains primarily appearance related markup rather than content related markup (i.e., it describes what something looks like rather than what it is). Both the FreeBSD Documentation Project and the Linux Documentation Project are migrating from the LinuxDoc DTD to the DocBook DTD. The LinuxDoc DTD is available from the ports collection in the textproc/linuxdoc category. diff --git a/en_US.ISO_8859-1/books/fdp-primer/sgml-primer/chapter.sgml b/en_US.ISO_8859-1/books/fdp-primer/sgml-primer/chapter.sgml index da050c4242..58e81d90bf 100644 --- a/en_US.ISO_8859-1/books/fdp-primer/sgml-primer/chapter.sgml +++ b/en_US.ISO_8859-1/books/fdp-primer/sgml-primer/chapter.sgml @@ -1,1594 +1,1594 @@ SGML Primer The majority of FDP documentation is written in applications of SGML. This chapter explains exactly what that means, how to read and understand the source to the documentation, and the sort of SGML tricks you will see used in the documentation. Portions of this section were inspired by Mark Galassi's Get Going With DocBook. Overview Way back when, electronic text was simple to deal with. Admittedly, you had to know which character set your document was written in (ASCII, EBCDIC, or one of a number of others) but that was about it. Text was text, and what you saw really was what you got. No frills, no formatting, no intelligence. Inevitably, this was not enough. Once you have text in a machine-usable format, you expect machines to be able to use it and manipulate it intelligently. You would like to indicate that certain phrases should be emphasised, or added to a glossary, or be hyperlinks. You might want filenames to be shown in a “typewriter” style font for viewing on screen, but as “italics” when printed, or any of a myriad of other options for presentation. It was once hoped that Artificial Intelligence (AI) would make this easy. Your computer would read in the document and automatically identify key phrases, filenames, text that the reader should type in, examples, and more. Unfortunately, real life has not happened quite like that, and our computers require some assistance before they can meaningfully process our text. More precisely, they need help identifying what is what. You or I can look at
To remove /tmp/foo use &man.rm.1;. &prompt.user; rm /tmp/foo
and easily see which parts are filenames, which are commands to be typed in, which parts are references to manual pages, and so on. But the computer processing the document can not. For this we need markup. “Markup” is commonly used to describe “adding value” or “increasing cost”. The term takes on both these meanings when applied to text. Markup is additional text included in the document, distinguished from the document's content in some way, so that programs that process the document can read the markup and use it when making decisions about the document. Editors can hide the markup from the user, so the user is not distracted by it. The extra information stored in the markup adds value to the document. Adding the markup to the document must typically be done by a person—after all, if computers could recognise the text sufficiently well to add the markup then there would be no need to add it in the first place. This increases the cost (i.e., the effort required) to create the document. The previous example is actually represented in this document like this; To remove /tmp/foo use &man.rm.1;. rm /tmp/foo]]> As you can see, the markup is clearly separate from the content. Obviously, if you are going to use markup you need to define what your markup means, and how it should be interpreted. You will need a markup language that you can follow when marking up your documents. Of course, one markup language might not be enough. A markup language for technical documentation has very different requirements than a markup language that was to be used for cookery recipes. This, in turn, would be very different from a markup language used to describe poetry. What you really need is a first language that you use to write these other markup languages. A meta markup language. This is exactly what the Standard Generalised Markup Language (SGML) is. Many markup languages have been written in SGML, including the two most used by the FDP, HTML and DocBook. Each language definition is more properly called a Document Type Definition (DTD). The DTD specifies the name of the elements that can be used, what order they appear in (and whether some markup can be used inside other markup) and related information. A DTD is sometimes referred to as an application of SGML. A DTD is a complete specification of all the elements that are allowed to appear, the order in which they should appear, which elements are mandatory, which are optional, and so forth. This makes it possible to write an SGML parser which reads in both the DTD and a document which claims to conform to the DTD. The parser can then confirm whether or not all the elements required by the DTD are in the document in the right order, and whether there are any errors in the markup. This is normally referred to as validating the document. This processing simply confirms that the choice of elements, their ordering, and so on, conforms to that listed in the DTD. It does not check that you have used appropriate markup for the content. If you were to try and mark up all the filenames in your document as function names, the parser would not flag this as an error (assuming, of course, that your DTD defines elements for filenames and functions, and that they are allowed to appear in the same place). It is likely that most of your contributions to the Documentation Project will consist of content marked up in either HTML or DocBook, rather than alterations to the DTDs. For this reason this book will not touch on how to write a DTD. Elements, tags, and attributes All the DTDs written in SGML share certain characteristics. This is hardly surprising, as the philosophy behind SGML will inevitably show through. One of the most obvious manifestations of this philisophy is that of content and elements. Your documentation (whether it is a single web page, or a lengthy book) is considered to consist of content. This content is then divided (and further subdivided) into elements. The purpose of adding markup is to name and identify the boundaries of these elements for further processing. For example, consider a typical book. At the very top level, the book is itself an element. This “book” element obviously contains chapters, which can be considered to be elements in their own right. Each chapter will contain more elements, such as paragraphs, quotations, and footnotes. Each paragraph might contain further elements, identifying content that was direct speech, or the name of a character in the story. You might like to think of this as “chunking” content. At the very top level you have one chunk, the book. Look a little deeper, and you have more chunks, the individual chapters. These are chunked further into paragraphs, footnotes, character names, and so on. Notice how you can make this differentation between different elements of the content without resorting to any SGML terms. It really is surprisingly straightforward. You could do this with a highlighter pen and a printout of the book, using different colours to indicate different chunks of content. Of course, we do not have an electronic highlighter pen, so we need some other way of indicating which element each piece of content belongs to. In languages written in SGML (HTML, DocBook, et al) this is done by means of tags. A tag is used to identify where a particular element starts, and where the element ends. The tag is not part of the element itself. Because each DTD was normally written to mark up specific types of information, each one will recognise different elements, and will therefore have different names for the tags. For an element called element-name the start tag will normally look like <element-name>. The corresponding closing tag for this element is </element-name>. Using an element (start and end tags) HTML has an element for indicating that the content enclosed by the element is a paragraph, called p. This element has both start and end tags. This is a paragraph. It starts with the start tag for the 'p' element, and it will end with the end tag for the 'p' element.

This is another paragraph. But this one is much shorter.

]]> Not all elements require an end tag. Some elements have no content. For example, in HTML you can indicate that you want a horizontal line to appear in the document. Obviously, this line has no content, so just the start tag is required for this element. Using an element (start tag only) HTML has an element for indicating a horizontal rule, called hr. This element does not wrap content, so only has a start tag. This is a paragraph.

This is another paragraph. A horizontal rule separates this from the previous paragraph.

]]> If it is not obvious by now, elements can contain other elements. In the book example earlier, the book element contained all the chapter elements, which in turn contained all the paragraph elements, and so on. Elements within elements; <sgmltag>em</sgmltag> This is a simple paragraph where some of the words have been emphasised.

]]> The DTD will specify the rules detailing which elements can contain other elements, and exactly what they can contain. People often confuse the terms tags and elements, and use the terms as if they were interchangeable. They are not. An element is a conceptual part of your document. An element has a defined start and end. The tags mark where the element starts and end. When this document (or anyone else knowledgable about SGML) refers to “the <p> tag” they mean the literal text consisting of the three characters <, p, and >. But the phrase “the <p> element” refers to the whole element. This distinction is very subtle. But keep it in mind. Elements can have attributes. An attribute has a name and a value, and is used for adding extra information to the element. This might be information that indicates how the content should be rendered, or might be something that uniquely identifies that occurence of the element, or it might be something else. An element's attributes are written inside the start tag for that element, and take the form attribute-name="attribute-value". In sufficiently recent versions of HTML, the p element has an attribute called align, which suggests an alignment (justification) for the paragraph to the program displaying the HTML. The align attribute can take one of four defined values, left, center, right and justify. If the attribute is not specified then the default is left. Using an element with an attribute The inclusion of the align attribute on this paragraph was superfluous, since the default is left.

This may appear in the center.

]]> Some attributes will only take specific values, such as left or justify. Others will allow you to enter anything you want. If you need to include quotes (") within an attribute then use single quotes around the attribute value. Single quotes around attributes I'm on the right!

]]> Sometimes you do not need to use quotes around attribute values at all. However, the rules for doing this are subtle, and it is far simpler just to always quote your attribute values. For you to do… In order to run the examples in this document you will need to install some software on your system and ensure that an environment variable is set correctly. Download and install textproc/docproj from the FreeBSD ports system. This is a meta-port that should download and install all of the programs and supporting files that are used by the Documentation Project. Add lines to your shell startup files to set SGML_CATALOG_FILES. <filename>.profile</filename>, for &man.sh.1; and &man.bash.1; users SGML_ROOT=/usr/local/share/sgml SGML_CATALOG_FILES=${SGML_ROOT}/jade/catalog SGML_CATALOG_FILES=${SGML_ROOT}/iso8879/catalog:$SGML_CATALOG_FILES SGML_CATALOG_FILES=${SGML_ROOT}/html/catalog:$SGML_CATALOG_FILES SGML_CATALOG_FILES=${SGML_ROOT}/docbook/catalog:$SGML_CATALOG_FILES export SGML_CATALOG_FILES <filename>.login</filename>, for &man.csh.1; and &man.tcsh.1; users setenv SGML_ROOT /usr/local/share/sgml setenv SGML_CATALOG_FILES ${SGML_ROOT}/jade/catalog setenv SGML_CATALOG_FILES ${SGML_ROOT}/iso8879/catalog:$SGML_CATALOG_FILES setenv SGML_CATALOG_FILES ${SGML_ROOT}/html/catalog:$SGML_CATALOG_FILES setenv SGML_CATALOG_FILES ${SGML_ROOT}/docbook/catalog:$SGML_CATALOG_FILES Then either log out, and log back in again, or run those commands from the command line to set the variable values. Create example.sgml, and enter the following text; An example HTML file

This is a paragraph containing some text.

This paragraph contains some more text.

This paragraph might be right-justified.

]]> Try and validate this file using an SGML parser. Part of textproc/docproj is the &man.nsgmls.1; validating parser. Normally, &man.nsgmls.1; reads in a document marked up according to an SGML DTD and returns a copy of the document's Element Structure Information Set (ESIS, but that is not important right now). However, when &man.nsgmls.1; is given the parameter, &man.nsgmls.1; will suppress its normal output, and just print error messages. This makes it a useful way to check to see if your document is valid or not. Use &man.nsgmls.1; to check that your document is valid; &prompt.user; nsgmls -s example.sgml As you will see, &man.nsgmls.1; returns without displaying any output. This means that your document validated successfully. See what happens when required elements are omitted. Try removing the title and /title tags, and re-run the validation. &prompt.user; nsgmls -s example.sgml nsgmls:example.sgml:5:4:E: character data is not allowed here nsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished The error output from &man.nsgmls.1; is organised into colon-separated groups, or columns. Column Meaning 1 The name of the program generating the error. This will always be nsgmls. 2 The name of the file that contains the error. 3 Line number where the error appears. 4 Column number where the error appears. 5 A one letter code indicating the nature of the message. I indicates an informational message, W is for warnings, and E is for errors It is not always the fifth column either. nsgmls -sv displays nsgmls:I: SP version "1.3" (depending on the installed version). As you can see, this is an informational message. , and X is for cross-references. As you can see, these messages are errors. 6 The text of the error message. More information about errors from &man.nsgmls.1; is available in the Unofficial 'Kindler, Gentler HTML Validator' FAQ. ]]> Simply omitting the title tags has generated 2 different errors. The first error indicates that content (in this case, characters, rather than the start tag for an element) has occured where the SGML parser was expecting something else. In this case, the parser was expecting to see one of the start tags for elements that are valid inside head (such as title). The second error is because head elements must contain a title element. Because it does not &man.nsgmls.1; considers that the element has not been properly finished. However, the closing tag indicates that the element has been closed before it has been finished. Put the title element back in. The DOCTYPE declaration The beginning of each document that you write must specify the name of the DTD that the document conforms to. This is so that SGML parsers can determine the DTD and ensure that the document does conform to it. This information is generally expressed on one line, in the DOCTYPE declaration. A typical declaration for a document written to conform with version 4.0 of the HTML DTD looks like this; ]]> That line contains a number of different components. <! Is the indicator that indicates that this is an SGML declaration. This line is declaring the document type. DOCTYPE Shows that this is an SGML declaration for the document type. html Names the first element that will appear in the document. PUBLIC "-//W3C//DTD HTML 4.0//EN" Lists the Formal Public Identifier (FPI) for the DTD that this document conforms to. Your SGML parser will use this to find the correct DTD when processing this document. PUBLIC is not a part of the FPI, but indicates to the SGML processor how to find the DTD referenced in the FPI. Other ways of telling the SGML parser how to find the DTD are shown later. > Returns to the document. Formal Public Identifiers (FPIs) You don't need to know this, but it's useful background, and might help you debug problems when your SGML processor can't locate the DTD you are using. FPIs must follow a specific syntax. This syntax is as follows; "Owner//Keyword Description//Language" Owner This indicates the owner of the FPI. If this string starts with “ISO” then this is an ISO owned FPI. For example, the FPI "ISO 8879:1986//ENTITIES Greek Symbols//EN" lists ISO 8879:1986 as being the owner for the set of entities for greek symbols. ISO 8879:1986 is the ISO number for the SGML standard. Otherwise, this string will either look like -//Owner or +//Owner (notice the only difference is the leading + or -). If the string starts with - then the owner information is unregistered, with a + it identifies it as being registered. ISO 9070:1991 defines how registered names are generated; it might be derived from the number of an ISO publication, an ISBN code, or an organisation code assigned according to ISO 6523. In addition, a registration authority could be created in order to assign registered names. The ISO council delegated this to the American National Standards Institute (ANSI). Because the FreeBSD Project hasn't been registered the owner string is -//FreeBSD. And as you can see, the W3C are not a registered owner either. Keyword There are several keywords that indicate the type of information in the file. Some of the most common keywords are DTD, ELEMENT, ENTITIES, and TEXT. DTD is used only for DTD files, ELEMENT is usually used for DTD fragments that contain only entity or element declarations. TEXT is used for SGML content (text and tags). Description Any description you want to supply for the contents of this file. This may include version numbers or any short text that is meaningful to you and unique for the SGML system. Language This is an ISO two-character code that identifies the native language for the file. EN is used for English. <filename>catalog</filename> files If you use the syntax above and try and process this document using an SGML processor, the processor will need to have some way of turning the FPI into the name of the file on your computer that contains the DTD. In order to do this it can use a catalog file. A catalog file (typically called catalog) contains lines that map FPIs to filenames. For example, if the catalog file contained the line; PUBLIC "-//W3C//DTD HTML 4.0//EN" "4.0/strict.dtd" The SGML processor would know to look up the DTD from strict.dtd in the 4.0 subdirectory of whichever directory held the catalog file that contained that line. Look at the contents of /usr/local/share/sgml/html/catalog. This is the catalog file for the HTML DTDs that will have been installed as part of the textproc/docproj port. <envar>SGML_CATALOG_FILES</envar> In order to locate a catalog file, your SGML processor will need to know where to look. Many of them feature command line parameters for specifying the path to one or more catalogs. In addition, you can set SGML_CATALOG_FILES to point to the files. This environment variable should consist of a colon-separated list of catalog files (including their full path). Typically, you will want to include the following files; /usr/local/share/sgml/docbook/catalog /usr/local/share/sgml/html/catalog /usr/local/share/sgml/iso8879/catalog /usr/local/share/sgml/jade/catalog You should already have done this. Alternatives to FPIs Instead of using an FPI to indicate the DTD that the document conforms to (and therefore, which file on the system contains the DTD) you can explicitly specify the name of the file. - The syntax for this is slightly different; + The syntax for this is slightly different: ]]> The SYSTEM keyword indicates that the SGML processor should locate the DTD in a system specific fashion. This typically (but not always) means the DTD will be provided as a filename. Using FPIs is preferred for reasons of portability. You don't want to have to ship a copy of the DTD around with your document, and if you used the SYSTEM identifier then everyone would need to keep their DTDs in the same place. Escaping back to SGML Earlier in this primer I said that SGML is only used when writing a DTD. This is not strictly true. There is certain SGML syntax that you will want to be able to use within your documents. For example, comments can be included in your document, and will be ignored by the parser. Comments are entered using SGML syntax. Other uses for SGML syntax in your document will be shown later too. Obviously, you need some way of indicating to the SGML processor that the following content is not elements within the document, but is SGML that the parser should act upon. These sections are marked by <! ... > in your document. Everything between these delimiters is SGML syntax as you might find within a DTD. As you may just have realised, the DOCTYPE declaration is an example of SGML syntax that you need to include in your document… Comments Comments are an SGML construction, and are normally only valid inside a DTD. However, as shows, it is possible to use SGML syntax within your document. The delimiter for SGML comments is the string “--”. The first occurence of this string opens a comment, and the second closes it. SGML generic comment <!-- test comment --> ]]> Use 2 dashes There is a problem with producing the Postscript and PDF versions of this document. The above example probably shows just one hyphen symbol, - after the <! and before the >. You must use two -, not one. The Postscript and PDF versions have translated the two - in the original to a longer, more professional em-dash, and broken this example in the process. The HTML, plain text, and RTF versions of this document are not affected. ]]> If you have used HTML before you may have been shown different rules for comments. In particular, you may think that the string <!-- opens a comment, and it is only closed by -->. This is not the case. A lot of web browsers have broken HTML parsers, and will accept that as valid. However, the SGML parsers used by the Documentation Project are much stricter, and will reject documents that make that error. Errorneous SGML comments ]]> The SGML parser will treat this as though it were actually; <!THIS IS OUTSIDE THE COMMENT> This is not valid SGML, and may give confusing error messages. ]]> As the example suggests, do not write comments like that. ]]> That is a (slightly) better approach, but it still potentially confusing to people new to SGML. For you to do… Add some comments to example.sgml, and check that the file still validates using &man.nsgmls.1; Add some invalid comments to example.sgml, and see the error messages that &man.nsgmls.1; gives when it encounters an invalid comment. Entities Entities are a mechanism for assigning names to chunks of content. As an SGML parser processes your document, any entities it finds are replaced by the content of the entity. This is a good way to have re-usable, easily changeable chunks of content in your SGML documents. It is also the only way to include one marked up file inside another using SGML. There are two types of entities which can be used in two different situations; general entities and parameter entities. General Entities You can not use general entities in an SGML context (although you define them in one). They can only be used in your document. Contrast this with parameter entities. Each general entity has a name. When you want to reference a general entity (and therefore include whatever text it represents in your document), you write &entity-name;. For example, suppose you had an entity called current.version which expanded to the current version number of your product. You could write; The current version of our product is ¤t.version;.]]> When the version number changes you can simply change the definition of the value of the general entity and reprocess your document. You can also use general entities to enter characters that you could not otherwise include in an SGML document. For example, < and & can not normally appear in an SGML document. When the SGML parser sees the < symbol it assumes that a tag (either a start tag or an end tag) is about to appear, and when it sees the & symbol it assumes the next text will be the name of an entity. Fortunately, you can use the two general entities &lt; and &amp; whenever you need to include one or other of these A general entity can only be defined within an SGML context. Typically, this is done immediately after the DOCTYPE declaration. Defining general entities ]>]]> Notice how the DOCTYPE declaration has been extended by adding a square bracket at the end of the first line. The two entities are then defined over the next two lines, before the square bracket is closed, and then the DOCTYPE declaration is closed. The square brackets are necessary to indicate that we are extending the DTD indicated by the DOCTYPE declaration. Parameter entities Like general entities, parameter entities are used to assign names to reusable chunks of text. However, where as general entities can only be used within your document, parameter entities can only be used within an SGML context. Parameter entities are defined in a similar way to general entities. However, instead of using &entity-name; to refer to them, use %entity-name; Parameter entities use the Percent symbol. . The definition also includes the % between the ENTITY keyword and the name of the entity. Defining parameter entities ]>]]> This may not seem particularly useful. It will be. For you to do… Add a general entity to example.sgml. ]> An example HTML file

This is a paragraph containing some text.

This paragraph contains some more text.

This paragraph might be right-justified.

The current version of this document is: &version;

]]> Validate the document using &man.nsgmls.1; Load example.sgml into your web browser (you may need to copy it to example.html before your browser recognises it as an HTML document). Unless your browser is very advanced, you won't see the entity reference &version; replaced with the version number. Most web browsers have very simplistic parsers which do not handle proper SGML This is a shame. Imagine all the problems and hacks (such as Server Side Includes) that could be avoided if they did. . The solution is to normalise your document using an SGML normaliser. The normaliser reads in valid SGML and outputs equally valid SGML which has been transformed in some way. One of the ways in which the normaliser transforms the SGML is to expand all the entity references in the document, replacing the entities with the text that they represent. You can use &man.sgmlnorm.1; to do this. &prompt.user; sgmlnorm example.sgml > example.html You should find a normalised (i.e., entity references expanded) copy of your document in example.html, ready to load into your web browser. If you look at the output from &man.sgmlnorm.1; you will see that it does not include a DOCTYPE declaration at the start. To include this you need to use the option; &prompt.user; sgmlnorm -d example.sgml > example.html Using entities to include files Entities (both general and parameter) are particularly useful when used to include one file inside another. Using general entities to include files Suppose you have some content for an SGML book organised into files, one file per chapter, called chapter1.sgml, chapter2.sgml, and so forth, with a book.sgml file that will contain these chapters. In order to use the contents of these files as the values for your entities, you declare them with the SYSTEM keyword. This directs the SGML parser to use the contents of the named file as the value of the entity. Using general entities to include files ]> &chapter.1; &chapter.2; &chapter.3; ]]> When using general entities to include other files within a document, the files being included (chapter1.sgml, chapter2.sgml, and so on) must not start with a DOCTYPE declaration. This is a syntax error. Using parameter entities to include files Recall that parameter entities can only be used inside an SGML context. Why then would you want to include a file within an SGML context? You can use this to ensure that you can reuse your general entities. Suppose that you had many chapters in your document, and you reused these chapters in two different books, each book organising the chapters in a different fashion. You could list the entities at the top of each book, but this quickly becomes cumbersome to manage. Instead, place the general entity definitions inside one file, and use a parameter entity to include that file within your document. Using parameter entities to include files First, place your entity definitions in a separate file, called chapters.ent. This file contains the following; ]]> Now create a parameter entity to refer to the contents of the file. Then use the parameter entity to load the file into the document, which will then make all the general entities available for use. Then use the general entities as before; %chapters; ]> &chapter.1; &chapter.2; &chapter.3; ]]> For you to do… Use general entities to include files Create three files, para1.sgml, para2.sgml, and para3.sgml. Put content similar to the following in each file; This is the first paragraph.

]]> Edit example.sgml so that it looks like this; ]> An example HTML file

The current version of this document is: &version;

¶1; ¶2; ¶3; ]]> Produce example.html by normalising example.sgml. &prompt.user; sgmlnorm -d example.sgml > example.html Load example.html in to your web browser, and confirm that the paran.sgml files have been included in example.html. Use parameter entities to include files You must have taken the previous steps first. Edit example.sgml so that it looks like this; %entities; ]> An example HTML file

The current version of this document is: &version;

¶1; ¶2; ¶3; ]]> Create a new file, entities.sgml, with - this content; + this content: ]]> Produce example.html by normalising example.sgml. &prompt.user; sgmlnorm -d example.sgml > example.html Load example.html in to your web browser, and confirm that the paran.sgml files have been included in example.html. Marked sections SGML provides a mechanism to indicate that particular pieces of the document should be processed in a special way. These are termed “marked sections”. Structure of a marked section <![ KEYWORD [ Contents of marked section ]]> As you would expect, being an SGML construct, a marked section - starts <!. + starts with <!. The first square bracket begins to delimit the marked section. KEYWORD describes how this marked section should be processed by the parser. The second square bracket indicates that the content of the marked section starts here. The marked section is finished by closing the two square brackets, and then returning to the document context from the SGML context with > Marked section keywords <literal>CDATA</literal>, <literal>RCDATA</literal> These keywords denote the marked sections content model, and allow you to change it from the default. When an SGML parser is processing a document it keeps track of what is called the “content model”. Briefly, the content model describes what sort of content the parser is expecting to see, and what it will do with it when it finds it. The two content models you will probably find most useful are CDATA and RCDATA. CDATA is for “Character Data”. If the parser is in this content model then it is expecting to see characters, and characters only. In this model the < and & symbols lose their special status, and will be treated as ordinary characters. RCDATA is for “Entity references and character data” If the parser is in this content model then it is expecting to see characters and entities. < loses its special status, but & will still be treated as starting the beginning of a general entity. This is particularly useful if you are including some verbatim text that contains lots of < and & characters. While you could go through the text ensuring that every < is converted to a &lt; and every & is converted to a &amp;, it can be easier to mark the section as only containing CDATA. When the SGML parser encounters this it will ignore the < and & symbols embedded in the content. Using a CDATA marked section <para>Here is an example of how you would include some text that contained many &lt; and &amp; symbols. The sample text is a fragment of HTML. The surrounding text (<para> and <programlisting>) are from DocBook.</para> <programlisting> <![ CDATA [ This is a sample that shows you some of the elements within HTML. Since the angle brackets are used so many times, it's simpler to say the whole example is a CDATA marked section than to use the entity names for the left and right angle brackets throughout.

  • This is a listitem
  • This is a second listitem
  • This is a third listitem

This is the end of the example.

]]> ]]> </programlisting> If you look at the source for this document you will see this technique used throughout. <literal>INCLUDE</literal> and <literal>IGNORE</literal> If the keyword is INCLUDE then the contents of the marked section will be processed. If the keyword is IGNORE then the marked section is ignored and will not be processed. It will not appear in the output. Using <literal>INCLUDE</literal> and <literal>IGNORE</literal> in marked sections <![ INCLUDE [ This text will be processed and included. ]]> <![ IGNORE [ This text will not be processed or included. ]]> By itself, this isn't too useful. If you wanted to remove text from your document you could cut it out, or wrap it in comments. It becomes more useful when you realise you can use parameter entities to control this. Remember that parameter entities can only be used in SGML contexts, and the keyword of a marked section is an SGML context. For example, suppose that you produced a hard-copy version of some documentation and an electronic version. In the electronic version you wanted to include some extra content that wasn't to appear in the hard-copy. Create a parameter entity, and set it's value to INCLUDE. Write your document, using marked sections to delimit content that should only appear in the electronic version. In these marked sections use the parameter entity in place of the keyword. When you want to produce the hard-copy version of the document, change the parameter entity's value to IGNORE and reprocess the document. Using a parameter entity to control a marked section <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [ <!ENTITY % electronic.copy "INCLUDE"> ]]> ... <![ %electronic.copy [ This content should only appear in the electronic version of the document. ]]> When producing the hard-copy version, change the entity's definition to; <!ENTITY % electronic.copy "IGNORE"> On reprocessing the document, the marked sections that use %electronic.copy as their keyword will be ignored. For you to do… Create a new file, section.sgml, that contains the following; <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [ <!ENTITY % text.output "INCLUDE"> ]> <html> <head> <title>An example using marked sections</title> </head> <body> <p>This paragraph <![ CDATA [contains many < characters (< < < < <) so it is easier to wrap it in a CDATA marked section ]]></p> <![ IGNORE [ <p>This paragraph will definitely not be included in the output.</p> ]]> <![ [ <p>This paragraph might appear in the output, or it might not.</p> <p>Its appearance is controlled by the parameter entity.</p> ]]> </body> </html> Normalise this file using &man.sgmlnorm.1; and examine the output. Notice which paragraphs have appeared, which have disappeared, and what has happened to the content of the CDATA marked section. Change the definition of the text.output entity from INCLUDE to IGNORE. Re-normalise the file, and examine the output to see what has changed. Conclusion That is the conclusion of this SGML primer. For reasons of space and complexity several things have not been covered in depth (or at all). However, the previous sections cover enough SGML for you to be able to follow the organisation of the FDP documentation. 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 6b42003e89..f564b25e4d 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,287 +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; + documentation in to the tree and: - be easy to automate converting the document to other formats + make it 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 + documentation is split into 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. + (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 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 + 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. Not every lang.encoding directory will contain all of these directories. It depends - on much translation has been accomplished by that translation + 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. 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. + 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 as had on just + every time you want to see the effect a change has had on just one chapter. diff --git a/en_US.ISO_8859-1/books/fdp-primer/tools/chapter.sgml b/en_US.ISO_8859-1/books/fdp-primer/tools/chapter.sgml index b47420fdb0..5ec9dcb95e 100644 --- a/en_US.ISO_8859-1/books/fdp-primer/tools/chapter.sgml +++ b/en_US.ISO_8859-1/books/fdp-primer/tools/chapter.sgml @@ -1,284 +1,284 @@ Tools The FDP uses a number of different software tools to help manage the FreeBSD documentation, convert it to different output formats, and so on. You will need to use these tools yourself if you are to work with the FreeBSD documentation. All these tools are available as FreeBSD Ports and Packages, greatly simplifying the work you have to do to install them. You will need to install these tools before you work through any of the examples in later chapters. The actual usage of these - tools is covered in these later chapters. + tools is covered in later chapters. Use <filename>textproc/docproj</filename> if possible You can save yourself a lot of time if you install the textproc/docproj port. This is a meta-port which does not contain any software itself. Instead, it depends on various other ports being installed correctly. Installing this port should automatically download and install all of the packages listed in this - chapter that you need that are missing from your system. + chapter that you need. One of the packages that you might need is the JadeTeX macro set. In turn, this macro set requires that TeX is installed. TeX is a large package, and you only need it if you want to produce Postscript or PDF output. To save yourself time and space you must specify whether or not you want JadeTeX (and therefore TeX) installed when you install this port. Either do; &prompt.root; make JADETEX=yes install or &prompt.root; make JADETEX=no install as necessary. Mandatory tools Software These programs are required before you can usefully work with the FreeBSD documentation. They are all included in textproc/docproj. SP (textproc/sp) A suite of applications, including a validating SGML parser, and an SGML normaliser. Jade (textproc/jade) A DSSSL implementation. Used for converting marked up documents to other formats, including HTML and TeX. Tidy (www/tidy) An HTML 'pretty printer', used to reformat some of the automatically generated HTML so that it is easier to follow. Lynx (www/lynx-current) A text-mode WWW browser, &man.lynx.1; can also convert HTML files to plain text. DTDs and Entities These are the DTDs and entity sets used by the FDP. They need to be installed before you can work with any of the documentation. HTML DTD (textproc/html) HTML is the markup language of choice for the World Wide Web, and is used throughout the FreeBSD web site. LinuxDoc DTD (textproc/linuxdoc) Some FreeBSD documentation is marked up in LinuxDoc. The FDP is actively migrating from LinuxDoc to DocBook. DocBook DTD (textproc/docbook) DocBook is designed for marking up technical documentation, and the FDP is migrating from LinuxDoc to DocBook. At the time - of writing, this document, and the FreeBSD Handbook are marked + of writing, this document and the FreeBSD Handbook are marked up in DocBook. ISO 8879 entities (textproc/iso8879) 19 of the ISO 8879:1986 character entity sets used by many DTDs. Includes named mathematical symbols, additional characters in the 'latin' character set (accents, diacriticals, and so on), and greek symbols. Stylesheets The stylesheets are used when converting and formatting the documentation for display on screen, printing, and so on. Modular DocBook Stylesheets (textproc/dsssl-docbook-modular) The Modular DocBook Stylesheets are used when converting documentation marked up in DocBook to other formats, such as - HTML, or RTF. + HTML or RTF. Optional tools You do not need to have any of the following installed. However, you may find it easier to work with the documentation if you do, and they may give you more flexibility in the output formats that can be generated. Software JadeTeX and teTeX (print/jadetex and print/teTeX) Jade and teTeX are used to convert DocBook documents to DVI, Postscript, and PDF formats. The JadeTeX macros are needed in order to do this. If you do not intend to convert your documentation to one of these formats (i.e., HTML, plain text, and RTF are sufficient) then you do not need to install JadeTeX and teTeX. This can be a significant space and time saver, as teTeX is over 30MB in size. If you decide to install JadeTeX and teTeX then you will need to configure teTeX after JadeTeX has been installed. print/jadetex/pkg/MESSAGE contains detailed instructions explaining what you need to do. Emacs or xemacs (editors/emacs or editors/xemacs) Both these editors include a special mode for editing documents marked up according to an SGML DTD. This mode includes commands to reduce the amount of typing you need, and help reduce the possibility of errors. - You do not need to use them, any text editor can be used to + You do not need to use them; any text editor can be used to edit marked up documents. You may find they make you more efficient. If anyone has recommendations for other software that is useful when manipulating SGML documents, please let Nik Clayton (nik@FreeBSD.org) know, so they can be added to this list. diff --git a/en_US.ISO_8859-1/books/fdp-primer/translations/chapter.sgml b/en_US.ISO_8859-1/books/fdp-primer/translations/chapter.sgml index abc80c3879..2ceb9b0153 100644 --- a/en_US.ISO_8859-1/books/fdp-primer/translations/chapter.sgml +++ b/en_US.ISO_8859-1/books/fdp-primer/translations/chapter.sgml @@ -1,474 +1,474 @@ Translations This is the FAQ for people translating the FreeBSD documentation (FAQ, Handbook, tutorials, man pages, and others) to different languages. It is very heavily based on the translation FAQ from the FreeBSD German Documentation Project, originally written by Frank Gründer elwood@mc5sys.in-berlin.de and translated back to English by Bernd Warken bwarken@mayn.de. The FAQ maintainer is Nik Clayton nik@FreeBSD.org. Why a FAQ? More and more people are approaching the freebsd-doc mailing list and volunteering to translate FreeBSD documentation to other languages. This FAQ aims to answer their questions so they can start translating documentation as quickly as possible. What do i18n and l10n mean? i18n means internationalisation and l10n means localisation. They are just a convenient shorthand. i18n can be read as “i” followed by 18 letters, followed by “n”. Similarly, l10n is “l” followed by 10 letters, followed by “n”. Is there a mailing list for translators? Yes, freebsd-translate@ngo.org.uk. Subscribe by sending a message to freebsd-translate-request@ngo.org.uk with the word subscribe in the body of the message. You will receive a reply asking you to confirm your subscription (in exactly the same manner as the the FreeBSD lists at FreeBSD.org). The primary language of the mailing list is English. However, posts in other languages will be accepted. The mailing list is not moderated, but you need to be a member of the list before you can post to it. The mailing list is archived, but they are not currently searchable. Sending the message help to majordomo@ngo.org.uk will send back instructions on how to access the archive. It is expected that the mailing list will transfer to FreeBSD.org and therefore become official in the near future. Are more translators needed? Yes. The more people work on translation the faster it gets done, and the faster changes to the English documentation are mirrored in the translated documents. You do not have to be a professional translator to be able to help. What languages do I need to know? Ideally, you will have a good knowledge of written English, and obviously you will need to be fluent in the language you are translating to. English is not strictly necessary. For example, you could do a Hungarian translation of the FAQ from the Spanish translation. What software do I need to know? It is strongly recommended that you maintain a local copy of the FreeBSD CVS repository (at least the documentation part) either using CTM or CVSup. The "Staying current with FreeBSD" chapter in the Handbook explains how to use these applications. You should be comfortable using CVS. This will allow you to see what has changed between different versions of the files that make up the documentation. [XXX To Do -- write a tutorial that shows how to use CVSup to get just the documentation, check it out, and see what's changed between two arbitrary revisions] How do I find out who else might be translating to the same language? The Documentation Project translations page lists the translation efforts - that are currently known about. If someone else is already working + that are currently known about. If others are already working on translating documentation to your language, please don't duplicate their efforts. Instead, contact them to see how you can help. If no one is listed on that page as translating for your - language then send a message to + language, then send a message to freebsd-doc@FreeBSD.org in case someone else is thinking of doing a translation, but hasn't announced it yet. - No one else is translating to my language. What do I do? + No one else is translating to my language. What do I do? Congratulations, you have just started the “FreeBSD your-language-here Documentation Translation Project”. Welcome aboard. First, decide whether or not you've got the time to spare. Since you are the only person working on your language at the moment it is going to be your responsibility to publicise your work and coordinate any volunteers that might want to help you. Write an e-mail to the Documentation Project mailing list, announcing that you are going to translate the documentation, so the Documentation Project translations page can be maintained. You should subscribe to the freebsd-translate@ngo.org.uk mailing list (as described earlier). If there is already someone in your country providing FreeBSD - mirroring services you should contact them and ask if they can - provide some webspace for your project, and possibly an e-mail + mirroring services you should contact them and ask if you can + have some webspace for your project, and possibly an e-mail address or mailing list services. Then pick a document and start translating. It is best to start with something fairly small—either the FAQ, or one of the tutorials. I've translated some documentation, where do I send it? That depends. If you are already working with a translation team (such as the Japanese team, or the German team) then they will have their own procedures for handling submitted documentation, and these will be outlined on their web pages. If you are the only person working on a particular language (or you are responsible for a translation project and want to submit your changes back to the FreeBSD project) then you should send your translation to the FreeBSD project (see the next question). I'm the only person working on translating to this language, how do I submit my translation? or We're a translation team, and want to submit documentation that our members have translated for us? First, make sure your translation is organised properly. This means that it should drop in to the existing documentation tree and build straight away. Currently, the FreeBSD documentation is stored in a top level directory called doc/. Directories below this are named according to the language code they are written in, as defined in ISO639 (/usr/share/misc/iso639 on a version of FreeBSD newer than 20th January 1999). If your language can be encoded in different ways (for example, Chinese) then there should be directories below this, one for each encoding format you have provided. Finally, you should have directories for each document. For example, a hypothetical Swedish translation might look like doc/ sv/ Makefile FAQ/ Makefile *.sgml sv is the ISO639 code for Swedish. Note the two Makefiles, which will be used to build the documentation. There is no separate language code for Swedish, so there is no intermittent directory between the "sv" and "FAQ" directories This directory structure is going to change radically quite soon. Please see the on-going discussions on the freebsd-doc@FreeBSD.org mailing list for more information. . Use &man.tar.1; and &man.gzip.1; to compress up your documentation, and send it to the project. &prompt.user; cd doc &prompt.user; tar cf swedish-docs.tar sv &prompt.user; gzip -9 swedish-docs.tar Put swedish-docs.tar.gz somewhere. If you do not have access to your own webspace (perhaps your ISP does not let you have any) then you can e-mail Nik Clayton nik@FreeBSD.org, and arrange to e-mail the files when it is convenient. Either way, you should use &man.send-pr.1; to submit a report indicating that you have submitted the documentation. It would be very helpful if you could get other people to look over your translation and double check it first, since it is unlikely that the person committing it will be fluent in the language. Someone (probably the Documentation Project Manager, currently Nik Clayton nik@FreeBSD.org) will then take your translation and confirm that it builds. In particular, the following things will be looked at: - Do all your files use RCS strings (such as "ID"). + Do all your files use RCS strings (such as "ID")? Does make all in the - sv directory work correctly. + sv directory work correctly? - Does make install work correctly. + Does make install work correctly? If there are any problems then whoever is looking at the submission will get back to you to try and work them out. - If there are no problems then your translation will be committed + If there are no problems your translation will be committed as soon as possible. Can I include language or country specific text in my translation? We would prefer that you did not. For example, suppose that you are translating the Handbook to Korean, and want to include a section about retailers in Korea in your Handbook. There's no real reason why that information should not be in the English (or German, or Spanish, or Japanese, or …) versions as well. It is feasible that an English speaker in Korea might try and pick up a copy of FreeBSD whilst over there. It also helps increase FreeBSD's perceived presence around the globe, which is not a bad thing. If you have country specific information, please submit it as a change to the English Handbook (using &man.send-pr.1;) and then translate the change back to your language in the translated Handbook. Thanks. How should language specific characters be included? Non-ASCII characters in the documentation should be included using SGML entities. Briefly, these look like an ampersand (&), the name of the entity, and a semi-colon (;). The entity names are defined in ISO8879, which is in the ports tree as textproc/iso8879. A few examples include &eacute; é Small “e” with an acute accent &Eacute; É Large “E” with an acute accent &uuml; ü Small “u” with an umlaut After you have installed the iso8879 port, the files in /usr/local/share/sgml/iso8879 contain the complete list. Addressing the reader In the English documents, the reader is addressed as “you”, there is no formal/informal distinction as there is in some languages. If you are translating to a language which does distinguish, use whichever form is typically used in other technical documentation in your language. If in doubt, use a mildly polite form. Do I need to include any additional information in my translations? Yes. The header of the English version of each document will look something like this; ]]> The exact boilerplate may change, but it will always include an Id line and the phrase The FreeBSD Documentation Project. Your translated documents should include their own Id line, and change the FreeBSD Documentation Project line to The FreeBSD language Documentation Project. In addition, you should add a third line which indicates which revision of the English text this is based on. So, the Spanish version of this file might start ]]>