Index: head/en_US.ISO8859-1/books/fdp-primer/docbook-markup/chapter.xml =================================================================== --- head/en_US.ISO8859-1/books/fdp-primer/docbook-markup/chapter.xml (revision 52150) +++ head/en_US.ISO8859-1/books/fdp-primer/docbook-markup/chapter.xml (revision 52151) @@ -1,2761 +1,2761 @@ 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 Document Type Definition (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 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 with additional elements and entities. These additions serve to make some of the markup easier or more precise. Throughout the rest of this document, the term DocBook is used to mean the &os;-extended DocBook DTD. Most of these extensions are not unique to &os;, 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 contact &a.doceng;. &os; Elements The additional &os; elements are not (currently) in the Ports Collection. They are stored in the &os; Subversion tree, as head/share/xml/freebsd.dtd. &os;-specific elements used in the examples below are clearly marked. &os; Entities This table shows some of the most useful entities available in the FDP. For a complete list, see the *.ent files in doc/share/xml. &os; Name Entities &os; &os; &os.stable; &os.stable; &os.current; &os.current; Manual Page Entities &man.ls.1; &man.ls.1; Usage: &man.ls.1; is the manual page for <command>ls</command>. &man.cp.1; &man.cp.1; Usage: The manual page for <command>cp</command> is &man.cp.1;. &man.command.sectionnumber; link to command manual page in section sectionnumber Entities are defined for all the &os; manual pages. &os; Mailing List Entities &a.doc; &a.doc; Usage: A link to the &a.doc;. &a.questions; &a.questions; Usage: A link to the &a.questions;. &a.listname; link to listname Entities are defined for all the &os; mailing lists. &os; Document Link Entities &url.books.handbook; &url.books.handbook; Usage: A link to the <link xlink:href="&url.books.handbook;/advanced-networking.html">Advanced Networking</link> chapter of the Handbook. &url.books.bookname; relative path to bookname Entities are defined for all the &os; books. &url.articles.committers-guide; &url.articles.committers-guide; Usage: A link to the <link xlink:href="&url.articles.committers-guide;">Committer's Guide</link> article. &url.articles.articlename; relative path to articlename Entities are defined for all the &os; articles. Other Operating System Name Entities &linux; &linux; The &linux; operating system. &unix; &unix; The &unix; operating system. &windows; &windows; The &windows; operating system. Miscellaneous Entities &prompt.root; &prompt.root; The root user prompt. &prompt.user; &prompt.user; A prompt for an unprivileged user. &postscript; &postscript; The &postscript; programming language. &tex; &tex; The &tex; typesetting language. &xorg; &xorg; The &xorg; open source X Window System. 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 FAQ, - and the Handbook are all marked up as books, for - example. + xlink:href="&url.books.faq;/index.html">FAQ, and the + 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 info. Boilerplate <tag>book</tag> with <tag>info</tag> book info titleYour Title Heretitle author personname firstnameYour first namefirstname surnameYour surnamesurname personname affiliation address emailYour email addressemail address affiliation author copyright year1998year holder role="mailto:your email address"Your nameholder copyright releaseinfo$&os;$releaseinfo abstract paraInclude an abstract of the book's contents here.para abstract info … 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 info. Boilerplate <tag>article</tag> with <tag>info</tag> article info titleYour title heretitle author personname firstnameYour first namefirstname surnameYour surnamesurname personname affiliation address emailYour email addressemailaddress address affiliation author copyright year1998year holder role="mailto:your email address"Your nameholder copyright releaseinfo$&os;$releaseinfo abstract paraInclude an abstract of the article's contents here.para abstract info … 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 chapter titleThe Chapter's Titletitle ... chapter 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 chapter titleThis is An Empty Chaptertitle parapara 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 chapter titleA Sample Chaptertitle paraSome text in the chapter.para sect1 titleFirst Sectiontitle … sect1 sect1 titleSecond Sectiontitle sect2 titleFirst Sub-Sectiontitle sect3 titleFirst Sub-Sub-Sectiontitle … sect3 sect2 sect2 titleSecond Sub-Section (1.2.2)title … sect2 sect1 chapter Section numbers are automatically generated and prepended to titles when the document is rendered to an output format. The generated section numbers and titles from the example above will be: 1.1. First Section 1.2. Second Section 1.2.1. First Sub-Section 1.2.1.1. First Sub-Sub-Section 1.2.2. Second Sub-Section Subdividing Using <tag>part</tag> Elements parts introduce another level of organization between book and chapter with one or more parts. This cannot be done in an article. part titleIntroductiontitle chapter titleOverviewtitle ... chapter chapter titleWhat is FreeBSD?title ... chapter chapter titleHistorytitle ... chapter part 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. <tag>para</tag> Example Usage: paraThis is a paragraph. It can contain just about any other element.para 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). <tag>blockquote</tag> Example Usage: paraA small excerpt from the US Constitution:para blockquote titlePreamble to the Constitution of the United Statestitle attributionCopied from a web site somewhereattribution paraWe the People of the United States, in Order to form a more perfect Union, establish Justice, insure domestic Tranquility, provide for the common defence, promote the general Welfare, and secure the Blessings of Liberty to ourselves and our Posterity, do ordain and establish this Constitution for the United States of America.para blockquote 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, and Important Information 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. Several types of admonitions are available: tip, note, warning, caution, and important. Which admonition to choose depends on the situation. The DocBook documentation suggests: Note is for information that should be heeded by all readers. Important is a variation on Note. Caution is for information regarding possible data loss or software damage. Warning is for information regarding possible hardware damage or injury to life or limb. <tag>tip</tag> and <tag>important</tag> Example Usage: tip para&os; may reduce stress.para tip important paraPlease use admonitions sparingly. Too many admonitions are visually jarring and can have the opposite of the intended effect.para important Appearance: &os; may reduce stress. Please use admonitions sparingly. Too many admonitions are visually jarring and can have the opposite of the intended effect. Examples Examples can be shown with example. <tag>example</tag> Source Usage: example paraEmpty files can be created easily:para screen&prompt.user; userinputtouch file1 file2 file3userinputscreen example Appearance: Rendered <tag>example</tag> Empty files can be created easily: &prompt.user; touch file1 file2 file3 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, variablelist, or procedure. There are other types of list elements in DocBook, but we will not cover them here. 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. <tag>itemizedlist</tag> and <tag>orderedlist</tag> Example Usage: itemizedlist listitem paraThis is the first itemized item.para listitem listitem paraThis is the second itemized item.para listitem itemizedlist orderedlist listitem paraThis is the first ordered item.para listitem listitem paraThis is the second ordered item.para listitem orderedlist 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. An alternate and often useful way of presenting information is the variablelist. These are lists where each entry has a term and a description. They are well suited for many types of descriptions, and present information in a form that is often easier for the reader than sections and subsections. A variablelist has a title, and then pairs of term and listitem entries. <tag>variablelist</tag> Example Usage: variablelist varlistentry termParallelterm listitem paraIn parallel communications, groups of bits arrive at the same time over multiple communications channels.para listitem varlistentry varlistentry termSerialterm listitem paraIn serial communications, bits arrive one at a time over a single communications channel.para listitem varlistentry variablelist Appearance: Parallel In parallel communications, groups of bits arrive at the same time over multiple communications channels. Serial In serial communications, bits arrive one at a time over a single communications channel. - A procedure shows a series of - steps, which may in turn - consist of more steps or - substeps. Each step - contains block elements and may include an optional title. + A procedure shows a series of steps, + which may in turn consist of more steps or + substeps. Each step contains block + elements and may include an optional title. Sometimes, steps are not sequential, but present a choice: do this or do that, but not both. For these alternative choices, use stepalternatives. <tag>procedure</tag> Example Usage: procedure step paraDo this.para step step paraThen do this.para step step substeps step paraAnd now do this smaller thing.para step step paraAnd now do this other smaller thing.para step substeps step step paraFinally, do one of these:para stepalternatives step paraGo left.para step step paraGo right.para step stepalternatives step procedure Appearance: Do this. Then do this. And now do this small thing. And this other small thing. Finally, do one of these: Go left. Go right. 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. <tag>programlisting</tag> Example Usage: paraWhen finished, the program will look like this:para programlisting#include &lt;stdio.h&gt; int main(void) { printf("hello, world\n"); return 0; }programlisting 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"); return 0; } Callouts A callout is a visual marker for referring to a piece of text or specific position within an example. Callouts are marked with the co element. Each element must have a unique id assigned to it. After the example, include a calloutlist that describes each callout. <tag>co</tag> and <tag>calloutlist</tag> Example paraWhen finished, the program will look like this:para programlisting#include &lt;stdio.h&gt; co xml:id="co-ex-include" int co xml:id="co-ex-return" main(void) { printf("hello, world\n"); co xml:id="co-ex-printf" }programlisting calloutlist callout arearefs="co-ex-include" paraIncludes the standard IO header file.para callout callout arearefs="co-ex-return" paraSpecifies that functionmain()function returns an int.para callout callout arearefs="co-ex-printf" paraThe functionprintf()function call that writes literalhello, worldliteral to standard output.para callout calloutlist 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. <tag>informaltable</tag> Example Usage: informaltable pgwide="1" tgroup cols="2" thead row entryThis is Column Head 1entry entryThis is Column Head 2entry row thead tbody row entryRow 1, column 1entry entryRow 1, column 2entry row row entryRow 2, column 1entry entryRow 2, column 2entry row tbody tgroup informaltable 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". - Table with <literal>frame="none"</literal> Example + Table with <literal>frame="none"</literal> + Example 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. <tag>screen</tag>, <tag>prompt</tag>, and <tag>userinput</tag> Example Usage: screen&prompt.user; userinputls -1userinput foo1 foo2 foo3 &prompt.user; userinputls -1 | grep foo2userinput foo2 &prompt.user; userinputsuuserinput promptPassword: prompt &prompt.root; userinputcat foo2userinput This is the file called 'foo2'screen 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. <tag>emphasis</tag> Example Usage: para&os; is without doubt emphasistheemphasis premiere &unix;-like operating system for the Intel architecture.para Appearance: &os; is without doubt the premiere &unix;-like operating system for the Intel architecture. Acronyms Many computer terms are acronyms, words formed from the first letter of each word in a phrase. Acronyms are marked up into acronym elements. It is helpful to the reader when an acronym is defined on the first use, as shown in the example below. <tag>acronym</tag> Example Usage: paraRequest For Comments (acronymRFCacronym) 1149 defined the use of avian carriers for transmission of Internet Protocol (acronymIPacronym) data. The quantity of acronymIPacronym data currently transmitted in that manner is unknown.para Appearance: Request For Comments (RFC) 1149 defined the use of avian carriers for transmission of Internet Protocol (IP) data. The quantity of IP data currently transmitted in that manner is unknown. 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. <tag>quote</tag> Example Usage: paraHowever, make sure that the search does not go beyond the quoteboundary between local and public administrationquote, as acronymRFCacronym 1535 calls it.para 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 Example Usage: paraTo switch to the second virtual terminal, press keycombo action="simul"keycapAltkeycap keycapF1keycapkeycombo.para paraTo exit commandvicommand without saving changes, type keycombo action="seq"keycapEsckeycapkeycap:keycap keycapqkeycapkeycap!keycapkeycombo.para paraMy window manager is configured so that keycombo action="simul"keycapAltkeycap mousebuttonrightmousebutton keycombo mouse button is used to move windows.para 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 to include a command name in-line but present it as something the user should type. 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. Applications, Commands, and Options Example Usage: paraapplicationSendmailapplication is the most widely used Unix mail application.para paraapplicationSendmailapplication includes the citerefentry refentrytitlesendmailrefentrytitle manvolnum8manvolnum citerefentry, &man.mailq.1;, and &man.newaliases.1; programs.para paraOne of the command line parameters to citerefentry refentrytitlesendmailrefentrytitle manvolnum8manvolnum citerefentry, option-bpoption, will display the current status of messages in the mail queue. Check this on the command line by running commandsendmail -bpcommand.para 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, Device Names To refer to the name of a file, a directory, a file extension, or a device name, use filename. <tag>filename</tag> Example Usage: paraThe source for the Handbook in English is found in filename/usr/doc/en_US.ISO8859-1/books/handbook/filename. The main file is called filenamebook.xmlfilename. There is also a filenameMakefilefilename and a number of files with a filename.entfilename extension.para parafilenamekbd0filename is the first keyboard detected by the system, and appears in filename/devfilename.para Appearance: The source for the Handbook in English is found in /usr/doc/en_US.ISO8859-1/books/handbook/. The main file is called book.xml. There is also a Makefile and a number of files with a .ent extension. kbd0 is the first keyboard detected by the system, and appears in /dev. 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 package tag. Since the Ports Collection can be installed in any number of locations, only include the category and the port name; do not include /usr/ports. By default, package refers to a binary package. To refer to a port that will be built from source, set the role attribute to port. <tag>package</tag> Example Usage: paraInstall the packagenet/wiresharkpackage binary package to view network traffic.para parapackage role="port"net/wiresharkpackage can also be built and installed from the Ports Collection.para Appearance: Install the net/wireshark binary package to view network traffic. net/wireshark can also be built and installed from the Ports Collection. Hosts, Domains, IP Addresses, User Names, Group Names, and Other System Items &os; Extension These elements are part of the &os; extension to DocBook, and do not exist in the original DocBook DTD. Information for system items is marked up with systemitem. The class attribute is used to identify the particular type of information shown. class="domainname" The text is a domain name, such as FreeBSD.org or ngo.org.uk. There is no hostname component. class="etheraddress" The text is an Ethernet MAC address, expressed as a series of 2 digit hexadecimal numbers separated by colons. class="fqdomainname" The text is a Fully Qualified Domain Name, with both hostname and domain name parts. class="ipaddress" The text is an IP address, probably expressed as a dotted quad. class="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). class="systemname" With class="systemname" the marked up information is the simple hostname, such as freefall or wcarchive. class="username" The text is a username, like root. class="groupname" The text is a groupname, like wheel. <tag>systemitem</tag> and Classes Example Usage: paraThe local machine can always be referred to by the name systemitem class="systemname"localhostsystemitem, which will have the IP address systemitem class="ipaddress"127.0.0.1systemitem.para paraThe systemitem class="domainname"FreeBSD.orgsystemitem domain contains a number of different hosts, including systemitem class="fqdomainname"freefall.FreeBSD.orgsystemitem and systemitem class="fqdomainname"bento.FreeBSD.orgsystemitem.para paraWhen adding an acronymIPacronym alias to an interface (using commandifconfigcommand) emphasisalwaysemphasis use a netmask of systemitem class="netmask"255.255.255.255systemitem (which can also be expressed as systemitem class="netmask"0xffffffffsystemitem).para paraThe acronymMACacronym address uniquely identifies every network card in existence. A typical acronymMACacronym address looks like systemitem class="etheraddress"08:00:20:87:ef:d0systemitem.para paraTo carry out most system administration functions requires logging in as systemitem class="username"rootsystemitem.para 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. To carry out most system administration functions requires logging in as root. Uniform Resource Identifiers (<acronym>URI</acronym>s) Occasionally it is useful to show a Uniform Resource Identifier (URI) without - making it an active hyperlink. The uri element + making it an active hyperlink. The uri element makes this possible: <tag>uri</tag> Example Usage: paraThis URL shows only as text: urihttps://www.FreeBSD.orguri. It does not create a link.para Appearance: This URL shows only as text: https://www.FreeBSD.org. It does not create a link. To create links, see . Email Addresses Email addresses are marked up as email elements. In the HTML output format, the wrapped text becomes a hyperlink to the email address. Other output formats that support hyperlinks may also make the email address into a link. <tag>email</tag> with a Hyperlink Example Usage: paraAn email address that does not actually exist, like emailnotreal@example.comemail, can be used as an example.para Appearance: An email address that does not actually exist, like notreal@example.com, can be used as an example. A &os;-specific extension allows setting the role attribute to nolink to prevent the creation of the hyperlink to the email address. <tag>email</tag> Without a Hyperlink Example Usage: paraSometimes a link to an email address like email role="nolink"notreal@example.comemail is not desired.para Appearance: Sometimes a link to an email address like notreal@example.com is not desired. 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, buildtarget and varname. buildtarget identifies a build target exported by a Makefile that can be given as a parameter to make. varname identifies a variable that can be set (in the environment, on the command line with make, or within the Makefile) to influence the process. <tag>buildtarget</tag> and <tag>varname</tag> Example Usage: paraTwo common targets in a filenameMakefilefilename are buildtargetallbuildtarget and buildtargetcleanbuildtarget.para paraTypically, invoking buildtargetallbuildtarget will rebuild the application, and invoking buildtargetcleanbuildtarget will remove the temporary files (filename.ofilename for example) created by the build process.para parabuildtargetcleanbuildtarget may be controlled by a number of variables, including varnameCLOBBERvarname and varnameRECURSEvarname.para 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. <tag>literal</tag> Example Usage: paraThe literalmaxusers 10literal 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.para 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. <tag>replaceable</tag> Example Usage: screen&prompt.user; userinputman replaceablecommandreplaceableuserinputscreen 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: paraThe literalmaxusers replaceablenreplaceableliteral 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.para paraFor a desktop workstation, literal32literal is a good value for replaceablenreplaceable.para 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. Showing <acronym>GUI</acronym> Buttons Buttons presented by a graphical user interface are marked with guibutton. To make the text look more like a graphical button, brackets and non-breaking spaces are added surrounding the text. <tag>guibutton</tag> Example Usage: paraEdit the file, then click guibutton[&nbsp;Save&nbsp;]guibutton to save the changes.para Appearance: Edit the file, then click [ Save ] to save the changes. Quoting System Errors System errors generated by &os; are marked with errorname. This indicates the exact error that appears. <tag>errorname</tag> Example Usage: screenerrornamePanic: cannot mount rooterrornamescreen Appearance: Panic: cannot mount root Images Image support in the documentation is somewhat experimental. The mechanisms described here are unlikely to change, but that is not guaranteed. To provide conversion between different image formats, the graphics/ImageMagick port must be installed. This port is not included in the textproc/docproj meta port, and must be installed separately. A good example of the use of images is the doc/en_US.ISO8859-1/articles/vm-design/ document. Examine the files in that directory to see how these elements are used together. Build different output formats to see how the format determines what images are shown in the rendered document. Image Formats The following image formats are currently supported. An image file will automatically be converted to bitmap or vector image depending on the output document format. These are the only formats in which images should be committed to the documentation repository. EPS (Encapsulated Postscript) Images that are primarily vector based, such as network diagrams, time lines, and similar, should be in this format. These images have a .eps extension. PNG (Portable Network Graphic) For bitmaps, such as screen captures, use this format. These images have the .png extension. PIC (PIC graphics language) PIC is a language for drawing simple vector-based figures used in the &man.pic.1; utility. These images have the .pic extension. SCR (SCReen capture) This format is specific to screenshots of console output. The following command generates an SCR file shot.scr from video buffer of /dev/ttyv0: &prompt.root; vidcontrol -p < /dev/ttyv0 > shot.scr This is preferable to PNG format for screenshots because the SCR file contains plain text of the command lines so that it can be converted to a PNG image or a plain text depending on the output document format. Use the appropriate format for each image. Documentation will often have a mix of EPS and PNG images. The Makefiles ensure that the correct format image is chosen depending on the output format used. Do not commit the same image to the repository in two different formats. The Documentation Project may eventually 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 File Locations Image files can be stored in one of several locations, depending on the document and image: In the same directory as the document itself, usually done for articles and small books that keep all their files in a single directory. In a subdirectory of the main document. Typically done when a large book uses separate subdirectories to organize individual chapters. When images are stored in a subdirectory of the main document directory, the subdirectory name must be included in their paths in the Makefile and the imagedata element. In a subdirectory of doc/share/images named after the document. For example, images for the Handbook are stored in doc/share/images/books/handbook. Images that work for multiple translations are stored in this upper level of the documentation file tree. Generally, these are images that can be used unchanged in non-English translations of the document. Image Markup Images are included as part of 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. Text elements are shown to the reader in several situations. When the document is viewed in HTML, text elements are shown while the image is loading, or if the mouse pointer is hovered over the image, or if a text-only browser is being used. In formats like plain text where graphics are not possible, the text elements are shown instead of the graphical ones. This example shows how to include an image called fig1.png in a document. The image is a rectangle with an A inside it: mediaobject imageobject imagedata fileref="fig1" imageobject textobject literallayout class="monospaced"+---------------+ | A | +---------------+literallayout textobject textobject phraseA picturephrase 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, 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. 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 … Links Links are also in-line elements. To show a URI without creating a link, see . <literal>xml:id</literal> Attributes Most DocBook elements accept an xml:id attribute to give that part of the document a unique name. The xml: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 xml:id attribute. Assigning an xml:id to all chapters and sections, even if there are no current plans to link to them, is a good idea. These xml:ids can be used as unique reference points by anyone referring to the HTML version of the document. <literal>xml:id</literal> on Chapters and Sections Example chapter xml:id="introduction" titleIntroductiontitle paraThis is the introduction. It contains a subsection, which is identified as well.para sect1 xml:id="introduction-moredetails" titleMore Detailstitle paraThis is a subsection.para sect1 chapter Use descriptive values for xml:id names. The values must be unique within the entire document, not just in a single file. In the example, the subsection xml:id is constructed by appending text to the chapter xml:id. This ensures that the xml: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. Crossreferences with <literal>xref</literal> xref provides the reader with a link to jump to another section of the document. The target xml:id is specified in the linkend attribute, and xref generates the link text automatically. <tag>xref</tag> Example Assume that this fragment appears somewhere in a document that includes the xml:id example shown above: paraMore information can be found in xref linkend="introduction".para paraMore specific information can be found in xref linkend="introduction-moredetails".para The link text will be generated automatically, looking like (emphasized text indicates the link text):
More information can be found in Chapter 1, Introduction. More specific information can be found in Section 1.1, More Details.
The link text is generated automatically from the chapter and section number and title elements. Linking to Other Documents on the Web The link element described here allows the writer to - define the link text. When link text is used, it is very important to be descriptive - to give the reader an idea of where the link goes. - Remember that DocBook can be rendered to multiple - types of media. The reader might 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 might not be able to - locate the linked section. + define the link text. When link text is used, it is very + important to be descriptive to give the reader an idea of + where the link goes. Remember that DocBook can be rendered to + multiple types of media. The reader might 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 might + not be able to locate the linked section. - The xlink:href attribute - is the URL of the page, - and the content of the element is the text that - will be displayed for the user to activate. + The xlink:href attribute is the + URL of the page, and the content of the + element is the text that will be displayed for the user to + activate. In many situations, it is preferable to show the actual URL rather than text. This can be done by leaving out the element text entirely. <tag>link</tag> to a &os; Documentation Web Page Example 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 &os; book links: paraRead the link xlink:href="&url.books.handbook;/svn.html#svn-intro"SVN introductionlink, then pick the nearest mirror from the list of link xlink:href="&url.books.handbook;/svn.html#svn-mirrors"Subversion mirror siteslink.para Appearance: Read the SVN introduction, then pick the nearest mirror from the list of Subversion mirror sites. Usage for &os; article links: paraRead this link xlink:href="&url.articles.bsdl-gpl;"article about the BSD licenselink, or just the link xlink:href="&url.articles.bsdl-gpl;#intro"introductionlink.para Appearance: Read this article about the BSD license, or just the introduction. <tag>link</tag> to a &os; Web Page Example Usage: paraOf course, you could stop reading this document and go to the link xlink:href="&url.base;/index.html"FreeBSD home pagelink instead.para Appearance: Of course, you could stop reading this document and go to the FreeBSD home page instead. <tag>link</tag> to an External Web Page Example Usage: paraWikipedia has an excellent reference on link xlink:href="http://en.wikipedia.org/wiki/GUID_Partition_Table"GUID Partition Tableslink.para Appearance: Wikipedia has an excellent reference on GUID Partition Tables. The link text can be omitted to show the actual URL: paraWikipedia has an excellent reference on GUID Partition Tables: link xlink:href="http://en.wikipedia.org/wiki/GUID_Partition_Table"link.para The same link can be entered using shorter notation instead of a separate ending tag: paraWikipedia has an excellent reference on GUID Partition Tables: link xlink:href="http://en.wikipedia.org/wiki/GUID_Partition_Table".para The two methods are equivalent. Appearance: Wikipedia has an excellent reference on GUID Partition Tables: http://en.wikipedia.org/wiki/GUID_Partition_Table. Index: head/en_US.ISO8859-1/books/fdp-primer/stylesheets/chapter.xml =================================================================== --- head/en_US.ISO8859-1/books/fdp-primer/stylesheets/chapter.xml (revision 52150) +++ head/en_US.ISO8859-1/books/fdp-primer/stylesheets/chapter.xml (revision 52151) @@ -1,74 +1,76 @@ - + Style Sheets XML is concerned with content, and says nothing about how that content should be presented to the reader or rendered on paper. Multiple style sheet languages have been developed to describe visual layout, including Extensible Stylesheet Language Transformation (XSLT), Document Style Semantics and Specification Language (DSSSL), and Cascading Style Sheets (CSS). The FDP documents use XSLT stylesheets to transform DocBook into XHTML, and then CSS formatting is applied to the XHTML pages. Printable output is currently rendered with legacy DSSSL stylesheets, but this will probably change in the future. <acronym>CSS</acronym> Cascading Style Sheets (CSS) are a mechanism for attaching style information (font, weight, size, color, and so forth) to elements in an XHTML document without abusing XHTML to do so. The DocBook Documents The &os; XSLT and DSSSL stylesheets refer to docbook.css, which is expected to be present in the same directory as the XHTML files. The project-wide CSS file is copied from doc/share/misc/docbook.css when documents are converted to XHTML, and is installed automatically. Index: head/en_US.ISO8859-1/books/fdp-primer/the-website/chapter.xml =================================================================== --- head/en_US.ISO8859-1/books/fdp-primer/the-website/chapter.xml (revision 52150) +++ head/en_US.ISO8859-1/books/fdp-primer/the-website/chapter.xml (revision 52151) @@ -1,281 +1,285 @@ - + The Website The &os; web site is part of the &os; documents. Files for the web site are stored in the en_US.ISO8859-1/htdocs subdirectory of the document tree directory, ~/doc in this example. Environment Variables Several environment variables control which parts of the web site are built or installed, and to which directories. The web build system uses &man.make.1;, and considers variables to be set when they have been defined, even if they are empty. The examples here show the recommended ways of defining and using these variables. Setting or defining these variables with other values or methods might lead to unexpected surprises. DESTDIR DESTDIR specifies the path where the web site files are to be installed. This variable is best set with &man.env.1; or the user shell's method of setting environment variables, setenv for &man.csh.1; or export for &man.sh.1;. ENGLISH_ONLY Default: undefined. Build and include all translations. ENGLISH_ONLY=yes: use only the English documents and ignore all translations. WEB_ONLY Default: undefined. Build both the web site and all the books and articles. WEB_ONLY=yes: build or install only HTML pages from the en_US.ISO8859-1/htdocs directory. Other directories and documents, including books and articles, will be ignored. WEB_LANG Default: undefined. Build and include all the available languages on the web site. Set to a space-separated list of languages to be included in the build or install. The formats are the same as the directory names in the document root directory. For example, to include the German and French documents: WEB_LANG="de_DE.ISO8859-1 fr_FR.ISO8859-1" WEB_ONLY, WEB_LANG, and ENGLISH_ONLY are &man.make.1; variables and can be set in /etc/make.conf, Makefile.inc, as environment variables on the command line, or in dot files. Building and Installing the Web Pages Having obtained the documentation and web site source files, the web site can be built. - An actual installation of the web site is run as the root - user because the permissions on the web server directory will - not allow files to be installed by an unprivileged user. - For testing, it can be useful to install the files as a normal - user to a temporary directory. + An actual installation of the web site is run as the + root user because the + permissions on the web server directory will not allow files to + be installed by an unprivileged user. For testing, it can be + useful to install the files as a normal user to a temporary + directory. In these examples, the web site files are built by user jru in their home directory, ~/doc, with a full path of /usr/home/jru/doc. The web site build uses the INDEX from the Ports Collection and might fail if that file or - /usr/ports is not - present. The simplest approach is to install the Ports - Collection. + /usr/ports is not present. The simplest + approach is to install the Ports + Collection. Build the Full Web Site and All Documents Build the web site and all documents. The resulting files are left in the document tree: &prompt.user; cd ~/doc/en_US.ISO8859-1/htdocs/ &prompt.user; make all Build Only the Web Site in English Build the web site only, in English, as user jru, and install the resulting files into /tmp/www for testing: &prompt.user; cd ~/doc/en_US.ISO8859-1/htdocs/ &prompt.user; env DESTDIR=/tmp/www make ENGLISH_ONLY=yes WEB_ONLY=yes all install Changes to static files can usually be tested by viewing the modified files directly with a web browser. If the site has been built as shown above, a modified main page can be viewed with: &prompt.user; firefox /tmp/www/data/index.html Modifications to dynamic files can be tested with a web server running on the local system. After building the site as shown above, this /usr/local/etc/apache24/httpd.conf can be used with www/apache24: # httpd.conf for testing the FreeBSD website Define TestRoot "/tmp/www/data" # directory for configuration files ServerRoot "/usr/local" Listen 80 # minimum required modules LoadModule authz_core_module libexec/apache24/mod_authz_core.so LoadModule mime_module libexec/apache24/mod_mime.so LoadModule unixd_module libexec/apache24/mod_unixd.so LoadModule cgi_module libexec/apache24/mod_cgi.so LoadModule dir_module libexec/apache24/mod_dir.so # run the webserver as user and group User www Group www ServerAdmin you@example.com ServerName fbsdtest # deny access to all files <Directory /> AllowOverride none Require all denied </Directory> # allow access to the website directory DocumentRoot "${TestRoot}" <Directory "${TestRoot}"> Options Indexes FollowSymLinks AllowOverride None Require all granted </Directory> # prevent access to .htaccess and .htpasswd files <Files ".ht*"> Require all denied </Files> ErrorLog "/var/log/httpd-error.log" LogLevel warn # set up the CGI script directory <Directory "${TestRoot}/cgi"> AllowOverride None Options None Require all granted Options +ExecCGI AddHandler cgi-script .cgi </Directory> Include etc/apache24/Includes/*.conf Start the web server with &prompt.root; service apache24 onestart - The web site can be viewed at - . Be aware that many - links refer to the real &os; site by name, and those links - will still go to the external site instead of the local test + The web site can be viewed at . Be aware that many links + refer to the real &os; site by name, and those links will + still go to the external site instead of the local test version. Fully testing the local site will require temporarily setting DNS so www.FreeBSD.org resolves to localhost or the local IP address. Build and Install the Web Site Build the web site and all documents as user jru. Install the resulting files as root into the default directory, /root/public_html: &prompt.user; cd ~/doc/en_US.ISO8859-1/htdocs &prompt.user; make all &prompt.user; su - Password: &prompt.root; cd /usr/home/jru/doc/en_US.ISO8859-1/htdocs &prompt.root; make install The install process does not delete any old or outdated files that existed previously in the same directory. If a new copy of the site is built and installed every day, this command will find and delete all files that have not been updated in three days: &prompt.root; find /usr/local/www -ctime 3 -delete Index: head/en_US.ISO8859-1/books/fdp-primer/tools/chapter.xml =================================================================== --- head/en_US.ISO8859-1/books/fdp-primer/tools/chapter.xml (revision 52150) +++ head/en_US.ISO8859-1/books/fdp-primer/tools/chapter.xml (revision 52151) @@ -1,140 +1,143 @@ - + Tools Several software tools are used to manage the FreeBSD documentation and render it to different output formats. Some of these tools are required and must be installed before working through the examples in the following chapters. Some are optional, adding capabilities or making the job of creating documentation less demanding. Required Tools Install textproc/docproj from the Ports Collection. This meta-port installs all the applications required to do useful work with the &os; documentation. Some further notes on particular components are given below. <acronym>DTD</acronym>s and <acronym>Entities</acronym> &os; documentation uses several Document Type Definitions (DTDs) and sets of XML entities. These are all installed by the textproc/docproj port. XHTML DTD (textproc/xhtml) XHTML is the markup language of choice for the World Wide Web, and is used throughout the &os; web site. - DocBook DTD (textproc/docbook-xml) + DocBook DTD + (textproc/docbook-xml) DocBook is designed for marking up technical documentation. Most of the &os; documentation is written in DocBook. ISO 8879 entities (textproc/iso8879) Character entities from the ISO 8879:1986 standard used by many DTDs. Includes named mathematical symbols, additional characters in the Latin character set (accents, diacriticals, and so on), and Greek symbols. Optional Tools These applications are not required, but can make working on the documentation easier or add capabilities. Software Vim (editors/vim) A popular editor for working with XML and derived documents, like DocBook XML. Emacs or XEmacs (editors/emacs or editors/xemacs) Both of these editors include a special mode for editing documents marked up according to an XML DTD. This mode includes commands to reduce the amount of typing needed, and help reduce the possibility of errors. Index: head/en_US.ISO8859-1/books/fdp-primer/working-copy/chapter.xml =================================================================== --- head/en_US.ISO8859-1/books/fdp-primer/working-copy/chapter.xml (revision 52150) +++ head/en_US.ISO8859-1/books/fdp-primer/working-copy/chapter.xml (revision 52151) @@ -1,176 +1,184 @@ - + The Working Copy The working copy is a copy of the &os; repository documentation tree downloaded onto the local computer. Changes are made to the local working copy, tested, and then submitted as patches to be committed to the main repository. A full copy of the documentation tree can occupy 700 megabytes of disk space. Allow for a full gigabyte of space to have room for temporary files and test versions of various output formats. - Subversion - is used to manage the &os; documentation files. It is obtained by installing the Subversion package: + Subversion + is used to manage the &os; documentation files. It is obtained by + installing the Subversion + package: &prompt.root; pkg install subversion Documentation and Manual Pages &os; documentation is not just books and articles. Manual pages for all the commands and configuration files are also part of the documentation, and part of the FDP's territory. Two repositories are involved: doc for the books and articles, and base for the operating system and manual pages. To edit manual pages, the base repository must be checked out separately. Repositories may contain multiple versions of documentation and source code. New modifications are almost always made only to the latest version, called head. Choosing a Directory &os; documentation is traditionally stored in /usr/doc/, and system source code with manual pages in /usr/src/. These directory trees are relocatable, and users may want to put the working copies in other locations to avoid interfering with existing information in the main directories. The examples that follow use ~/doc and ~/src, both subdirectories of the user's home directory. Checking Out a Copy A download of a working copy from the repository is called a checkout, and done with svn checkout. This example checks out a copy of the latest version (head) of the main documentation tree: &prompt.user; svn checkout https://svn.FreeBSD.org/doc/head ~/doc A checkout of the source code to work on manual pages is very similar: &prompt.user; svn checkout https://svn.FreeBSD.org/base/head ~/src Updating a Working Copy The documents and files in the &os; repository change daily. People modify files and commit changes frequently. Even a short time after an initial checkout, there will already be differences between the local working copy and the main &os; repository. To update the local version with the changes that have been made to the main repository, use svn update on the directory containing the local working copy: &prompt.user; svn update ~/doc Get in the protective habit of using svn update before editing document files. Someone else may have edited that file very recently, and the local working copy will not include the latest changes until it has been updated. Editing the newest version of a file is much easier than trying to combine an older, edited local file with the newer version from the repository. Reverting Changes Sometimes it turns out that changes were not necessary after all, or the writer just wants to start over. Files can be reset to their unchanged form with svn revert. For example, to erase the edits made to chapter.xml and reset it to unmodified form: &prompt.user; svn revert chapter.xml Making a Diff After edits to a file or group of files are completed, the differences between the local working copy and the version on the &os; repository must be collected into a single file for submission. These diff files are produced by redirecting the output of svn diff into a file: &prompt.user; cd ~/doc &prompt.user; svn diff > doc-fix-spelling.diff Give the file a meaningful name that identifies the contents. The example above is for spelling fixes to the whole documentation tree. If the diff file is to be submitted with the web - Submit a &os; - problem report interface, add a + Submit + a &os; problem report interface, add a .txt extension to give the earnest and simple-minded web form a clue that the contents are plain text. Be careful: svn diff includes all changes made in the current directory and any subdirectories. If there are files in the working copy with edits that are not ready to be submitted yet, provide a list of only the files that are to be included: &prompt.user; cd ~/doc &prompt.user; svn diff disks/chapter.xml printers/chapter.xml > disks-printers.diff <application>Subversion</application> References These examples show very basic usage of Subversion. More detail is available - in the Subversion Book - and the Subversion + in the Subversion + Book and the Subversion documentation. Index: head/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.xml =================================================================== --- head/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.xml (revision 52150) +++ head/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.xml (revision 52151) @@ -1,598 +1,607 @@ - + Writing Style Tips Technical documentation can be improved by consistent use of several principles. Most of these can be classified into three goals: be clear, be complete, and be concise. These goals can conflict with each other. Good writing consists of a balance between them. Be Clear Clarity is extremely important. The reader may be a novice, or reading the document in a second language. Strive for simple, uncomplicated text that clearly explains the concepts. Avoid flowery or embellished speech, jokes, or colloquial expressions. Write as simply and clearly as possible. Simple text is easier to understand and translate. Keep explanations as short, simple, and clear as possible. Avoid empty phrases like in order to, which usually just means to. Avoid potentially patronizing words like basically. Avoid Latin - terms like i.e. or cf., which + terms like i.e., or cf., which may be unknown outside of academic or scientific groups. Write in a formal style. Avoid addressing the reader as you. For example, say copy the file to /tmp rather than you can copy the file to /tmp. Give clear, correct, tested examples. A trivial example is better than no example. A good example is better yet. Do not give bad examples, identifiable by apologies or sentences like but really it should never be done that way. Bad examples are worse than no examples. Give good examples, because even when warned not to use the example as shown, the reader will usually just use the example as shown. Avoid weasel words like should, might, try, or could. These words imply that the speaker is unsure of the facts, and create doubt in the reader. Similarly, give instructions as imperative commands: not you should do this, but merely do this. Be Complete Do not make assumptions about the reader's abilities or skill level. Tell them what they need to know. Give links to other documents to provide background information without having to recreate it. Put yourself in the reader's place, anticipate the questions they will ask, and answer them. Be Concise While features should be documented completely, sometimes there is so much information that the reader cannot easily find the specific detail needed. The balance between being complete and being concise is a challenge. One approach is to have an introduction, then a quick start section that describes the most common situation, followed by an in-depth reference section. Guidelines To promote consistency between the myriad authors of the &os; documentation, some guidelines have been drawn up for authors to follow. Use American English Spelling There are several variants of English, with different spellings for the same word. Where spellings differ, use the American English variant. color, not colour, rationalize, not rationalise, and so on. The use of British English may be accepted in the case of a contributed article, however the spelling must be consistent within the whole document. The other documents such as books, web site, manual pages, etc. will have to use American English. Do not use contractions Do not use contractions. Always spell the phrase out in full. Don't use contractions is wrong. Avoiding contractions makes for a more formal tone, is more precise, and is slightly easier for translators. Use the serial comma In a list of items within a paragraph, separate each item from the others with a comma. Separate the last item from the others with a comma and the word and. For example:
This is a list of one, two and three items.
Is this a list of three items, one, two, and three, or a list of two items, one and two and three? It is better to be explicit and include a serial comma:
This is a list of one, two, and three items.
Avoid redundant phrases Do not use redundant phrases. In particular, the command, the file, and man command are often redundant. For example, commands: Wrong: Use the svn command to update sources. Right: Use svn to update sources. Filenames: Wrong: … in the filename /etc/rc.local… Right: … in /etc/rc.local… Manual page references (the second example uses citerefentry with the &man.csh.1; entity):. Wrong: See man csh for more information. Right: See &man.csh.1;. Two spaces between sentences Always use two spaces between sentences, as it improves readability and eases use of tools such as Emacs. A period and spaces followed by a capital letter does not always mark a new sentence, especially in names. Jordan K. Hubbard is a good example. It has a capital H following a period and a space, and is certainly not a new sentence. - For more information about writing style, see Elements of + For more information about writing style, see Elements of Style, by William Strunk. Style Guide To keep the source for the documentation consistent when many different people are editing it, please follow these style conventions. Letter Case Tags are entered in lower case, para, not PARA. Text that appears in SGML contexts is generally written in upper case, <!ENTITY…>, and <!DOCTYPE…>, not <!entity…> and <!doctype…>. Acronyms Acronyms should be defined the first time they appear in a document, as in: Network Time Protocol (NTP). After the acronym has been defined, use the acronym alone unless it makes more sense contextually to use the whole term. Acronyms are usually defined only once per chapter or per document. All acronyms should be enclosed in acronym tags. Indentation The first line in each file starts with no indentation, regardless of the indentation level of the file which might contain the current file. Opening tags increase the indentation level by two spaces. Closing tags decrease the indentation level by two spaces. Blocks of eight spaces at the start of a line should be replaced with a tab. Do not use spaces in front of tabs, and do not add extraneous whitespace at the end of a line. Content within elements should be indented by two spaces if the content runs over more than one line. For example, the source for this section looks like this: chapter title...title sect1 title...title sect2 titleIndentationtitle paraThe first line in each file starts with no indentation, emphasisregardlessemphasis of the indentation level of the file which might contain the current file.para ... sect2 sect1 chapter Tags containing long attributes follow the same rules. Following the indentation rules in this case helps editors and writers see which content is inside the tags: paraSee the link linkend="gmirror-troubleshooting"Troubleshootinglink section if there are problems booting. Powering down and disconnecting the original filenameada0filename disk will allow it to be kept as an offline backup.para paraIt is also possible to journal the boot disk of a &os; system. Refer to the article link xlink:href="&url.articles.gjournal-desktop;"Implementing UFS Journaling on a Desktop PClink for detailed instructions.para When an element is too long to fit on the remainder of a line without wrapping, moving the start tag to the next line can make the source easier to read. In this example, the systemitem element has been moved to the next line to avoid wrapping and indenting: paraWith file flags, even systemitem class="username"rootsystemitem can be prevented from removing or altering files.para Configurations to help various text editors conform to these guidelines can be found in . Tag Style Tag Spacing Tags that start at the same indent as a previous tag should be separated by a blank line, and those that are not at the same indent as a previous tag should not: article lang='en' articleinfo titleNIStitle pubdateOctober 1999pubdate abstract para... ... ...para abstract articleinfo sect1 title...title para...para sect1 sect1 title...title para...para sect1 article Separating Tags Tags like itemizedlist which will always have further tags inside them, and in fact do not take character data themselves, are always on a line by themselves. Tags like para and term do not need other tags to contain normal character data, and their contents begin immediately after the tag, on the same line. The same applies to when these two types of tags close. This leads to an obvious problem when mixing these tags. When a starting tag which cannot contain character data directly follows a tag of the type that requires other tags within it to use character data, they are on separate lines. The second tag should be properly indented. When a tag which can contain character data closes directly after a tag which cannot contain character data closes, they co-exist on the same line. Whitespace Changes Do not commit changes to content at the same time as changes to formatting. When content and whitespace changes are kept separate, translation teams can easily see whether a change was content that must be translated or only whitespace. For example, if two sentences have been added to a paragraph so that the line lengths now go over 80 columns, first commit the change with the too-long lines. Then fix the line wrapping, and commit this second change. In the commit message for the second change, indicate that this is a whitespace-only change that can be ignored by translators. Non-Breaking Space Avoid line breaks in places where they look ugly or make it difficult to follow a sentence. Line breaks depend on the width of the chosen output medium. In particular, viewing the HTML documentation with a text browser can lead to badly formatted paragraphs like the next one: Data capacity ranges from 40 MB to 15 GB. Hardware compression … The general entity &nbsp; prohibits line breaks between parts belonging together. Use non-breaking spaces in the following places: between numbers and units: 57600&nbsp;bps between program names and version numbers: &os;&nbsp;9.2 between multiword names (use with caution when applying this to more than 3-4 word names like The &os; Brazilian Portuguese Documentation Project): Word List This list of words shows the correct spelling and capitalization when used in &os; documentation. If a word is not on this list, ask about it on the &a.doc;. Word XML Code Notes CD-ROM - acronymCD-ROMacronym + acronymCD-ROMacronym DoS (Denial of Service) - acronymDoSacronym + acronymDoSacronym email file system IPsec Internet manual page mail server name server Ports Collection read-only Soft Updates stdin varnamestdinvarname stdout varnamestdoutvarname stderr varnamestderrvarname Subversion applicationSubversionapplication Do not refer to the Subversion application as SVN in upper case. To refer to the - command, use commandsvncommand. + command, use commandsvncommand. &unix; &unix; userland things that apply to user space, not the kernel web server Index: head/en_US.ISO8859-1/books/fdp-primer/xhtml-markup/chapter.xml =================================================================== --- head/en_US.ISO8859-1/books/fdp-primer/xhtml-markup/chapter.xml (revision 52150) +++ head/en_US.ISO8859-1/books/fdp-primer/xhtml-markup/chapter.xml (revision 52151) @@ -1,599 +1,604 @@ - + <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 - http://www.w3.org/. + http://www.w3.org/. 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 by the textproc/docproj port. + textproc/xhtml. They are automatically + installed by 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 &os; 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 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 titleThe Document's Titletitle 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. <tag>h1</tag>, <tag>h2</tag>, and Other Header Tags Usage: h1First sectionh1 <!-- Document introduction goes here --> h2This is the heading for the first sectionh2 <!-- Content for the first section goes here --> h3This is the heading for the first sub-sectionh3 <!-- Content for the first sub-section goes here --> h2This is the heading for the second sectionh2 <!-- Content for the second section goes here --> 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. Do not leave gaps in the numbering. Paragraphs XHTML supports a single paragraph element, p. <tag>p</tag> Example Usage: pThis is a paragraph. It can contain just about any other element.p Block Quotations A block quotation is an extended quotation from another document that will appear in a separate paragraph. <tag>blockquote</tag> Example Usage: pA small excerpt from the US Constitution:p blockquoteWe 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.blockquote Lists XHTML can present the user with three types of lists: ordered, unordered, and definition. Entries in an ordered list will be numbered, while entries in an unordered list will be preceded by bullet points. Definition lists have two sections for each entry. The first section is the term being defined, and the second section is the definition. 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. <tag>ul</tag> and <tag>ol</tag> Example Usage: pAn unordered list. Listitems will probably be preceded by bullets.p ul liFirst itemli liSecond itemli liThird itemli ul pAn ordered list, with list items consisting of multiple paragraphs. Each item (note: not each paragraph) will be numbered.p ol lipThis is the first item. It only has one paragraph.pli lipThis is the first paragraph of the second item.p pThis is the second paragraph of the second item.pli lipThis is the first and only paragraph of the third item.pli ol Definition Lists with <tag>dl</tag> Usage: dl dtTerm 1dt ddpParagraph 1 of definition 1.p pParagraph 2 of definition 1.pdd dtTerm 2dt ddpParagraph 1 of definition 2.pdd dtTerm 3dt ddpParagraph 1 of definition 3.pdd dl Pre-formatted Text Pre-formatted text is shown to the user exactly as it is in the file. Text is shown in a fixed font. Multiple spaces and line breaks are shown exactly as they are in the file. Wrap pre-formatted text in the pre element. <tag>pre</tag> Example For example, the pre tags could be used to mark up an email message: pre 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 &lt;URL:https://people.FreeBSD.org/~nik/primer/index.html&gt; Comments appreciated. Npre 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 <tag>table</tag> Usage: pThis is a simple 2x2 table.p table tr tdTop left celltd tdTop right celltd tr tr tdBottom left celltd tdBottom right celltd tr table A cell can span multiple rows and columns by adding the rowspan or colspan attributes with values for the number of rows or columns to be spanned. Using <tag class="attribute">rowspan</tag> Usage: pOne tall thin cell on the left, two short cells next to it on the right.p table tr td rowspan="2"Long and thintd tr tr tdTop celltd tdBottom celltd tr table Using <tag class="attribute">colspan</tag> Usage: pOne long cell on top, two short cells below it.p table tr td colspan="2"Top celltd tr tr tdBottom left celltd tdBottom right celltd tr table Using <tag class="attribute">rowspan</tag> and <tag class="attribute">colspan</tag> Together Usage: pOn a 3x3 grid, the top left block is a 2x2 set of cells merged into one. The other cells are normal.p table tr td colspan="2" rowspan="2"Top left large celltd tdTop right celltd tr tr <!-- Because the large cell on the left merges into this row, the first <td> will occur on its right --> tdMiddle right celltd tr tr tdBottom left celltd tdBottom middle celltd tdBottom right celltd tr table 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. em is typically rendered in italic and strong is rendered in bold. This is not always the case, and should not be relied upon. According to best practices, web pages only hold structural and semantical information, and stylesheets are later applied to them. Think of semantics, not formatting, when using these tags. <tag>em</tag> and <tag>strong</tag> Example Usage: pemThisem has been emphasized, while strongthisstrong has been strongly emphasized.p Indicating Fixed-Pitch Text Content that should be rendered in a fixed pitch (typewriter) typeface is tagged with tt (for teletype). <tag>tt</tag> Example Usage: pMany system settings are stored in tt/etctt.p Links Links are also inline elements. Linking to Other Documents on the Web A link points to the URL of a 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, indicated to the user by showing it in a different color or with an underline. Using <tag class="starttag">a href="..."</tag> Usage: pMore information is available at the a href="http://www.&os;.org/"&os; web sitea.p This link always takes the user to the top of the linked document. Linking to Specific Parts of Documents To link to a specific point within a document, that document must include an anchor at the desired point. Anchors are included by setting the id attribute of an element to a name. This example creates an anchor by setting the id attribute of a p element. Creating an Anchor Usage: p id="samplepara"This paragraph can be referenced in other links with the name ttsampleparatt.p Links to anchors are similar to plain links, but include a # symbol and the anchor's ID at the end of the URL. Linking to a Named Part of a Different Document The samplepara example is part of a document called foo.html. A link to that specific paragraph in the document is constructed in this example. pMore information can be found in the a href="foo.html#samplepara"sample paragrapha of ttfoo.htmltt.p To link to a named anchor within the same document, omit the document's URL, and just use the # symbol followed by the name of the anchor. Linking to a Named Part of the Same Document The samplepara example resides in this document. To link to it: pMore information can be found in the a href="#samplepara"sample paragrapha of this document.p Index: head/en_US.ISO8859-1/books/fdp-primer/xml-primer/chapter.xml =================================================================== --- head/en_US.ISO8859-1/books/fdp-primer/xml-primer/chapter.xml (revision 52150) +++ head/en_US.ISO8859-1/books/fdp-primer/xml-primer/chapter.xml (revision 52151) @@ -1,1418 +1,1423 @@ - + XML Primer Most FDP documentation is written with markup languages based on XML. This chapter explains what that means, how to read and understand the documentation source, and the XML techniques used. - Portions of this section were inspired by Mark Galassi's - Get + Portions of this section were inspired by Mark Galassi's Get Going With DocBook. Overview In the original days of computers, electronic text was simple. There were a few character sets like ASCII or EBCDIC, but that was about it. Text was text, and what you saw really was what you got. No frills, no formatting, no intelligence. Inevitably, this was not enough. When text is in a machine-usable format, machines are expected to be able to use and manipulate it intelligently. Authors want to indicate that certain phrases should be emphasized, or added to a glossary, or made into hyperlinks. Filenames could be shown in a typewriter style font for viewing on screen, but as italics when printed, or any of a myriad of other options for presentation. It was once hoped that Artificial Intelligence (AI) would make this easy. The computer would read the document and automatically identify key phrases, filenames, text that the reader should type in, examples, and more. Unfortunately, real life has not happened quite like that, and computers still require assistance before they can meaningfully process text. More precisely, they need help identifying what is what. Consider this text:
To remove /tmp/foo, use &man.rm.1;. &prompt.user; rm /tmp/foo
It is easy to see which parts are filenames, which are commands to be typed in, which parts are references to manual pages, and so on. But the computer processing the document cannot. For this we need markup. Markup is commonly used to describe adding value or increasing cost. The term takes on both these meanings when applied to text. Markup is additional text included in the document, distinguished from the document's content in some way, so that programs that process the document can read the markup and use it when making decisions about the document. Editors can hide the markup from the user, so the user is not distracted by it. The extra information stored in the markup adds value to the document. Adding the markup to the document must typically be done by a person—after all, if computers could recognize the text sufficiently well to add the markup then there would be no need to add it in the first place. This increases the cost (the effort required) to create the document. The previous example is actually represented in this document like this: paraTo remove filename/tmp/foofilename, use &man.rm.1;.para screen&prompt.user; userinputrm /tmp/foouserinputscreen The markup is clearly separate from the content. Markup languages define what the markup means and how it should be interpreted. Of course, one markup language might not be enough. A markup language for technical documentation has very different requirements than a markup language that is intended for cookery recipes. This, in turn, would be very different from a markup language used to describe poetry. What is really needed is a first language used to write these other markup languages. A meta markup language. This is exactly what the eXtensible Markup Language (XML) is. Many markup languages have been written in XML, including the two most used by the FDP, XHTML and DocBook. Each language definition is more properly called a grammar, vocabulary, schema or Document Type Definition (DTD). There are various languages to specify an XML grammar, or schema. A schema is a complete specification of all the elements that are allowed to appear, the order in which they should appear, which elements are mandatory, which are optional, and so forth. This makes it possible to write an XML parser which reads in both the schema and a document which claims to conform to the schema. The parser can then confirm whether or not all the elements required by the vocabulary are in the document in the right order, and whether there are any errors in the markup. This is normally referred to as validating the document. Validation confirms that the choice of elements, their ordering, and so on, conforms to that listed in the grammar. It does not check whether appropriate markup has been used for the content. If all the filenames in a document were marked up as function names, the parser would not flag this as an error (assuming, of course, that the schema defines elements for filenames and functions, and that they are allowed to appear in the same place). Most contributions to the Documentation Project will be content marked up in either XHTML or DocBook, rather than alterations to the schemas. For this reason, this book will not touch on how to write a vocabulary. Elements, Tags, and Attributes All the vocabularies written in XML share certain characteristics. This is hardly surprising, as the philosophy behind XML will inevitably show through. One of the most obvious manifestations of this philosophy is that of content and elements. Documentation, whether it is a single web page, or a lengthy book, is considered to consist of content. This content is then divided and further subdivided into elements. The purpose of adding markup is to name and identify the boundaries of these elements for further processing. For example, consider a typical book. At the very top level, the book is itself an element. This book element obviously contains chapters, which can be considered to be elements in their own right. Each chapter will contain more elements, such as paragraphs, quotations, and footnotes. Each paragraph might contain further elements, identifying content that was direct speech, or the name of a character in the story. It may be helpful to think of this as chunking content. At the very top level is one chunk, the book. Look a little deeper, and there are more chunks, the individual chapters. These are chunked further into paragraphs, footnotes, character names, and so on. Notice how this differentiation between different elements of the content can be made without resorting to any XML terms. It really is surprisingly straightforward. This could be done with a highlighter pen and a printout of the book, using different colors to indicate different chunks of content. Of course, we do not have an electronic highlighter pen, so we need some other way of indicating which element each piece of content belongs to. In languages written in XML (XHTML, DocBook, et al) this is done by means of tags. A tag is used to identify where a particular element starts, and where the element ends. The tag is not part of the element itself. Because each grammar was normally written to mark up specific types of information, each one will recognize different elements, and will therefore have different names for the tags. For an element called element-name the start tag will - normally look like element-name. - The corresponding closing tag for this element is element-name. + normally look like element-name. + The corresponding closing tag for this element is element-name. Using an Element (Start and End Tags) XHTML has an element for indicating that the content enclosed by the element is a paragraph, called p. pThis is a paragraph. It starts with the start tag for the 'p' element, and it will end with the end tag for the 'p' element.p pThis is another paragraph. But this one is much shorter.p Some elements have no content. For example, in XHTML, a horizontal line can be included in the document. For these empty elements, XML introduced a shorthand form that is completely equivalent to the two-tag version: Using an Element Without Content XHTML has an element for indicating a horizontal rule, called hr. This element does not wrap content, so it looks like this: pOne paragraph.p hrhr pThis is another paragraph. A horizontal rule separates this from the previous paragraph.p The shorthand version consists of a single tag: pOne paragraph.p hr pThis is another paragraph. A horizontal rule separates this from the previous paragraph.p As shown above, elements can contain other elements. In the book example earlier, the book element contained all the chapter elements, which in turn contained all the paragraph elements, and so on. Elements Within Elements; <tag>em</tag> pThis is a simple emparagraphem where some of the emwordsem have been ememphasizedem.p The grammar consists of rules that describe which elements can contain other elements, and exactly what they can contain. People often confuse the terms tags and elements, and use the terms as if they were interchangeable. They are not. An element is a conceptual part of your document. An element has a defined start and end. The tags mark where the element starts and ends. When this document (or anyone else knowledgeable about XML) refers to the p tag they mean the literal text consisting of the three characters <, p, and >. But the phrase the p element refers to the whole element. This distinction is very subtle. But keep it in mind. Elements can have attributes. An attribute has a name and a value, and is used for adding extra information to the element. This might be information that indicates how the content should be rendered, or might be something that uniquely identifies that occurrence of the element, or it might be something else. An element's attributes are written inside the start tag for that element, and take the form attribute-name="attribute-value". In XHTML, the p element has an attribute called align, which suggests an alignment (justification) for the paragraph to the program displaying the XHTML. The align attribute can take one of four defined values, left, center, right and justify. If the attribute is not specified then the default is left. Using an Element with an Attribute p align="left"The inclusion of the align attribute on this paragraph was superfluous, since the default is left.p p align="center"This may appear in the center.p Some attributes only take specific values, such as left or justify. Others allow any value. Single Quotes Around Attributes p align='right'I am on the right!p Attribute values in XML must be enclosed in either single or double quotes. Double quotes are traditional. Single quotes are useful when the attribute value contains double quotes. Information about attributes, elements, and tags is stored in catalog files. The Documentation Project uses standard DocBook catalogs and includes additional catalogs for &os;-specific features. Paths to the catalog files are defined in an environment variable so they can be found by the document build tools. To Do… Before running the examples in this document, install - textproc/docproj from - the &os; Ports Collection. This is a - meta-port that downloads and installs - the standard programs and supporting files needed by the - Documentation Project. &man.csh.1; users must use - rehash for the shell to recognize new - programs after they have been installed, or log out - and then log back in again. + textproc/docproj from the &os; Ports + Collection. This is a meta-port that + downloads and installs the standard programs and supporting + files needed by the Documentation Project. &man.csh.1; users + must use rehash for the shell to recognize + new programs after they have been installed, or log out and + then log back in again. Create example.xml, and enter this text: !DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" html xmlns="http://www.w3.org/1999/xhtml" head titleAn Example XHTML Filetitle head body pThis is a paragraph containing some text.p pThis paragraph contains some more text.p p align="right"This paragraph might be right-justified.p body html Try to validate this file using an XML parser. textproc/docproj includes the xmllint validating parser. Use xmllint to validate the document: &prompt.user; xmllint --valid --noout example.xml xmllint returns without displaying any output, showing that the document validated successfully. See what happens when required elements are omitted. Delete the line with the title and title tags, and re-run the validation. &prompt.user; xmllint --valid --noout example.xml example.xml:5: element head: validity error : Element head content does not follow the DTD, expecting ((script | style | meta | link | object | isindex)* , ((title , (script | style | meta | link | object | isindex)* , (base , (script | style | meta | link | object | isindex)*)?) | (base , (script | style | meta | link | object | isindex)* , title , (script | style | meta | link | object | isindex)*))), got () This shows that the validation error comes from the fifth line of the example.xml file and that the content of the head is the part which does not follow the rules of the XHTML grammar. Then xmllint shows the line where the error was found and marks the exact character position with a ^ sign. Replace the title element. The DOCTYPE Declaration The beginning of each document can specify the name of the DTD to which the document conforms. This DOCTYPE declaration is used by XML parsers to identify the DTD and ensure that the document does conform to it. A typical declaration for a document written to conform with version 1.0 of the XHTML DTD looks like this: !DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" That line contains a number of different components. <! The indicator shows this is an XML declaration. DOCTYPE Shows that this is an XML declaration of the document type. html Names the first element that will appear in the document. - PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + PUBLIC "-//W3C//DTD XHTML 1.0 + Transitional//EN" Lists the Formal Public Identifier (FPI) Formal Public Identifier for the DTD to which this document conforms. The XML parser uses this to find the correct DTD when processing this document. PUBLIC is not a part of the FPI, but indicates to the XML processor how to find the DTD referenced in the FPI. Other ways of telling the XML parser how to find the - DTD are shown later. + DTD are shown later. "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" A local filename or a URL to find the DTD. > Ends the declaration and returns to the document. Formal Public Identifiers (<acronym>FPI</acronym>s) Formal Public Identifier It is not necessary to know this, but it is useful background, and might help debug problems when the - XML processor can not locate the + XML processor cannot locate the DTD. FPIs must follow a specific syntax: "Owner//Keyword Description//Language" Owner The owner of the FPI. The beginning of the string identifies the owner of the FPI. For example, the FPI "ISO 8879:1986//ENTITIES Greek Symbols//EN" lists ISO 8879:1986 as being the owner for the set of entities for Greek symbols. ISO 8879:1986 is the International Organization for Standardization (ISO) number for the SGML standard, the predecessor (and a superset) of XML. Otherwise, this string will either look like -//Owner or +//Owner (notice the only difference is the leading + or -). If the string starts with - then the owner information is unregistered, with a + identifying it as registered. ISO 9070:1991 defines how registered names are generated. It might be derived from the number of an ISO publication, an ISBN code, or an organization code assigned according to ISO 6523. Additionally, a registration authority could be created in order to assign registered names. The ISO council delegated this to the American National Standards Institute (ANSI). Because the &os; Project has not been registered, the owner string is -//&os;. As seen in the example, the W3C are not a registered owner either. Keyword There are several keywords that indicate the type of information in the file. Some of the most common keywords are DTD, ELEMENT, ENTITIES, and TEXT. DTD is used only for DTD files, ELEMENT is usually used for DTD fragments that contain only entity or element declarations. TEXT is used for XML content (text and tags). Description Any description can be given for the contents of this file. This may include version numbers or any short text that is meaningful and unique for the XML system. Language An ISO two-character code that identifies the native language for the file. EN is used for English. <filename>catalog</filename> Files With the syntax above, an XML processor needs to have some way of turning the FPI into the name of the file containing the DTD. A catalog file (typically called catalog) contains lines that map FPIs to filenames. For example, if the catalog file contained the line: PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "1.0/transitional.dtd" The XML processor knows that the DTD is called transitional.dtd in the 1.0 subdirectory of the directory that held catalog. Examine the contents of /usr/local/share/xml/dtd/xhtml/catalog.xml. This is the catalog file for the XHTML DTDs that were installed as part of the textproc/docproj port. Alternatives to <acronym>FPI</acronym>s Instead of using an FPI to indicate the DTD to which the document conforms (and therefore, which file on the system contains the DTD), the filename can be explicitly specified. The syntax is slightly different: !DOCTYPE html SYSTEM "/path/to/file.dtd" The SYSTEM keyword indicates that the XML processor should locate the DTD in a system specific fashion. This typically (but not always) means the DTD will be provided as a filename. Using FPIs is preferred for reasons of portability. If the SYSTEM identifier is used, then the DTD must be provided and kept in the same location for everyone. Escaping Back to <acronym>XML</acronym> Some of the underlying XML syntax can be useful within documents. For example, comments can be included in the document, and will be ignored by the parser. Comments are entered using XML syntax. Other uses for XML syntax will be shown later. XML sections begin with a <! tag and end with a >. These sections contain instructions for the parser rather than elements of the document. Everything between these tags is XML syntax. The DOCTYPE declaration shown earlier is an example of XML syntax included in the document. Comments An XML document may contain comments. They may appear anywhere as long as they are not inside tags. They are even allowed in some locations inside the DTD (e.g., between entity declarations). XML comments start with the string <!-- and end with the string -->. Here are some examples of valid XML comments: <acronym>XML</acronym> Generic Comments <!-- This is inside the comment --> <!--This is another comment--> <!-- This is how you write multiline comments --> <p>A simple <!-- Comment inside an element's content --> paragraph.</p> XML comments may contain any strings except --: Erroneous <acronym>XML</acronym> Comment <!-- This comment--is wrong --> To Do… Add some comments to example.xml, and check that the file still validates using xmllint. Add some invalid comments to example.xml, and see the error messages that xmllint gives when it encounters an invalid comment. Entities Entities are a mechanism for assigning names to chunks of content. As an XML parser processes a document, any entities it finds are replaced by the content of the entity. This is a good way to have re-usable, easily changeable chunks of content in XML documents. It is also the only way to include one marked up file inside another using XML. There are two types of entities for two different situations: general entities and parameter entities. General Entities General entities are used to assign names to reusable chunks of text. These entities can only be used in the document. They cannot be used in an XML context. To include the text of a general entity in the document, include &entity-name; in the text. For example, consider a general entity called current.version which expands to the current version number of a product. To use it in the document, write: paraThe current version of our product is &current.version;.para When the version number changes, edit the definition of the general entity, replacing the value. Then reprocess the document. General entities can also be used to enter characters that could not otherwise be included in an XML document. For example, < and & cannot normally appear in an XML document. The XML parser sees the < symbol as the start of a tag. Likewise, when the & symbol is seen, the next text is expected to be an entity name. These symbols can be included by using two predefined general entities: &lt; and &amp;. General entities can only be defined within an XML context. Such definitions are usually done immediately after the DOCTYPE declaration. Defining General Entities <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [ <!ENTITY current.version "3.0-RELEASE"> <!ENTITY last.version "2.2.7-RELEASE"> ]> The DOCTYPE declaration has been extended by adding a square bracket at the end of the first line. The two entities are then defined over the next two lines, the square bracket is closed, and then the DOCTYPE declaration is closed. The square brackets are necessary to indicate that the DTD indicated by the DOCTYPE declaration is being extended. Parameter Entities Parameter entities, like general entities, are used to assign names to reusable chunks of text. But parameter entities can only be used within an XML context. Parameter entity definitions are similar to those for general entities. However, parameter entities are included with %entity-name;. The definition also includes the % between the ENTITY keyword and the name of the entity. For a mnemonic, think Parameter entities use the Percent symbol. Defining Parameter Entities <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [ <!ENTITY % entity "<!ENTITY version '1.0'>"> <!-- use the parameter entity --> %entity; ]> At first sight, parameter entities do not look very useful, but they make it possible to include other files into an XML document. To Do… Add a general entity to example.xml. <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [ <!ENTITY version "1.1"> ]> html xmlns="http://www.w3.org/1999/xhtml" head titleAn Example XHTML Filetitle head <!-- There may be some comments in here as well --> body pThis is a paragraph containing some text.p pThis paragraph contains some more text.p p align="right"This paragraph might be right-justified.p pThe current version of this document is: &version;p body html Validate the document using xmllint. Load example.xml into a web browser. It may have to be copied to example.html before the browser recognizes it as an XHTML document. Older browsers with simple parsers may not render this file as expected. The entity reference &version; may not be replaced by the version number, or the XML context closing ]> may not be recognized and instead shown in the output. The solution is to normalize the document with an XML normalizer. The normalizer reads valid XML and writes equally valid XML which has been transformed in some way. One way the normalizer transforms the input is by expanding all the entity references in the document, replacing the entities with the text that they represent. xmllint can be used for this. It also has an option to drop the initial DTD section so that the closing ]> does not confuse browsers: &prompt.user; xmllint --noent --dropdtd example.xml > example.html A normalized copy of the document with entities expanded is produced in example.html, ready to load into a web browser. Using Entities to Include Files Both general and parameter entities are particularly useful for including one file inside another. Using General Entities to Include Files Consider some content for an XML book organized into files, one file per chapter, called chapter1.xml, chapter2.xml, and so forth, with a book.xml that will contain these chapters. In order to use the contents of these files as the values for entities, they are declared with the SYSTEM keyword. This directs the XML parser to include the contents of the named file as the value of the entity. Using General Entities to Include Files <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [ <!ENTITY chapter.1 SYSTEM "chapter1.xml"> <!ENTITY chapter.2 SYSTEM "chapter2.xml"> <!ENTITY chapter.3 SYSTEM "chapter3.xml"> <!-- And so forth --> ]> html xmlns="http://www.w3.org/1999/xhtml" <!-- Use the entities to load in the chapters --> &chapter.1; &chapter.2; &chapter.3; html When using general entities to include other files within a document, the files being included (chapter1.xml, chapter2.xml, and so on) must not start with a DOCTYPE declaration. This is a syntax error because entities are low-level constructs and they are resolved before any parsing happens. Using Parameter Entities to Include Files Parameter entities can only be used inside an XML context. Including a file in an XML context can be used to ensure that general entities are reusable. Suppose that there are many chapters in the document, and these chapters were reused in two different books, each book organizing the chapters in a different fashion. The entities could be listed at the top of each book, but that quickly becomes cumbersome to manage. Instead, place the general entity definitions inside one file, and use a parameter entity to include that file within the document. Using Parameter Entities to Include Files Place the entity definitions in a separate file called chapters.ent and containing this text: <!ENTITY chapter.1 SYSTEM "chapter1.xml"> <!ENTITY chapter.2 SYSTEM "chapter2.xml"> <!ENTITY chapter.3 SYSTEM "chapter3.xml"> Create a parameter entity to refer to the contents of the file. Then use the parameter entity to load the file into the document, which will then make all the general entities available for use. Then use the general entities as before: <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [ <!-- Define a parameter entity to load in the chapter general entities --> <!ENTITY % chapters SYSTEM "chapters.ent"> <!-- Now use the parameter entity to load in this file --> %chapters; ]> html xmlns="http://www.w3.org/1999/xhtml" &chapter.1; &chapter.2; &chapter.3; html To Do… Use General Entities to Include Files Create three files, para1.xml, para2.xml, and para3.xml. Put content like this in each file: pThis is the first paragraph.p Edit example.xml so that it looks like this: <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [ <!ENTITY version "1.1"> <!ENTITY para1 SYSTEM "para1.xml"> <!ENTITY para2 SYSTEM "para2.xml"> <!ENTITY para3 SYSTEM "para3.xml"> ]> html xmlns="http://www.w3.org/1999/xhtml" head titleAn Example XHTML Filetitle head body pThe current version of this document is: &version;p &para1; &para2; &para3; body html Produce example.html by normalizing example.xml. &prompt.user; xmllint --dropdtd --noent example.xml > example.html Load example.html into the web browser and confirm that the paran.xml files have been included in example.html. Use Parameter Entities to Include Files The previous steps must have completed before this step. Edit example.xml so that it looks like this: <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [ <!ENTITY % entities SYSTEM "entities.ent"> %entities; ]> html xmlns="http://www.w3.org/1999/xhtml" head titleAn Example XHTML Filetitle head body pThe current version of this document is: &version;p &para1; &para2; &para3; body html Create a new file called entities.ent with this content: <!ENTITY version "1.1"> <!ENTITY para1 SYSTEM "para1.xml"> <!ENTITY para2 SYSTEM "para2.xml"> <!ENTITY para3 SYSTEM "para3.xml"> Produce example.html by normalizing example.xml. &prompt.user; xmllint --dropdtd --noent example.xml > example.html Load example.html into the web browser and confirm that the paran.xml files have been included in example.html. Marked Sections XML provides a mechanism to indicate that particular pieces of the document should be processed in a special way. These are called marked sections. Structure of a Marked Section <![KEYWORD[ Contents of marked section ]]> As expected of an XML construct, a marked section starts with <!. The first square bracket begins the marked section. KEYWORD describes how this marked section is to be processed by the parser. The second square bracket indicates the start of the marked section's content. The marked section is finished by closing the two square brackets, and then returning to the document context from the XML context with >. Marked Section Keywords <literal>CDATA</literal> These keywords denote the marked sections content model, and allow you to change it from the default. When an XML parser is processing a document, it keeps track of the content model. The content model describes the content the parser is expecting to see and what it will do with that content. The CDATA content model is one of the most useful. CDATA is for Character Data. When the parser is in this content model, it expects to see only characters. In this model the < and & symbols lose their special status, and will be treated as ordinary characters. When using CDATA in examples of text marked up in XML, remember that the content of CDATA is not validated. The included text must be check with other means. For example, the content could be written in another document, validated, and then pasted into the CDATA section. Using a <literal>CDATA</literal> Marked Section paraHere is an example of how to include some text that contains many literal&lt;literal and literal&amp;literal symbols. The sample text is a fragment of acronymXHTMLacronym. The surrounding text (para and programlisting) are from DocBook.para programlisting<![CDATA[pThis is a sample that shows some of the elements within acronymXHTMLacronym. Since the angle brackets are used so many times, it is simpler to say the whole example is a CDATA marked section than to use the entity names for the left and right angle brackets throughout.p ul liThis is a listitemli liThis is a second listitemli liThis is a third listitemli ul pThis is the end of the example.p]]>programlisting <literal>INCLUDE</literal> and <literal>IGNORE</literal> When the keyword is INCLUDE, then the contents of the marked section will be processed. When the keyword is IGNORE, the marked section is ignored and will not be processed. It will not appear in the output. Using <literal>INCLUDE</literal> and <literal>IGNORE</literal> in Marked Sections <![INCLUDE[ This text will be processed and included. ]]> <![IGNORE[ This text will not be processed or included. ]]> By itself, this is not too useful. Text to be removed from the document could be cut out, or wrapped in comments. It becomes more useful when controlled by parameter entities, yet this usage is limited to entity files. For example, suppose that documentation was produced in a hard-copy version and an electronic version. Some extra text is desired in the electronic version content that was not to appear in the hard-copy. Create an entity file that defines general entities to include each chapter and guard these definitions with a parameter entity that can be set to either INCLUDE or IGNORE to control whether the entity is defined. After these conditional general entity definitions, place one more definition for each general entity to set them to an empty value. This technique makes use of the fact that entity definitions cannot be overridden but the first definition always takes effect. So the inclusion of the chapter is controlled with the corresponding parameter entity. Set to INCLUDE, the first general entity definition will be read and the second one will be ignored. Set to IGNORE, the first definition will be ignored and the second one will take effect. Using a Parameter Entity to Control a Marked Section <!ENTITY % electronic.copy "INCLUDE"> <![%electronic.copy;[ <!ENTITY chap.preface SYSTEM "preface.xml"> ]]> <!ENTITY chap.preface ""> When producing the hard-copy version, change the parameter entity's definition to: <!ENTITY % electronic.copy "IGNORE"> To Do… Modify entities.ent to contain the following: <!ENTITY version "1.1"> <!ENTITY % conditional.text "IGNORE"> <![%conditional.text;[ <!ENTITY para1 SYSTEM "para1.xml"> ]]> <!ENTITY para1 ""> <!ENTITY para2 SYSTEM "para2.xml"> <!ENTITY para3 SYSTEM "para3.xml"> Normalize example.xml and notice that the conditional text is not present in the output document. Set the parameter entity guard to INCLUDE and regenerate the normalized document and the text will appear again. This method makes sense if there are more conditional chunks depending on the same condition. For example, to control generating printed or online text. Conclusion That is the conclusion of this XML primer. For reasons of space and complexity, several things have not been covered in depth (or at all). However, the previous sections cover enough XML to introduce the organization of the FDP documentation.