Index: head/en_US.ISO8859-1/books/fdp-primer/sgml-markup/chapter.xml =================================================================== --- head/en_US.ISO8859-1/books/fdp-primer/sgml-markup/chapter.xml (revision 42004) +++ head/en_US.ISO8859-1/books/fdp-primer/sgml-markup/chapter.xml (nonexistent) @@ -1,2759 +0,0 @@ - - - - - XML Markup - - This chapter describes the two markup languages you will - encounter when you contribute to the FreeBSD documentation - project. Each section describes the markup language, and details - the markup that you are likely to want to use, or that is already - in use. - - These markup languages contain a large number of elements, and - it can be confusing sometimes to know which element to use for a - particular situation. This section goes through the elements you - are most likely to need, and gives examples of how you would use - them. - - This is not an exhaustive list of - elements, since that would just reiterate the documentation for - each language. The aim of this section is to list those elements - more likely to be useful to you. If you have a question about how - best to markup a particular piece of content, please post it to - the &a.doc;. - - - Inline Versus Block - - In the remainder of this document, when describing elements, - inline means that the element can occur - within a block element, and does not cause a line break. A - block element, by comparison, will cause a - line break (and other processing) when it is encountered. - - - - XHTML - - XHTML is the XML version of the HyperText Markup Language, - which is the markup language - of choice on the World Wide Web. More information can be found - at . - - XHTML is used to markup pages on the FreeBSD web site. It - should not (generally) be used to mark up other documentation, - since DocBook offers a far richer set of elements to choose - from. Consequently, you will normally only encounter XHTML pages - if you are writing for the web site. - - HTML has gone through a number of versions, 1, 2, 3.0, 3.2, - 4.0 and then an XML-compliant version has also been created, which - is called XHTML and the latest widespread version of it is - XHTML 1.0(available in both - strict and transitional - variants). - - The XHTML DTDs are available from the Ports Collection - in the textproc/xhtml port. - They are automatically installed as part of the textproc/docproj port. - - - Formal Public Identifier (FPI) - - There are a number of XHTML FPIs, depending upon the - version (also known as the level) of XHTML that you want to - declare your document to be compliant with. - - The majority of XHTML documents on the FreeBSD web site - comply with the transitional version of XHTML 1.0. - - PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" - - - - Sectional Elements - - An XHTML document is normally split into two sections. The - first section, called the head, contains - meta-information about the document, such as its title, the - name of the author, the parent document, and so on. The - second section, the body, contains the - content that will be displayed to the user. - - These sections are indicated with head - and body elements respectively. These - elements are contained within the top-level - html element. - - - Normal XHTML Document Structure - - <html xmlns="http://www.w3.org/1999/xhtml"> - <head> - <title>The Document's Title</title> - </head> - - <body> - - … - - </body> -</html> - - - - - Block Elements - - - Headings - - XHTML allows you to denote headings in your document, at - up to six different levels. - - The largest and most prominent heading is - h1, then h2, - continuing down to h6. - - The element's content is the text of the heading. - - - <sgmltag>h1</sgmltag>, <sgmltag>h2</sgmltag>, - and Other Header Tags - - Use: - - First section - - - -

This is the heading for the first section

- - - -

This is the heading for the first sub-section

- - - -

This is the heading for the second section

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

Sub-section

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

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

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

- -
    -
  • First item
    • - -
  • Second item
    • - -
  • Third item
    • -
- -

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

- -
    -

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

    2. - -

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

    - -

    This is the second paragraph of the second item.

    3. - -

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

    4. -
]]> - - - - Definition Lists with <sgmltag>dl</sgmltag> - - Use: - - -
Term 1
- -

Paragraph 1 of definition 1.

- -

Paragraph 2 of definition 1.

- -
Term 2
- -

Paragraph 1 of definition 2.

- -
Term 3
- -

Paragraph 1 of definition 3.

-]]> - - - - - Pre-formatted Text - - You can indicate that text should be shown to the user - exactly as it is in the file. Typically, this means that - the text is shown in a fixed font, multiple spaces are not - merged into one, and line breaks in the text are - significant. - - In order to do this, wrap the content in the - pre element. - - - <sgmltag>pre</sgmltag> - - You could use pre to mark up an - email message: - - From: nik@FreeBSD.org - To: freebsd-doc@FreeBSD.org - Subject: New documentation available - - There is a new copy of my primer for contributors to the FreeBSD - Documentation Project available at - - <URL:http://people.FreeBSD.org/~nik/primer/index.html> - - Comments appreciated. - - N]]> - - Keep in mind that < and - & still are recognized as special - characters in pre-formatted text. This is why the example - shown had to use &lt; instead of - <. For consistency, - &gt; was used in place of - >, too. Watch out for the special - characters that may appear in text copied from a - plain-text source, e.g., an email message or program - code. - - - - - Tables - - - Most text-mode browsers (such as Lynx) do not render - tables particularly effectively. If you are relying on - the tabular display of your content, you should consider - using alternative markup to prevent confusion. - - - Mark up tabular information using the - table element. A table consists of one - or more table rows (tr), each containing - one or more cells of table data (td). - Each cell can contain other block elements, such as - paragraphs or lists. It can also contain another table - (this nesting can repeat indefinitely). If the cell only - contains one paragraph then you do not need to include the - p element. - - - Simple Use of <sgmltag>table</sgmltag> - - Use: - - This is a simple 2x2 table.

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

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

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

