From owner-svn-doc-all@FreeBSD.ORG Sat Jul 13 21:12:09 2013 Return-Path: Delivered-To: svn-doc-all@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) by hub.freebsd.org (Postfix) with ESMTP id F12E2F78; Sat, 13 Jul 2013 21:12:08 +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 D2DEB1039; Sat, 13 Jul 2013 21:12:08 +0000 (UTC) Received: from svn.freebsd.org ([127.0.1.70]) by svn.freebsd.org (8.14.7/8.14.7) with ESMTP id r6DLC8SJ070188; Sat, 13 Jul 2013 21:12:08 GMT (envelope-from wblock@svn.freebsd.org) Received: (from wblock@localhost) by svn.freebsd.org (8.14.7/8.14.5/Submit) id r6DLC8fl070186; Sat, 13 Jul 2013 21:12:08 GMT (envelope-from wblock@svn.freebsd.org) Message-Id: <201307132112.r6DLC8fl070186@svn.freebsd.org> From: Warren Block Date: Sat, 13 Jul 2013 21:12:08 +0000 (UTC) To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r42274 - head/en_US.ISO8859-1/books/fdp-primer/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: Sat, 13 Jul 2013 21:12:09 -0000 Author: wblock Date: Sat Jul 13 21:12:08 2013 New Revision: 42274 URL: http://svnweb.freebsd.org/changeset/doc/42274 Log: Revise and edit the XHTML chapter. Improve clarity, voice, and examples. Replace CDATA with longer but technically correct ("the best kind of correct") sgmltag usage. Modified: head/en_US.ISO8859-1/books/fdp-primer/xhtml-markup/chapter.xml Modified: head/en_US.ISO8859-1/books/fdp-primer/xhtml-markup/chapter.xml ============================================================================== --- head/en_US.ISO8859-1/books/fdp-primer/xhtml-markup/chapter.xml Sat Jul 13 18:20:08 2013 (r42273) +++ head/en_US.ISO8859-1/books/fdp-primer/xhtml-markup/chapter.xml Sat Jul 13 21:12:08 2013 (r42274) @@ -60,9 +60,9 @@ transitional variants. The XHTML DTDs are - available from the Ports Collection in + available from the Ports Collection in textproc/xhtml. They are - automatically installed as part of the textproc/docproj port. @@ -91,7 +91,7 @@ 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 + a document conforms. Most XHTML documents on the FreeBSD web site comply with the transitional version of XHTML 1.0. @@ -106,7 +106,7 @@ 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 + body, contains content that will be displayed to the user. These sections are indicated with head @@ -118,17 +118,17 @@ Normal <acronym>XHTML</acronym> Document Structure - <html xmlns="http://www.w3.org/1999/xhtml"> - <head> - <title>The Document's Title</title> - </head> + html xmlns="http://www.w3.org/1999/xhtml" + head + titleThe Document's Titletitle + head - <body> + body … - </body> -</html> + body +html @@ -153,47 +153,28 @@ Usage: - First section + h1First sectionh1 - +<!-- Document introduction goes here --> -

This is the heading for the first section

+h2This is the heading for the first sectionh2 - +<!-- Content for the first section goes here --> -

This is the heading for the first sub-section

+h3This is the heading for the first sub-sectionh3 - +<!-- Content for the first sub-section goes here --> -

This is the heading for the second section

+h2This is the heading for the second sectionh2 -]]> +<!-- Content for the second section goes here --> Generally, an XHTML page should have one first level heading (h1). This can contain many second level headings (h2), - which can in turn contain many third level headings. 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

- -]]> - + which can in turn contain many third level headings. + Do not leave gaps in the numbering. @@ -207,8 +188,8 @@ Usage: - This is a paragraph. It can contain just about any - other element.

]]> + pThis is a paragraph. It can contain just about any + other element.p @@ -216,7 +197,7 @@ Block Quotations A block quotation is an extended quotation from another - document that should not appear within the current + document that will appear in a separate paragraph. @@ -224,14 +205,14 @@ Usage: - A small excerpt from the US Constitution:

