From 4047241ce668f7a77732b3598250136310d93419 Mon Sep 17 00:00:00 2001 From: Warren Block Date: Sun, 23 Jun 2013 19:45:12 +0000 Subject: Split the old sgml-markup chapter into two chapters, one for XHTML and one for DocBook. Both are edited and expanded versions of the content from the old chapter. --- en_US.ISO8859-1/books/fdp-primer/Makefile | 3 +- en_US.ISO8859-1/books/fdp-primer/book.xml | 3 +- en_US.ISO8859-1/books/fdp-primer/chapters.ent | 3 +- .../books/fdp-primer/docbook-markup/chapter.xml | 2248 ++++++++++++++++ .../books/fdp-primer/overview/chapter.xml | 5 +- .../books/fdp-primer/sgml-markup/chapter.xml | 2759 -------------------- .../books/fdp-primer/xhtml-markup/chapter.xml | 613 +++++ 7 files changed, 2870 insertions(+), 2764 deletions(-) create mode 100644 en_US.ISO8859-1/books/fdp-primer/docbook-markup/chapter.xml delete mode 100644 en_US.ISO8859-1/books/fdp-primer/sgml-markup/chapter.xml create mode 100644 en_US.ISO8859-1/books/fdp-primer/xhtml-markup/chapter.xml diff --git a/en_US.ISO8859-1/books/fdp-primer/Makefile b/en_US.ISO8859-1/books/fdp-primer/Makefile index 60eaeea096..88291309b9 100644 --- a/en_US.ISO8859-1/books/fdp-primer/Makefile +++ b/en_US.ISO8859-1/books/fdp-primer/Makefile @@ -23,7 +23,8 @@ SRCS= book.xml SRCS+= overview/chapter.xml SRCS+= psgml-mode/chapter.xml SRCS+= see-also/chapter.xml -SRCS+= sgml-markup/chapter.xml +SRCS+= xhtml-markup/chapter.xml +SRCS+= docbook-markup/chapter.xml SRCS+= sgml-primer/chapter.xml SRCS+= stylesheets/chapter.xml SRCS+= structure/chapter.xml diff --git a/en_US.ISO8859-1/books/fdp-primer/book.xml b/en_US.ISO8859-1/books/fdp-primer/book.xml index 3d7fd3fdc0..af5dcffcac 100644 --- a/en_US.ISO8859-1/books/fdp-primer/book.xml +++ b/en_US.ISO8859-1/books/fdp-primer/book.xml @@ -248,7 +248,8 @@ Password: &chap.overview; &chap.tools; &chap.xml-primer; - &chap.xml-markup; + &chap.xhtml-markup; + &chap.docbook-markup; &chap.stylesheets; &chap.structure; &chap.doc-build; diff --git a/en_US.ISO8859-1/books/fdp-primer/chapters.ent b/en_US.ISO8859-1/books/fdp-primer/chapters.ent index 37c1e4f805..14b1677f56 100644 --- a/en_US.ISO8859-1/books/fdp-primer/chapters.ent +++ b/en_US.ISO8859-1/books/fdp-primer/chapters.ent @@ -13,7 +13,8 @@ - + + diff --git a/en_US.ISO8859-1/books/fdp-primer/docbook-markup/chapter.xml b/en_US.ISO8859-1/books/fdp-primer/docbook-markup/chapter.xml new file mode 100644 index 0000000000..a2e014fef5 --- /dev/null +++ b/en_US.ISO8859-1/books/fdp-primer/docbook-markup/chapter.xml @@ -0,0 +1,2248 @@ + + + + + DocBook Markup + + + Introduction + + This chapter is an introduction to DocBook as it is used for + &os; documentation. DocBook is a large and complex markup + system, but the subset described here covers the parts that are + most widely used for &os; documentation. While a moderate + subset is covered, it is impossible to anticipate every + situation. Please post questions that this document does + not answer to the &a.doc;. + + DocBook was originally developed by HaL Computer Systems and + O'Reilly & Associates to be a DTD for + writing technical documentation A short history + can be found under + http://www.oasis-open.org/docbook/intro.shtml#d0e41.. + Since 1998 it is maintained by the + DocBook Technical Committee. As such, and unlike + LinuxDoc and XHTML, DocBook is very heavily + oriented towards markup that describes what + something is, rather than describing how it + should be presented. + + The DocBook DTD is available from the + Ports Collection in the + textproc/docbook-xml-450 + port. It is automatically installed as part of the + textproc/docproj + port. + + + Formal Versus Informal + + 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 informal version of the element. The + informal version will not have a title. + + + + Inline Versus 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. + + + + + &os; Extensions + + The &os; 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 &os;-specific element is listed below, it is + clearly marked. + + Throughout the rest of this document, the term + DocBook is used to mean the &os;-extended + DocBook DTD. + + + There is nothing about these extensions that is &os; + 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 + &a.doceng;. + + + The &os; extensions are not (currently) in the + Ports Collection. They are stored in the &os; Subversion + tree, as head/share/xml/freebsd.dtd. + + + + Formal Public Identifier (FPI) + + In compliance with the DocBook guidelines for writing + FPIs for DocBook customizations, the + FPI for the &os; extended DocBook + DTD is: + + PUBLIC "-//FreeBSD//DTD DocBook V4.2-Based Extension//EN" + + + + Document Structure + + DocBook allows structuring documentation in several ways. + The &os; Documentation Project uses two primary types of DocBook + document: the book and the article. + + Books are organized into chapters. + This is a mandatory requirement. There may be + parts between the book and the chapter to + provide another layer of organization. For example, the + Handbook is arranged in this way. + + A chapter may (or may not) contain one or more sections. + These are indicated with the sect1 element. + If a section contains another section then use the + sect2 element, and so on, up to + sect5. + + Chapters and sections contain the remainder of the + content. + + An article is simpler than a book, and does not use + chapters. Instead, the content of an article is organized into + one or more sections, using the same sect1 + (and sect2 and so on) elements that are used + in books. + + The nature of the document being written should be used to + determine whether it is best marked up as a book or an article. + Articles are well suited to information that does not need to be + broken down into several chapters, and that is, relatively + speaking, quite short, at up to 20-25 pages of content. Books + are best suited to information that can be broken up into + several chapters, possibly with appendices and similar content + as well. + + The &os; tutorials + are all marked up as articles, while this + document, the + FreeBSD FAQ, + and the FreeBSD + Handbook are all marked up as books, for + example. + + + Starting a Book + + The content of a 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 is 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 email address</email></address> + </affiliation> + </author> + + <copyright> + <year>1998</year> + <holder role="mailto:your email address">Your name</holder> + </copyright> + + <releaseinfo>$FreeBSD$</releaseinfo> + + <abstract> + <para>Include an abstract of the book's contents here.</para> + </abstract> + </bookinfo> + + … + +</book> + + + + + Starting an Article + + The content of the article is contained within the + article element. As well as containing + structural markup, this element can contain elements that + include additional information about the article. This is + either meta-information, used for reference purposes, or + additional content used to produce a title page. + + This additional information is contained within + articleinfo. + + + Boilerplate <sgmltag>article</sgmltag> with + <sgmltag>articleinfo</sgmltag> + + + + <article> + <articleinfo> + <title>Your title here</title> + + <author> + <firstname>Your first name</firstname> + <surname>Your surname</surname> + <affiliation> + <address><email>Your email address</email></address> + </affiliation> + </author> + + <copyright> + <year>1998</year> + <holder role="mailto:your email address">Your name</holder> + </copyright> + + <releaseinfo>$FreeBSD$</releaseinfo> + + <abstract> + <para>Include an abstract of the article's contents here.</para> + </abstract> + </articleinfo> + + … + +</article> + + + + + Indicating Chapters + + Use chapter to mark up your chapters. + Each chapter has a mandatory title. + Articles do not contain chapters, they are reserved for + books. + + + A Simple Chapter + + + The Chapter's Title + + ... +]]> + + + A chapter cannot be empty; it must contain elements in + addition to title. If you need to + include an empty chapter then just use an empty + paragraph. + + + Empty Chapters + + + This is An Empty Chapter + + +]]> + + + + + Sections Below Chapters + + In books, chapters may (but do not need to) be broken up + into sections, subsections, and so on. In articles, sections + are the main structural element, and each article must contain + at least one section. Use the + sectn element. + The n indicates the section number, + which identifies the section level. + + The first + sectn is + sect1. You can have one or more of these + in a chapter. They can contain one or more + sect2 elements, and so on, down to + sect5. + + + Sections in Chapters + + + A Sample Chapter + + Some text in the chapter. + + + First Section (1.1) + + … + + + + Second Section (1.2) + + + First Sub-Section (1.2.1) + + + First Sub-Sub-Section (1.2.1.1) + + … + + + + + Second Sub-Section (1.2.2) + + … + + +]]> + + + + This example includes section numbers in the section + titles. You should not do this in your documents. Adding + the section numbers is carried out by the stylesheets (of + which more later), and you do not need to manage them + yourself. + + + + + Subdividing Using <sgmltag>part</sgmltag> + Elements + + parts introduce another level of + organization between book and + chapter with one or more + parts. This cannot be done in an + article. + + + Introduction + + + Overview + + ... + + + + What is FreeBSD? + + ... + + + + History + + ... + +]]> + + + + + Block Elements + + + Paragraphs + + DocBook supports three types of paragraphs: + formalpara, para, and + simpara. + + Almost all paragraphs in &os; documentation use + para. formalpara + includes a title element, and + simpara disallows some elements from + within para. Stick with + para. + + + <sgmltag>para</sgmltag> + + Usage: + + 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. These are rarely needed. + + Blockquotes can optionally contain a title and an + attribution (or they can be left untitled and + unattributed). + + + <sgmltag>blockquote</sgmltag> + + Usage: + + A small excerpt from the US Constitution: + +
+ Preamble to the Constitution of the United States + + Copied from a web site somewhere + + We the People of the United States, in Order to form a more + perfect Union, establish Justice, insure domestic Tranquility, + provide for the common defence, promote the general Welfare, and + secure the Blessings of Liberty to ourselves and our Posterity, do + ordain and establish this Constitution for the United States of + America. +
]]> + + Appearance: + + A small excerpt from the US Constitution: + +
+ Preamble to the Constitution of the United + States + + Copied from a web site + somewhere + + We the People of the United States, in Order to form + a more perfect Union, establish Justice, insure domestic + Tranquility, provide for the common defence, promote the + general Welfare, and secure the Blessings of Liberty to + ourselves and our Posterity, do ordain and establish + this Constitution for the United States of + America. +
+ + + + + Tips, Notes, Warnings, Cautions, Important Information + and Sidebars + + Extra information may need to be separated from + the main body of the text. Typically this is + meta information of which the user should be + aware. + + 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 loosely defined by the DocBook + documentation, which 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> + + Usage: + + + Installing FreeBSD may make you want to delete Windows from your + hard disk. +]]> + + + Appearance: + + + Installing FreeBSD may make you want to delete Windows + from your hard disk. + + + + + Lists and Procedures + + Information often needs to be presented as lists, or as a + number of steps that must be carried out in order to + accomplish a particular goal. + + To do this, use itemizedlist, + orderedlist, or + procedureThere are other + types of list element in DocBook, but we are not + concerned with those at the + moment. + + itemizedlist and + orderedlist are similar to their + counterparts in HTML, ul + and ol. Each one consists of one or more + listitem elements, and each + listitem contains one or more block + elements. The listitem elements are + analogous to HTML's li + tags. However, unlike HTML, they are required. + + procedure is slightly different. It + consists of steps, which may in turn + consists of more steps or + substeps. Each step + contains block elements. + + + <sgmltag>itemizedlist</sgmltag>, + <sgmltag>orderedlist</sgmltag>, and + <sgmltag>procedure</sgmltag> + + Usage: + + + + This is the first itemized item. + + + + This is the second itemized item. + + + + + + This is the first ordered item. + + + + This is the second ordered item. + + + + + + Do this. + + + + Then do this. + + + + And now do this. + +]]> + + Appearance: + + + + This is the first itemized item. + + + + This is the second itemized item. + + + + + + This is the first ordered item. + + + + This is the second ordered item. + + + + + + + + + Do this. + + + + Then do this. + + + + And now do this. + + + + + + Showing File Samples + + Fragments of a file (or perhaps a complete file) are shown + by wrapping them in the programlisting + element. + + White space and line breaks within + programlisting are + significant. In particular, this means that the opening tag + should appear on the same line as the first line of the + output, and the closing tag should appear on the same line + as the last line of the output, otherwise spurious blank + lines may be included. + + + <sgmltag>programlisting</sgmltag> + + Usage: + + When finished, the program will 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 finished, the program will look like this: + + #include <stdio.h> + +int +main(void) +{ + printf("hello, world\n"); +} + + + + + Callouts + + A callout is a mechanism for referring back to an + earlier piece of text or specific position within an earlier + example without linking to it within the text. + + To do this, mark areas of interest in the example + (programlisting, + literallayout, or whatever) with the + co element. Each element must have a + unique id assigned to it. After the + example include a calloutlist that refers + back to the example and provides additional + commentary. + + + <sgmltag>co</sgmltag> and + <sgmltag>calloutlist</sgmltag> + + When finished, the program will look like + this: + +#include <stdio.h> + +int +main(void) +{ + printf("hello, world\n"); +} + + + + Includes the standard IO header file. + + + + Specifies that main() returns an + int. + + + + The printf() call that writes + hello, world to standard output. + +]]> + + Appearance: + + When finished, the program will look like this: + + #include <stdio.h> + +int +main(void) +{ + printf("hello, world\n"); +} + + + + Includes the standard IO header file. + + + + Specifies that main() returns + an int. + + + + The printf() call that writes + hello, world to standard + output. + + + + + + + Tables + + Unlike HTML, DocBook does not need + tables for layout purposes, as the stylesheet handles those + issues. 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 there is 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> + + Usage: + + + + + + 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 + + + + + + + Always use the pgwide attribute with + a value of 1 with the + informaltable element. A bug in Internet + Explorer can cause the table to render incorrectly if this + is omitted. + + Table borders can be suppressed by setting the + frame attribute to none + in the informaltable element. For example, + <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 + + Examples for the user to follow are often necessary. + Typically, these will consist of dialogs with the computer; + the user types in a command, the user gets a response back, + the user types another command, and so on. + + A number of distinct elements and entities come into + play here. + + + + screen + + + Everything the user sees in this example will be + on the computer screen, so the next element is + screen. + + Within screen, white space is + significant. + + + + + prompt, + &prompt.root; and + &prompt.user; + + + Some of the things the user will be seeing on the + screen are prompts from the computer (either from the + operating system, 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. 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 &os; + 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 + be displayed differently than system output text. + + + + + + <sgmltag>screen</sgmltag>, <sgmltag>prompt</sgmltag>, + and <sgmltag>userinput</sgmltag> + + Usage: + + &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 + + + Emphasizing Information + + To emphasize 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 the document, no equivalent of + HTML's b and + i. If the information being presented is + important, then consider presenting it in + important rather than + emphasis. + + + <sgmltag>emphasis</sgmltag> + + Usage: + + 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. + + + + + Quotations + + To quote text from another document or source, or to + denote a phrase that is used figuratively, use + quote. Most of the markup tags available + for normal text are also available from within a + quote. + + + Quotations + + Usage: + + However, make sure that the search does not go beyond the + boundary between local and public administration, + as RFC 1535 calls it.]]> + + Appearance: + + However, make sure that the search does not go beyond + the boundary between local and public + administration, as RFC 1535 calls it. + + + + + Keys, Mouse Buttons, and Combinations + + To refer to a specific key on the keyboard, use + keycap. To refer to a mouse button, use + mousebutton. And to refer to + combinations of key presses or mouse clicks, wrap them all + in keycombo. + + keycombo has an attribute called + action, which may be one of + click, double-click, + other, press, + seq, or simul. The + last two values denote whether the keys or buttons should be + pressed in sequence, or simultaneously. + + The stylesheets automatically add any connecting + symbols, such as +, between the key + names, when wrapped in keycombo. + + + Keys, Mouse Buttons, and Combinations + + Usage: + + To switch to the second virtual terminal, press + Alt + F1. + +To exit vi without saving changes, type + Esc: + q!. + +My window manager is configured so that + Alt + right + mouse button is used to move windows.]]> + + Appearance: + + To switch to the second virtual terminal, press + Alt + F1. + + To exit vi without saving changes, + type + Esc + : + q + !. + + My window manager is configured so that + + Alt + right mouse button + is used to move windows. + + + + + Applications, Commands, Options, and Cites + + Both applications and commands are frequently referred to + when writing documentation. The distinction between them is + that an application is the name of a program or suite of + programs that fulfill a particular task. A command is the + filename of a program that the user can type and run at a + command line. + + It is often necessary to show some of the options that a + command might take. + + Finally, it is often useful to list a command with its + manual section number, in the command(number) + format so common in Unix manuals. + + Mark up application names with + application. + + To list a command with its manual section + number (which should be most of the time) the DocBook + element is citerefentry. This will + contain a further two elements, + refentrytitle and + manvolnum. The content of + refentrytitle is the name of the command, + and the content of manvolnum is the + manual page section. + + This can be cumbersome to write, and so a series of + general + entities have been created to make this easier. + Each entity takes the form + &man.manual-page.manual-section;. + + The file that contains these entities is in + doc/share/xml/man-refs.ent, and can be + referred to using this FPI: + + PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN" + + Therefore, the introduction to &os; documentation will + usually include this: + + <!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [ + +<!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"> +%man; + +… + +]> + + Use command when to include a command + name in-line but present it as something the + user should type in. + + Use option to mark up the options + which will be passed to a command. + + When referring to the same command multiple times in + close proximity, it is preferred to use the + &man.command.section; + notation to markup the first reference and use + command to markup subsequent references. + This makes the generated output, especially + HTML, appear visually better. + + This can be confusing, and sometimes the choice is not + always clear. Hopefully this example makes it + clearer. + + + Applications, Commands, and Options + + Usage: + + Sendmail is the most + widely used Unix mail application. + +Sendmail includes the + + sendmail + 8 + , &man.mailq.1;, and &man.newaliases.1; + 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 + , &man.mailq.1;, and &man.newaliases.1; + 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 + + To refer to the name of a file, a directory, or a file + extension, use filename. + + + <sgmltag>filename</sgmltag> + + Usage: + + The XML source for the Handbook in English is + found in /usr/doc/en_US.ISO8859-1/books/handbook/. The first + file is called book.xml in that + directory. There is also a Makefile + and a number of files with a .ent + extension.]]> + + Appearance: + + The XML source for the Handbook in English can be + found in /usr/doc/en/handbook/. The + first file is called handbook.xml in + that directory. There is also a + Makefile and a number of files with a + .ent extension. + + + + + The Name of Ports + + + &os; Extension + + These elements are part of the &os; extension to + DocBook, and do not exist in the original DocBook + DTD. + + + To include the name of a program from the &os; + Ports Collection in the document, use the + filename tag with the + role attribute set to + package. Since ports can be installed in + any number of locations, only include the category and the + port name; do not include + /usr/ports. + + + <sgmltag>filename</sgmltag> Tag with + <literal>package</literal> Role + + Usage: + + Install the net/wireshark port to view network traffic.]]> + + Appearance: + + Install the net/wireshark port to view + network traffic. + + + + + Devices + + + &os; Extension + + These elements are part of the &os; extension to + DocBook, and do not exist in the original DocBook + DTD. + + + There are two names for devices: the device name as it + appears in /dev, or the name of the + device as it appears in the kernel. For this latter course, + use devicename. + + Sometimes there is no choice. Some devices, such as + network cards, do not have entries in + /dev, or the entries are markedly + different from their kernel device names. + + + <sgmltag>devicename</sgmltag> + + Usage: + + 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, network 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, network 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 + + + &os; Extension + + These elements are part of the &os; extension to + DocBook, and do not exist in the original DocBook + DTD. + + + Identification information for networked computers (hosts) + can be marked up 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. The hostname can be + explicitly specified 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="ip6addr" + + + The text is an IPv6 + address. + + + + + 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 + (CIDR notation). + + + + + role="mac" + + + The text is an Ethernet MAC + address, expressed as a series of 2 digit hexadecimal + numbers separated by colons. + + + + + + <sgmltag>hostid</sgmltag> and Roles + + Usage: + + 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.]]> + + 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 + + + &os; Extension + + These elements are part of the &os; extension to + DocBook, and do not exist in the original DocBook + DTD. + + + To refer to a specific username, such as + root or bin, use + username. + + + <sgmltag>username</sgmltag> + + Usage: + + To carry out most system administration functions + requires logging in as root.]]> + + Appearance: + + To carry out most system administration functions + requires logging in as root. + + + + + Describing <filename>Makefile</filename>s + + + &os; Extension + + These elements are part of the &os; 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> + + Usage: + + 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 + + Literal text, or text which should be entered verbatim, is + often needed in documentation. This is text that is excerpted + from another file, or which should be copied exactly as shown + from the documentation into another file. + + Some of the time, programlisting will + be sufficient to denote this text. But + 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> + + Usage: + + 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 the user is shown + what to do, or referred to a file or command line, but + cannot simply copy the example provided. Instead, they + must supply 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> + + Usage: + + &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. + + Usage: + + 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. + + + + + Quoting System Errors + + System errors generated by &os; are marked with + errorname. This indicates the exact error + that appears. + + + <sgmltag>errorname</sgmltag> + + Usage: + + Panic: cannot mount root]]> + + + Appearance: + + + Panic: cannot mount root + + + + + + + Images + + + Image support in the documentation is currently + extremely experimental. The mechanisms described here are + unlikely to change, but that is not guaranteed. + + Installation of the + graphics/ImageMagick + port is required. It is used to convert between the different + image formats. This port is not in + the textproc/docproj meta + port, it must be installed by hand. + + The best example of what follows in practice is the + doc/en_US.ISO8859-1/articles/vm-design/ + document. If the description that follows is unclear, take a + look at the files in that directory to see how everything + hangs together. Experiment with creating different formatted + versions of the document to see how the image markup appears + in the formatted output. + + + + Image Formats + + Two image formats are currently supported. Which to + choose will depend on the nature of the image. + + Images that are primarily vector based, such as network + diagrams, time lines, and similar, should be in + EPS (Encapsulated Postscript) format. + These images have a .eps + extension. + + For bitmaps, such as screen captures, use the + PNG (Portable Network Graphic) format. + These images have the .png + extension. + + These are the only formats in which + images should be committed to the Subversion + repository. + + Use the appropriate format for each image. It is to be + expected that documentation will have a mix of + EPS and PNG images. The + Makefiles ensure that the correct format + image is chosen depending on the output format that you use + for your documentation. Do not commit the same + image to the repository in two different + formats. + + + It is anticipated that the Documentation Project will + switch to using the SVG (Scalable Vector + Graphic) format for vector images. However, the current + state of SVG capable editing tools makes + this impractical. + + + + + Image Markup + + The markup for an image is relatively simple. First, + markup a mediaobject. The + mediaobject can contain other, more + specific objects. We are concerned with two, the + imageobject and the + textobject. + + Include one imageobject, + and two textobject elements. The + imageobject will point to the name of the + image file (without the extension). The + textobject elements contain information + that will be presented to the user as well as, or instead of, + the image itself. + + There are two circumstances where this can + happen. + + + + When the reader is viewing the documentation in + HTML. In this case, each image will + need associated alternate text to show the user, typically + while the image is loading, or if they hover the mouse + pointer over the image. + + + + When the reader is viewing the documentation in + plain text. In this case, each image should have an + ASCII art equivalent to show the + user. + + + + + An example will make things easier to understand. Suppose + there is an image called fig1.png that is + to be included in the document. This image is of a rectangle + with an A inside it. The markup for this would be as + follows. + + <mediaobject> + <imageobject> + <imagedata fileref="fig1"> + </imageobject> + + <textobject> + <literallayout class="monospaced">+---------------+ +| A | ++---------------+</literallayout> + </textobject> + + <textobject> + <phrase>A picture</phrase> + </textobject> +</mediaobject> + + + + Include an imagedata element + inside the imageobject element. The + fileref attribute should contain the + filename of the image to include, without the extension. + The stylesheets will work out which extension should be + added to the filename automatically. + + + + + The first textobject contains a + literallayout element, where the + class attribute is set to + monospaced. This is an opportunity to + demonstrate ASCII art skills. This + content will be used if the document is converted to plain + text. + + Notice how the first and last lines of the content + of the literallayout element butt up + next to the element's tags. This ensures no extraneous + white space is included. + + + + The second textobject contains a + single phrase element. The contents of + this phrase will become the alt + attribute for the image when this document is converted to + HTML. + + + + + + Image <filename>Makefile</filename> Entries + + Images must be listed in the Makefile + in the IMAGES variable. This variable must + contain the names of all the source + images. For example, if there are three figures, + fig1.eps, fig2.png, + fig3.png, then the + Makefile should have lines like this in + it. + + … +IMAGES= fig1.eps fig2.png fig3.png +… + + or + + … +IMAGES= fig1.eps +IMAGES+= fig2.png +IMAGES+= fig3.png +… + + Again, the Makefile will work out + the complete list of images it needs to build the source + document, you only need to list the image files + you provided. + + + + Images and Chapters in Subdirectories + + Be careful when separating documentation into smaller + files in different directories (see ). + + Suppose there is a book with three chapters, and the + chapters are stored in their own directories, called + chapter1/chapter.xml, + chapter2/chapter.xml, and + chapter3/chapter.xml. If each chapter + has images associated with it, it is suggested to place + those images in each chapter's subdirectory + (chapter1/, + chapter2/, and + chapter3/). + + However, doing this requires including the directory + names in the IMAGES variable in the + Makefile, and + including the directory name in the + imagedata element in the document + document. + + For example, if the book has + chapter1/fig1.png, then + chapter1/chapter.xml should + contain: + + <mediaobject> + <imageobject> + <imagedata fileref="chapter1/fig1"> + </imageobject> + + … + +</mediaobject> + + + + The directory name must be included in the + fileref attribute. + + + + The Makefile must contain: + + … +IMAGES= chapter1/fig1.png +… + + Then everything will work. + + + + + Links + + + Links are also in-line elements. + + + + <literal>id</literal> Attributes + + Most DocBook elements accept an id + attribute to give that part of the document a unique name. + The id can be used as a target for a + crossreference or link. + + Any portion of the document that will be a link target + must have an id attribute. Assigning an + id to all chapters and sections, even if + there are no current plans to link to them, is a good idea. + These ids can be used as unique anchor + reference points by anyone referring to the + HTML version of the document. + + + <literal>id</literal> on Chapters and + Sections + + + Introduction + + This is the introduction. It contains a subsection, + which is identified as well. + + + Sub-sect 1 + + This is a subsection. + +]]> + + + Use descriptive values for id names. + The values must be unique within the entire document, not just + in a single file. In the example, the subsection + id is constructed by appending text to the + chapter id. This ensures that the + ids are unique. It also helps both reader + and anyone editing the document to see where the link is + located within the document, similar to a directory + path to a file. + + To allow the user to jump into a specific portion of the + document, even 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 will not + show up in the document.]]> + + + + + Crossreferences with <literal>xref</literal> + + xref provides the reader with a link to + jump to another section of the document. The target + id is specified in the + linkend attribute, and + xref generates the link text + automatically. + + + 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 link text will be generated automatically, looking + like (emphasized text indicates the + link text): + +
+ More information can be found in Chapter + 1, The Sample Chapter. + + More specific information can be found in + Section 1.1, + Sample Sub-Sect. +
+ + + The link text is generated automatically from the chapter + and section number and title + elements. + + + xref cannot link to an + id attribute on an + anchor element. The + anchor has no content, so the + xref cannot generate the link + text. + + + + + Linking to the Same Document or Other Documents on the + Web + + The link elements described here allow the writer to + define the link text. It is very important to use descriptive + link text to give the reader an idea of where the link will + take them. Remember that DocBook can be rendered to multiple + types of media. The reader may be looking at a printed book + or other form of media where there are no links. If the link + text is not descriptive enough, the reader may not be able to + locate the linked section. + + + Links to the Same Document + + link is used to create a link + within the same document. The target id + is specified in the linkend attribute. + This element wraps content, which is used for the link + text. + + + 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 + sample chapter. + +More specific information can be found in the + even more samples section.]]> + + This output will be generated + (emphasized text is used to show the + link text): + +
+ More information can be found in the + sample chapter. + + More specific information can be found in the + even more samples section. +
+ + + + link can be used to include links + to the id of an + anchor element, since the + link content defines the link + text. + + + + + Linking to Other Documents on the Web + + The ulink is used to link to + external documents on the web. The url + attribute is the URL of the page that the + link points to, and the content of the element is the text + that will be displayed for the user to activate. + + + <sgmltag>ulink</sgmltag> to a &os; Documentation Web + Page + + Link to the book or article URL + entity. To link to a specific chapter in a book, add a + slash and the chapter file name, followed by an optional + anchor within the chapter. For articles, link to the + article URL entity, followed by an + optional anchor within the article. + URL entities can be found in + doc/share/xml/urls.ent. + + Usage for book links: + + Read the SVN + introduction, then pick the nearest mirror from + the list of Subversion + mirror sites.]]> + + Appearance: + + Read the SVN + introduction, then pick the nearest mirror from + the list of Subversion + mirror sites. + + Usage for article links: + + Read this article + about the BSD license, or just the introduction.]]> + + Appearance: + + Read this article + about the BSD license, or just the introduction. + + + + <sgmltag>ulink</sgmltag> to a &os; Web Page + + Usage: + + Of course, you could stop reading this document and + go to the FreeBSD + home page instead.]]> + + Appearance: + + Of course, you could stop reading this document and go + to the FreeBSD home + page instead. + + + + <sgmltag>ulink</sgmltag> to an External Web + Page + + Usage: + + Wikipedia has an excellent reference on + GUID + Partition Tables.]]> + + Wikipedia has an excellent reference on + GUID + Partition Tables. + + + + + diff --git a/en_US.ISO8859-1/books/fdp-primer/overview/chapter.xml b/en_US.ISO8859-1/books/fdp-primer/overview/chapter.xml index e1e15426fa..5ead068fd9 100644 --- a/en_US.ISO8859-1/books/fdp-primer/overview/chapter.xml +++ b/en_US.ISO8859-1/books/fdp-primer/overview/chapter.xml @@ -211,7 +211,8 @@ to the tags which surround the text or the entities that represent that text in the XML file. A reference to the commonly used tags and entities can be - found in . + found in and + . @@ -291,4 +292,4 @@ - \ No newline at end of file + diff --git a/en_US.ISO8859-1/books/fdp-primer/sgml-markup/chapter.xml b/en_US.ISO8859-1/books/fdp-primer/sgml-markup/chapter.xml deleted file mode 100644 index 49626b5055..0000000000 --- a/en_US.ISO8859-1/books/fdp-primer/sgml-markup/chapter.xml +++ /dev/null @@ -1,2759 +0,0 @@ - - - - - XML Markup - - This chapter describes the two 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 &a.doc;. - - - Inline Versus 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. - - - - XHTML - - XHTML is the XML version of the HyperText Markup Language, - which is the markup language - of choice on the World Wide Web. More information can be found - at . - - XHTML is used to markup pages on the FreeBSD web site. It - should not (generally) be used to mark up other documentation, - since DocBook offers a far richer set of elements to choose - from. Consequently, you will normally only encounter XHTML pages - if you are writing for the web site. - - HTML has gone through a number of versions, 1, 2, 3.0, 3.2, - 4.0 and then an XML-compliant version has also been created, which - is called XHTML and the latest widespread version of it is - XHTML 1.0(available in both - strict and transitional - variants). - - The XHTML DTDs are available from the Ports Collection - in the textproc/xhtml port. - They are automatically installed as part of the textproc/docproj port. - - - Formal Public Identifier (FPI) - - There are a number of XHTML FPIs, depending upon the - version (also known as the level) of XHTML that you want to - declare your document to be compliant with. - - The majority of XHTML documents on the FreeBSD web site - comply with the transitional version of XHTML 1.0. - - PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" - - - - Sectional Elements - - An XHTML document is normally split into 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 XHTML Document Structure - - <html xmlns="http://www.w3.org/1999/xhtml"> - <head> - <title>The Document's Title</title> - </head> - - <body> - - … - - </body> -</html> - - - - - Block Elements - - - Headings - - XHTML 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>, - and Other Header Tags - - 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 XHTML 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, preceding 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 - - XHTML 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 - preceded by a bullet point. Definition lists are composed - of two sections for each entry. The first section is the - term being defined, and the second section is the definition - of the term. - - Ordered lists are indicated by the ol - element, unordered lists by the ul - element, and definition lists by the dl - element. - - Ordered and unordered lists contain listitems, indicated - by the li element. A listitem can - contain textual content, or it may be further wrapped in one - or more p elements. - - Definition lists contain definition terms - (dt) and definition descriptions - (dd). A definition term can only contain - inline elements. A definition description can contain other - block elements. - - - <sgmltag>ul</sgmltag> and - <sgmltag>ol</sgmltag> - - Use: - - An unordered list. Listitems will probably be - preceded 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.

