diff --git a/en/tutorials/docproj-primer/Makefile b/en/tutorials/docproj-primer/Makefile new file mode 100644 index 0000000000..6321390a6d --- /dev/null +++ b/en/tutorials/docproj-primer/Makefile @@ -0,0 +1,38 @@ +# +# $Id: Makefile,v 1.1 1999-04-20 20:59:49 nik Exp $ +# +# Build the FreeBSD Documentation Project Primer. +# + +MAINTAINER=nik@FreeBSD.ORG + +DOC?= book + +FORMATS?= html-split + +INSTALL_COMPRESSED?= gz +INSTALL_ONLY_COMPRESSED?= + +# +# SRCS lists the individual SGML files that make up the document. Changes +# to any of these files will force a rebuild +# + +# SGML content +SRCS= book.sgml +SRCS+= overview/chapter.sgml +SRCS+= psgml-mode/chapter.sgml +SRCS+= see-also/chapter.sgml +SRCS+= sgml-markup/chapter.sgml +SRCS+= sgml-primer/chapter.sgml +SRCS+= stylesheets/chapter.sgml +SRCS+= the-faq/chapter.sgml +SRCS+= the-handbook/chapter.sgml +SRCS+= the-website/chapter.sgml +SRCS+= tools/chapter.sgml +SRCS+= writing-style/chapter.sgml + +# Entities +SRCS+= chapters.ent + +.include "../../../share/mk/docproj.docbook.mk" diff --git a/en/tutorials/docproj-primer/book.sgml b/en/tutorials/docproj-primer/book.sgml new file mode 100644 index 0000000000..2355b1683d --- /dev/null +++ b/en/tutorials/docproj-primer/book.sgml @@ -0,0 +1,278 @@ + + + +%man; + + %chapters; +]> + + + + FreeBSD Documentation Project Primer for New Contributors + + + Nik + Clayton + +
nik@FreeBSD.ORG
+ + + + + 1998 + 1999 + Nik Clayton + + + $Date: 1999-04-20 20:59:49 $ + + $ID$ + + + Redistribution and use in source (SGML DocBook) and 'compiled' + forms (SGML, HTML, PDF, PostScript, RTF and so forth) with or without + modification, are permitted provided that the following conditions are + met: + + + + Redistributions of source code (SGML DocBook) must retain the + above copyright notice, this list of conditions and the following + disclaimer as the first lines of this file unmodified. + + + + Redistributions in compiled form (transformed to other DTDs, + converted to PDF, PostScript, RTF and other formats) must + reproduce the above copyright notice, this list of conditions and + the following disclaimer in the documentation and/or other + materials provided with the distribution. + + + + + THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY + EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR + PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR + ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR + BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF + LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING + NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS + DOCUMENTATION, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH + DAMAGE. + + + + + Thank you for becoming a part of the FreeBSD Documentation + Project. Your contribution is extremely valuable. + + This primer covers everything you will need to know in order + to start contributing to the FreeBSD Documentation Project, from + the tools and software you will be using (both mandatory and + recommended) to the philosophy behind the Documentation + Project. + + This document is a work in progress, and is not complete. Sections + that are known to be incomplete are indicated with a + * in their name. + + + + + Preface + + + Shell Prompts + + The following table shows the default system prompt and superuser + prompt. The examples will use this prompt to indicate which user you + should be running the example as. + + + + + + User + Prompt + + + + + + Normal user + &prompt.user; + + + + root + &prompt.root; + + + + + + + + Typographic Conventions + + The following table describes the typographic conventions used in + this book. + + + + + + Meaning + Examples + + + + + + The name of commands, files, and directories. On screen + computer output. + Edit your .login + file.Use ls -a to list all + files.You have mail. + + + + + What you type, when contrasted with on-screen computer + output. + + &prompt.user; su +Password: + + + + Manual page references. + + Use + su + 1 + to change user names. + + + + User and group names + + Only root can do this. + + + + Emphasis + + You must do this. + + + + Command line variables; replace with the real name or + variable. + + To delete a file, type rm filename + + + + Environment variables + + $HOME is your home directory. + + + + + + + + Notes, warnings, and examples + + Within the text appear notes, warnings, and examples. + + + Notes are represented like this, and contain information that + you should take note of, as it may affect what you do. + + + + Warnings are represented like this, and contain information + warning you about possible damage if you do not follow the + instructions. This damage may be physical, to your hardware or to + you, or it may be non-physical, such as the inadvertant deletion of + important files. + + + + A sample example + + Examples are represented like this, and typically contain + examples you should walk through, or show you what the results of a + particular action should be. + + + + + Acknowledgments + + My thanks to Sue Blake, Patrick Durusau, Jon Hamilton, Peter + Flynn, and Christopher Maden, who took the time to read early drafts + of this document and offer many valuable comments and + criticisms. + + + + &chap.overview; + &chap.sgml-primer; + &chap.tools; + &chap.sgml-markup; + &chap.stylesheets; + &chap.the-faq; + &chap.the-handbook; + &chap.the-website; + &chap.writing-style; + &chap.psgml-mode; + &chap.see-also; + + + + diff --git a/en/tutorials/docproj-primer/chapter.decl b/en/tutorials/docproj-primer/chapter.decl new file mode 100644 index 0000000000..494cb2946d --- /dev/null +++ b/en/tutorials/docproj-primer/chapter.decl @@ -0,0 +1 @@ + diff --git a/en/tutorials/docproj-primer/chapters.ent b/en/tutorials/docproj-primer/chapters.ent new file mode 100644 index 0000000000..974039f391 --- /dev/null +++ b/en/tutorials/docproj-primer/chapters.ent @@ -0,0 +1,22 @@ + + + + + + + + + + + + + diff --git a/en/tutorials/docproj-primer/overview/chapter.sgml b/en/tutorials/docproj-primer/overview/chapter.sgml new file mode 100644 index 0000000000..84fef1dc71 --- /dev/null +++ b/en/tutorials/docproj-primer/overview/chapter.sgml @@ -0,0 +1,89 @@ + + + + Overview + + Welcome to the FreeBSD Documentation Project, and thank you for + volunteering. One of the keys to the success of a project such as FreeBSD + is the availability of good quality documentation, and your contribution + will help that success. + + After you have read this primer you should; + + + + Have an understanding of the text formats used by the + Documentation Project, and why they were chosen. + + + + Be able to read and understand the source code for the Handbook, + FAQ, and website, and follow how they are converted into HTML, + PostScript, and other formats. + + + + Be able to make changes to the documentation, test them, and + either contribute them back to the project or (if you have commit + privileges) commit them. + + + + This primer assumes that you already understand; + + + + How to maintain an up-to-date copy of the FreeBSD CVS tree using + CVS and one of CVSup or CTM, and how to check out particular versions + of files. + + Alternatively, how to retrieve versions of files using the + CVSWeb interface. + + + + How to use the ports system to download and install new + software. + + + + + + diff --git a/en/tutorials/docproj-primer/psgml-mode/chapter.sgml b/en/tutorials/docproj-primer/psgml-mode/chapter.sgml new file mode 100644 index 0000000000..5208c5f016 --- /dev/null +++ b/en/tutorials/docproj-primer/psgml-mode/chapter.sgml @@ -0,0 +1,148 @@ + + + + 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, + 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/tutorials/docproj-primer/see-also/chapter.sgml b/en/tutorials/docproj-primer/see-also/chapter.sgml new file mode 100644 index 0000000000..eaecab8f99 --- /dev/null +++ b/en/tutorials/docproj-primer/see-also/chapter.sgml @@ -0,0 +1,119 @@ + + + + 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 + + + + The HTML 4.0 + specification + + + + + + DocBook + + + + The Davenport + Group, maintainers of the DocBook DTD + + + + + + The Linux Documentation Project + + + + The Linux Documentation + Project web pages + + + + + + + diff --git a/en/tutorials/docproj-primer/sgml-markup/chapter.sgml b/en/tutorials/docproj-primer/sgml-markup/chapter.sgml new file mode 100644 index 0000000000..e749463375 --- /dev/null +++ b/en/tutorials/docproj-primer/sgml-markup/chapter.sgml @@ -0,0 +1,2210 @@ + + + + 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;