+ pA small excerpt from the US Constitution:p -
We the People of the United States, in Order to form +blockquoteWe the People of the United States, in Order to form a more perfect Union, establish Justice, insure domestic Tranquility, provide for the common defence, promote the general Welfare, and secure the Blessings of Liberty to ourselves and our Posterity, do ordain and establish this Constitution for the - United States of America.
]]> + United States of America.blockquote @@ -241,12 +222,11 @@ 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 + Entries in an ordered list will be + numbered, while entries in an unordered list will be + preceded by bullet points. Definition lists have two sections for each entry. The first section is the term - being defined, and the second section is the definition of the - term. + being defined, and the second section is the definition. Ordered lists are indicated by the ol element, unordered lists by the ul @@ -270,31 +250,31 @@ Usage: - An unordered list. Listitems will probably be - preceded by bullets.

+ pAn unordered list. Listitems will probably be + preceded by bullets.p -
    -
  • First item
    • +ul + liFirst itemli -
  • Second item
    • + liSecond itemli -
  • Third item
    • -
+ liThird itemli +ul -

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

+ numbered.p -
    -

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

    2. +ol + lipThis is the first item. It only has one paragraph.pli -

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

    + lipThis is the first paragraph of the second item.p -

    This is the second paragraph of the second item.

    3. + pThis is the second paragraph of the second item.pli -

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

    4. -
]]> + lipThis is the first and only paragraph of the third + item.pli +ol @@ -302,33 +282,33 @@ Usage: - -
Term 1
+ dl + dtTerm 1dt -

Paragraph 1 of definition 1.

+ ddpParagraph 1 of definition 1.p -

Paragraph 2 of definition 1.

+ pParagraph 2 of definition 1.pdd -
Term 2
+ dtTerm 2dt -

Paragraph 1 of definition 2.

+ ddpParagraph 1 of definition 2.pdd -
Term 3
+ dtTerm 3dt -

Paragraph 1 of definition 3.

-]]> + ddpParagraph 1 of definition 3.pdd +dl 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. + Pre-formatted text is shown to the user exactly as it + is in the file. Text is shown in a fixed font. + Multiple spaces and line breaks are shown exactly as they are + in the file. - In order to do this, wrap the content in the + Wrap pre-formatted text in the pre element. @@ -337,18 +317,18 @@ For example, the pre tags could be used to mark up an email message: - From: nik@FreeBSD.org + pre From: nik@FreeBSD.org To: freebsd-doc@FreeBSD.org Subject: New documentation available There is a new copy of my primer for contributors to the FreeBSD Documentation Project available at - <URL:http://people.FreeBSD.org/~nik/primer/index.html> + &lt;URL:http://people.FreeBSD.org/~nik/primer/index.html&gt; Comments appreciated. - N]]> + Npre Keep in mind that < and & still are recognized as special @@ -379,101 +359,101 @@ Usage: - This is a simple 2x2 table.

+ pThis is a simple 2x2 table.p - - - +table + tr + tdTop left celltd - - + tdTop right celltd + tr - - + tr + tdBottom left celltd - - -
Top left cellTop right cell
Bottom left cellBottom right cell
]]> + tdBottom right celltd + tr +table - 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. + A cell can span multiple rows and columns by adding + the rowspan or + colspan attributes with values for + the number of rows or columns to be spanned. - Using <literal>rowspan</literal> + Using <sgmltag class="attribute">rowspan</sgmltag> Usage: - One tall thin cell on the left, two short cells next to - it on the right.

+ pOne tall thin cell on the left, two short cells next to + it on the right.p - - - - +table + tr + td rowspan="2"Long and thintd + tr - - + tr + tdTop celltd - - -
Long and thin
Top cellBottom cell
]]> + tdBottom celltd + tr +table - Using <literal>colspan</literal> + Using <sgmltag class="attribute">colspan</sgmltag> Usage: - One long cell on top, two short cells below it.