- - - - - - - - - - - - - - - - - - - - - -
Top left large cellTop right cell
Middle right cell
Bottom left cellBottom middle cellBottom right cell
]]> - - - - - - In-line Elements - - - Emphasizing Information - - You have two levels of emphasis available in XHTML, - em and strong. - em is for a normal level of emphasis and - strong indicates stronger - emphasis. - - Typically, em is rendered in italic - and strong is rendered in bold. This is - not always the case, however, and you should not rely on - it. According to best practices, webpages only hold - structural and semantical information and stylesheets are - later applied to use these two so you should think of - semantics not formatting when using these tags. - - - <sgmltag>em</sgmltag> and - <sgmltag>strong</sgmltag> - - Use: - - This has been emphasized, while - this has been strongly emphasized.

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

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

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

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

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

]]> - - - - - - - DocBook - - DocBook was originally developed by HaL Computer Systems and - O'Reilly & Associates to be a DTD for writing technical - documentation A short history can be found under - - http://www.oasis-open.org/docbook/intro.shtml#d0e41.. - Since 1998 it is maintained by the - DocBook Technical Committee. As such, and unlike - LinuxDoc and XHTML, DocBook is very heavily oriented towards - markup that describes what something is, - rather than describing how it should be - presented. - - - Formal Versus Informal - - Some elements may exist in two forms, - formal and informal. - Typically, the formal version of the element will consist of a - title followed by the informal version of the element. The - informal version will not have a title. - - - The DocBook DTD is available from the Ports Collection - in the textproc/docbook-xml-450 - port. It is automatically installed as part of the textproc/docproj port. - - - &os; Extensions - - The FreeBSD Documentation Project has extended the DocBook - DTD by adding some new elements. These elements serve to make - some of the markup more precise. - - Where a FreeBSD specific element is listed below it is - clearly marked. - - Throughout the rest of this document, the term - DocBook is used to mean the FreeBSD extended - DocBook DTD. - - - There is nothing about these extensions that is FreeBSD - specific, it was just felt that they were useful - enhancements for this particular project. Should anyone - from any of the other *nix camps (NetBSD, OpenBSD, Linux, - …) be interested in collaborating on a standard - DocBook extension set, please get in touch with - &a.doceng;. - - - The &os; extensions are not (currently) in the - Ports Collection. They are stored in the &os; Subversion - tree, as head/share/xml/freebsd.dtd. - - - - Formal Public Identifier (FPI) - - In compliance with the DocBook guidelines for writing FPIs - for DocBook customizations, the FPI for the FreeBSD extended - DocBook DTD is: - - PUBLIC "-//FreeBSD//DTD DocBook V4.2-Based Extension//EN" - - - - Document Structure - - DocBook allows you to structure your documentation in - several ways. In the FreeBSD Documentation Project we are - using two primary types of DocBook document: the book and the - article. - - A book is organized into chapters. - This is a mandatory requirement. There may be - parts between the book and the chapter to - provide another layer of organization. For example, the - Handbook is arranged in this way. - - A chapter may (or may not) contain one or more sections. - These are indicated with the sect1 element. - If a section contains another section then use the - sect2 element, and so on, up to - sect5. - - Chapters and sections contain the remainder of the - content. - - An article is simpler than a book, and does not use - chapters. Instead, the content of an article is organized - into one or more sections, using the same - sect1 (and sect2 and so - on) elements that are used in books. - - Obviously, you should consider the nature of the - documentation you are writing in order to decide whether it is - best marked up as a book or an article. Articles are well - suited to information that does not need to be broken down - into several chapters, and that is, relatively speaking, quite - short, at up to 20-25 pages of content. Books are best suited - to information that can be broken up into several chapters, - possibly with appendices and similar content as well. - - The FreeBSD - tutorials are all marked up as articles, while this - document, the - FreeBSD FAQ, - and the FreeBSD - Handbook are all marked up as books, for - example. - - - Starting a Book - - The content of the book is contained within the - book element. As well as containing - structural markup, this element can contain elements that - include additional information about the book. This is - either meta-information, used for reference purposes, or - additional content used to produce a title page. - - This additional information should be contained within - bookinfo. - - - Boilerplate <sgmltag>book</sgmltag> with - <sgmltag>bookinfo</sgmltag> - - - - <book> - <bookinfo> - <title>Your Title Here</title> - - <author> - <firstname>Your first name</firstname> - <surname>Your surname</surname> - <affiliation> - <address><email>Your email address</email></address> - </affiliation> - </author> - - <copyright> - <year>1998</year> - <holder role="mailto:your email address">Your name</holder> - </copyright> - - <releaseinfo>$FreeBSD$</releaseinfo> - - <abstract> - <para>Include an abstract of the book's contents here.</para> - </abstract> - </bookinfo> - - … - -</book> - - - - - Starting an Article - - The content of the article is contained within the - article element. As well as containing - structural markup, this element can contain elements that - include additional information about the article. This is - either meta-information, used for reference purposes, or - additional content used to produce a title page. - - This additional information should be contained within - articleinfo. - - - Boilerplate <sgmltag>article</sgmltag> with - <sgmltag>articleinfo</sgmltag> - - - - <article> - <articleinfo> - <title>Your title here</title> - - <author> - <firstname>Your first name</firstname> - <surname>Your surname</surname> - <affiliation> - <address><email>Your email address</email></address> - </affiliation> - </author> - - <copyright> - <year>1998</year> - <holder role="mailto:your email address">Your name</holder> - </copyright> - - <releaseinfo>$FreeBSD$</releaseinfo> - - <abstract> - <para>Include an abstract of the article's contents here.</para> - </abstract> - </articleinfo> - - … - -</article> - - - - - Indicating Chapters - - Use chapter to mark up your chapters. - Each chapter has a mandatory title. - Articles do not contain chapters, they are reserved for - books. - - - A Simple Chapter - - - The Chapter's Title - - ... -]]> - - - A chapter cannot be empty; it must contain elements in - addition to title. If you need to - include an empty chapter then just use an empty - paragraph. - - - Empty Chapters - - - This is An Empty Chapter - - -]]> - - - - - Sections Below Chapters - - In books, chapters may (but do not need to) be broken up - into sections, subsections, and so on. In articles, - sections are the main structural element, and each article - must contain at least one section. Use the - sectn element. - The n indicates the section - number, which identifies the section level. - - The first - sectn is - sect1. You can have one or more of these - in a chapter. They can contain one or more - sect2 elements, and so on, down to - sect5. - - - Sections in Chapters - - - A Sample Chapter - - Some text in the chapter. - - - First Section (1.1) - - … - - - - Second Section (1.2) - - - First Sub-Section (1.2.1) - - - First Sub-Sub-Section (1.2.1.1) - - … - - - - - Second Sub-Section (1.2.2) - - … - - -]]> - - - - This example includes section numbers in the section - titles. You should not do this in your documents. Adding - the section numbers is carried out by the stylesheets (of - which more later), and you do not need to manage them - yourself. - - - - - Subdividing Using <sgmltag>part</sgmltag> - Elements - - You can introduce another layer of organization between - book and chapter with - one or more parts. This cannot be done - in an article. - - - Introduction - - - Overview - - ... - - - - What is FreeBSD? - - ... - - - - History - - ... - -]]> - - - - - Block Elements - - - Paragraphs - - DocBook supports three types of paragraphs: - formalpara, para, and - simpara. - - Most of the time you will only need to use - para. formalpara - includes a title element, and - simpara disallows some elements from - within para. Stick with - para. - - - <sgmltag>para</sgmltag> - - Use: - - This is a paragraph. It can contain just about any - other element. ]]> - - Appearance: - - This is a paragraph. It can contain just about any - other element. - - - - - Block Quotations - - A block quotation is an extended quotation from another - document that should not appear within the current - paragraph. You will probably only need it - infrequently. - - Blockquotes can optionally contain a title and an - attribution (or they can be left untitled and - unattributed). - - - <sgmltag>blockquote</sgmltag> - - Use: - - A small excerpt from the US Constitution: - -
- Preamble to the Constitution of the United States - - Copied from a web site somewhere - - We the People of the United States, in Order to form a more perfect - Union, establish Justice, insure domestic Tranquility, provide for the - common defence, promote the general Welfare, and secure the Blessings - of Liberty to ourselves and our Posterity, do ordain and establish this - Constitution for the United States of America. -
]]> - - Appearance: - - A small excerpt from the US Constitution: - -
- Preamble to the Constitution of the United - States - - Copied from a web site - somewhere - - We the People of the United States, in Order to form - a more perfect Union, establish Justice, insure domestic - Tranquility, provide for the common defence, promote the - general Welfare, and secure the Blessings of Liberty to - ourselves and our Posterity, do ordain and establish - this Constitution for the United States of - America. -
- - - - - Tips, Notes, Warnings, Cautions, Important Information - and Sidebars - - You may need to include extra information separate from - the main body of the text. Typically this is - meta information that the user should be - aware of. - - Depending on the nature of the information, one of - tip, note, - warning, caution, and - important should be used. Alternatively, - if the information is related to the main text but is not - one of the above, use sidebar. - - The circumstances in which to choose one of these - elements over another is unclear. The DocBook documentation - suggests: - - - - A Note is for information that should be heeded by - all readers. - - - - An Important element is a variation on Note. - - - - A Caution is for information regarding possible data - loss or software damage. - - - - A Warning is for information regarding possible - hardware damage or injury to life or limb. - - - - - <sgmltag>warning</sgmltag> - - Use: - - - Installing FreeBSD may make you want to delete Windows from your - hard disk. -]]> - - - Appearance: - - - Installing FreeBSD may make you want to delete Windows - from your hard disk. - - - - - Lists and Procedures - - You will often need to list pieces of information to the - user, or present them with a number of steps that must be - carried out in order to accomplish a particular goal. - - In order to do this, use - itemizedlist, - orderedlist, or - procedureThere are other - types of list element in DocBook, but we are not - concerned with those at the - moment. - - itemizedlist and - orderedlist are similar to their - counterparts in HTML, ul and - ol. Each one consists of one or more - listitem elements, and each - listitem contains one or more block - elements. The listitem elements are - analogous to HTML's li tags. However, - unlike HTML, they are required. - - procedure is slightly different. It - consists of steps, which may in turn - consists of more steps or - substeps. Each step - contains block elements. - - - <sgmltag>itemizedlist</sgmltag>, - <sgmltag>orderedlist</sgmltag>, and - <sgmltag>procedure</sgmltag> - - Use: - - - - This is the first itemized item. - - - - This is the second itemized item. - - - - - - This is the first ordered item. - - - - This is the second ordered item. - - - - - - Do this. - - - - Then do this. - - - - And now do this. - -]]> - - Appearance: - - - - This is the first itemized item. - - - - This is the second itemized item. - - - - - - This is the first ordered item. - - - - This is the second ordered item. - - - - - - - - - Do this. - - - - Then do this. - - - - And now do this. - - - - - - Showing File Samples - - If you want to show a fragment of a file (or perhaps a - complete file) to the user, wrap it in the - programlisting element. - - White space and line breaks within - programlisting are - significant. In particular, this means that the opening tag - should appear on the same line as the first line of the - output, and the closing tag should appear on the same line - as the last line of the output, otherwise spurious blank - lines may be included. - - - <sgmltag>programlisting</sgmltag> - - Use: - - When you have finished, your program should look like - this: - -#include <stdio.h> - -int -main(void) -{ - printf("hello, world\n"); -}]]> - - Notice how the angle brackets in the - #include line need to be referenced by - their entities instead of being included literally. - - Appearance: - - When you have finished, your program should look like - this: - - #include <stdio.h> - -int -main(void) -{ - printf("hello, world\n"); -} - - - - - Callouts - - A callout is a mechanism for referring back to an - earlier piece of text or specific position within an earlier - example without linking to it within the text. - - To do this, mark areas of interest in your example - (programlisting, - literallayout, or whatever) with the - co element. Each element must have a - unique id assigned to it. After the - example include a calloutlist that refers - back to the example and provides additional - commentary. - - - <sgmltag>co</sgmltag> and - <sgmltag>calloutlist</sgmltag> - - When you have finished, your program should look like - this: - -#include <stdio.h> - -int -main(void) -{ - printf("hello, world\n"); -} - - - - Includes the standard IO header file. - - - - Specifies that main() returns an - int. - - - - The printf() call that writes - hello, world to standard output. - -]]> - - Appearance: - - When you have finished, your program should look like - this: - - #include <stdio.h> - -int -main(void) -{ - printf("hello, world\n"); -} - - - - Includes the standard IO header file. - - - - Specifies that main() returns - an int. - - - - The printf() call that writes - hello, world to standard - output. - - - - - - - Tables - - Unlike HTML, you do not need to use tables for layout - purposes, as the stylesheet handles those issues for you. - Instead, just use tables for marking up tabular data. - - In general terms (and see the DocBook documentation for - more detail) a table (which can be either formal or - informal) consists of a table element. - This contains at least one tgroup - element, which specifies (as an attribute) the number of - columns in this table group. Within the tablegroup you can - then have one thead element, which - contains elements for the table headings (column headings), - and one tbody which contains the body of - the table. - - Both tgroup and - thead contain row - elements, which in turn contain entry - elements. Each entry element specifies - one cell in the table. - - - <sgmltag>informaltable</sgmltag> - - Use: - - - - - - This is Column Head 1 - This is Column Head 2 - - - - - - Row 1, column 1 - Row 1, column 2 - - - - Row 2, column 1 - Row 2, column 2 - - - -]]> - - Appearance: - - - - - - This is Column Head 1 - This is Column Head 2 - - - - - - Row 1, column 1 - Row 1, column 2 - - - - Row 2, column 1 - Row 2, column 2 - - - - - - - Always use the pgwide attribute with - a value of 1 with the - informaltable element. A bug in Internet - Explorer can cause the table to render incorrectly if this - is omitted. - - If you do not want a border around the table the - frame attribute can be added to the - informaltable element with a value of - none (i.e., <informaltable - frame="none">). - - - Tables Where <literal>frame="none"</literal> - - Appearance: - - - - - - This is Column Head 1 - This is Column Head 2 - - - - - - Row 1, column 1 - Row 1, column 2 - - - - Row 2, column 1 - Row 2, column 2 - - - - - - - - - Examples for the User to Follow - - A lot of the time you need to show examples for the user - to follow. Typically, these will consist of dialogs with - the computer; the user types in a command, the user gets a - response back, they type in another command, and so - on. - - A number of distinct elements and entities come into - play here. - - - - screen - - - Everything the user sees in this example will be - on the computer screen, so the next element is - screen. - - Within screen, white space is - significant. - - - - - prompt, - &prompt.root; and - &prompt.user; - - - Some of the things the user will be seeing on the - screen are prompts from the computer (either from the - operating system, command shell, or application). - These should be marked up using - prompt. - - As a special case, the two shell prompts for the - normal user and the root user have been provided as - entities. Every time you want to indicate the user is - at a shell prompt, use one of - &prompt.root; and - &prompt.user; as necessary. - They do not need to be inside - prompt. - - - &prompt.root; and - &prompt.user; are FreeBSD - extensions to DocBook, and are not part of the - original DTD. - - - - - - userinput - - - When displaying text that the user should type in, - wrap it in userinput tags. It will - probably be displayed differently to the user. - - - - - - <sgmltag>screen</sgmltag>, <sgmltag>prompt</sgmltag>, - and <sgmltag>userinput</sgmltag> - - Use: - - &prompt.user; ls -1 -foo1 -foo2 -foo3 -&prompt.user; ls -1 | grep foo2 -foo2 -&prompt.user; su -Password: -&prompt.root; cat foo2 -This is the file called 'foo2']]> - - Appearance: - - &prompt.user; ls -1 -foo1 -foo2 -foo3 -&prompt.user; ls -1 | grep foo2 -foo2 -&prompt.user; su -Password: -&prompt.root; cat foo2 -This is the file called 'foo2' - - - - Even though we are displaying the contents of the file - foo2, it is not - marked up as programlisting. Reserve - programlisting for showing fragments of - files outside the context of user actions. - - - - - - In-line Elements - - - Emphasizing Information - - When you want to emphasize a particular word or phrase, - use emphasis. This may be presented as - italic, or bold, or might be spoken differently with a - text-to-speech system. - - There is no way to change the presentation of the - emphasis within your document, no equivalent of HTML's - b and i. If the - information you are presenting is important then consider - presenting it in important rather than - emphasis. - - - <sgmltag>emphasis</sgmltag> - - Use: - - FreeBSD is without doubt the - premiere Unix like operating system for the Intel architecture.]]> - - Appearance: - - FreeBSD is without doubt the - premiere Unix like operating system for the Intel - architecture. - - - - - Quotations - - To quote text from another document or source, or to - denote a phrase that is used figuratively, use - quote. Within a quote - tag, you may use most of the markup tags available for - normal text. - - - Quotations - - Use: - - However, make sure that the search does not go beyond the - boundary between local and public administration, - as RFC 1535 calls it.]]> - - Appearance: - - However, make sure that the search does not go beyond - the boundary between local and public - administration, as RFC 1535 calls it. - - - - - Keys, Mouse Buttons, and Combinations - - To refer to a specific key on the keyboard, use - keycap. To refer to a mouse button, use - mousebutton. And to refer to - combinations of key presses or mouse clicks, wrap them all - in keycombo. - - keycombo has an attribute called - action, which may be one of - click, double-click, - other, press, - seq, or simul. The - last two values denote whether the keys or buttons should be - pressed in sequence, or simultaneously. - - The stylesheets automatically add any connecting - symbols, such as +, between the key - names, when wrapped in keycombo. - - - Keys, Mouse Buttons, and Combinations - - Use: - - To switch to the second virtual terminal, press - Alt - F1. - -To exit vi without saving your work, type - Esc: - q!. - -My window manager is configured so that - Alt - right - mouse button is used to move windows.]]> - - Appearance: - - To switch to the second virtual terminal, press - Alt - F1. - - To exit vi without saving your - work, type - Esc - : - q - !. - - My window manager is configured so that - - Alt - right mouse button - is used to move windows. - - - - - Applications, Commands, Options, and Cites - - You will frequently want to refer to both applications - and commands when writing documentation. The distinction - between them is simple: an application is the name for a - suite (or possibly just 1) of programs that fulfill a - particular task. A command is the name of a program that - the user can run. - - In addition, you will occasionally need to list one or - more of the options that a command might take. - - Finally, you will often want to list a command with its - manual section number, in the command(number) - format so common in Unix manuals. - - Mark up application names with - application. - - When you want to list a command with its manual section - number (which should be most of the time) the DocBook - element is citerefentry. This will - contain a further two elements, - refentrytitle and - manvolnum. The content of - refentrytitle is the name of the command, - and the content of manvolnum is the - manual page section. - - This can be cumbersome to write, and so a series of - general - entities have been created to make this easier. - Each entity takes the form - &man.manual-page.manual-section;. - - The file that contains these entities is in - doc/share/xml/man-refs.ent, and can be - referred to using this FPI: - - PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN" - - Therefore, the introduction to your documentation will - probably look like this: - - <!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [ - -<!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"> -%man; - -… - -]> - - Use command when you want to include - a command name in-line but present it as - something the user should type in. - - Use option to mark up the options - which will be passed to a command. - - When referring to the same command multiple times in - close proximity it is preferred to use the - &man.command.section; - notation to markup the first reference and use - command to markup subsequent references. - This makes the generated output, especially HTML, appear - visually better. - - This can be confusing, and sometimes the choice is not - always clear. Hopefully this example makes it - clearer. - - - Applications, Commands, and Options - - Use: - - Sendmail is the most - widely used Unix mail application. - -Sendmail includes the - - sendmail - 8 - , &man.mailq.1;, and &man.newaliases.1; - programs. - -One of the command line parameters to - sendmail - 8 - , , will display the current - status of messages in the mail queue. Check this on the command - line by running sendmail -bp.]]> - - Appearance: - - Sendmail is the most widely - used Unix mail application. - - Sendmail includes the - - sendmail - 8 - , &man.mailq.1;, and &man.newaliases.1; - programs. - - One of the command line parameters to - - sendmail - 8 - , , will display the - current status of messages in the mail queue. Check this - on the command line by running - sendmail -bp. - - - - Notice how the - &man.command.section; - notation is easier to follow. - - - - - Files, Directories, Extensions - - Whenever you wish to refer to the name of a file, a - directory, or a file extension, use - filename. - - - <sgmltag>filename</sgmltag> - - Use: - - The SGML source for the Handbook in English can be - found in /usr/doc/en_US.ISO8859-1/books/handbook/. The first - file is called book.xml in that - directory. You should also see a Makefile - and a number of files with a .ent - extension.]]> - - Appearance: - - The SGML source for the Handbook in English can be - found in /usr/doc/en/handbook/. The - first file is called handbook.xml in - that directory. You should also see a - Makefile and a number of files with a - .ent extension. - - - - - The Name of Ports - - - &os; Extension - - These elements are part of the FreeBSD extension to - DocBook, and do not exist in the original DocBook - DTD. - - - You might need to include the name of a program from the - FreeBSD Ports Collection in the documentation. Use the - filename tag with the - role attribute set to - package to identify these. Since ports - can be installed in any number of locations, only include - the category and the port name; do not include - /usr/ports. - - - <sgmltag>filename</sgmltag> Tag with - <literal>package</literal> Role - - Use: - - Install the net/ethereal port to view network traffic.]]> - - Appearance: - - Install the net/ethereal port to view - network traffic. - - - - - Devices - - - &os; Extension - - These elements are part of the FreeBSD extension to - DocBook, and do not exist in the original DocBook - DTD. - - - When referring to devices you have two choices. You can - either refer to the device as it appears in - /dev, or you can use the name of the - device as it appears in the kernel. For this latter course, - use devicename. - - Sometimes you will not have a choice. Some devices, - such as networking cards, do not have entries in - /dev, or the entries are markedly - different from those entries. - - - <sgmltag>devicename</sgmltag> - - Use: - - sio is used for serial - communication in FreeBSD. sio manifests - through a number of entries in /dev, including - /dev/ttyd0 and /dev/cuaa0. - -By contrast, the networking devices, such as - ed0 do not appear in /dev. - -In MS-DOS, the first floppy drive is referred to as - a:. In FreeBSD it is - /dev/fd0.]]> - - Appearance: - - sio is used for serial - communication in FreeBSD. sio - manifests through a number of entries in - /dev, including - /dev/ttyd0 and - /dev/cuaa0. - - By contrast, the networking devices, such as - ed0 do not appear in - /dev. - - In MS-DOS, the first floppy drive is referred to as - a:. In FreeBSD it is - /dev/fd0. - - - - - Hosts, Domains, IP Addresses, and So Forth - - - &os; Extension - - These elements are part of the FreeBSD extension to - DocBook, and do not exist in the original DocBook - DTD. - - - You can markup identification information for networked - computers (hosts) in several ways, depending on the nature - of the information. All of them use - hostid as the element, with the - role attribute selecting the type of the - marked up information. - - - - No role attribute, or - role="hostname" - - - With no role attribute (i.e., - hostid.../hostid) - the marked up information is the simple hostname, such - as freefall or - wcarchive. You can explicitly - specify this with - role="hostname". - - - - - role="domainname" - - - The text is a domain name, such as - FreeBSD.org or - ngo.org.uk. There is no hostname - component. - - - - - role="fqdn" - - - The text is a Fully Qualified Domain Name, with - both hostname and domain name parts. - - - - - role="ipaddr" - - - The text is an IP address, probably expressed as a - dotted quad. - - - - - role="ip6addr" - - - The text is an IPv6 address. - - - - - role="netmask" - - - The text is a network mask, which might be - expressed as a dotted quad, a hexadecimal string, or - as a / followed by a number. - - - - - role="mac" - - - The text is an Ethernet MAC address, expressed as - a series of 2 digit hexadecimal numbers separated by - colons. - - - - - - <sgmltag>hostid</sgmltag> and Roles - - Use: - - The local machine can always be referred to by the - name localhost, which will have the IP address - 127.0.0.1. - -The FreeBSD.org domain - contains a number of different hosts, including - freefall.FreeBSD.org and - pointyhat.FreeBSD.org. - -When adding an IP alias to an interface (using - ifconfig) always use a - netmask of 255.255.255.255 - (which can also be expressed as 0xffffffff). - -The MAC address uniquely identifies every network card - in existence. A typical MAC address looks like 08:00:20:87:ef:d0.]]> - - Appearance: - - The local machine can always be referred to by the - name localhost, which will have the IP - address 127.0.0.1. - - The FreeBSD.org - domain contains a number of different hosts, including - freefall.FreeBSD.org and - bento.FreeBSD.org. - - When adding an IP alias to an interface (using - ifconfig) always - use a netmask of - 255.255.255.255 - (which can also be expressed as 0xffffffff). - - The MAC address uniquely identifies every network card - in existence. A typical MAC address looks like 08:00:20:87:ef:d0. - - - - - Usernames - - - &os; Extension - - These elements are part of the FreeBSD extension to - DocBook, and do not exist in the original DocBook - DTD. - - - When you need to refer to a specific username, such as - root or bin, use - username. - - - <sgmltag>username</sgmltag> - - Use: - - To carry out most system administration functions you - will need to be root.]]> - - Appearance: - - To carry out most system administration functions you - will need to be root. - - - - - Describing <filename>Makefile</filename>s - - - &os; Extension - - These elements are part of the FreeBSD extension to - DocBook, and do not exist in the original DocBook - DTD. - - - Two elements exist to describe parts of - Makefiles, - maketarget and - makevar. - - maketarget identifies a build target - exported by a Makefile that can be - given as a parameter to make. - makevar identifies a variable that can be - set (in the environment, on the make - command line, or within the Makefile) - to influence the process. - - - <sgmltag>maketarget</sgmltag> and - <sgmltag>makevar</sgmltag> - - Use: - - Two common targets in a Makefile - are all and clean. - -Typically, invoking all will rebuild the - application, and invoking clean will remove - the temporary files (.o for example) created by - the build process. - -clean may be controlled by a number of - variables, including CLOBBER and - RECURSE.]]> - - Appearance: - - Two common targets in a Makefile - are all and - clean. - - Typically, invoking all will - rebuild the application, and invoking - clean will remove the temporary - files (.o for example) created by the - build process. - - clean may be controlled by a - number of variables, including CLOBBER - and RECURSE. - - - - - Literal Text - - You will often need to include literal - text in the documentation. This is text that is excerpted - from another file, or which should be copied from the - documentation into another file verbatim. - - Some of the time, programlisting will - be sufficient to denote this text. - programlisting is not always appropriate, - particularly when you want to include a portion of a file - in-line with the rest of the - paragraph. - - On these occasions, use - literal. - - - <sgmltag>literal</sgmltag> - - Use: - - The maxusers 10 line in the kernel - configuration file determines the size of many system tables, and is - a rough guide to how many simultaneous logins the system will - support.]]> - - Appearance: - - The maxusers 10 line in the kernel - configuration file determines the size of many system - tables, and is a rough guide to how many simultaneous - logins the system will support. - - - - - Showing Items That the User <emphasis>Must</emphasis> - Fill In - - There will often be times when you want to show the user - what to do, or refer to a file, or command line, or similar, - where the user cannot simply copy the examples that you - provide, but must instead include some information - themselves. - - replaceable is designed for this - eventuality. Use it inside other - elements to indicate parts of that element's content that - the user must replace. - - - <sgmltag>replaceable</sgmltag> - - Use: - - &prompt.user; man command]]> - - Appearance: - - - &prompt.user; man command - - - replaceable can be used in many - different elements, including literal. - This example also shows that - replaceable should only be wrapped - around the content that the user is - meant to provide. The other content should be left - alone. - - Use: - - The maxusers n - line in the kernel configuration file determines the size of many system - tables, and is a rough guide to how many simultaneous logins the system will - support. - -For a desktop workstation, 32 is a good value - for n.]]> - - Appearance: - - The - maxusers n - line in the kernel configuration file determines the size - of many system tables, and is a rough guide to how many - simultaneous logins the system will support. - - For a desktop workstation, 32 is a - good value for n. - - - - - Quoting System Errors - - You might want to show errors generated by FreeBSD. - Mark these with errorname. This - indicates the exact error that appears. - - - <sgmltag>errorname</sgmltag> - - Use: - - Panic: cannot mount root ]]> - - - - Appearance: - - - Panic: cannot mount root - - - - - - - Images - - - Image support in the documentation is currently - extremely experimental. The mechanisms described here are - unlikely to change, but that is not guaranteed. - - You will also need to install the - graphics/ImageMagick - port, which is used to convert between the different image - formats. This is a big port, and most of it is not - required. However, while we are working on the - Makefiles and other infrastructure it - makes things easier. This port is not - in the textproc/docproj - meta port, you must install it by hand. - - The best example of what follows in practice is the - doc/en_US.ISO8859-1/articles/vm-design/ - document. If you are unsure of the description that - follows, take a look at the files in that directory to see - how everything hangs together. Experiment with creating - different formatted versions of the document to see how the - image markup appears in the formatted output. - - - - Image Formats - - We currently support two formats for images. The format - you should use will depend on the nature of your - image. - - For images that are primarily vector based, such as - network diagrams, time lines, and similar, use Encapsulated - Postscript, and make sure that your images have the - .eps extension. - - For bitmaps, such as screen captures, use the Portable - Network Graphic format, and make sure that your images have - the .png extension. - - These are the only formats in which - images should be committed to the Subversion - repository. - - Use the right format for the right image. It is to be - expected that your documentation will have a mix of EPS and - PNG images. The Makefiles ensure that - the correct format image is chosen depending on the output - format that you use for your documentation. Do - not commit the same image to the repository in two different - formats. - - - It is anticipated that the Documentation Project will - switch to using the Scalable Vector Graphic (SVG) format - for vector images. However, the current state of SVG - capable editing tools makes this impractical. - - - - - Markup - - The markup for an image is relatively simple. First, - markup a mediaobject. The - mediaobject can contain other, more - specific objects. We are concerned with two, the - imageobject and the - textobject. - - You should include one imageobject, - and two textobject elements. The - imageobject will point to the name of the - image file that will be used (without the extension). The - textobject elements contain information - that will be presented to the user as well as, or instead - of, the image. - - There are two circumstances where this can - happen. - - - - When the reader is viewing the documentation in - HTML. In this case, each image will need to have - associated alternate text to show the user, typically - whilst the image is loading, or if they hover the mouse - pointer over the image. - - - - When the reader is viewing the documentation in - plain text. In this case, each image should have an - ASCII art equivalent to show the user. - - - - An example will probably make things easier to - understand. Suppose you have an image, called - fig1.png, that you want to include in the - document. This image is of a rectangle with an A inside it. - The markup for this would be as follows. - - <mediaobject> - <imageobject> - <imagedata fileref="fig1"> - </imageobject> - - <textobject> - <literallayout class="monospaced">+---------------+ -| A | -+---------------+</literallayout> - </textobject> - - <textobject> - <phrase>A picture</phrase> - </textobject> -</mediaobject> - - - - Include an imagedata element - inside the imageobject element. The - fileref attribute should contain the - filename of the image to include, without the extension. - The stylesheets will work out which extension should be - added to the filename automatically. - - - - - The first textobject should - contain a literallayout element, - where the class attribute is set to - monospaced. This is your opportunity - to demonstrate your ASCII art skills. This content will - be used if the document is converted to plain - text. - - Notice how the first and last lines of the content - of the literallayout element butt up - next to the element's tags. This ensures no extraneous - white space is included. - - - - The second textobject should - contain a single phrase element. The - contents of this will become the alt - attribute for the image when this document is converted - to HTML. - - - - - - <filename>Makefile</filename> Entries - - Your images must be listed in the - Makefile in the - IMAGES variable. This variable should - contain the name of all your source - images. For example, if you have created three figures, - fig1.eps, - fig2.png, - fig3.png, then your - Makefile should have lines like this in - it. - - … -IMAGES= fig1.eps fig2.png fig3.png -… - - or - - … -IMAGES= fig1.eps -IMAGES+= fig2.png -IMAGES+= fig3.png -… - - Again, the Makefile will work out - the complete list of images it needs to build your source - document, you only need to list the image files - you provided. - - - - Images and Chapters in Subdirectories - - You must be careful when you separate your documentation - into smaller files (see - ) in - different directories. - - Suppose you have a book with three chapters, and the - chapters are stored in their own directories, called - chapter1/chapter.xml, - chapter2/chapter.xml, and - chapter3/chapter.xml. If each chapter - has images associated with it, it is suggested to place - those images in each chapter's subdirectory - (chapter1/, - chapter2/, and - chapter3/). - - However, if you do this you must include the directory - names in the IMAGES variable in the - Makefile, and you - must include the directory name in the - imagedata element in your - document. - - For example, if you have - chapter1/fig1.png, then - chapter1/chapter.xml should - contain: - - <mediaobject> - <imageobject> - <imagedata fileref="chapter1/fig1"> - </imageobject> - - … - -</mediaobject> - - - - The directory name must be included in the - fileref attribute. - - - - The Makefile must contain: - - … -IMAGES= chapter1/fig1.png -… - - Then everything should just work. - - - - - Links - - - Links are also in-line elements. - - - - Linking to Other Parts of the Same Document - - Linking within the same document requires you to specify - where you are linking from (i.e., the text the user will - click, or otherwise indicate, as the source of the link) and - where you are linking to (the link's destination). - - Each element within DocBook has an attribute called - id. You can place text in this attribute - to uniquely name the element it is attached to. - - This value will be used when you specify the link - source. - - Normally, you will only be linking to chapters or - sections, so you would add the id - attribute to these elements. - - - Attribute <literal>id</literal> on Chapters and - Sections - - - Introduction - - This is the introduction. It contains a subsection, - which is identified as well. - - - Sub-sect 1 - - This is the subsection. - -]]> - - - Obviously, you should use more descriptive values. The - values must be unique within the document (i.e., not just - the file, but the document the file might be included in as - well). Notice how the id for the - subsection is constructed by appending text to the - id of the chapter. This helps to ensure - that they are unique. - - If you want to allow the user to jump into a specific - portion of the document (possibly in the middle of a - paragraph or an example), use anchor. - This element has no content, but takes an - id attribute. - - - <sgmltag>anchor</sgmltag> - - This paragraph has an embedded - link target in it. It will not show up in - the document.]]> - - - When you want to provide the user with a link they can - activate (probably by clicking) to go to a section of the - document that has an id attribute, you - can use either xref or - link. - - Both of these elements have a linkend - attribute. The value of this attribute should be the value - that you have used in a id attribute (it - does not matter if that value has not yet occurred in your - document; this will work for forward links as well as - backward links). - - If you use xref then you have no - control over the text of the link. It will be generated for - you. - - - Using <sgmltag>xref</sgmltag> - - Assume that this fragment appears somewhere in a - document that includes the id - example: - - More information can be found - in . - -More specific information can be found - in .]]> - - The text of the link will be generated automatically, - and will look like (emphasized text - indicates the text that will be the link): - -
- More information can be found in Chapter - One. - - More specific information can be found in - the section called Sub-Sect - 1. -
- - - Notice how the text from the link is derived from the - section title or the chapter number. - - - This means that you cannot use - xref to link to an - id attribute on an - anchor element. The - anchor has no content, so the - xref cannot generate the text for the - link. - - - If you want to control the text of the link then use - link. This element wraps content, and - the content will be used for the link. - - - Using <sgmltag>link</sgmltag> - - Assume that this fragment appears somewhere in a - document that includes the id - example. - - More information can be found in - the first chapter. - -More specific information can be found in - this section.]]> - - This will generate the following - (emphasized text indicates the text - that will be the link): - -
- More information can be found in the first - chapter. - - More specific information can be found in - this section. -
- - - - That last one is a bad example. Never use words like - this or here as the source - for the link. The reader will need to hunt around the - surrounding context to see where the link is actually - taking them. - - - - You can use - link to include a link to an - id on an anchor - element, since the link content defines - the text that will be used for the link. - - - - - Linking to Documents on the WWW - - Linking to external documents is much simpler, as long - as you know the URL of the document you want to link to. - Use ulink. The url - attribute is the URL of the page that the link points to, - and the content of the element is the text that will be - displayed for the user to activate. - - - <sgmltag>ulink</sgmltag> - - Use: - - Of course, you could stop reading this document and - go to the FreeBSD - home page instead.]]> - - Appearance: - - Of course, you could stop reading this document and go - to the FreeBSD home - page instead. - - - - - Property changes on: head/en_US.ISO8859-1/books/fdp-primer/sgml-markup/chapter.xml ___________________________________________________________________ Deleted: svn:keywords ## -1 +0,0 ## -FreeBSD=%H \ No newline at end of property Deleted: svn:mime-type ## -1 +0,0 ## -text/sgml \ No newline at end of property Index: head/en_US.ISO8859-1/books/fdp-primer/Makefile =================================================================== --- head/en_US.ISO8859-1/books/fdp-primer/Makefile (revision 42004) +++ head/en_US.ISO8859-1/books/fdp-primer/Makefile (revision 42005) @@ -1,51 +1,52 @@ # # $FreeBSD$ # # Build the FreeBSD Documentation Project Primer. # MAINTAINER=doc@FreeBSD.org DOC?= book FORMATS?= html-split html INSTALL_COMPRESSED?= gz INSTALL_ONLY_COMPRESSED?= # # SRCS lists the individual XML files that make up the document. Changes # to any of these files will force a rebuild # # XML content SRCS= book.xml SRCS+= overview/chapter.xml SRCS+= psgml-mode/chapter.xml SRCS+= see-also/chapter.xml -SRCS+= sgml-markup/chapter.xml +SRCS+= xhtml-markup/chapter.xml +SRCS+= docbook-markup/chapter.xml SRCS+= sgml-primer/chapter.xml SRCS+= stylesheets/chapter.xml SRCS+= structure/chapter.xml SRCS+= doc-build/chapter.xml SRCS+= the-website/chapter.xml SRCS+= tools/chapter.xml SRCS+= translations/chapter.xml SRCS+= writing-style/chapter.xml SRCS+= examples/appendix.xml # Images from the cross-document image library IMAGES_LIB= callouts/1.png IMAGES_LIB+= callouts/2.png IMAGES_LIB+= callouts/3.png IMAGES_LIB+= callouts/4.png IMAGES_LIB+= callouts/5.png # Entities SRCS+= chapters.ent URL_RELPREFIX?= ../../../.. DOC_PREFIX?= ${.CURDIR}/../../.. .include "${DOC_PREFIX}/share/mk/doc.project.mk" Index: head/en_US.ISO8859-1/books/fdp-primer/book.xml =================================================================== --- head/en_US.ISO8859-1/books/fdp-primer/book.xml (revision 42004) +++ head/en_US.ISO8859-1/books/fdp-primer/book.xml (revision 42005) @@ -1,266 +1,267 @@ %chapters; ]> FreeBSD Documentation Project Primer for New Contributors The FreeBSD Documentation Project 1998 1999 2000 2001 2002 2003 2004 2005 2006 2007 2008 2009 2010 2011 2012 2013 DocEng $FreeBSD$ $FreeBSD$ &legalnotice; Thank you for becoming a part of the FreeBSD Documentation Project. Your contribution is extremely valuable. This primer covers details needed to start contributing to the FreeBSD Documentation Project, from the tools and software (both mandatory and recommended) to the philosophy behind the Documentation Project. This document is a work in progress. Corrections and additions are welcomed. Preface Shell Prompts The following table shows the default system prompt and superuser prompt. The examples will use this prompt to indicate which user you should be running the example as. User Prompt Normal user &prompt.user; root &prompt.root; Typographic Conventions The following table describes the typographic conventions used in this book. Meaning Examples The names of commands. Use ls -l to list all files. The names of files. Edit .login. On screen computer output. You have mail. What you type, when contrasted with on-screen computer output. &prompt.user; su Password: Manual page references. Use &man.su.1; to change user names. User and group names Only root can do this. Emphasis You must do this. Command line variables; replace with the real name or variable. To delete a file, type rm filename Environment variables $HOME is your home directory. Notes, Tips, Important Information, Warnings, and Examples Within the text appear notes, warnings, and examples. Notes are represented like this, and contain information that you should take note of, as it may affect what you do. Tips are represented like this, and contain information that you might find useful, or lead to an easier way to do something. Important information is represented like this. Typically they flag extra steps you may need to carry out. Warnings are represented like this, and contain information warning you about possible damage if you do not follow the instructions. This damage may be physical, to your hardware or to you, or it may be non-physical, such as the inadvertent deletion of important files. A Sample Example Examples are represented like this, and typically contain examples you should walk through, or show you what the results of a particular action should be. Acknowledgments My thanks to Sue Blake, Patrick Durusau, Jon Hamilton, Peter Flynn, and Christopher Maden, who took the time to read early drafts of this document and offer many valuable comments and criticisms. &chap.overview; &chap.tools; &chap.xml-primer; - &chap.xml-markup; + &chap.xhtml-markup; + &chap.docbook-markup; &chap.stylesheets; &chap.structure; &chap.doc-build; &chap.the-website; &chap.translations; &chap.writing-style; &chap.psgml-mode; &chap.see-also; &app.examples; Index: head/en_US.ISO8859-1/books/fdp-primer/chapters.ent =================================================================== --- head/en_US.ISO8859-1/books/fdp-primer/chapters.ent (revision 42004) +++ head/en_US.ISO8859-1/books/fdp-primer/chapters.ent (revision 42005) @@ -1,26 +1,27 @@ - + + 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 (nonexistent) +++ head/en_US.ISO8859-1/books/fdp-primer/docbook-markup/chapter.xml (revision 42005) @@ -0,0 +1,2248 @@ + + + + + DocBook Markup + + + Introduction + + This chapter is an introduction to DocBook as it is used for + &os; documentation. DocBook is a large and complex markup + system, but the subset described here covers the parts that are + most widely used for &os; documentation. While a moderate + subset is covered, it is impossible to anticipate every + situation. Please post questions that this document does + not answer to the &a.doc;. + + DocBook was originally developed by HaL Computer Systems and + O'Reilly & Associates to be a DTD for + writing technical documentation A short history + can be found under + http://www.oasis-open.org/docbook/intro.shtml#d0e41.. + Since 1998 it is maintained by the + DocBook Technical Committee. As such, and unlike + LinuxDoc and XHTML, DocBook is very heavily + oriented towards markup that describes what + something is, rather than describing how it + should be presented. + + The DocBook DTD is available from the + Ports Collection in the + textproc/docbook-xml-450 + port. It is automatically installed as part of the + textproc/docproj + port. + + + Formal Versus Informal + + Some elements may exist in two forms, + formal and informal. + Typically, the formal version of the element will consist of a + title followed by the informal version of the element. The + informal version will not have a title. + + + + Inline Versus Block + + In the remainder of this document, when describing + elements, inline means that the element + can occur within a block element, and does not cause a line + break. A block element, by comparison, + will cause a line break (and other processing) when it is + encountered. + + + + + &os; Extensions + + The &os; Documentation Project has extended the + DocBook DTD by adding some new elements. + These elements serve to make some of the markup more + precise. + + Where a &os;-specific element is listed below, it is + clearly marked. + + Throughout the rest of this document, the term + DocBook is used to mean the &os;-extended + DocBook DTD. + + + There is nothing about these extensions that is &os; + specific, it was just felt that they were useful + enhancements for this particular project. Should anyone + from any of the other *nix camps (NetBSD, OpenBSD, Linux, + …) be interested in collaborating on a standard + DocBook extension set, please get in touch with + &a.doceng;. + + + The &os; extensions are not (currently) in the + Ports Collection. They are stored in the &os; Subversion + tree, as head/share/xml/freebsd.dtd. + + + + Formal Public Identifier (FPI) + + In compliance with the DocBook guidelines for writing + FPIs for DocBook customizations, the + FPI for the &os; extended DocBook + DTD is: + + PUBLIC "-//FreeBSD//DTD DocBook V4.2-Based Extension//EN" + + + + Document Structure + + DocBook allows structuring documentation in several ways. + The &os; Documentation Project uses two primary types of DocBook + document: the book and the article. + + Books are organized into chapters. + This is a mandatory requirement. There may be + parts between the book and the chapter to + provide another layer of organization. For example, the + Handbook is arranged in this way. + + A chapter may (or may not) contain one or more sections. + These are indicated with the sect1 element. + If a section contains another section then use the + sect2 element, and so on, up to + sect5. + + Chapters and sections contain the remainder of the + content. + + An article is simpler than a book, and does not use + chapters. Instead, the content of an article is organized into + one or more sections, using the same sect1 + (and sect2 and so on) elements that are used + in books. + + The nature of the document being written should be used to + determine whether it is best marked up as a book or an article. + Articles are well suited to information that does not need to be + broken down into several chapters, and that is, relatively + speaking, quite short, at up to 20-25 pages of content. Books + are best suited to information that can be broken up into + several chapters, possibly with appendices and similar content + as well. + + The &os; tutorials + are all marked up as articles, while this + document, the + FreeBSD FAQ, + and the FreeBSD + Handbook are all marked up as books, for + example. + + + Starting a Book + + The content of a book is contained within the + book element. As well as containing + structural markup, this element can contain elements that + include additional information about the book. This is either + meta-information, used for reference purposes, or additional + content used to produce a title page. + + This additional information is contained within + bookinfo. + + + Boilerplate <sgmltag>book</sgmltag> with + <sgmltag>bookinfo</sgmltag> + + + + <book> + <bookinfo> + <title>Your Title Here</title> + + <author> + <firstname>Your first name</firstname> + <surname>Your surname</surname> + <affiliation> + <address><email>Your email address</email></address> + </affiliation> + </author> + + <copyright> + <year>1998</year> + <holder role="mailto:your email address">Your name</holder> + </copyright> + + <releaseinfo>$FreeBSD$</releaseinfo> + + <abstract> + <para>Include an abstract of the book's contents here.</para> + </abstract> + </bookinfo> + + … + +</book> + + + + + Starting an Article + + The content of the article is contained within the + article element. As well as containing + structural markup, this element can contain elements that + include additional information about the article. This is + either meta-information, used for reference purposes, or + additional content used to produce a title page. + + This additional information is contained within + articleinfo. + + + Boilerplate <sgmltag>article</sgmltag> with + <sgmltag>articleinfo</sgmltag> + + + + <article> + <articleinfo> + <title>Your title here</title> + + <author> + <firstname>Your first name</firstname> + <surname>Your surname</surname> + <affiliation> + <address><email>Your email address</email></address> + </affiliation> + </author> + + <copyright> + <year>1998</year> + <holder role="mailto:your email address">Your name</holder> + </copyright> + + <releaseinfo>$FreeBSD$</releaseinfo> + + <abstract> + <para>Include an abstract of the article's contents here.</para> + </abstract> + </articleinfo> + + … + +</article> + + + + + Indicating Chapters + + Use chapter to mark up your chapters. + Each chapter has a mandatory title. + Articles do not contain chapters, they are reserved for + books. + + + A Simple Chapter + + + The Chapter's Title + + ... +]]> + + + A chapter cannot be empty; it must contain elements in + addition to title. If you need to + include an empty chapter then just use an empty + paragraph. + + + Empty Chapters + + + This is An Empty Chapter + + +]]> + + + + + Sections Below Chapters + + In books, chapters may (but do not need to) be broken up + into sections, subsections, and so on. In articles, sections + are the main structural element, and each article must contain + at least one section. Use the + sectn element. + The n indicates the section number, + which identifies the section level. + + The first + sectn is + sect1. You can have one or more of these + in a chapter. They can contain one or more + sect2 elements, and so on, down to + sect5. + + + Sections in Chapters + + + A Sample Chapter + + Some text in the chapter. + + + First Section (1.1) + + … + + + + Second Section (1.2) + + + First Sub-Section (1.2.1) + + + First Sub-Sub-Section (1.2.1.1) + + … + + + + + Second Sub-Section (1.2.2) + + … + + +]]> + + + + This example includes section numbers in the section + titles. You should not do this in your documents. Adding + the section numbers is carried out by the stylesheets (of + which more later), and you do not need to manage them + yourself. + + + + + Subdividing Using <sgmltag>part</sgmltag> + Elements + + parts introduce another level of + organization between book and + chapter with one or more + parts. This cannot be done in an + article. + + + Introduction + + + Overview + + ... + + + + What is FreeBSD? + + ... + + + + History + + ... + +]]> + + + + + Block Elements + + + Paragraphs + + DocBook supports three types of paragraphs: + formalpara, para, and + simpara. + + Almost all paragraphs in &os; documentation use + para. formalpara + includes a title element, and + simpara disallows some elements from + within para. Stick with + para. + + + <sgmltag>para</sgmltag> + + Usage: + + This is a paragraph. It can contain just about any + other element. ]]> + + Appearance: + + This is a paragraph. It can contain just about any + other element. + + + + + Block Quotations + + A block quotation is an extended quotation from another + document that should not appear within the current + paragraph. These are rarely needed. + + Blockquotes can optionally contain a title and an + attribution (or they can be left untitled and + unattributed). + + + <sgmltag>blockquote</sgmltag> + + Usage: + + A small excerpt from the US Constitution: + +
+ Preamble to the Constitution of the United States + + Copied from a web site somewhere + + We the People of the United States, in Order to form a more + perfect Union, establish Justice, insure domestic Tranquility, + provide for the common defence, promote the general Welfare, and + secure the Blessings of Liberty to ourselves and our Posterity, do + ordain and establish this Constitution for the United States of + America. +
]]> + + Appearance: + + A small excerpt from the US Constitution: + +
+ Preamble to the Constitution of the United + States + + Copied from a web site + somewhere + + We the People of the United States, in Order to form + a more perfect Union, establish Justice, insure domestic + Tranquility, provide for the common defence, promote the + general Welfare, and secure the Blessings of Liberty to + ourselves and our Posterity, do ordain and establish + this Constitution for the United States of + America. +
+ + + + + Tips, Notes, Warnings, Cautions, Important Information + and Sidebars + + Extra information may need to be separated from + the main body of the text. Typically this is + meta information of which the user should be + aware. + + Depending on the nature of the information, one of + tip, note, + warning, caution, and + important should be used. Alternatively, + if the information is related to the main text but is not + one of the above, use sidebar. + + The circumstances in which to choose one of these + elements over another is loosely defined by the DocBook + documentation, which suggests: + + + + A Note is for information that should be heeded by + all readers. + + + + An Important element is a variation on Note. + + + + A Caution is for information regarding possible data + loss or software damage. + + + + A Warning is for information regarding possible + hardware damage or injury to life or limb. + + + + + <sgmltag>warning</sgmltag> + + Usage: + + + Installing FreeBSD may make you want to delete Windows from your + hard disk. +]]> + + + Appearance: + + + Installing FreeBSD may make you want to delete Windows + from your hard disk. + + + + + Lists and Procedures + + Information often needs to be presented as lists, or as a + number of steps that must be carried out in order to + accomplish a particular goal. + + To do this, use itemizedlist, + orderedlist, or + procedureThere are other + types of list element in DocBook, but we are not + concerned with those at the + moment. + + itemizedlist and + orderedlist are similar to their + counterparts in HTML, ul + and ol. Each one consists of one or more + listitem elements, and each + listitem contains one or more block + elements. The listitem elements are + analogous to HTML's li + tags. However, unlike HTML, they are required. + + procedure is slightly different. It + consists of steps, which may in turn + consists of more steps or + substeps. Each step + contains block elements. + + + <sgmltag>itemizedlist</sgmltag>, + <sgmltag>orderedlist</sgmltag>, and + <sgmltag>procedure</sgmltag> + + Usage: + + + + This is the first itemized item. + + + + This is the second itemized item. + + + + + + This is the first ordered item. + + + + This is the second ordered item. + + + + + + Do this. + + + + Then do this. + + + + And now do this. + +]]> + + Appearance: + + + + This is the first itemized item. + + + + This is the second itemized item. + + + + + + This is the first ordered item. + + + + This is the second ordered item. + + + + + + + + + Do this. + + + + Then do this. + + + + And now do this. + + + + + + Showing File Samples + + Fragments of a file (or perhaps a complete file) are shown + by wrapping them in the programlisting + element. + + White space and line breaks within + programlisting are + significant. In particular, this means that the opening tag + should appear on the same line as the first line of the + output, and the closing tag should appear on the same line + as the last line of the output, otherwise spurious blank + lines may be included. + + + <sgmltag>programlisting</sgmltag> + + Usage: + + When finished, the program will look like + this: + +#include <stdio.h> + +int +main(void) +{ + printf("hello, world\n"); +}]]> + + Notice how the angle brackets in the + #include line need to be referenced by + their entities instead of being included literally. + + Appearance: + + When finished, the program will look like this: + + #include <stdio.h> + +int +main(void) +{ + printf("hello, world\n"); +} + + + + + Callouts + + A callout is a mechanism for referring back to an + earlier piece of text or specific position within an earlier + example without linking to it within the text. + + To do this, mark areas of interest in the example + (programlisting, + literallayout, or whatever) with the + co element. Each element must have a + unique id assigned to it. After the + example include a calloutlist that refers + back to the example and provides additional + commentary. + + + <sgmltag>co</sgmltag> and + <sgmltag>calloutlist</sgmltag> + + When finished, the program will look like + this: + +#include <stdio.h> + +int +main(void) +{ + printf("hello, world\n"); +} + + + + Includes the standard IO header file. + + + + Specifies that main() returns an + int. + + + + The printf() call that writes + hello, world to standard output. + +]]> + + Appearance: + + When finished, the program will look like this: + + #include <stdio.h> + +int +main(void) +{ + printf("hello, world\n"); +} + + + + Includes the standard IO header file. + + + + Specifies that main() returns + an int. + + + + The printf() call that writes + hello, world to standard + output. + + + + + + + Tables + + Unlike HTML, DocBook does not need + tables for layout purposes, as the stylesheet handles those + issues. Instead, just use tables for marking up tabular + data. + + In general terms (and see the DocBook documentation for + more detail) a table (which can be either formal or informal) + consists of a table element. This contains + at least one tgroup element, which + specifies (as an attribute) the number of columns in this + table group. Within the tablegroup there is one + thead element, which contains elements for + the table headings (column headings), and one + tbody which contains the body of the + table. + + Both tgroup and + thead contain row + elements, which in turn contain entry + elements. Each entry element specifies + one cell in the table. + + + <sgmltag>informaltable</sgmltag> + + Usage: + + + + + + This is Column Head 1 + This is Column Head 2 + + + + + + Row 1, column 1 + Row 1, column 2 + + + + Row 2, column 1 + Row 2, column 2 + + + +]]> + + Appearance: + + + + + + This is Column Head 1 + This is Column Head 2 + + + + + + Row 1, column 1 + Row 1, column 2 + + + + Row 2, column 1 + Row 2, column 2 + + + + + + + Always use the pgwide attribute with + a value of 1 with the + informaltable element. A bug in Internet + Explorer can cause the table to render incorrectly if this + is omitted. + + Table borders can be suppressed by setting the + frame attribute to none + in the informaltable element. For example, + <informaltable frame="none">. + + + Tables Where <literal>frame="none"</literal> + + Appearance: + + + + + + This is Column Head 1 + This is Column Head 2 + + + + + + Row 1, column 1 + Row 1, column 2 + + + + Row 2, column 1 + Row 2, column 2 + + + + + + + + + Examples for the User to Follow + + Examples for the user to follow are often necessary. + Typically, these will consist of dialogs with the computer; + the user types in a command, the user gets a response back, + the user types another command, and so on. + + A number of distinct elements and entities come into + play here. + + + + screen + + + Everything the user sees in this example will be + on the computer screen, so the next element is + screen. + + Within screen, white space is + significant. + + + + + prompt, + &prompt.root; and + &prompt.user; + + + Some of the things the user will be seeing on the + screen are prompts from the computer (either from the + operating system, command shell, or application). These + should be marked up using + prompt. + + As a special case, the two shell prompts for the + normal user and the root user have been provided as + entities. To indicate the user is at a shell prompt, + use one of &prompt.root; and + &prompt.user; as necessary. They + do not need to be inside + prompt. + + + &prompt.root; and + &prompt.user; are &os; + extensions to DocBook, and are not part of the + original DTD. + + + + + + userinput + + + When displaying text that the user should type in, + wrap it in userinput tags. It will + be displayed differently than system output text. + + + + + + <sgmltag>screen</sgmltag>, <sgmltag>prompt</sgmltag>, + and <sgmltag>userinput</sgmltag> + + Usage: + + &prompt.user; ls -1 +foo1 +foo2 +foo3 +&prompt.user; ls -1 | grep foo2 +foo2 +&prompt.user; su +Password: +&prompt.root; cat foo2 +This is the file called 'foo2']]> + + Appearance: + + &prompt.user; ls -1 +foo1 +foo2 +foo3 +&prompt.user; ls -1 | grep foo2 +foo2 +&prompt.user; su +Password: +&prompt.root; cat foo2 +This is the file called 'foo2' + + + + Even though we are displaying the contents of the file + foo2, it is not + marked up as programlisting. Reserve + programlisting for showing fragments of + files outside the context of user actions. + + + + + + In-line Elements + + + Emphasizing Information + + To emphasize a particular word or phrase, use + emphasis. This may be presented as + italic, or bold, or might be spoken differently with a + text-to-speech system. + + There is no way to change the presentation of the + emphasis within the document, no equivalent of + HTML's b and + i. If the information being presented is + important, then consider presenting it in + important rather than + emphasis. + + + <sgmltag>emphasis</sgmltag> + + Usage: + + FreeBSD is without doubt the + premiere Unix like operating system for the Intel architecture.]]> + + Appearance: + + FreeBSD is without doubt the + premiere Unix like operating system for the Intel + architecture. + + + + + Quotations + + To quote text from another document or source, or to + denote a phrase that is used figuratively, use + quote. Most of the markup tags available + for normal text are also available from within a + quote. + + + Quotations + + Usage: + + However, make sure that the search does not go beyond the + boundary between local and public administration, + as RFC 1535 calls it.]]> + + Appearance: + + However, make sure that the search does not go beyond + the boundary between local and public + administration, as RFC 1535 calls it. + + + + + Keys, Mouse Buttons, and Combinations + + To refer to a specific key on the keyboard, use + keycap. To refer to a mouse button, use + mousebutton. And to refer to + combinations of key presses or mouse clicks, wrap them all + in keycombo. + + keycombo has an attribute called + action, which may be one of + click, double-click, + other, press, + seq, or simul. The + last two values denote whether the keys or buttons should be + pressed in sequence, or simultaneously. + + The stylesheets automatically add any connecting + symbols, such as +, between the key + names, when wrapped in keycombo. + + + Keys, Mouse Buttons, and Combinations + + Usage: + + To switch to the second virtual terminal, press + Alt + F1. + +To exit vi without saving changes, type + Esc: + q!. + +My window manager is configured so that + Alt + right + mouse button is used to move windows.]]> + + Appearance: + + To switch to the second virtual terminal, press + Alt + F1. + + To exit vi without saving changes, + type + Esc + : + q + !. + + My window manager is configured so that + + Alt + right mouse button + is used to move windows. + + + + + Applications, Commands, Options, and Cites + + Both applications and commands are frequently referred to + when writing documentation. The distinction between them is + that an application is the name of a program or suite of + programs that fulfill a particular task. A command is the + filename of a program that the user can type and run at a + command line. + + It is often necessary to show some of the options that a + command might take. + + Finally, it is often useful to list a command with its + manual section number, in the command(number) + format so common in Unix manuals. + + Mark up application names with + application. + + To list a command with its manual section + number (which should be most of the time) the DocBook + element is citerefentry. This will + contain a further two elements, + refentrytitle and + manvolnum. The content of + refentrytitle is the name of the command, + and the content of manvolnum is the + manual page section. + + This can be cumbersome to write, and so a series of + general + entities have been created to make this easier. + Each entity takes the form + &man.manual-page.manual-section;. + + The file that contains these entities is in + doc/share/xml/man-refs.ent, and can be + referred to using this FPI: + + PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN" + + Therefore, the introduction to &os; documentation will + usually include this: + + <!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [ + +<!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"> +%man; + +… + +]> + + Use command when to include a command + name in-line but present it as something the + user should type in. + + Use option to mark up the options + which will be passed to a command. + + When referring to the same command multiple times in + close proximity, it is preferred to use the + &man.command.section; + notation to markup the first reference and use + command to markup subsequent references. + This makes the generated output, especially + HTML, appear visually better. + + This can be confusing, and sometimes the choice is not + always clear. Hopefully this example makes it + clearer. + + + Applications, Commands, and Options + + Usage: + + Sendmail is the most + widely used Unix mail application. + +Sendmail includes the + + sendmail + 8 + , &man.mailq.1;, and &man.newaliases.1; + programs. + +One of the command line parameters to + sendmail + 8 + , , will display the current + status of messages in the mail queue. Check this on the command + line by running sendmail -bp.]]> + + Appearance: + + Sendmail is the most widely + used Unix mail application. + + Sendmail includes the + + sendmail + 8 + , &man.mailq.1;, and &man.newaliases.1; + programs. + + One of the command line parameters to + + sendmail + 8 + , , will display the + current status of messages in the mail queue. Check this + on the command line by running + sendmail -bp. + + + + Notice how the + &man.command.section; + notation is easier to follow. + + + + + Files, Directories, Extensions + + To refer to the name of a file, a directory, or a file + extension, use filename. + + + <sgmltag>filename</sgmltag> + + Usage: + + The XML source for the Handbook in English is + found in /usr/doc/en_US.ISO8859-1/books/handbook/. The first + file is called book.xml in that + directory. There is also a Makefile + and a number of files with a .ent + extension.]]> + + Appearance: + + The XML source for the Handbook in English can be + found in /usr/doc/en/handbook/. The + first file is called handbook.xml in + that directory. There is also a + Makefile and a number of files with a + .ent extension. + + + + + The Name of Ports + + + &os; Extension + + These elements are part of the &os; extension to + DocBook, and do not exist in the original DocBook + DTD. + + + To include the name of a program from the &os; + Ports Collection in the document, use the + filename tag with the + role attribute set to + package. Since ports can be installed in + any number of locations, only include the category and the + port name; do not include + /usr/ports. + + + <sgmltag>filename</sgmltag> Tag with + <literal>package</literal> Role + + Usage: + + Install the net/wireshark port to view network traffic.]]> + + Appearance: + + Install the net/wireshark port to view + network traffic. + + + + + Devices + + + &os; Extension + + These elements are part of the &os; extension to + DocBook, and do not exist in the original DocBook + DTD. + + + There are two names for devices: the device name as it + appears in /dev, or the name of the + device as it appears in the kernel. For this latter course, + use devicename. + + Sometimes there is no choice. Some devices, such as + network cards, do not have entries in + /dev, or the entries are markedly + different from their kernel device names. + + + <sgmltag>devicename</sgmltag> + + Usage: + + sio is used for serial + communication in FreeBSD. sio manifests + through a number of entries in /dev, including + /dev/ttyd0 and /dev/cuaa0. + +By contrast, network devices such as + ed0 do not appear in /dev. + +In MS-DOS, the first floppy drive is referred to as + a:. In FreeBSD it is + /dev/fd0.]]> + + Appearance: + + sio is used for serial + communication in FreeBSD. sio + manifests through a number of entries in + /dev, including + /dev/ttyd0 and + /dev/cuaa0. + + By contrast, network devices such as + ed0 do not appear in + /dev. + + In MS-DOS, the first floppy drive is referred to as + a:. In FreeBSD it is + /dev/fd0. + + + + + Hosts, Domains, IP Addresses, and So Forth + + + &os; Extension + + These elements are part of the &os; extension to + DocBook, and do not exist in the original DocBook + DTD. + + + Identification information for networked computers (hosts) + can be marked up in several ways, depending on the nature of + the information. All of them use hostid as + the element, with the role attribute + selecting the type of the marked up information. + + + + No role attribute, or + role="hostname" + + + With no role attribute (i.e., + hostid.../hostid) + the marked up information is the simple hostname, such + as freefall or + wcarchive. The hostname can be + explicitly specified with + role="hostname". + + + + + role="domainname" + + + The text is a domain name, such as + FreeBSD.org or + ngo.org.uk. There is no hostname + component. + + + + + role="fqdn" + + + The text is a Fully Qualified Domain Name, with + both hostname and domain name parts. + + + + + role="ipaddr" + + + The text is an IP address, + probably expressed as a dotted quad. + + + + + role="ip6addr" + + + The text is an IPv6 + address. + + + + + role="netmask" + + + The text is a network mask, which might be + expressed as a dotted quad, a hexadecimal string, or as + a / followed by a number + (CIDR notation). + + + + + role="mac" + + + The text is an Ethernet MAC + address, expressed as a series of 2 digit hexadecimal + numbers separated by colons. + + + + + + <sgmltag>hostid</sgmltag> and Roles + + Usage: + + The local machine can always be referred to by the + name localhost, which will have the IP + address 127.0.0.1. + +The FreeBSD.org + domain contains a number of different hosts, including + freefall.FreeBSD.org and + bento.FreeBSD.org. + +When adding an IP alias to an + interface (using ifconfig) + always use a netmask of + 255.255.255.255 (which can + also be expressed as + 0xffffffff). + +The MAC address uniquely identifies + every network card in existence. A typical + MAC address looks like + 08:00:20:87:ef:d0.]]> + + Appearance: + + The local machine can always be referred to by the + name localhost, which will have the IP + address 127.0.0.1. + + The FreeBSD.org + domain contains a number of different hosts, including + freefall.FreeBSD.org and + bento.FreeBSD.org. + + When adding an IP alias to an + interface (using ifconfig) + always use a netmask of + 255.255.255.255 (which can + also be expressed as + 0xffffffff). + + The MAC address uniquely identifies + every network card in existence. A typical + MAC address looks like + 08:00:20:87:ef:d0. + + + + + Usernames + + + &os; Extension + + These elements are part of the &os; extension to + DocBook, and do not exist in the original DocBook + DTD. + + + To refer to a specific username, such as + root or bin, use + username. + + + <sgmltag>username</sgmltag> + + Usage: + + To carry out most system administration functions + requires logging in as root.]]> + + Appearance: + + To carry out most system administration functions + requires logging in as root. + + + + + Describing <filename>Makefile</filename>s + + + &os; Extension + + These elements are part of the &os; extension to + DocBook, and do not exist in the original DocBook + DTD. + + + Two elements exist to describe parts of + Makefiles, + maketarget and + makevar. + + maketarget identifies a build target + exported by a Makefile that can be + given as a parameter to make. + makevar identifies a variable that can be + set (in the environment, on the make + command line, or within the Makefile) + to influence the process. + + + <sgmltag>maketarget</sgmltag> and + <sgmltag>makevar</sgmltag> + + Usage: + + Two common targets in a Makefile + are all and + clean. + +Typically, invoking all will + rebuild the application, and invoking + clean will remove the temporary + files (.o for example) created by the + build process. + +clean may be controlled by a + number of variables, including CLOBBER + and RECURSE.]]> + + Appearance: + + Two common targets in a Makefile + are all and + clean. + + Typically, invoking all will + rebuild the application, and invoking + clean will remove the temporary + files (.o for example) created by the + build process. + + clean may be controlled by a + number of variables, including CLOBBER + and RECURSE. + + + + + Literal Text + + Literal text, or text which should be entered verbatim, is + often needed in documentation. This is text that is excerpted + from another file, or which should be copied exactly as shown + from the documentation into another file. + + Some of the time, programlisting will + be sufficient to denote this text. But + programlisting is not always appropriate, + particularly when you want to include a portion of a file + in-line with the rest of the + paragraph. + + On these occasions, use + literal. + + + <sgmltag>literal</sgmltag> + + Usage: + + The maxusers 10 line in the kernel + configuration file determines the size of many system tables, and is + a rough guide to how many simultaneous logins the system will + support.]]> + + Appearance: + + The maxusers 10 line in the kernel + configuration file determines the size of many system + tables, and is a rough guide to how many simultaneous + logins the system will support. + + + + + Showing Items That the User <emphasis>Must</emphasis> + Fill In + + There will often be times when the user is shown + what to do, or referred to a file or command line, but + cannot simply copy the example provided. Instead, they + must supply some information themselves. + + replaceable is designed for this + eventuality. Use it inside other + elements to indicate parts of that element's content that + the user must replace. + + + <sgmltag>replaceable</sgmltag> + + Usage: + + &prompt.user; man command]]> + + Appearance: + + + &prompt.user; man command + + + replaceable can be used in many + different elements, including literal. + This example also shows that + replaceable should only be wrapped + around the content that the user is + meant to provide. The other content should be left + alone. + + Usage: + + The maxusers n + line in the kernel configuration file determines the size of many system + tables, and is a rough guide to how many simultaneous logins the system will + support. + +For a desktop workstation, 32 is a good value + for n.]]> + + Appearance: + + The + maxusers n + line in the kernel configuration file determines the size + of many system tables, and is a rough guide to how many + simultaneous logins the system will support. + + For a desktop workstation, 32 is a + good value for n. + + + + + Quoting System Errors + + System errors generated by &os; are marked with + errorname. This indicates the exact error + that appears. + + + <sgmltag>errorname</sgmltag> + + Usage: + + Panic: cannot mount root]]> + + + Appearance: + + + Panic: cannot mount root + + + + + + + Images + + + Image support in the documentation is currently + extremely experimental. The mechanisms described here are + unlikely to change, but that is not guaranteed. + + Installation of the + graphics/ImageMagick + port is required. It is used to convert between the different + image formats. This port is not in + the textproc/docproj meta + port, it must be installed by hand. + + The best example of what follows in practice is the + doc/en_US.ISO8859-1/articles/vm-design/ + document. If the description that follows is unclear, take a + look at the files in that directory to see how everything + hangs together. Experiment with creating different formatted + versions of the document to see how the image markup appears + in the formatted output. + + + + Image Formats + + Two image formats are currently supported. Which to + choose will depend on the nature of the image. + + Images that are primarily vector based, such as network + diagrams, time lines, and similar, should be in + EPS (Encapsulated Postscript) format. + These images have a .eps + extension. + + For bitmaps, such as screen captures, use the + PNG (Portable Network Graphic) format. + These images have the .png + extension. + + These are the only formats in which + images should be committed to the Subversion + repository. + + Use the appropriate format for each image. It is to be + expected that documentation will have a mix of + EPS and PNG images. The + Makefiles ensure that the correct format + image is chosen depending on the output format that you use + for your documentation. Do not commit the same + image to the repository in two different + formats. + + + It is anticipated that the Documentation Project will + switch to using the SVG (Scalable Vector + Graphic) format for vector images. However, the current + state of SVG capable editing tools makes + this impractical. + + + + + Image Markup + + The markup for an image is relatively simple. First, + markup a mediaobject. The + mediaobject can contain other, more + specific objects. We are concerned with two, the + imageobject and the + textobject. + + Include one imageobject, + and two textobject elements. The + imageobject will point to the name of the + image file (without the extension). The + textobject elements contain information + that will be presented to the user as well as, or instead of, + the image itself. + + There are two circumstances where this can + happen. + + + + When the reader is viewing the documentation in + HTML. In this case, each image will + need associated alternate text to show the user, typically + while the image is loading, or if they hover the mouse + pointer over the image. + + + + When the reader is viewing the documentation in + plain text. In this case, each image should have an + ASCII art equivalent to show the + user. + + + + + An example will make things easier to understand. Suppose + there is an image called fig1.png that is + to be included in the document. This image is of a rectangle + with an A inside it. The markup for this would be as + follows. + + <mediaobject> + <imageobject> + <imagedata fileref="fig1"> + </imageobject> + + <textobject> + <literallayout class="monospaced">+---------------+ +| A | ++---------------+</literallayout> + </textobject> + + <textobject> + <phrase>A picture</phrase> + </textobject> +</mediaobject> + + + + Include an imagedata element + inside the imageobject element. The + fileref attribute should contain the + filename of the image to include, without the extension. + The stylesheets will work out which extension should be + added to the filename automatically. + + + + + The first textobject contains a + literallayout element, where the + class attribute is set to + monospaced. This is an opportunity to + demonstrate ASCII art skills. This + content will be used if the document is converted to plain + text. + + Notice how the first and last lines of the content + of the literallayout element butt up + next to the element's tags. This ensures no extraneous + white space is included. + + + + The second textobject contains a + single phrase element. The contents of + this phrase will become the alt + attribute for the image when this document is converted to + HTML. + + + + + + Image <filename>Makefile</filename> Entries + + Images must be listed in the Makefile + in the IMAGES variable. This variable must + contain the names of all the source + images. For example, if there are three figures, + fig1.eps, fig2.png, + fig3.png, then the + Makefile should have lines like this in + it. + + … +IMAGES= fig1.eps fig2.png fig3.png +… + + or + + … +IMAGES= fig1.eps +IMAGES+= fig2.png +IMAGES+= fig3.png +… + + Again, the Makefile will work out + the complete list of images it needs to build the source + document, you only need to list the image files + you provided. + + + + Images and Chapters in Subdirectories + + Be careful when separating documentation into smaller + files in different directories (see ). + + Suppose there is a book with three chapters, and the + chapters are stored in their own directories, called + chapter1/chapter.xml, + chapter2/chapter.xml, and + chapter3/chapter.xml. If each chapter + has images associated with it, it is suggested to place + those images in each chapter's subdirectory + (chapter1/, + chapter2/, and + chapter3/). + + However, doing this requires including the directory + names in the IMAGES variable in the + Makefile, and + including the directory name in the + imagedata element in the document + document. + + For example, if the book has + chapter1/fig1.png, then + chapter1/chapter.xml should + contain: + + <mediaobject> + <imageobject> + <imagedata fileref="chapter1/fig1"> + </imageobject> + + … + +</mediaobject> + + + + The directory name must be included in the + fileref attribute. + + + + The Makefile must contain: + + … +IMAGES= chapter1/fig1.png +… + + Then everything will work. + + + + + Links + + + Links are also in-line elements. + + + + <literal>id</literal> Attributes + + Most DocBook elements accept an id + attribute to give that part of the document a unique name. + The id can be used as a target for a + crossreference or link. + + Any portion of the document that will be a link target + must have an id attribute. Assigning an + id to all chapters and sections, even if + there are no current plans to link to them, is a good idea. + These ids can be used as unique anchor + reference points by anyone referring to the + HTML version of the document. + + + <literal>id</literal> on Chapters and + Sections + + + Introduction + + This is the introduction. It contains a subsection, + which is identified as well. + + + Sub-sect 1 + + This is a subsection. + +]]> + + + Use descriptive values for id names. + The values must be unique within the entire document, not just + in a single file. In the example, the subsection + id is constructed by appending text to the + chapter id. This ensures that the + ids are unique. It also helps both reader + and anyone editing the document to see where the link is + located within the document, similar to a directory + path to a file. + + To allow the user to jump into a specific portion of the + document, even in the middle of a paragraph or an example, use + anchor. This element has no content, but + takes an id attribute. + + + <sgmltag>anchor</sgmltag> + + This paragraph has an embedded + link target in it. It will not + show up in the document.]]> + + + + + Crossreferences with <literal>xref</literal> + + xref provides the reader with a link to + jump to another section of the document. The target + id is specified in the + linkend attribute, and + xref generates the link text + automatically. + + + Using <sgmltag>xref</sgmltag> + + Assume that this fragment appears somewhere in a + document that includes the id + example: + + More information can be found + in . + +More specific information can be found + in .]]> + + The link text will be generated automatically, looking + like (emphasized text indicates the + link text): + +
+ More information can be found in Chapter + 1, The Sample Chapter. + + More specific information can be found in + Section 1.1, + Sample Sub-Sect. +
+ + + The link text is generated automatically from the chapter + and section number and title + elements. + + + xref cannot link to an + id attribute on an + anchor element. The + anchor has no content, so the + xref cannot generate the link + text. + + + + + Linking to the Same Document or Other Documents on the + Web + + The link elements described here allow the writer to + define the link text. It is very important to use descriptive + link text to give the reader an idea of where the link will + take them. Remember that DocBook can be rendered to multiple + types of media. The reader may be looking at a printed book + or other form of media where there are no links. If the link + text is not descriptive enough, the reader may not be able to + locate the linked section. + + + Links to the Same Document + + link is used to create a link + within the same document. The target id + is specified in the linkend attribute. + This element wraps content, which is used for the link + text. + + + Using <sgmltag>link</sgmltag> + + Assume that this fragment appears somewhere in a + document that includes the id + example. + + More information can be found in the + sample chapter. + +More specific information can be found in the + even more samples section.]]> + + This output will be generated + (emphasized text is used to show the + link text): + +
+ More information can be found in the + sample chapter. + + More specific information can be found in the + even more samples section. +
+ + + + link can be used to include links + to the id of an + anchor element, since the + link content defines the link + text. + + + + + Linking to Other Documents on the Web + + The ulink is used to link to + external documents on the web. The url + attribute is the URL of the page that the + link points to, and the content of the element is the text + that will be displayed for the user to activate. + + + <sgmltag>ulink</sgmltag> to a &os; Documentation Web + Page + + Link to the book or article URL + entity. To link to a specific chapter in a book, add a + slash and the chapter file name, followed by an optional + anchor within the chapter. For articles, link to the + article URL entity, followed by an + optional anchor within the article. + URL entities can be found in + doc/share/xml/urls.ent. + + Usage for book links: + + Read the SVN + introduction, then pick the nearest mirror from + the list of Subversion + mirror sites.]]> + + Appearance: + + Read the SVN + introduction, then pick the nearest mirror from + the list of Subversion + mirror sites. + + Usage for article links: + + Read this article + about the BSD license, or just the introduction.]]> + + Appearance: + + Read this article + about the BSD license, or just the introduction. + + + + <sgmltag>ulink</sgmltag> to a &os; Web Page + + Usage: + + Of course, you could stop reading this document and + go to the FreeBSD + home page instead.]]> + + Appearance: + + Of course, you could stop reading this document and go + to the FreeBSD home + page instead. + + + + <sgmltag>ulink</sgmltag> to an External Web + Page + + Usage: + + Wikipedia has an excellent reference on + GUID + Partition Tables.]]> + + Wikipedia has an excellent reference on + GUID + Partition Tables. + + + + + Property changes on: head/en_US.ISO8859-1/books/fdp-primer/docbook-markup/chapter.xml ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Added: svn:mime-type ## -0,0 +1 ## +text/sgml \ No newline at end of property Index: head/en_US.ISO8859-1/books/fdp-primer/overview/chapter.xml =================================================================== --- head/en_US.ISO8859-1/books/fdp-primer/overview/chapter.xml (revision 42004) +++ head/en_US.ISO8859-1/books/fdp-primer/overview/chapter.xml (revision 42005) @@ -1,294 +1,295 @@ Overview Welcome to the &os; Documentation Project (FDP). Quality documentation is very important to the success of &os;. Your contributions are very valuable. This document's main purpose is to explain how the FDP is organized, how to write and submit documentation, and how to effectively use the available tools. Everyone is welcome to contribute to the FDP. There is no membership requirement or minimum quota of documentation that needs to be produced. After you have finished reading this document you will be able to: Identify which parts of &os; are maintained by the FDP. Install the required tools and files. Make changes to the documentation. Submit changes back for review and eventual inclusion in the &os; documentation. The &os; Documentation Set The FDP is responsible for four categories of &os; documentation. Handbook: The Handbook is the comprehensive online resource and reference for &os; users. FAQ: The FAQ uses a short question and answer format to address questions that are frequently asked on the various mailing lists and forums devoted to &os;. This format does not permit long and comprehensive answers. Manual pages: The English language system manual pages are usually not written by the FDP, as they are part of the base system. However, the FDP can reword parts of existing manual pages to make them clearer or to correct inaccuracies. Web site: This is the main &os; presence on the web, visible at http://www.FreeBSD.org/ and many mirrors around the world. The web site is typically a new user's first exposure to &os;. Translation teams are responsible for translating the Handbook and web site into different languages. Manual pages are not translated. Documentation source for the &os; web site, Handbook, and FAQ is available in the Subversion repository at https://svn.FreeBSD.org/doc/. Source for manual pages is available in a separate Subversion repository located at https://svn.FreeBSD.org/base/. The commit messages to the FDP are visible to anyone usingvsvn. They are also archived at &a.svn-doc-all.url;. In addition, many people have written tutorials or how-to articles about &os;. Some are stored in the FDP. In other cases, the author has decided to keep the documentation separate from the FDP. The FDP endeavors to provide links to as much of this documentation as possible. Quick Start This section outlines the steps which new contributors need to follow before they can make changes to the FDP. New contributors will interact with other members of the &os; Documentation Team which can assist in learning how to use XML and the . If a new user contributes regularly, a Documentation Team member may be assigned as a mentor to guide the user through the process from contributor to documentation committer. Subscribe to the &a.doc;. Some members of the mailing list also interact on the #bsddocs IRC channel on EFnet. Install the textproc/docproj package or port. This meta-port installs all of the utilities needed by the FDP. Install a local working copy of the documentation from a mirror of the &os; repository. For the fastest download, pick the nearest mirror from the list of Subversion mirror sites. If /usr/doc already exists, move or delete it first to prevent file conflicts. &prompt.user; svn checkout https://svn0.us-west.FreeBSD.org/doc/head /usr/doc Before making any documentation edits, configure your editor to conform to FDP standards. How to do so varies by editor. Some editor configurations are listed in . The editor should be configured as follows: Word wrap set to 70 characters. Tab stops set to 2. Replace each group of 8 leading spaces with a single tab. Determine which file to edit. Run svn up within the local working copy to make sure that it is current. Before making major changes to a file, discuss the proposed changes first with the &a.doc;. When making edits, determine which tags and entities are needed to achieve the desired formatting. One way to learn is to compare some text in the HTML formatted version of the document to the tags which surround the text or the entities that represent that text in the XML file. A reference to the commonly used tags and entities can be - found in . + found in and + . Once the edits are complete, check for problems by running: &prompt.user; igor -R filename.xml | less -RS While reviewing the output, edit the file to fix the listed tab errors, spelling mistakes, and improper grammar. Save the changes and rerun this command to find any remaining problems. Repeat until all of the errors that you deem fixable are resolved. If you get stuck trying to fix errors, ask for assistance on the &a.doc;. Always build-test changes before submitting them. By default, typing make in the top-level directory of the type of documentation being edited will generate that documentation in split HTML format. For example, to build the English version of the Handbook, type make in the en_US.ISO8859-1/books/handbook/ directory. This step is necessary to make sure that the edits do not break the build. In order to build the output in other formats, other make targets are defined in head/share/mk/doc.docbook.mk. Use quotes around the list of formats when building more than one format with a single command. For example, to convert the document to both .html and .txt, use this command: &prompt.user; make FORMATS="html txt" Once these steps are successfully completed, generate a diff file of the changes. While in /usr/doc, run this command, replacing bsdinstall with the name of the directory containing the edits: &prompt.user; svn diff > bsdinstall.diff.txt Submit the diff file using the web-based Problem Report system or with &man.send-pr.1;. If using the web form, input a synopsis of [patch] short description of problem. Select the category docs and the class doc-bug. The body of the message should contain a short description of the edits and any important discussion points. Use the [ Browse... ] button to attach the .diff.txt file and enter the captcha phrase. It is important to remember that the FDP is comprised of volunteers who review edits in their spare time and who live in different time zones across the globe. It takes time to review edits and to either commit them or respond if additional edits are required. If you do not receive a response in a reasonable amount of time, send a follow-up email to the &a.doc; and ask if anyone has had a chance to review the patch or if additional information is required. - \ No newline at end of file + 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 (nonexistent) +++ head/en_US.ISO8859-1/books/fdp-primer/xhtml-markup/chapter.xml (revision 42005) @@ -0,0 +1,613 @@ + + + + + <acronym>XHTML</acronym> Markup + + + Introduction + + This chapter describes usage of the XHTML + markup language used for the &os; web site. + + XHTML is the XML + version of the HyperText Markup Language, the markup language of + choice on the World Wide Web. More information can be found at + . + + XHTML is used to mark up pages on the + &os; web site. It is usually not used to mark up other + documentation, since DocBook offers a far richer set of elements + from which to choose. Consequently, XHTML + pages will normally only be encountered when writing for the web + site. + + HTML has gone through a number of + versions. The XML-compliant version + described here is called XHTML. The latest + widespread version is XHTML 1.0, available in + both strict and + transitional variants. + + The XHTML DTDs are + available from the Ports Collection in + textproc/xhtml. They are + automatically installed as part of the textproc/docproj port. + + + This is not an exhaustive list of + elements, since that would just repeat the documentation for + XHTML. The aim is to list those elements + most commonly used. Please post questions about elements or + uses not covered here to the &a.doc;. + + + + Inline Versus Block + + In the remainder of this document, when describing + elements, inline means that the element + can occur within a block element, and does not cause a line + break. A block element, by comparison, + will cause a line break (and other processing) when it is + encountered. + + + + + Formal Public Identifier (<acronym>FPI</acronym>) + + There are a number of XHTML + FPIs, depending upon the version, or + level of XHTML to which + a document conforms. Most XHTML documents on the FreeBSD web + site comply with the transitional version of + XHTML 1.0. + + PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + + + + Sectional Elements + + An XHTML document is normally split into + two sections. The first section, called the + head, contains meta-information about the + document, such as its title, the name of the author, the parent + document, and so on. The second section, the + body, contains the content that will be + displayed to the user. + + These sections are indicated with head + and body elements respectively. These + elements are contained within the top-level + html element. + + + Normal <acronym>XHTML</acronym> Document + Structure + + <html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <title>The Document's Title</title> + </head> + + <body> + + … + + </body> +</html> + + + + + Block Elements + + + Headings + + XHTML has tags to denote headings in + the document at up to six different levels. + + The largest and most prominent heading is + h1, then h2, + continuing down to h6. + + The element's content is the text of the heading. + + + <sgmltag>h1</sgmltag>, <sgmltag>h2</sgmltag>, + and Other Header Tags + + Usage: + + First section + + + +