+ +
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. 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. + +

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

    + +

    This is the second paragraph of the second item.

    3. + +

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

    4. +
]]> + + + + 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 cellTop right cell
Bottom left cellBottom 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 cellBottom cell
]]> + + + + Using <literal>colspan</literal> + + Use: + + +One long cell on top, two short cells below it.

+ + + + + + + + + + + +
Top cell
Bottom left cellBottom 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 cellTop right cell
Middle right cell
Bottom left cellBottom middle cellBottom 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. + + + <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 + 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. + + + + + 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.0-Based Extension//EN" + + + + Sectional elements + + DocBook contains a number of elements for marking up the structure + of a book. + + Generally, the top level (first) element will be + book. + + 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. + + + 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> + + + + + Indicating chapters + + Use chapter to mark up your chapters. Each + chapter has a mandatory title. + + + A simple chapter + + + + The chapter's title + + ... +]]> + + + A chapter can not 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 + + Chapters can be broken up into sections, subsections, and so + on. 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) + + ... + + +]]> + + + + + Subdividing using <sgmltag>part</sgmltag>s + + You can introduce another layer of organisation between + book and chapter with one or + more parts. + + + + Introduction + + + Overview + + ... + + + + What is FreeBSD? + + ... + + + + History + + ... + +]]> + + + + + Block elements + + + 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</para> + + <attribution>Copied from a web site somewhere</attribution> + + <para>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.</para> +</blockquote>]]></programlisting> + + <para>Appearance:</para> + + <blockquote> + <title>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 + HTML, ul and ol. Each one + consists of one or more listentry elements, and + each listentry contains one or more block + elements. The listentry elements are analagous to + HTMLs 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. + +]]> + + 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. + + + + + + + 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 closing tag should + appear on the same line as the last line of the output, otherwise a + spurious blank line will 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. + + + + informalexample + + + Most of the time these examples will occur + “mid-flow” as it were, and you won't need to put a + title on them. So, most of the time, the outermost element + will be informalexample. For those times + when you do need to include a title on the example, use + example. + + + + + 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>informalexample</sgmltag>, + <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 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 + 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 + (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; + + PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN" + + Therefore, the introduction to your documentation will probably + look like this; + + <!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook V3.0-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 + 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 + 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/tutorials/docproj-primer/sgml-primer/chapter.sgml b/en/tutorials/docproj-primer/sgml-primer/chapter.sgml new file mode 100644 index 0000000000..c25bacf1f1 --- /dev/null +++ b/en/tutorials/docproj-primer/sgml-primer/chapter.sgml @@ -0,0 +1,1554 @@ + + + + SGML Primer + + The Documentation Project makes heavy use of the Standard Generalized + Markup Language (SGML). This chapter describes what SGML is, how to read + and understand markup, and some of the SGML tricks you will see used in + the FAQ, Handbook, and website. + + 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 the 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;. + + 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 they are 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 of 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. + + SGML is not a markup langugage. Instead, SGML + is the language in which you write markup + languages. There have been many markup languages written + using SGML. HTML and DocBook are two of these. + + This is an important point to understand. Most of the time you are + not writing SGML documents. Instead, you are writing documents in a + particular markup language. The definition of the markup language you + are using is written in SGML. + + Each language definition (which is written in SGML) 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 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 a + parser which reads in 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 philisophy 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 types of content. + + Of course, we don't 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 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/3.0/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/3.0/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 is passed as a parameter to + it, &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. + + + + + + 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 the + it. + + This information is generally expressed on one line, in the DOCTYPE + declaration. + + A typical declaration for 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/3.0/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 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 delimiters 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 an SGML term. You might feel more comfortable thinking + of them as variables. There are two types of entity in SGML, general + entities and parameter entities. + + + General Entities + + General entities are a way of assigning names to chunks of text, + and reusing that text (which may contain markup) throughout your + document. + + 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 normally include in an SGML document. For example, < and + & can not normally appear in an SGML document. Normally, when the + SGML processor sees a < symbol it assumes that a tag (either a start + tag or an end tag) is about to appear, and when it sees a & 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 don't do 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. Normalising it involves converting all the entity + references to the values of those entities. + + 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) come into their own + when you realise they can be used to include other files. + + + 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; + + + + + +]]> + + + + 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 <!. + + 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 processor 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. + + + + + + + diff --git a/en/tutorials/docproj-primer/stylesheets/chapter.sgml b/en/tutorials/docproj-primer/stylesheets/chapter.sgml new file mode 100644 index 0000000000..85e5855414 --- /dev/null +++ b/en/tutorials/docproj-primer/stylesheets/chapter.sgml @@ -0,0 +1,68 @@ + + + + * Stylesheets + + SGML says nothing about how a document should be displayed to the + user, or rendered on paper. To do that, various languages have been + developed to describe stylesheets, including DynaText, Panorama, SPICE, + JSSS, FOSI, CSS, and DSSSL. + + For DocBook, we are using stylesheets written in DSSSL. For HTML we + are using CSS. + + + * DSSSL + + The Documentation Project uses a slightly customised version of + Norm Walsh's modular DocBook stylesheets. + + These can be found in + textproc/dsssl-docbook-modular. + + + + * CSS + + + + + + diff --git a/en/tutorials/docproj-primer/the-faq/chapter.sgml b/en/tutorials/docproj-primer/the-faq/chapter.sgml new file mode 100644 index 0000000000..24cc68a30a --- /dev/null +++ b/en/tutorials/docproj-primer/the-faq/chapter.sgml @@ -0,0 +1,47 @@ + + + + * The FAQ + + + + + + diff --git a/en/tutorials/docproj-primer/the-handbook/chapter.sgml b/en/tutorials/docproj-primer/the-handbook/chapter.sgml new file mode 100644 index 0000000000..9b860d2e7f --- /dev/null +++ b/en/tutorials/docproj-primer/the-handbook/chapter.sgml @@ -0,0 +1,280 @@ + + + + * The Handbook + + + Logical structure + + The Handbook is written to comply with the FreeBSD DocBook extended + DTD. + + The Handbook is organised as a DocBook book. It + is then divided into parts, each of which may contain + several chapters. chapters are + further subdivided into sections (sect1) and + subsections (sect2, sect3) and so + on. + + + + Physical organisation + + The Handbook (and its translations) are in the + doc/language/handbook + subdirectory of the main CVS + repository. language corresponds to the ISO + language code for that translation, en for English, + ja for Japanese, and so on. + + There are a number of files and directories within the + handbook directory. + + + The Handbook's organisation may change over time, and this + document may lag in detailing the organisational changes. If you have + any questions about how the Handbook is organised, please contact the + FreeBSD Documentation Project, doc@FreeBSD.ORG. + + + + <filename>Makefile</filename> + + The Makefile defines the rules that are used + to convert the Handbook from its source form (DocBook) to a number of + other target formats (including HTML, PostScript, and plain + text). + + A more detailed description of the Makefile + is in . + + + + <filename>handbook.sgml</filename> + + This is the top level document in the Handbook. It contains the + Handbook's DOCTYPE + declaration, as well as the elements that describe the + Handbook's structure. + + handbook.sgml uses parameter entities to load in + the files with the .ent extension. These files + (described later) then define general + entities that are used throughout the rest of the + Handbook. + + + + <filename><replaceable>directory</replaceable>/chapter.sgml</filename> + + Each chapter in the Handbook is stored in a file called + chapter.sgml in a separate directory from the + other chapters. Each directory is named after the value of the + id attribute on the chapter + element. + + For example, if one of the chapter files contains: + + +... +]]> + + then it will be called chapter.sgml in the + kernelconfiguration directory. In general, the + entire contents of the chapter will be held in this file. + + When the HTML version of the Handbook is produced, this will yield + kernelconfiguration.html. This is because of the + id value, and is not related to the name of the + directory. + + In earlier versions of the Handbook the files were stored in the + same directory as handbook.sgml, and named after + the value of the id attribute on the file's + chapter element. Moving them in to separate + directories prepares for future plans for the Handbook. Specifically, + it will soon be possible to include images in each chapter. It + makes more sense for each image to be stored in a directory with the + text for the chapter than to try and keep the text for all the + chapters, and all the images, in one large directory. Namespace + collisions would be inevitable, and it is easier to work with several + directories with a few files in them than it is to work with one + directory that has many files in it. + + A brief look will show that there are many directories with + individual chapter.sgml files, including + basics/chapter.sgml, + introduction/chapter.sgml, and + printing/chapter.sgml. + + + Chapters and/or directories should not be named in a fashion + that reflects their ordering within the Handbook. This ordering + might change as the content within the Handbook is reorganised; this + sort of reorganistion should not (generally) include the need to + rename files (unless entire chapters are being promoted or demoted + within the hierarchy). + + + Each chapter.sgml file will not be a complete + SGML document. In particular, they will not have their own DOCTYPE + line at the start of the file. + + This is unfortunate for two reasons; + + + + It makes it impossible to treat these as generic SGML files + and simply convert them to HTML, RTF, PS, and other formats in the + same way the main Handbook is generated. This + would force you to rebuild the Handbook every + time you want to see the effect a change as had on just one + chapter. + + + + Emacs' sgml-mode can not use it to + determine the DTD to use, losing useful benefits of + sgml-mode (element completion, automatic + validation, and so on). + + + + + + + Style guide + + To keep the source for the Handbook consistent when many different + people are editing it, please follow these style conventions. + + + Letter case + + Tags are entered in lower case, <para>, + not <PARA>. + + Text that appears in SGML contexts is generally written in upper + case, <!ENTITY…>, and + <!DOCTYPE…>, not + <!entity…> and + <!doctype…>. + + + + Indentation + + Each file starts with indentation set at column 0, + regardless of the indentation level of the file + which might contain this one. + + Every start tag increases the indentation level by 2 spaces, and + every end tag decreases the indentation level by 2 spaces. Content + within elements should be indented by two spaces if the content runs + over more than one line. + + For example, the source for this section looks something + like; + + + + ... + + + ... + + + Indentation + + Each file starts with indentation set at column 0, + regardless of the indentation level of the file + which might contain this one. + + Every start tag increases the indentation level by 2 spaces, and + every end tag decreases the indentation level by 2 spaces. Content + within elements should be indented by two spaces if the content runs + over more than one line. + + ... + + +]]> + + If you use Emacs or + Xemacs to edit the files then + sgml-mode should be loaded automatically, and the + Emacs local variables at the bottom of each file should enforce these + styles. + + + + White space changes + + When committing changes, do not commit changes to the + content at the same time as changes to the + formatting. + + This is so that the teams that convert the Handbook to other + languages can quickly see what content has actually changed in your + commit, without having to decide whether a line has changed because of + the content, or just because it has been refilled. + + For example, if you have added two sentances to a paragraph, such + that the line lengths on the paragraph now go over 80 columns, first + commit your change with the too-long line lengths. Then fix the line + wrapping, and commit this second change. In the commit message for the + second change, be sure to indicate that this is a whitespace-only + change, and that the translation team can ignore it. + + + + + Converting the Handbook to other formats + + + + + + + diff --git a/en/tutorials/docproj-primer/the-website/chapter.sgml b/en/tutorials/docproj-primer/the-website/chapter.sgml new file mode 100644 index 0000000000..01e4e129f5 --- /dev/null +++ b/en/tutorials/docproj-primer/the-website/chapter.sgml @@ -0,0 +1,47 @@ + + + + * The Website + + + + + + diff --git a/en/tutorials/docproj-primer/tools/chapter.sgml b/en/tutorials/docproj-primer/tools/chapter.sgml new file mode 100644 index 0000000000..2080134fad --- /dev/null +++ b/en/tutorials/docproj-primer/tools/chapter.sgml @@ -0,0 +1,210 @@ + + * Tools + + The Documentation Project uses a number of tools to assist in the + production of documentation. You will need to install some or all of these + tools before you will be able to make changes. + + + 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. + + 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. + + + + Software + + The project uses the following applications; + + + + Jade and + SP + + + These are two application suites by James Clark, who has + produced many useful SGML-processing applications. + Jade is “James' DSSSL + Engine”, a system that takes SGML documentation and a DSSSL + stylesheet and produces converted output. + SP contains a number of useful + applications to manipulate, normalise, and interrogate SGML + documents. + + Don't be concerned if these terms are unfamliar to you. + + They can be found in the ports system as + textproc/jade and + textproc/sp respectively. + + + Installed as part of + textproc/docproj. + + + + + + teTeX + + + teTeX is a distrubution of the TeX + typesetting system, and is used (in conjunction with Jade) to + produce the Postscript and PDF output formats. + + v0.9 of teTeX is required, which is + currently in the ports collection as + print/teTeX-beta. + + + Might be installed as part of + textproc/docproj, depending on the + JADETEX setting. + + + + + + Emacs or + Xemacs + + + Neither of these programs is required. However, both of them + feature PSGML-MODE, a useful extension when dealing with SGML + documents that can reduce the amount of typing you need to do, and + remove some of the more obvious errors. + + They can be found in editor/emacs20 and + editor/xemacs20. + + + Not installed as part of + textproc/docproj. + + + + + + + + Document Type Definitions (DTDs) + + The project uses the following DTDs; + + + + 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 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 category. + + + Installed as part of + textproc/docproj. + + + + + + LinuxDoc + + + LinuxDoc is an adaptation of the QWERTZ DTD, first adopted by + the 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. + + + Installed as part of + textproc/docproj. + + + + + + DocBook + + + DocBook was designed by the Davenport Group + to be a DTD for writing technical documentation. As such, it + contains XXX + + + Installed as part of + textproc/docproj. + + + + + + + + DSSSL Stylesheets + + The Documentation Project uses a slightly customised version of + Norm Walsh's modular DocBook stylesheets. + + These can be found in + textproc/dsssl-docbook-modular. + + + Installed as part of textproc/docproj. + + + + + diff --git a/en/tutorials/docproj-primer/writing-style/chapter.sgml b/en/tutorials/docproj-primer/writing-style/chapter.sgml new file mode 100644 index 0000000000..07361a43be --- /dev/null +++ b/en/tutorials/docproj-primer/writing-style/chapter.sgml @@ -0,0 +1,137 @@ + + + + Writing style + + In order to promote consistency between the myriad authors of the + FreeBSD documentation, some guidelines have been drawn up for authors to + follow. + + + + Do not use contractions + + + Do not use contractions. Always spell the phrase out in full. + “Don't use contractions” would be wrong. + + Avoiding contractions makes for a more formal tone, is more + precise, and slightly easier for translators. + + + + + Use the serial comma + + + In a list of items within a paragraph, seperate each item from + the others with a comma. Seperate the last item from the others with + a comma and the word “and”. + + For example, look at the following quote; + +
+ This is a list of one, two and three items. +
+ + Is this a list of three items, “one”, + “two”, and “three”, or a list of two items, + “one” and “two and three”? + + It is better to be explicit and include a serial comma; + +
+ This is a list of one, two, and three items. +
+ + + + + Avoid redundant phrases + + + Try not to use redundant phrases. In particular, “the + command”, “the file”, and “man + command” are probably redundant. + + These two examples show this for commands. The second example + is preferred. + + + Use the command cvsup to update your + sources + + + + Use cvsup to update your sources + + + These two examples show this for filenames. The second example + is preferred. + + + … in the filename + /etc/rc.local… + + + + … in + /etc/rc.local… + + + These two examples show this for manual references. The second + example is preferred (the second example uses + citerefentry). + + + See man csh for more + information. + + + + See &man.csh.1; + + + + + + + + diff --git a/en_US.ISO8859-1/books/fdp-primer/Makefile b/en_US.ISO8859-1/books/fdp-primer/Makefile new file mode 100644 index 0000000000..6321390a6d --- /dev/null +++ b/en_US.ISO8859-1/books/fdp-primer/Makefile @@ -0,0 +1,38 @@ +# +# $Id: Makefile,v 1.1 1999-04-20 20:59:49 nik Exp $ +# +# Build the FreeBSD Documentation Project Primer. +# + +MAINTAINER=nik@FreeBSD.ORG + +DOC?= book + +FORMATS?= html-split + +INSTALL_COMPRESSED?= gz +INSTALL_ONLY_COMPRESSED?= + +# +# SRCS lists the individual SGML files that make up the document. Changes +# to any of these files will force a rebuild +# + +# SGML content +SRCS= book.sgml +SRCS+= overview/chapter.sgml +SRCS+= psgml-mode/chapter.sgml +SRCS+= see-also/chapter.sgml +SRCS+= sgml-markup/chapter.sgml +SRCS+= sgml-primer/chapter.sgml +SRCS+= stylesheets/chapter.sgml +SRCS+= the-faq/chapter.sgml +SRCS+= the-handbook/chapter.sgml +SRCS+= the-website/chapter.sgml +SRCS+= tools/chapter.sgml +SRCS+= writing-style/chapter.sgml + +# Entities +SRCS+= chapters.ent + +.include "../../../share/mk/docproj.docbook.mk" diff --git a/en_US.ISO8859-1/books/fdp-primer/book.sgml b/en_US.ISO8859-1/books/fdp-primer/book.sgml new file mode 100644 index 0000000000..2355b1683d --- /dev/null +++ b/en_US.ISO8859-1/books/fdp-primer/book.sgml @@ -0,0 +1,278 @@ + + + +%man; + + %chapters; +]> + + + + FreeBSD Documentation Project Primer for New Contributors + + + Nik + Clayton + +
nik@FreeBSD.ORG
+ + + + + 1998 + 1999 + Nik Clayton + + + $Date: 1999-04-20 20:59:49 $ + + $ID$ + + + Redistribution and use in source (SGML DocBook) and 'compiled' + forms (SGML, HTML, PDF, PostScript, RTF and so forth) with or without + modification, are permitted provided that the following conditions are + met: + + + + Redistributions of source code (SGML DocBook) must retain the + above copyright notice, this list of conditions and the following + disclaimer as the first lines of this file unmodified. + + + + Redistributions in compiled form (transformed to other DTDs, + converted to PDF, PostScript, RTF and other formats) must + reproduce the above copyright notice, this list of conditions and + the following disclaimer in the documentation and/or other + materials provided with the distribution. + + + + + THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY + EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR + PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR + ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR + BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF + LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING + NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS + DOCUMENTATION, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH + DAMAGE. + + + + + Thank you for becoming a part of the FreeBSD Documentation + Project. Your contribution is extremely valuable. + + This primer covers everything you will need to know in order + to start contributing to the FreeBSD Documentation Project, from + the tools and software you will be using (both mandatory and + recommended) to the philosophy behind the Documentation + Project. + + This document is a work in progress, and is not complete. Sections + that are known to be incomplete are indicated with a + * in their name. + + + + + Preface + + + Shell Prompts + + The following table shows the default system prompt and superuser + prompt. The examples will use this prompt to indicate which user you + should be running the example as. + + + + + + User + Prompt + + + + + + Normal user + &prompt.user; + + + + root + &prompt.root; + + + + + + + + Typographic Conventions + + The following table describes the typographic conventions used in + this book. + + + + + + Meaning + Examples + + + + + + The name of commands, files, and directories. On screen + computer output. + Edit your .login + file.Use ls -a to list all + files.You have mail. + + + + + What you type, when contrasted with on-screen computer + output. + + &prompt.user; su +Password: + + + + Manual page references. + + Use + su + 1 + to change user names. + + + + User and group names + + Only root can do this. + + + + Emphasis + + You must do this. + + + + Command line variables; replace with the real name or + variable. + + To delete a file, type rm filename + + + + Environment variables + + $HOME is your home directory. + + + + + + + + Notes, warnings, and examples + + Within the text appear notes, warnings, and examples. + + + Notes are represented like this, and contain information that + you should take note of, as it may affect what you do. + + + + Warnings are represented like this, and contain information + warning you about possible damage if you do not follow the + instructions. This damage may be physical, to your hardware or to + you, or it may be non-physical, such as the inadvertant deletion of + important files. + + + + A sample example + + Examples are represented like this, and typically contain + examples you should walk through, or show you what the results of a + particular action should be. + + + + + Acknowledgments + + My thanks to Sue Blake, Patrick Durusau, Jon Hamilton, Peter + Flynn, and Christopher Maden, who took the time to read early drafts + of this document and offer many valuable comments and + criticisms. + + + + &chap.overview; + &chap.sgml-primer; + &chap.tools; + &chap.sgml-markup; + &chap.stylesheets; + &chap.the-faq; + &chap.the-handbook; + &chap.the-website; + &chap.writing-style; + &chap.psgml-mode; + &chap.see-also; + + + + diff --git a/en_US.ISO8859-1/books/fdp-primer/chapter.decl b/en_US.ISO8859-1/books/fdp-primer/chapter.decl new file mode 100644 index 0000000000..494cb2946d --- /dev/null +++ b/en_US.ISO8859-1/books/fdp-primer/chapter.decl @@ -0,0 +1 @@ + diff --git a/en_US.ISO8859-1/books/fdp-primer/chapters.ent b/en_US.ISO8859-1/books/fdp-primer/chapters.ent new file mode 100644 index 0000000000..974039f391 --- /dev/null +++ b/en_US.ISO8859-1/books/fdp-primer/chapters.ent @@ -0,0 +1,22 @@ + + + + + + + + + + + + + diff --git a/en_US.ISO8859-1/books/fdp-primer/overview/chapter.sgml b/en_US.ISO8859-1/books/fdp-primer/overview/chapter.sgml new file mode 100644 index 0000000000..84fef1dc71 --- /dev/null +++ b/en_US.ISO8859-1/books/fdp-primer/overview/chapter.sgml @@ -0,0 +1,89 @@ + + + + Overview + + Welcome to the FreeBSD Documentation Project, and thank you for + volunteering. One of the keys to the success of a project such as FreeBSD + is the availability of good quality documentation, and your contribution + will help that success. + + After you have read this primer you should; + + + + Have an understanding of the text formats used by the + Documentation Project, and why they were chosen. + + + + Be able to read and understand the source code for the Handbook, + FAQ, and website, and follow how they are converted into HTML, + PostScript, and other formats. + + + + Be able to make changes to the documentation, test them, and + either contribute them back to the project or (if you have commit + privileges) commit them. + + + + This primer assumes that you already understand; + + + + How to maintain an up-to-date copy of the FreeBSD CVS tree using + CVS and one of CVSup or CTM, and how to check out particular versions + of files. + + Alternatively, how to retrieve versions of files using the + CVSWeb interface. + + + + How to use the ports system to download and install new + software. + + + + + + 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 new file mode 100644 index 0000000000..5208c5f016 --- /dev/null +++ b/en_US.ISO8859-1/books/fdp-primer/psgml-mode/chapter.sgml @@ -0,0 +1,148 @@ + + + + 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, + 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 new file mode 100644 index 0000000000..eaecab8f99 --- /dev/null +++ b/en_US.ISO8859-1/books/fdp-primer/see-also/chapter.sgml @@ -0,0 +1,119 @@ + + + + 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 + + + + The HTML 4.0 + specification + + + + + + DocBook + + + + The Davenport + Group, maintainers of the DocBook DTD + + + + + + The Linux Documentation Project + + + + 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 new file mode 100644 index 0000000000..e749463375 --- /dev/null +++ b/en_US.ISO8859-1/books/fdp-primer/sgml-markup/chapter.sgml @@ -0,0 +1,2210 @@ + + + + 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;