+ pOne long cell on top, two short cells below it.p - - - - +table + tr + td colspan="2"Top celltd + tr - - + tr + tdBottom left celltd - - -
Top cell
Bottom left cellBottom right cell
]]> + tdBottom right celltd + tr +table - Using <literal>rowspan</literal> and - <literal>colspan</literal> Together + Using <sgmltag class="attribute">rowspan</sgmltag> and + <sgmltag class="attribute">colspan</sgmltag> Together Usage: - On a 3x3 grid, the top left block is a 2x2 set of - cells merged into one. The other cells are normal.

+ pOn a 3x3 grid, the top left block is a 2x2 set of + cells merged into one. The other cells are normal.p - - - +table + tr + td colspan="2" rowspan="2"Top left large celltd - - + tdTop right celltd + tr - - + tr + <!-- Because the large cell on the left merges into + this row, the first <td> will occur on its + right --> - - + tdMiddle right celltd + tr - - + tr + tdBottom left celltd - + tdBottom middle celltd - - -
Top left large cellTop right cell
Middle right cell
Bottom left cellBottom middle cellBottom right cell
]]> + tdBottom right celltd + tr +table @@ -490,11 +470,11 @@ normal level of emphasis and strong indicates stronger emphasis. - Typically, em is rendered in italic + em is typically 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 + not always the case, and should not be relied upon. + According to best practices, web pages only hold structural and + semantical information, and stylesheets are later applied to them. Think of semantics, not formatting, when using these tags. @@ -504,8 +484,8 @@ Usage: - This has been emphasized, while - this has been strongly emphasized.

]]> + pemThisem has been emphasized, while + strongthisstrong has been strongly emphasized.p @@ -521,9 +501,8 @@ Usage: - This document was originally written by - Nik Clayton, who can be reached by email as - nik@FreeBSD.org.

]]> + pMany system settings are stored in + tt/etctt.p @@ -537,75 +516,76 @@ Linking to Other Documents on the Web - A link points to the URL of another + A link points to the URL of a document on the web. The link is indicated with - a, and the href + 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. + document. The content of the element becomes the link, + indicated to the user by showing it in + a different color or with an underline. - Using <literal><a href="..."></literal> + Using <sgmltag class="starttag">a href="..."</sgmltag> Usage: - More information is available at the - FreeBSD web site.

]]> + pMore information is available at the + a href="http://www.&os;.org/"&os; web sitea.p - These links will take the user to the top of the chosen + This link always takes the user to the top of the linked document. - - Linking to Other Parts of Documents + + Linking to Specific 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. + To link to a specific point within a document, that + document must include an + anchor at the desired point. Anchors are included by setting the + id attribute of an element to a name. + This example creates an anchor by setting the id attribute + of a p element. - Using <literal><a id="..."></literal> + Creating an Anchor Usage: - This paragraph can be referenced - in other links with the name para1.

]]> + p id="samplepara"This paragraph can be referenced + in other links with the name ttsampleparatt.p - 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. + Links to anchors are similar to plain links, + but include a # symbol and the anchor's ID + at the end of the URL. - Linking to a Named Part of Another Document + Linking to a Named Part of a Different 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.

]]> + The samplepara example + is part of a document called + foo.html. A link to that specific + paragraph in the document is constructed in this example. + + pMore information can be found in the + a href="foo.html#samplepara"sample paragrapha of + ttfoo.htmltt.p - 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 - #). + To link to a named anchor within the same + document, omit the document's URL, and just + use the # symbol followed by the name of the anchor. Linking to a Named Part of the Same Document - Assume that the para1 example - resides in this document: + The samplepara example + resides in this document. To link to it: - More information can be found in the - first paragraph of this - document.

]]> + pMore information can be found in the + a href="#samplepara"sample paragrapha of this + document.p