From owner-svn-doc-all@FreeBSD.ORG Sun Jun 23 19:45:13 2013 Return-Path: Delivered-To: svn-doc-all@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [8.8.178.115]) by hub.freebsd.org (Postfix) with ESMTP id EFBB0BB8; Sun, 23 Jun 2013 19:45:13 +0000 (UTC) (envelope-from wblock@FreeBSD.org) Received: from svn.freebsd.org (svn.freebsd.org [IPv6:2001:1900:2254:2068::e6a:0]) by mx1.freebsd.org (Postfix) with ESMTP id DF48A1AB1; Sun, 23 Jun 2013 19:45:13 +0000 (UTC) Received: from svn.freebsd.org ([127.0.1.70]) by svn.freebsd.org (8.14.7/8.14.7) with ESMTP id r5NJjDwh055483; Sun, 23 Jun 2013 19:45:13 GMT (envelope-from wblock@svn.freebsd.org) Received: (from wblock@localhost) by svn.freebsd.org (8.14.7/8.14.5/Submit) id r5NJjDxK055478; Sun, 23 Jun 2013 19:45:13 GMT (envelope-from wblock@svn.freebsd.org) Message-Id: <201306231945.r5NJjDxK055478@svn.freebsd.org> From: Warren Block Date: Sun, 23 Jun 2013 19:45:13 +0000 (UTC) To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r42005 - in head/en_US.ISO8859-1/books/fdp-primer: . docbook-markup overview sgml-markup xhtml-markup X-SVN-Group: doc-head MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-doc-all@freebsd.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: "SVN commit messages for the entire doc trees \(except for " user" , " projects" , and " translations" \)" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sun, 23 Jun 2013 19:45:14 -0000 Author: wblock Date: Sun Jun 23 19:45:12 2013 New Revision: 42005 URL: http://svnweb.freebsd.org/changeset/doc/42005 Log: Split the old sgml-markup chapter into two chapters, one for XHTML and one for DocBook. Both are edited and expanded versions of the content from the old chapter. Added: head/en_US.ISO8859-1/books/fdp-primer/docbook-markup/ head/en_US.ISO8859-1/books/fdp-primer/docbook-markup/chapter.xml - copied, changed from r41997, head/en_US.ISO8859-1/books/fdp-primer/sgml-markup/chapter.xml head/en_US.ISO8859-1/books/fdp-primer/xhtml-markup/ head/en_US.ISO8859-1/books/fdp-primer/xhtml-markup/chapter.xml - copied, changed from r41997, head/en_US.ISO8859-1/books/fdp-primer/sgml-markup/chapter.xml Deleted: head/en_US.ISO8859-1/books/fdp-primer/sgml-markup/ Modified: head/en_US.ISO8859-1/books/fdp-primer/Makefile head/en_US.ISO8859-1/books/fdp-primer/book.xml head/en_US.ISO8859-1/books/fdp-primer/chapters.ent head/en_US.ISO8859-1/books/fdp-primer/overview/chapter.xml Modified: head/en_US.ISO8859-1/books/fdp-primer/Makefile ============================================================================== --- head/en_US.ISO8859-1/books/fdp-primer/Makefile Sun Jun 23 17:59:58 2013 (r42004) +++ head/en_US.ISO8859-1/books/fdp-primer/Makefile Sun Jun 23 19:45:12 2013 (r42005) @@ -23,7 +23,8 @@ SRCS= book.xml SRCS+= overview/chapter.xml SRCS+= psgml-mode/chapter.xml SRCS+= see-also/chapter.xml -SRCS+= sgml-markup/chapter.xml +SRCS+= xhtml-markup/chapter.xml +SRCS+= docbook-markup/chapter.xml SRCS+= sgml-primer/chapter.xml SRCS+= stylesheets/chapter.xml SRCS+= structure/chapter.xml Modified: head/en_US.ISO8859-1/books/fdp-primer/book.xml ============================================================================== --- head/en_US.ISO8859-1/books/fdp-primer/book.xml Sun Jun 23 17:59:58 2013 (r42004) +++ head/en_US.ISO8859-1/books/fdp-primer/book.xml Sun Jun 23 19:45:12 2013 (r42005) @@ -248,7 +248,8 @@ Password: &chap.overview; &chap.tools; &chap.xml-primer; - &chap.xml-markup; + &chap.xhtml-markup; + &chap.docbook-markup; &chap.stylesheets; &chap.structure; &chap.doc-build; Modified: head/en_US.ISO8859-1/books/fdp-primer/chapters.ent ============================================================================== --- head/en_US.ISO8859-1/books/fdp-primer/chapters.ent Sun Jun 23 17:59:58 2013 (r42004) +++ head/en_US.ISO8859-1/books/fdp-primer/chapters.ent Sun Jun 23 19:45:12 2013 (r42005) @@ -13,7 +13,8 @@ - + + Copied and modified: head/en_US.ISO8859-1/books/fdp-primer/docbook-markup/chapter.xml (from r41997, head/en_US.ISO8859-1/books/fdp-primer/sgml-markup/chapter.xml) ============================================================================== --- head/en_US.ISO8859-1/books/fdp-primer/sgml-markup/chapter.xml Fri Jun 21 17:57:26 2013 (r41997, copy source) +++ head/en_US.ISO8859-1/books/fdp-primer/docbook-markup/chapter.xml Sun Jun 23 19:45:12 2013 (r42005) @@ -31,620 +31,40 @@ $FreeBSD$ --> - - XML Markup + + DocBook 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. + + Introduction - - 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 + 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 - 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. + 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 @@ -656,209 +76,217 @@ 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;. - + + Inline Versus Block - The &os; extensions are not (currently) in the - Ports Collection. They are stored in the &os; Subversion - tree, as head/share/xml/freebsd.dtd. - + 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 (FPI) + + &os; Extensions - In compliance with the DocBook guidelines for writing FPIs - for DocBook customizations, the FPI for the FreeBSD extended - DocBook DTD is: + 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. - PUBLIC "-//FreeBSD//DTD DocBook V4.2-Based Extension//EN" - + + 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;. + - - Document Structure + The &os; extensions are not (currently) in the + Ports Collection. They are stored in the &os; Subversion + tree, as head/share/xml/freebsd.dtd. + - 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. + + Formal Public Identifier (FPI) - Chapters and sections contain the remainder of the - content. + In compliance with the DocBook guidelines for writing + FPIs for DocBook customizations, the + FPI for the &os; extended DocBook + DTD is: - 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. + PUBLIC "-//FreeBSD//DTD DocBook V4.2-Based Extension//EN" + - - Starting a Book + + Document Structure - 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. + 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 should be contained within - bookinfo. + This additional information is contained within + bookinfo. - - Boilerplate <sgmltag>book</sgmltag> with - <sgmltag>bookinfo</sgmltag> + + 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> + <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> - - +</book> + + - - Starting an Article + + 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. + 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. + This additional information is contained within + articleinfo. - - Boilerplate <sgmltag>article</sgmltag> with - <sgmltag>articleinfo</sgmltag> + + Boilerplate <sgmltag>article</sgmltag> with + <sgmltag>articleinfo</sgmltag> - + - <article> - <articleinfo> - <title>Your title here</title> - - <author> *** DIFF OUTPUT TRUNCATED AT 1000 LINES ***