+ +
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. 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. + +

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

    + +

    This is the second paragraph of the second item.

    3. + +

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

    4. +
]]> + + + + 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 cellTop right cell
Bottom left cellBottom 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 cellBottom cell
]]> + + + + Using <literal>colspan</literal> + + Use: + + +One long cell on top, two short cells below it.

+ + + + + + + + + + + +
Top cell
Bottom left cellBottom 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 cellTop right cell
Middle right cell
Bottom left cellBottom middle cellBottom 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. + + + <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 + 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. + + + + + 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.0-Based Extension//EN" + + + + Sectional elements + + DocBook contains a number of elements for marking up the structure + of a book. + + Generally, the top level (first) element will be + book. + + 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. + + + 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> + + + + + Indicating chapters + + Use chapter to mark up your chapters. Each + chapter has a mandatory title. + + + A simple chapter + + + + The chapter's title + + ... +]]> + + + A chapter can not 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 + + Chapters can be broken up into sections, subsections, and so + on. 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) + + ... + + +]]> + + + + + Subdividing using <sgmltag>part</sgmltag>s + + You can introduce another layer of organisation between + book and chapter with one or + more parts. + + + + Introduction + + + Overview + + ... + + + + What is FreeBSD? + + ... + + + + History + + ... + +]]> + + + + + Block elements + + + 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</para> + + <attribution>Copied from a web site somewhere</attribution> + + <para>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.</para> +</blockquote>]]></programlisting> + + <para>Appearance:</para> + + <blockquote> + <title>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 + HTML, ul and ol. Each one + consists of one or more listentry elements, and + each listentry contains one or more block + elements. The listentry elements are analagous to + HTMLs 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. + +]]> + + 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. + + + + + + + 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 closing tag should + appear on the same line as the last line of the output, otherwise a + spurious blank line will 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. + + + + informalexample + + + Most of the time these examples will occur + “mid-flow” as it were, and you won't need to put a + title on them. So, most of the time, the outermost element + will be informalexample. For those times + when you do need to include a title on the example, use + example. + + + + + 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>informalexample</sgmltag>, + <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 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 + 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 + (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; + + PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN" + + Therefore, the introduction to your documentation will probably + look like this; + + <!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook V3.0-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 + 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 + 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 new file mode 100644 index 0000000000..c25bacf1f1 --- /dev/null +++ b/en_US.ISO8859-1/books/fdp-primer/sgml-primer/chapter.sgml @@ -0,0 +1,1554 @@ + + + + SGML Primer + + The Documentation Project makes heavy use of the Standard Generalized + Markup Language (SGML). This chapter describes what SGML is, how to read + and understand markup, and some of the SGML tricks you will see used in + the FAQ, Handbook, and website. + + 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 the 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;. + + 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 they are 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 of 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. + + SGML is not a markup langugage. Instead, SGML + is the language in which you write markup + languages. There have been many markup languages written + using SGML. HTML and DocBook are two of these. + + This is an important point to understand. Most of the time you are + not writing SGML documents. Instead, you are writing documents in a + particular markup language. The definition of the markup language you + are using is written in SGML. + + Each language definition (which is written in SGML) 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 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 a + parser which reads in 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 philisophy 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 types of content. + + Of course, we don't 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 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/3.0/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/3.0/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 is passed as a parameter to + it, &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. + + + + + + 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 the + it. + + This information is generally expressed on one line, in the DOCTYPE + declaration. + + A typical declaration for 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/3.0/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 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 delimiters 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 an SGML term. You might feel more comfortable thinking + of them as variables. There are two types of entity in SGML, general + entities and parameter entities. + + + General Entities + + General entities are a way of assigning names to chunks of text, + and reusing that text (which may contain markup) throughout your + document. + + 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 normally include in an SGML document. For example, < and + & can not normally appear in an SGML document. Normally, when the + SGML processor sees a < symbol it assumes that a tag (either a start + tag or an end tag) is about to appear, and when it sees a & 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 don't do 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. Normalising it involves converting all the entity + references to the values of those entities. + + 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) come into their own + when you realise they can be used to include other files. + + + 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; + + + + + +]]> + + + + 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 <!. + + 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 processor 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. + + + + + + + diff --git a/en_US.ISO8859-1/books/fdp-primer/stylesheets/chapter.sgml b/en_US.ISO8859-1/books/fdp-primer/stylesheets/chapter.sgml new file mode 100644 index 0000000000..85e5855414 --- /dev/null +++ b/en_US.ISO8859-1/books/fdp-primer/stylesheets/chapter.sgml @@ -0,0 +1,68 @@ + + + + * Stylesheets + + SGML says nothing about how a document should be displayed to the + user, or rendered on paper. To do that, various languages have been + developed to describe stylesheets, including DynaText, Panorama, SPICE, + JSSS, FOSI, CSS, and DSSSL. + + For DocBook, we are using stylesheets written in DSSSL. For HTML we + are using CSS. + + + * DSSSL + + The Documentation Project uses a slightly customised version of + Norm Walsh's modular DocBook stylesheets. + + These can be found in + textproc/dsssl-docbook-modular. + + + + * CSS + + + + + + diff --git a/en_US.ISO8859-1/books/fdp-primer/the-website/chapter.sgml b/en_US.ISO8859-1/books/fdp-primer/the-website/chapter.sgml new file mode 100644 index 0000000000..01e4e129f5 --- /dev/null +++ b/en_US.ISO8859-1/books/fdp-primer/the-website/chapter.sgml @@ -0,0 +1,47 @@ + + + + * The Website + + + + + + diff --git a/en_US.ISO8859-1/books/fdp-primer/tools/chapter.sgml b/en_US.ISO8859-1/books/fdp-primer/tools/chapter.sgml new file mode 100644 index 0000000000..2080134fad --- /dev/null +++ b/en_US.ISO8859-1/books/fdp-primer/tools/chapter.sgml @@ -0,0 +1,210 @@ + + * Tools + + The Documentation Project uses a number of tools to assist in the + production of documentation. You will need to install some or all of these + tools before you will be able to make changes. + + + 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. + + 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. + + + + Software + + The project uses the following applications; + + + + Jade and + SP + + + These are two application suites by James Clark, who has + produced many useful SGML-processing applications. + Jade is “James' DSSSL + Engine”, a system that takes SGML documentation and a DSSSL + stylesheet and produces converted output. + SP contains a number of useful + applications to manipulate, normalise, and interrogate SGML + documents. + + Don't be concerned if these terms are unfamliar to you. + + They can be found in the ports system as + textproc/jade and + textproc/sp respectively. + + + Installed as part of + textproc/docproj. + + + + + + teTeX + + + teTeX is a distrubution of the TeX + typesetting system, and is used (in conjunction with Jade) to + produce the Postscript and PDF output formats. + + v0.9 of teTeX is required, which is + currently in the ports collection as + print/teTeX-beta. + + + Might be installed as part of + textproc/docproj, depending on the + JADETEX setting. + + + + + + Emacs or + Xemacs + + + Neither of these programs is required. However, both of them + feature PSGML-MODE, a useful extension when dealing with SGML + documents that can reduce the amount of typing you need to do, and + remove some of the more obvious errors. + + They can be found in editor/emacs20 and + editor/xemacs20. + + + Not installed as part of + textproc/docproj. + + + + + + + + Document Type Definitions (DTDs) + + The project uses the following DTDs; + + + + 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 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 category. + + + Installed as part of + textproc/docproj. + + + + + + LinuxDoc + + + LinuxDoc is an adaptation of the QWERTZ DTD, first adopted by + the 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. + + + Installed as part of + textproc/docproj. + + + + + + DocBook + + + DocBook was designed by the Davenport Group + to be a DTD for writing technical documentation. As such, it + contains XXX + + + Installed as part of + textproc/docproj. + + + + + + + + DSSSL Stylesheets + + The Documentation Project uses a slightly customised version of + Norm Walsh's modular DocBook stylesheets. + + These can be found in + textproc/dsssl-docbook-modular. + + + Installed as part of textproc/docproj. + + + + + diff --git a/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.sgml b/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.sgml new file mode 100644 index 0000000000..07361a43be --- /dev/null +++ b/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.sgml @@ -0,0 +1,137 @@ + + + + Writing style + + In order to promote consistency between the myriad authors of the + FreeBSD documentation, some guidelines have been drawn up for authors to + follow. + + + + Do not use contractions + + + Do not use contractions. Always spell the phrase out in full. + “Don't use contractions” would be wrong. + + Avoiding contractions makes for a more formal tone, is more + precise, and slightly easier for translators. + + + + + Use the serial comma + + + In a list of items within a paragraph, seperate each item from + the others with a comma. Seperate the last item from the others with + a comma and the word “and”. + + For example, look at the following quote; + +
+ This is a list of one, two and three items. +
+ + Is this a list of three items, “one”, + “two”, and “three”, or a list of two items, + “one” and “two and three”? + + It is better to be explicit and include a serial comma; + +
+ This is a list of one, two, and three items. +
+ + + + + Avoid redundant phrases + + + Try not to use redundant phrases. In particular, “the + command”, “the file”, and “man + command” are probably redundant. + + These two examples show this for commands. The second example + is preferred. + + + Use the command cvsup to update your + sources + + + + Use cvsup to update your sources + + + These two examples show this for filenames. The second example + is preferred. + + + … in the filename + /etc/rc.local… + + + + … in + /etc/rc.local… + + + These two examples show this for manual references. The second + example is preferred (the second example uses + citerefentry). + + + See man csh for more + information. + + + + See &man.csh.1; + + + + + + + + diff --git a/en_US.ISO_8859-1/books/fdp-primer/Makefile b/en_US.ISO_8859-1/books/fdp-primer/Makefile new file mode 100644 index 0000000000..6321390a6d --- /dev/null +++ b/en_US.ISO_8859-1/books/fdp-primer/Makefile @@ -0,0 +1,38 @@ +# +# $Id: Makefile,v 1.1 1999-04-20 20:59:49 nik Exp $ +# +# Build the FreeBSD Documentation Project Primer. +# + +MAINTAINER=nik@FreeBSD.ORG + +DOC?= book + +FORMATS?= html-split + +INSTALL_COMPRESSED?= gz +INSTALL_ONLY_COMPRESSED?= + +# +# SRCS lists the individual SGML files that make up the document. Changes +# to any of these files will force a rebuild +# + +# SGML content +SRCS= book.sgml +SRCS+= overview/chapter.sgml +SRCS+= psgml-mode/chapter.sgml +SRCS+= see-also/chapter.sgml +SRCS+= sgml-markup/chapter.sgml +SRCS+= sgml-primer/chapter.sgml +SRCS+= stylesheets/chapter.sgml +SRCS+= the-faq/chapter.sgml +SRCS+= the-handbook/chapter.sgml +SRCS+= the-website/chapter.sgml +SRCS+= tools/chapter.sgml +SRCS+= writing-style/chapter.sgml + +# Entities +SRCS+= chapters.ent + +.include "../../../share/mk/docproj.docbook.mk" diff --git a/en_US.ISO_8859-1/books/fdp-primer/book.sgml b/en_US.ISO_8859-1/books/fdp-primer/book.sgml new file mode 100644 index 0000000000..2355b1683d --- /dev/null +++ b/en_US.ISO_8859-1/books/fdp-primer/book.sgml @@ -0,0 +1,278 @@ + + + +%man; + + %chapters; +]> + + + + FreeBSD Documentation Project Primer for New Contributors + + + Nik + Clayton + +
nik@FreeBSD.ORG
+ + + + + 1998 + 1999 + Nik Clayton + + + $Date: 1999-04-20 20:59:49 $ + + $ID$ + + + Redistribution and use in source (SGML DocBook) and 'compiled' + forms (SGML, HTML, PDF, PostScript, RTF and so forth) with or without + modification, are permitted provided that the following conditions are + met: + + + + Redistributions of source code (SGML DocBook) must retain the + above copyright notice, this list of conditions and the following + disclaimer as the first lines of this file unmodified. + + + + Redistributions in compiled form (transformed to other DTDs, + converted to PDF, PostScript, RTF and other formats) must + reproduce the above copyright notice, this list of conditions and + the following disclaimer in the documentation and/or other + materials provided with the distribution. + + + + + THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY + EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR + PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR + ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR + BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF + LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING + NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS + DOCUMENTATION, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH + DAMAGE. + + + + + Thank you for becoming a part of the FreeBSD Documentation + Project. Your contribution is extremely valuable. + + This primer covers everything you will need to know in order + to start contributing to the FreeBSD Documentation Project, from + the tools and software you will be using (both mandatory and + recommended) to the philosophy behind the Documentation + Project. + + This document is a work in progress, and is not complete. Sections + that are known to be incomplete are indicated with a + * in their name. + + + + + Preface + + + Shell Prompts + + The following table shows the default system prompt and superuser + prompt. The examples will use this prompt to indicate which user you + should be running the example as. + + + + + + User + Prompt + + + + + + Normal user + &prompt.user; + + + + root + &prompt.root; + + + + + + + + Typographic Conventions + + The following table describes the typographic conventions used in + this book. + + + + + + Meaning + Examples + + + + + + The name of commands, files, and directories. On screen + computer output. + Edit your .login + file.Use ls -a to list all + files.You have mail. + + + + + What you type, when contrasted with on-screen computer + output. + + &prompt.user; su +Password: + + + + Manual page references. + + Use + su + 1 + to change user names. + + + + User and group names + + Only root can do this. + + + + Emphasis + + You must do this. + + + + Command line variables; replace with the real name or + variable. + + To delete a file, type rm filename + + + + Environment variables + + $HOME is your home directory. + + + + + + + + Notes, warnings, and examples + + Within the text appear notes, warnings, and examples. + + + Notes are represented like this, and contain information that + you should take note of, as it may affect what you do. + + + + Warnings are represented like this, and contain information + warning you about possible damage if you do not follow the + instructions. This damage may be physical, to your hardware or to + you, or it may be non-physical, such as the inadvertant deletion of + important files. + + + + A sample example + + Examples are represented like this, and typically contain + examples you should walk through, or show you what the results of a + particular action should be. + + + + + Acknowledgments + + My thanks to Sue Blake, Patrick Durusau, Jon Hamilton, Peter + Flynn, and Christopher Maden, who took the time to read early drafts + of this document and offer many valuable comments and + criticisms. + + + + &chap.overview; + &chap.sgml-primer; + &chap.tools; + &chap.sgml-markup; + &chap.stylesheets; + &chap.the-faq; + &chap.the-handbook; + &chap.the-website; + &chap.writing-style; + &chap.psgml-mode; + &chap.see-also; + + + + diff --git a/en_US.ISO_8859-1/books/fdp-primer/chapter.decl b/en_US.ISO_8859-1/books/fdp-primer/chapter.decl new file mode 100644 index 0000000000..494cb2946d --- /dev/null +++ b/en_US.ISO_8859-1/books/fdp-primer/chapter.decl @@ -0,0 +1 @@ + diff --git a/en_US.ISO_8859-1/books/fdp-primer/chapters.ent b/en_US.ISO_8859-1/books/fdp-primer/chapters.ent new file mode 100644 index 0000000000..974039f391 --- /dev/null +++ b/en_US.ISO_8859-1/books/fdp-primer/chapters.ent @@ -0,0 +1,22 @@ + + + + + + + + + + + + + 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 new file mode 100644 index 0000000000..84fef1dc71 --- /dev/null +++ b/en_US.ISO_8859-1/books/fdp-primer/overview/chapter.sgml @@ -0,0 +1,89 @@ + + + + Overview + + Welcome to the FreeBSD Documentation Project, and thank you for + volunteering. One of the keys to the success of a project such as FreeBSD + is the availability of good quality documentation, and your contribution + will help that success. + + After you have read this primer you should; + + + + Have an understanding of the text formats used by the + Documentation Project, and why they were chosen. + + + + Be able to read and understand the source code for the Handbook, + FAQ, and website, and follow how they are converted into HTML, + PostScript, and other formats. + + + + Be able to make changes to the documentation, test them, and + either contribute them back to the project or (if you have commit + privileges) commit them. + + + + This primer assumes that you already understand; + + + + How to maintain an up-to-date copy of the FreeBSD CVS tree using + CVS and one of CVSup or CTM, and how to check out particular versions + of files. + + Alternatively, how to retrieve versions of files using the + CVSWeb interface. + + + + How to use the ports system to download and install new + software. + + + + + + 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 new file mode 100644 index 0000000000..5208c5f016 --- /dev/null +++ b/en_US.ISO_8859-1/books/fdp-primer/psgml-mode/chapter.sgml @@ -0,0 +1,148 @@ + + + + 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, + 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 new file mode 100644 index 0000000000..eaecab8f99 --- /dev/null +++ b/en_US.ISO_8859-1/books/fdp-primer/see-also/chapter.sgml @@ -0,0 +1,119 @@ + + + + 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 + + + + The HTML 4.0 + specification + + + + + + DocBook + + + + The Davenport + Group, maintainers of the DocBook DTD + + + + + + The Linux Documentation Project + + + + 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 new file mode 100644 index 0000000000..e749463375 --- /dev/null +++ b/en_US.ISO_8859-1/books/fdp-primer/sgml-markup/chapter.sgml @@ -0,0 +1,2210 @@ + + + + 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;