This is the heading for the first section

+ + + +

This is the heading for the first sub-section

+ + + +

This is the heading for the second section

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

Sub-section

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

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

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

+ +
    +
  • First item
    • + +
  • Second item
    • + +
  • Third item
    • +
+ +

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

+ +
    +

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

    2. + +

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

    + +

    This is the second paragraph of the second item.

    3. + +

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

    4. +
]]> + + + + Definition Lists with <sgmltag>dl</sgmltag> + + Usage: + + +
Term 1
+ +

Paragraph 1 of definition 1.

+ +

Paragraph 2 of definition 1.

+ +
Term 2
+ +

Paragraph 1 of definition 2.

+ +
Term 3
+ +

Paragraph 1 of definition 3.

+]]> + + + + + Pre-formatted Text + + Pre-formatted text can be shown to the user exactly as it + is in the file. Typically, this means that the text is shown + in a fixed font, multiple spaces are not merged into one, and + line breaks in the text are significant. + + In order to do this, wrap the content in the + pre element. + + + <sgmltag>pre</sgmltag> + + For example, the pre tags could be + used to mark up an email message: + + From: nik@FreeBSD.org + To: freebsd-doc@FreeBSD.org + Subject: New documentation available + + There is a new copy of my primer for contributors to the FreeBSD + Documentation Project available at + + <URL:http://people.FreeBSD.org/~nik/primer/index.html> + + Comments appreciated. + + N]]> + + Keep in mind that < and + & still are recognized as special + characters in pre-formatted text. This is why the example + shown had to use &lt; instead of + <. For consistency, + &gt; was used in place of + >, too. Watch out for the special + characters that may appear in text copied from a plain-text + source, like an email message or program code. + + + + + Tables + + Mark up tabular information using the + table element. A table consists of one or + more table rows (tr), each containing one + or more cells of table data (td). Each + cell can contain other block elements, such as paragraphs or + lists. It can also contain another table (this nesting can + repeat indefinitely). If the cell only contains one paragraph + then the pelement is not needed. + + + Simple Use of <sgmltag>table</sgmltag> + + Usage: + + This is a simple 2x2 table.

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

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

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