-]]> - - - - - 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 into 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 - email message: - - From: nik@FreeBSD.org - To: freebsd-doc@FreeBSD.org - Subject: New documentation available - - There is a new copy of my primer for contributors to the FreeBSD - Documentation Project available at - - <URL:http://people.FreeBSD.org/~nik/primer/index.html> - - Comments appreciated. - - N]]> - - Keep in mind that < and - & still are recognized as special - characters in pre-formatted text. This is why the example - shown had to use &lt; instead of - <. For consistency, - &gt; was used in place of - >, too. Watch out for the special - characters that may appear in text copied from a - plain-text source, e.g., an email message or program - code. - - - - - 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 or 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 into 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 - - - Emphasizing Information - - You have two levels of emphasis available in XHTML, - 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. According to best practices, webpages only hold - structural and semantical information and stylesheets are - later applied to use these two so you should think of - semantics not formatting when using these tags. - - - <sgmltag>em</sgmltag> and - <sgmltag>strong</sgmltag> - - Use: - - This has been emphasized, while - this has been strongly emphasized.

]]> - - - - - 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 email as - nik@FreeBSD.org.

]]> - - - - - - Links - - - Links are also inline 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 color, 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 - id attribute instead of - href. - - - Using <literal><a id="..."></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 id 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 preceding - #). - - - Linking to a Named Part of the Same 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 originally developed by HaL Computer Systems and - O'Reilly & Associates to be a DTD for writing technical - documentation A short history can be found under - - http://www.oasis-open.org/docbook/intro.shtml#d0e41.. - Since 1998 it is maintained by the - DocBook Technical Committee. As such, and unlike - LinuxDoc and XHTML, DocBook is very heavily oriented towards - markup that describes what something is, - rather than describing how it should be - presented. - - - Formal Versus Informal - - 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 informal 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-xml-450 - port. It is automatically installed as part of the textproc/docproj port. - - - &os; 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 - &a.doceng;. - - - The &os; extensions are not (currently) in the - Ports Collection. They are stored in the &os; Subversion - tree, as head/share/xml/freebsd.dtd. - - - - Formal Public Identifier (FPI) - - In compliance with the DocBook guidelines for writing FPIs - for DocBook customizations, the FPI for the FreeBSD extended - DocBook DTD is: - - PUBLIC "-//FreeBSD//DTD DocBook V4.2-Based Extension//EN" - - - - Document Structure - - DocBook allows you to structure your documentation in - several ways. In the FreeBSD Documentation Project we are - using two primary types of DocBook document: the book and the - article. - - A book is organized into chapters. - This is a mandatory requirement. There may be - parts between the book and the chapter to - provide another layer of organization. For example, the - Handbook is arranged in this way. - - A chapter may (or may not) contain one or more sections. - These are indicated with the sect1 element. - If a section contains another section then use the - sect2 element, and so on, up to - sect5. - - Chapters and sections contain the remainder of the - content. - - An article is simpler than a book, and does not use - chapters. Instead, the content of an article is organized - into one or more sections, using the same - sect1 (and sect2 and so - on) elements that are used in books. - - Obviously, you should consider the nature of the - documentation you are writing in order to decide whether it is - best marked up as a book or an article. Articles are well - suited to information that does not need to be broken down - into several chapters, and that is, relatively speaking, quite - short, at up to 20-25 pages of content. Books are best suited - to information that can be broken up into several chapters, - possibly with appendices and similar content as well. - - The FreeBSD - tutorials are all marked up as articles, while this - document, the - FreeBSD FAQ, - and the FreeBSD - Handbook are all marked up as books, for - example. - - - 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 email address</email></address> - </affiliation> - </author> - - <copyright> - <year>1998</year> - <holder role="mailto:your email address">Your name</holder> - </copyright> - - <releaseinfo>$FreeBSD$</releaseinfo> - - <abstract> - <para>Include an abstract of the book's contents here.</para> - </abstract> - </bookinfo> - - … - -</book> - - - - - Starting an Article - - The content of the article is contained within the - article element. As well as containing - structural markup, this element can contain elements that - include additional information about the article. This is - either meta-information, used for reference purposes, or - additional content used to produce a title page. - - This additional information should be contained within - articleinfo. - - - Boilerplate <sgmltag>article</sgmltag> with - <sgmltag>articleinfo</sgmltag> - - - - <article> - <articleinfo> - <title>Your title here</title> - - <author> - <firstname>Your first name</firstname> - <surname>Your surname</surname> - <affiliation> - <address><email>Your email address</email></address> - </affiliation> - </author> - - <copyright> - <year>1998</year> - <holder role="mailto:your email address">Your name</holder> - </copyright> - - <releaseinfo>$FreeBSD$</releaseinfo> - - <abstract> - <para>Include an abstract of the article's contents here.</para> - </abstract> - </articleinfo> - - … - -</article> - - - - - Indicating Chapters - - Use chapter to mark up your chapters. - Each chapter has a mandatory title. - Articles do not contain chapters, they are reserved for - books. - - - A Simple Chapter - - - The Chapter's Title - - ... -]]> - - - A chapter cannot be empty; it must contain elements in - addition to title. If you need to - include an empty chapter then just use an empty - paragraph. - - - Empty Chapters - - - This is An Empty Chapter - - -]]> - - - - - Sections Below Chapters - - In books, chapters may (but do not need to) be broken up - into sections, subsections, and so on. In articles, - sections are the main structural element, and each article - must contain at least one section. Use the - sectn element. - The n indicates the section - number, which identifies the section level. - - The first - sectn is - sect1. You can have one or more of these - in a chapter. They can contain one or more - sect2 elements, and so on, down to - sect5. - - - Sections in Chapters - - - A Sample Chapter - - Some text in the chapter. - - - First Section (1.1) - - … - - - - Second Section (1.2) - - - First Sub-Section (1.2.1) - - - First Sub-Sub-Section (1.2.1.1) - - … - - - - - Second Sub-Section (1.2.2) - - … - - -]]> - - - - This example includes section numbers in the section - titles. You should not do this in your documents. Adding - the section numbers is carried out by the stylesheets (of - which more later), and you do not need to manage them - yourself. - - - - - Subdividing Using <sgmltag>part</sgmltag> - Elements - - You can introduce another layer of organization between - book and chapter with - one or more parts. This cannot be done - in an article. - - - 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 - - Copied from a web site somewhere - - We the People of the United States, in Order to form a more perfect - Union, establish Justice, insure domestic Tranquility, provide for the - common defence, promote the general Welfare, and secure the Blessings - of Liberty to ourselves and our Posterity, do ordain and establish this - Constitution for the United States of America. -
]]> - - Appearance: - - A small excerpt from the US Constitution: - -
- Preamble to the Constitution of the United - States - - Copied from a web site - somewhere - - We the People of the United States, in Order to form - a more perfect Union, establish Justice, insure domestic - Tranquility, provide for the common defence, promote the - general Welfare, and secure the Blessings of Liberty to - ourselves and our Posterity, do ordain and establish - this Constitution for the United States of - America. -
- - - - - 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 - hard disk. -]]> - - - Appearance: - - - Installing FreeBSD may make you want to delete Windows - from your hard disk. - - - - - 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 are not - concerned with those at the - moment. - - itemizedlist and - orderedlist are similar to their - counterparts in HTML, ul and - ol. Each one consists of one or more - listitem elements, and each - listitem contains one or more block - elements. The listitem elements are - analogous to HTML's li tags. However, - unlike HTML, they are required. - - procedure is slightly different. It - consists of steps, which may in turn - consists of more steps or - substeps. Each step - contains block elements. - - - <sgmltag>itemizedlist</sgmltag>, - <sgmltag>orderedlist</sgmltag>, and - <sgmltag>procedure</sgmltag> - - Use: - - - - This is the first itemized item. - - - - This is the second itemized item. - - - - - - This is the first ordered item. - - - - This is the second ordered item. - - - - - - Do this. - - - - Then do this. - - - - And now do this. - -]]> - - Appearance: - - - - This is the first itemized item. - - - - This is the second itemized item. - - - - - - This is the first ordered item. - - - - This is the second ordered item. - - - - - - - - - Do this. - - - - Then do this. - - - - And now do this. - - - - - - Showing File Samples - - If you want to show a fragment of a file (or perhaps a - complete file) to the user, wrap it in the - programlisting element. - - White space and line breaks within - programlisting are - significant. In particular, this means that the opening tag - should appear on the same line as the first line of the - output, and the closing tag should appear on the same line - as the last line of the output, otherwise spurious blank - lines may be included. - - - <sgmltag>programlisting</sgmltag> - - Use: - - When you have finished, your program should look like - this: - -#include <stdio.h> - -int -main(void) -{ - printf("hello, world\n"); -}]]> - - Notice how the angle brackets in the - #include line need to be referenced by - their entities instead of being included literally. - - Appearance: - - When you have finished, your program should look like - this: - - #include <stdio.h> - -int -main(void) -{ - printf("hello, world\n"); -} - - - - - Callouts - - A callout is a mechanism for referring back to an - earlier piece of text or specific position within an earlier - example without linking to it within the text. - - To do this, mark areas of interest in your example - (programlisting, - literallayout, or whatever) with the - co element. Each element must have a - unique id assigned to it. After the - example include a calloutlist that refers - back to the example and provides additional - commentary. - - - <sgmltag>co</sgmltag> and - <sgmltag>calloutlist</sgmltag> - - When you have finished, your program should look like - this: - -#include <stdio.h> - -int -main(void) -{ - printf("hello, world\n"); -} - - - - Includes the standard IO header file. - - - - Specifies that main() returns an - int. - - - - The printf() call that writes - hello, world to standard output. - -]]> - - Appearance: - - When you have finished, your program should look like - this: - - #include <stdio.h> - -int -main(void) -{ - printf("hello, world\n"); -} - - - - Includes the standard IO header file. - - - - Specifies that main() returns - an int. - - - - The printf() call that writes - hello, world to standard - output. - - - - - - - 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 - - - - - - - Always use the pgwide attribute with - a value of 1 with the - informaltable element. A bug in Internet - Explorer can cause the table to render incorrectly if this - is omitted. - - If you do not 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 into - play here. - - - - screen - - - Everything the user sees in this example will be - on the computer screen, so the next element is - screen. - - Within screen, white space is - significant. - - - - - prompt, - &prompt.root; and - &prompt.user; - - - Some of the things the user will be seeing on the - screen are prompts from the computer (either from the - operating system, command shell, or application). - These should be marked up using - prompt. - - As a special case, the two shell prompts for the - normal user and the root user have been provided as - entities. Every time you want to indicate the user is - at a shell prompt, use one of - &prompt.root; and - &prompt.user; as necessary. - They do not need to be inside - prompt. - - - &prompt.root; and - &prompt.user; are FreeBSD - extensions to DocBook, and are not part of the - original DTD. - - - - - - userinput - - - When displaying text that the user should type in, - wrap it in userinput tags. It will - probably be displayed differently to the user. - - - - - - <sgmltag>screen</sgmltag>, <sgmltag>prompt</sgmltag>, - and <sgmltag>userinput</sgmltag> - - Use: - - &prompt.user; ls -1 -foo1 -foo2 -foo3 -&prompt.user; ls -1 | grep foo2 -foo2 -&prompt.user; su -Password: -&prompt.root; cat foo2 -This is the file called 'foo2']]> - - Appearance: - - &prompt.user; ls -1 -foo1 -foo2 -foo3 -&prompt.user; ls -1 | grep foo2 -foo2 -&prompt.user; su -Password: -&prompt.root; cat foo2 -This is the file called 'foo2' - - - - Even though we are displaying the contents of the file - foo2, it is not - marked up as programlisting. Reserve - programlisting for showing fragments of - files outside the context of user actions. - - - - - - In-line Elements - - - Emphasizing Information - - When you want to emphasize 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. - - - - - Quotations - - To quote text from another document or source, or to - denote a phrase that is used figuratively, use - quote. Within a quote - tag, you may use most of the markup tags available for - normal text. - - - Quotations - - Use: - - However, make sure that the search does not go beyond the - boundary between local and public administration, - as RFC 1535 calls it.]]> - - Appearance: - - However, make sure that the search does not go beyond - the boundary between local and public - administration, as RFC 1535 calls it. - - - - - Keys, Mouse Buttons, and Combinations - - To refer to a specific key on the keyboard, use - keycap. To refer to a mouse button, use - mousebutton. And to refer to - combinations of key presses or mouse clicks, wrap them all - in keycombo. - - keycombo has an attribute called - action, which may be one of - click, double-click, - other, press, - seq, or simul. The - last two values denote whether the keys or buttons should be - pressed in sequence, or simultaneously. - - The stylesheets automatically add any connecting - symbols, such as +, between the key - names, when wrapped in keycombo. - - - Keys, Mouse Buttons, and Combinations - - Use: - - To switch to the second virtual terminal, press - Alt - F1. - -To exit vi without saving your work, type - Esc: - q!. - -My window manager is configured so that - Alt - right - mouse button is used to move windows.]]> - - Appearance: - - To switch to the second virtual terminal, press - Alt - F1. - - To exit vi without saving your - work, type - Esc - : - q - !. - - My window manager is configured so that - - Alt - right mouse button - is used to move windows. - - - - - Applications, Commands, Options, and Cites - - You will frequently want to refer to both applications - and commands when writing documentation. The distinction - between them is simple: an application is the name for a - suite (or possibly just 1) of programs that fulfill 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 its - manual section number, in the command(number) - format so common in Unix manuals. - - Mark up application names with - application. - - When you want to list a command with its manual section - number (which should be most of the time) the DocBook - element is citerefentry. This will - contain a further two elements, - refentrytitle and - manvolnum. The content of - refentrytitle is the name of the command, - and the content of manvolnum is the - manual page section. - - This can be cumbersome to write, and so a series of - general - entities have been created to make this easier. - Each entity takes the form - &man.manual-page.manual-section;. - - The file that contains these entities is in - doc/share/xml/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 V4.1-Based Extension//EN" [ - -<!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"> -%man; - -… - -]> - - Use command when you want to include - a command name in-line but present it as - something the user should type in. - - Use option to mark up the options - which will be passed to a command. - - When referring to the same command multiple times in - close proximity it is preferred to use the - &man.command.section; - notation to markup the first reference and use - command to markup subsequent references. - This makes the generated output, especially HTML, appear - visually better. - - 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.mailq.1;, and &man.newaliases.1; - 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 - , &man.mailq.1;, and &man.newaliases.1; - 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_US.ISO8859-1/books/handbook/. The first - file is called book.xml 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.xml in - that directory. You should also see a - Makefile and a number of files with a - .ent extension. - - - - - The Name of Ports - - - &os; Extension - - These elements are part of the FreeBSD extension to - DocBook, and do not exist in the original DocBook - DTD. - - - You might need to include the name of a program from the - FreeBSD Ports Collection in the documentation. Use the - filename tag with the - role attribute set to - package to identify these. Since ports - can be installed in any number of locations, only include - the category and the port name; do not include - /usr/ports. - - - <sgmltag>filename</sgmltag> Tag with - <literal>package</literal> Role - - Use: - - Install the net/ethereal port to view network traffic.]]> - - Appearance: - - Install the net/ethereal port to view - network traffic. - - - - - Devices - - - &os; 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 - - - &os; 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="ip6addr" - - - The text is an IPv6 address. - - - - - 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 separated 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 - pointyhat.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.]]> - - 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 - - - &os; 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 - - - &os; 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 documentation. This is text that is excerpted - from another file, or which should be copied from the - documentation 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 cannot 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. - - - - - Quoting System Errors - - You might want to show errors generated by FreeBSD. - Mark these with errorname. This - indicates the exact error that appears. - - - <sgmltag>errorname</sgmltag> - - Use: - - Panic: cannot mount root ]]> - - - - Appearance: - - - Panic: cannot mount root - - - - - - - Images - - - Image support in the documentation is currently - extremely experimental. The mechanisms described here are - unlikely to change, but that is not guaranteed. - - You will also need to install the - graphics/ImageMagick - port, which is used to convert between the different image - formats. This is a big port, and most of it is not - required. However, while we are working on the - Makefiles and other infrastructure it - makes things easier. This port is not - in the textproc/docproj - meta port, you must install it by hand. - - The best example of what follows in practice is the - doc/en_US.ISO8859-1/articles/vm-design/ - document. If you are unsure of the description that - follows, take a look at the files in that directory to see - how everything hangs together. Experiment with creating - different formatted versions of the document to see how the - image markup appears in the formatted output. - - - - Image Formats - - We currently support two formats for images. The format - you should use will depend on the nature of your - image. - - For images that are primarily vector based, such as - network diagrams, time lines, and similar, use Encapsulated - Postscript, and make sure that your images have the - .eps extension. - - For bitmaps, such as screen captures, use the Portable - Network Graphic format, and make sure that your images have - the .png extension. - - These are the only formats in which - images should be committed to the Subversion - repository. - - Use the right format for the right image. It is to be - expected that your documentation will have a mix of EPS and - PNG images. The Makefiles ensure that - the correct format image is chosen depending on the output - format that you use for your documentation. Do - not commit the same image to the repository in two different - formats. - - - It is anticipated that the Documentation Project will - switch to using the Scalable Vector Graphic (SVG) format - for vector images. However, the current state of SVG - capable editing tools makes this impractical. - - - - - Markup - - The markup for an image is relatively simple. First, - markup a mediaobject. The - mediaobject can contain other, more - specific objects. We are concerned with two, the - imageobject and the - textobject. - - You should include one imageobject, - and two textobject elements. The - imageobject will point to the name of the - image file that will be used (without the extension). The - textobject elements contain information - that will be presented to the user as well as, or instead - of, the image. - - There are two circumstances where this can - happen. - - - - When the reader is viewing the documentation in - HTML. In this case, each image will need to have - associated alternate text to show the user, typically - whilst the image is loading, or if they hover the mouse - pointer over the image. - - - - When the reader is viewing the documentation in - plain text. In this case, each image should have an - ASCII art equivalent to show the user. - - - - An example will probably make things easier to - understand. Suppose you have an image, called - fig1.png, that you want to include in the - document. This image is of a rectangle with an A inside it. - The markup for this would be as follows. - - <mediaobject> - <imageobject> - <imagedata fileref="fig1"> - </imageobject> - - <textobject> - <literallayout class="monospaced">+---------------+ -| A | -+---------------+</literallayout> - </textobject> - - <textobject> - <phrase>A picture</phrase> - </textobject> -</mediaobject> - - - - Include an imagedata element - inside the imageobject element. The - fileref attribute should contain the - filename of the image to include, without the extension. - The stylesheets will work out which extension should be - added to the filename automatically. - - - - - The first textobject should - contain a literallayout element, - where the class attribute is set to - monospaced. This is your opportunity - to demonstrate your ASCII art skills. This content will - be used if the document is converted to plain - text. - - Notice how the first and last lines of the content - of the literallayout element butt up - next to the element's tags. This ensures no extraneous - white space is included. - - - - The second textobject should - contain a single phrase element. The - contents of this will become the alt - attribute for the image when this document is converted - to HTML. - - - - - - <filename>Makefile</filename> Entries - - Your images must be listed in the - Makefile in the - IMAGES variable. This variable should - contain the name of all your source - images. For example, if you have created three figures, - fig1.eps, - fig2.png, - fig3.png, then your - Makefile should have lines like this in - it. - - … -IMAGES= fig1.eps fig2.png fig3.png -… - - or - - … -IMAGES= fig1.eps -IMAGES+= fig2.png -IMAGES+= fig3.png -… - - Again, the Makefile will work out - the complete list of images it needs to build your source - document, you only need to list the image files - you provided. - - - - Images and Chapters in Subdirectories - - You must be careful when you separate your documentation - into smaller files (see - ) in - different directories. - - Suppose you have a book with three chapters, and the - chapters are stored in their own directories, called - chapter1/chapter.xml, - chapter2/chapter.xml, and - chapter3/chapter.xml. If each chapter - has images associated with it, it is suggested to place - those images in each chapter's subdirectory - (chapter1/, - chapter2/, and - chapter3/). - - However, if you do this you must include the directory - names in the IMAGES variable in the - Makefile, and you - must include the directory name in the - imagedata element in your - document. - - For example, if you have - chapter1/fig1.png, then - chapter1/chapter.xml should - contain: - - <mediaobject> - <imageobject> - <imagedata fileref="chapter1/fig1"> - </imageobject> - - … - -</mediaobject> - - - - The directory name must be included in the - fileref attribute. - - - - The Makefile must contain: - - … -IMAGES= chapter1/fig1.png -… - - Then everything should just work. - - - - - Links - - - Links are also in-line elements. - - - - Linking to Other Parts of the Same Document - - Linking within the same document requires you 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. - - - Attribute <literal>id</literal> on Chapters and - Sections - - - 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 will not 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 occurred in your - document; this will work for forward links as well as - backward links). - - If you use xref then you have no - control over the text of the link. It will be generated for - you. - - - Using <sgmltag>xref</sgmltag> - - Assume that this fragment appears somewhere in a - document that includes the id - example: - - More information can be found - in . - -More specific information can be found - in .]]> - - The text of the link will be generated automatically, - and will look like (emphasized 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 cannot use - xref to link to an - id attribute on an - anchor element. The - anchor has no content, so the - xref cannot 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 - this section.]]> - - This will generate the following - (emphasized text indicates the text - that will be the link): - -
- More information can be found in the first - chapter. - - More specific information can be found in - this section. -
- - - - That last one is a bad example. Never use words like - this or here as the source - for the link. The reader will need to hunt around the - surrounding context to see where the link is actually - taking them. - - - - You can use - link to include a link to an - id on an anchor - element, since the link content defines - the text that will be used for the link. - - - - - Linking to Documents on the WWW - - Linking to external documents is much simpler, as long - as you know the URL of the document you want to link to. - Use ulink. The url - attribute is the URL of the page that the link points to, - and the content of the element is the text that will be - displayed for the user to activate. - - - <sgmltag>ulink</sgmltag> - - Use: - - Of course, you could stop reading this document and - go to the FreeBSD - home page instead.]]> - - Appearance: - - Of course, you could stop reading this document and go - to the FreeBSD home - page instead. - - - - - diff --git a/en_US.ISO8859-1/books/fdp-primer/xhtml-markup/chapter.xml b/en_US.ISO8859-1/books/fdp-primer/xhtml-markup/chapter.xml new file mode 100644 index 0000000000..43e0f8adbe --- /dev/null +++ b/en_US.ISO8859-1/books/fdp-primer/xhtml-markup/chapter.xml @@ -0,0 +1,613 @@ + + + + + <acronym>XHTML</acronym> Markup + + + Introduction + + This chapter describes usage of the XHTML + markup language used for the &os; web site. + + XHTML is the XML + version of the HyperText Markup Language, the markup language of + choice on the World Wide Web. More information can be found at + . + + XHTML is used to mark up pages on the + &os; web site. It is usually not used to mark up other + documentation, since DocBook offers a far richer set of elements + from which to choose. Consequently, XHTML + pages will normally only be encountered when writing for the web + site. + + HTML has gone through a number of + versions. The XML-compliant version + described here is called XHTML. The latest + widespread version is XHTML 1.0, available in + both strict and + transitional variants. + + The XHTML DTDs are + available from the Ports Collection in + textproc/xhtml. They are + automatically installed as part of the textproc/docproj port. + + + This is not an exhaustive list of + elements, since that would just repeat the documentation for + XHTML. The aim is to list those elements + most commonly used. Please post questions about elements or + uses not covered here to the &a.doc;. + + + + Inline Versus 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. + + + + + Formal Public Identifier (<acronym>FPI</acronym>) + + There are a number of XHTML + FPIs, depending upon the version, or + level of XHTML to which + a document conforms. Most XHTML documents on the FreeBSD web + site comply with the transitional version of + XHTML 1.0. + + PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + + + + Sectional Elements + + An XHTML document is normally split into + 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 <acronym>XHTML</acronym> Document + Structure + + <html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <title>The Document's Title</title> + </head> + + <body> + + … + + </body> +</html> + + + + + Block Elements + + + Headings + + XHTML has tags to denote headings in + the 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>, + and Other Header Tags + + Usage: + + 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 XHTML 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, preceding it. Leaving gaps in the numbering is to + be avoided. + + + Bad Ordering of + <sgmltag>h<replaceable>n</replaceable></sgmltag> + Elements + + Usage: + + First section + + + +