+ +
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. 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. + +

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

    + +

    This is the second paragraph of the second item.

    3. + +

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

    4. +
]]> + + + + 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 cellTop right cell
Bottom left cellBottom 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 cellBottom cell
]]> + + + + Using <literal>colspan</literal> + + Use: + + +One long cell on top, two short cells below it.

+ + + + + + + + + + + +
Top cell
Bottom left cellBottom 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 cellTop right cell
Middle right cell
Bottom left cellBottom middle cellBottom 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. + + + <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 + 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. + + + + + 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.0-Based Extension//EN" + + + + Sectional elements + + DocBook contains a number of elements for marking up the structure + of a book. + + Generally, the top level (first) element will be + book. + + 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. + + + 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> + + + + + Indicating chapters + + Use chapter to mark up your chapters. Each + chapter has a mandatory title. + + + A simple chapter + + + + The chapter's title + + ... +]]> + + + A chapter can not 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 + + Chapters can be broken up into sections, subsections, and so + on. 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) + + ... + + +]]> + + + + + Subdividing using <sgmltag>part</sgmltag>s + + You can introduce another layer of organisation between + book and chapter with one or + more parts. + + + + Introduction + + + Overview + + ... + + + + What is FreeBSD? + + ... + + + + History + + ... + +]]> + + + + + Block elements + + + 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</para> + + <attribution>Copied from a web site somewhere</attribution> + + <para>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.</para> +</blockquote>]]></programlisting> + + <para>Appearance:</para> + + <blockquote> + <title>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 + HTML, ul and ol. Each one + consists of one or more listentry elements, and + each listentry contains one or more block + elements. The listentry elements are analagous to + HTMLs 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. + +]]> + + 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. + + + + + + + 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 closing tag should + appear on the same line as the last line of the output, otherwise a + spurious blank line will 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. + + + + informalexample + + + Most of the time these examples will occur + “mid-flow” as it were, and you won't need to put a + title on them. So, most of the time, the outermost element + will be informalexample. For those times + when you do need to include a title on the example, use + example. + + + + + 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>informalexample</sgmltag>, + <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 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 + 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 + (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; + + PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN" + + Therefore, the introduction to your documentation will probably + look like this; + + <!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook V3.0-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 + 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 + 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 new file mode 100644 index 0000000000..c25bacf1f1 --- /dev/null +++ b/en_US.ISO_8859-1/books/fdp-primer/sgml-primer/chapter.sgml @@ -0,0 +1,1554 @@ + + + + SGML Primer + + The Documentation Project makes heavy use of the Standard Generalized + Markup Language (SGML). This chapter describes what SGML is, how to read + and understand markup, and some of the SGML tricks you will see used in + the FAQ, Handbook, and website. + + 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 the 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;. + + 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 they are 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 of 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. + + SGML is not a markup langugage. Instead, SGML + is the language in which you write markup + languages. There have been many markup languages written + using SGML. HTML and DocBook are two of these. + + This is an important point to understand. Most of the time you are + not writing SGML documents. Instead, you are writing documents in a + particular markup language. The definition of the markup language you + are using is written in SGML. + + Each language definition (which is written in SGML) 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 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 a + parser which reads in 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 philisophy 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 types of content. + + Of course, we don't 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 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/3.0/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/3.0/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 is passed as a parameter to + it, &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. + + + + + + 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 the + it. + + This information is generally expressed on one line, in the DOCTYPE + declaration. + + A typical declaration for 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/3.0/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 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 delimiters 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 an SGML term. You might feel more comfortable thinking + of them as variables. There are two types of entity in SGML, general + entities and parameter entities. + + + General Entities + + General entities are a way of assigning names to chunks of text, + and reusing that text (which may contain markup) throughout your + document. + + 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 normally include in an SGML document. For example, < and + & can not normally appear in an SGML document. Normally, when the + SGML processor sees a < symbol it assumes that a tag (either a start + tag or an end tag) is about to appear, and when it sees a & 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 don't do 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. Normalising it involves converting all the entity + references to the values of those entities. + + 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) come into their own + when you realise they can be used to include other files. + + + 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; + + + + + +]]> + + + + 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 <!. + + 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 processor 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. + + + + + + + diff --git a/en_US.ISO_8859-1/books/fdp-primer/stylesheets/chapter.sgml b/en_US.ISO_8859-1/books/fdp-primer/stylesheets/chapter.sgml new file mode 100644 index 0000000000..85e5855414 --- /dev/null +++ b/en_US.ISO_8859-1/books/fdp-primer/stylesheets/chapter.sgml @@ -0,0 +1,68 @@ + + + + * Stylesheets + + SGML says nothing about how a document should be displayed to the + user, or rendered on paper. To do that, various languages have been + developed to describe stylesheets, including DynaText, Panorama, SPICE, + JSSS, FOSI, CSS, and DSSSL. + + For DocBook, we are using stylesheets written in DSSSL. For HTML we + are using CSS. + + + * DSSSL + + The Documentation Project uses a slightly customised version of + Norm Walsh's modular DocBook stylesheets. + + These can be found in + textproc/dsssl-docbook-modular. + + + + * CSS + + + + + + diff --git a/en_US.ISO_8859-1/books/fdp-primer/the-faq/chapter.sgml b/en_US.ISO_8859-1/books/fdp-primer/the-faq/chapter.sgml new file mode 100644 index 0000000000..24cc68a30a --- /dev/null +++ b/en_US.ISO_8859-1/books/fdp-primer/the-faq/chapter.sgml @@ -0,0 +1,47 @@ + + + + * The FAQ + + + + + + diff --git a/en_US.ISO_8859-1/books/fdp-primer/the-handbook/chapter.sgml b/en_US.ISO_8859-1/books/fdp-primer/the-handbook/chapter.sgml new file mode 100644 index 0000000000..9b860d2e7f --- /dev/null +++ b/en_US.ISO_8859-1/books/fdp-primer/the-handbook/chapter.sgml @@ -0,0 +1,280 @@ + + + + * The Handbook + + + Logical structure + + The Handbook is written to comply with the FreeBSD DocBook extended + DTD. + + The Handbook is organised as a DocBook book. It + is then divided into parts, each of which may contain + several chapters. chapters are + further subdivided into sections (sect1) and + subsections (sect2, sect3) and so + on. + + + + Physical organisation + + The Handbook (and its translations) are in the + doc/language/handbook + subdirectory of the main CVS + repository. language corresponds to the ISO + language code for that translation, en for English, + ja for Japanese, and so on. + + There are a number of files and directories within the + handbook directory. + + + The Handbook's organisation may change over time, and this + document may lag in detailing the organisational changes. If you have + any questions about how the Handbook is organised, please contact the + FreeBSD Documentation Project, doc@FreeBSD.ORG. + + + + <filename>Makefile</filename> + + The Makefile defines the rules that are used + to convert the Handbook from its source form (DocBook) to a number of + other target formats (including HTML, PostScript, and plain + text). + + A more detailed description of the Makefile + is in . + + + + <filename>handbook.sgml</filename> + + This is the top level document in the Handbook. It contains the + Handbook's DOCTYPE + declaration, as well as the elements that describe the + Handbook's structure. + + handbook.sgml uses parameter entities to load in + the files with the .ent extension. These files + (described later) then define general + entities that are used throughout the rest of the + Handbook. + + + + <filename><replaceable>directory</replaceable>/chapter.sgml</filename> + + Each chapter in the Handbook is stored in a file called + chapter.sgml in a separate directory from the + other chapters. Each directory is named after the value of the + id attribute on the chapter + element. + + For example, if one of the chapter files contains: + + +... +]]> + + then it will be called chapter.sgml in the + kernelconfiguration directory. In general, the + entire contents of the chapter will be held in this file. + + When the HTML version of the Handbook is produced, this will yield + kernelconfiguration.html. This is because of the + id value, and is not related to the name of the + directory. + + In earlier versions of the Handbook the files were stored in the + same directory as handbook.sgml, and named after + the value of the id attribute on the file's + chapter element. Moving them in to separate + directories prepares for future plans for the Handbook. Specifically, + it will soon be possible to include images in each chapter. It + makes more sense for each image to be stored in a directory with the + text for the chapter than to try and keep the text for all the + chapters, and all the images, in one large directory. Namespace + collisions would be inevitable, and it is easier to work with several + directories with a few files in them than it is to work with one + directory that has many files in it. + + A brief look will show that there are many directories with + individual chapter.sgml files, including + basics/chapter.sgml, + introduction/chapter.sgml, and + printing/chapter.sgml. + + + Chapters and/or directories should not be named in a fashion + that reflects their ordering within the Handbook. This ordering + might change as the content within the Handbook is reorganised; this + sort of reorganistion should not (generally) include the need to + rename files (unless entire chapters are being promoted or demoted + within the hierarchy). + + + Each chapter.sgml file will not be a complete + SGML document. In particular, they will not have their own DOCTYPE + line at the start of the file. + + This is unfortunate for two reasons; + + + + It makes it impossible to treat these as generic SGML files + and simply convert them to HTML, RTF, PS, and other formats in the + same way the main Handbook is generated. This + would force you to rebuild the Handbook every + time you want to see the effect a change as had on just one + chapter. + + + + Emacs' sgml-mode can not use it to + determine the DTD to use, losing useful benefits of + sgml-mode (element completion, automatic + validation, and so on). + + + + + + + Style guide + + To keep the source for the Handbook consistent when many different + people are editing it, please follow these style conventions. + + + Letter case + + Tags are entered in lower case, <para>, + not <PARA>. + + Text that appears in SGML contexts is generally written in upper + case, <!ENTITY…>, and + <!DOCTYPE…>, not + <!entity…> and + <!doctype…>. + + + + Indentation + + Each file starts with indentation set at column 0, + regardless of the indentation level of the file + which might contain this one. + + Every start tag increases the indentation level by 2 spaces, and + every end tag decreases the indentation level by 2 spaces. Content + within elements should be indented by two spaces if the content runs + over more than one line. + + For example, the source for this section looks something + like; + + + + ... + + + ... + + + Indentation + + Each file starts with indentation set at column 0, + regardless of the indentation level of the file + which might contain this one. + + Every start tag increases the indentation level by 2 spaces, and + every end tag decreases the indentation level by 2 spaces. Content + within elements should be indented by two spaces if the content runs + over more than one line. + + ... + + +]]> + + If you use Emacs or + Xemacs to edit the files then + sgml-mode should be loaded automatically, and the + Emacs local variables at the bottom of each file should enforce these + styles. + + + + White space changes + + When committing changes, do not commit changes to the + content at the same time as changes to the + formatting. + + This is so that the teams that convert the Handbook to other + languages can quickly see what content has actually changed in your + commit, without having to decide whether a line has changed because of + the content, or just because it has been refilled. + + For example, if you have added two sentances to a paragraph, such + that the line lengths on the paragraph now go over 80 columns, first + commit your change with the too-long line lengths. Then fix the line + wrapping, and commit this second change. In the commit message for the + second change, be sure to indicate that this is a whitespace-only + change, and that the translation team can ignore it. + + + + + Converting the Handbook to other formats + + + + + + + diff --git a/en_US.ISO_8859-1/books/fdp-primer/the-website/chapter.sgml b/en_US.ISO_8859-1/books/fdp-primer/the-website/chapter.sgml new file mode 100644 index 0000000000..01e4e129f5 --- /dev/null +++ b/en_US.ISO_8859-1/books/fdp-primer/the-website/chapter.sgml @@ -0,0 +1,47 @@ + + + + * The Website + + + + + + 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 new file mode 100644 index 0000000000..2080134fad --- /dev/null +++ b/en_US.ISO_8859-1/books/fdp-primer/tools/chapter.sgml @@ -0,0 +1,210 @@ + + * Tools + + The Documentation Project uses a number of tools to assist in the + production of documentation. You will need to install some or all of these + tools before you will be able to make changes. + + + 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. + + 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. + + + + Software + + The project uses the following applications; + + + + Jade and + SP + + + These are two application suites by James Clark, who has + produced many useful SGML-processing applications. + Jade is “James' DSSSL + Engine”, a system that takes SGML documentation and a DSSSL + stylesheet and produces converted output. + SP contains a number of useful + applications to manipulate, normalise, and interrogate SGML + documents. + + Don't be concerned if these terms are unfamliar to you. + + They can be found in the ports system as + textproc/jade and + textproc/sp respectively. + + + Installed as part of + textproc/docproj. + + + + + + teTeX + + + teTeX is a distrubution of the TeX + typesetting system, and is used (in conjunction with Jade) to + produce the Postscript and PDF output formats. + + v0.9 of teTeX is required, which is + currently in the ports collection as + print/teTeX-beta. + + + Might be installed as part of + textproc/docproj, depending on the + JADETEX setting. + + + + + + Emacs or + Xemacs + + + Neither of these programs is required. However, both of them + feature PSGML-MODE, a useful extension when dealing with SGML + documents that can reduce the amount of typing you need to do, and + remove some of the more obvious errors. + + They can be found in editor/emacs20 and + editor/xemacs20. + + + Not installed as part of + textproc/docproj. + + + + + + + + Document Type Definitions (DTDs) + + The project uses the following DTDs; + + + + 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 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 category. + + + Installed as part of + textproc/docproj. + + + + + + LinuxDoc + + + LinuxDoc is an adaptation of the QWERTZ DTD, first adopted by + the 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. + + + Installed as part of + textproc/docproj. + + + + + + DocBook + + + DocBook was designed by the Davenport Group + to be a DTD for writing technical documentation. As such, it + contains XXX + + + Installed as part of + textproc/docproj. + + + + + + + + DSSSL Stylesheets + + The Documentation Project uses a slightly customised version of + Norm Walsh's modular DocBook stylesheets. + + These can be found in + textproc/dsssl-docbook-modular. + + + Installed as part of textproc/docproj. + + + + + diff --git a/en_US.ISO_8859-1/books/fdp-primer/writing-style/chapter.sgml b/en_US.ISO_8859-1/books/fdp-primer/writing-style/chapter.sgml new file mode 100644 index 0000000000..07361a43be --- /dev/null +++ b/en_US.ISO_8859-1/books/fdp-primer/writing-style/chapter.sgml @@ -0,0 +1,137 @@ + + + + Writing style + + In order to promote consistency between the myriad authors of the + FreeBSD documentation, some guidelines have been drawn up for authors to + follow. + + + + Do not use contractions + + + Do not use contractions. Always spell the phrase out in full. + “Don't use contractions” would be wrong. + + Avoiding contractions makes for a more formal tone, is more + precise, and slightly easier for translators. + + + + + Use the serial comma + + + In a list of items within a paragraph, seperate each item from + the others with a comma. Seperate the last item from the others with + a comma and the word “and”. + + For example, look at the following quote; + +
+ This is a list of one, two and three items. +
+ + Is this a list of three items, “one”, + “two”, and “three”, or a list of two items, + “one” and “two and three”? + + It is better to be explicit and include a serial comma; + +
+ This is a list of one, two, and three items. +
+ + + + + Avoid redundant phrases + + + Try not to use redundant phrases. In particular, “the + command”, “the file”, and “man + command” are probably redundant. + + These two examples show this for commands. The second example + is preferred. + + + Use the command cvsup to update your + sources + + + + Use cvsup to update your sources + + + These two examples show this for filenames. The second example + is preferred. + + + … in the filename + /etc/rc.local… + + + + … in + /etc/rc.local… + + + These two examples show this for manual references. The second + example is preferred (the second example uses + citerefentry). + + + See man csh for more + information. + + + + See &man.csh.1; + + + + + + + +