+ + + + + + + + + + + + + + + + + + + + + +
Top left large cellTop right cell
Middle right cell
Bottom left cellBottom middle cellBottom right cell
]]> + + + + + + In-line Elements + + + Emphasizing Information + + Two levels of emphasis are available in + XHTML, em and + strong. em is for a + normal level of emphasis and strong + indicates stronger emphasis. + + Typically, em is rendered in italic + and strong is rendered in bold. This is + not always the case, however, and should not be relied upon. + According to best practices, webpages only hold structural and + semantical information and stylesheets are later applied to + them. Think of semantics, not formatting, when using these + tags. + + + <sgmltag>em</sgmltag> and + <sgmltag>strong</sgmltag> + + Usage: + + This has been emphasized, while + this has been strongly emphasized.

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

]]> + + + + + Links + + + Links are also inline elements. + + + + Linking to Other Documents on the Web + + A link points to the URL of another + document on the web. The link is indicated with + a, and the href + attribute contains the URL of the target + document. The content of the element becomes the link, and + is normally indicated to the user in some way, + typically by a different color or underlining. + + + Using <literal><a href="..."></literal> + + Usage: + + More information is available at the + FreeBSD web site.

]]> + + + These links will take the user to the top of the chosen + document. + + + + Linking to Other Parts of Documents + + Linking to a point within another document, or within + the same document, requires that the document author include + anchors. Anchors are indicated with + a and the id attribute + instead of href. + + + Using <literal><a id="..."></literal> + + Usage: + + This paragraph can be referenced + in other links with the name para1.

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

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

]]> + + + + + Property changes on: head/en_US.ISO8859-1/books/fdp-primer/xhtml-markup/chapter.xml ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Added: svn:mime-type ## -0,0 +1 ## +text/sgml \ No newline at end of property