Sub-section

+ +]]> + + + + + Paragraphs + + XHTML supports a single paragraph + element, p. + + + <sgmltag>p</sgmltag> + + Usage: + + 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> + + Usage: + + 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 + + XHTML 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 + preceded by a bullet point. Definition lists are composed of + two sections for each entry. The first section is the term + being defined, and the second section is the definition of the + term. + + Ordered lists are indicated by the ol + element, unordered lists by the ul + element, and definition lists by the dl + element. + + Ordered and unordered lists contain listitems, indicated + by the li element. A listitem can + contain textual content, or it may be further wrapped in one + or more p elements. + + Definition lists contain definition terms + (dt) and definition descriptions + (dd). A definition term can only contain + inline elements. A definition description can contain other + block elements. + + + <sgmltag>ul</sgmltag> and + <sgmltag>ol</sgmltag> + + Usage: + + An unordered list. Listitems will probably be + preceded 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> + + Usage: + + +
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.

+]]> + + + + + Pre-formatted Text + + Pre-formatted text can 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 into one, and + line breaks in the text are significant. + + In order to do this, wrap the content in the + pre element. + + + <sgmltag>pre</sgmltag> + + For example, the pre tags could be + used to mark up an email message: + + From: nik@FreeBSD.org + To: freebsd-doc@FreeBSD.org + Subject: New documentation available + + There is a new copy of my primer for contributors to the FreeBSD + Documentation Project available at + + <URL:http://people.FreeBSD.org/~nik/primer/index.html> + + Comments appreciated. + + N]]> + + Keep in mind that < and + & still are recognized as special + characters in pre-formatted text. This is why the example + shown had to use &lt; instead of + <. For consistency, + &gt; was used in place of + >, too. Watch out for the special + characters that may appear in text copied from a plain-text + source, like an email message or program code. + + + + + Tables + + 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 the pelement is not needed. + + + Simple Use of <sgmltag>table</sgmltag> + + Usage: + + 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 or columns that should be spanned. + + + Using <literal>rowspan</literal> + + Usage: + + 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> + + Usage: + + 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 + + Usage: + + On a 3x3 grid, the top left block is a 2x2 set of + cells merged into 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 + + + Emphasizing Information + + Two levels of emphasis are available in + XHTML, 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 should not be relied upon. + According to best practices, webpages only hold structural and + semantical information and stylesheets are later applied to + them. Think of semantics, not formatting, when using these + tags. + + + <sgmltag>em</sgmltag> and + <sgmltag>strong</sgmltag> + + Usage: + + This has been emphasized, while + this has been strongly emphasized.

]]> + + + + + Indicating Fixed-Pitch Text + + Content that should be rendered in a fixed pitch + (typewriter) typeface is tagged with tt + (for teletype). + + + <sgmltag>tt</sgmltag> + + Usage: + + This document was originally written by + Nik Clayton, who can be reached by email as + nik@FreeBSD.org.

]]> + + + + + Links + + + Links are also inline elements. + + + + Linking to Other Documents on the Web + + A link points to the URL of another + document on the web. 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, + typically by a different color or underlining. + + + Using <literal><a href="..."></literal> + + Usage: + + 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. Anchors are indicated with + a and the id attribute + instead of href. + + + Using <literal><a id="..."></literal> + + Usage: + + 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 ID + 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 preceding + #). + + + Linking to a Named Part of the Same Document + + Assume that the para1 example + resides in this document: + + More information can be found in the + first paragraph of this + document.

]]> + + + + + -- cgit v1.2.3