Examples

@@ -269,7 +271,7 @@ Converting DocBook to Postscript - The source SGML file must be converted to a &tex; + The source XML file must be converted to a &tex; file. &prompt.user; jade -V tex-backend \ Modified: projects/sgml2xml/en_US.ISO8859-1/books/fdp-primer/overview/chapter.sgml ============================================================================== --- projects/sgml2xml/en_US.ISO8859-1/books/fdp-primer/overview/chapter.sgml Thu Sep 13 18:03:11 2012 (r39527) +++ projects/sgml2xml/en_US.ISO8859-1/books/fdp-primer/overview/chapter.sgml Fri Sep 14 08:32:33 2012 (r39528) @@ -63,7 +63,7 @@ - Be able to read and understand the SGML source code for + Be able to read and understand the XML source code for the documentation maintained by the FDP. Modified: projects/sgml2xml/en_US.ISO8859-1/books/fdp-primer/see-also/chapter.sgml ============================================================================== --- projects/sgml2xml/en_US.ISO8859-1/books/fdp-primer/see-also/chapter.sgml Thu Sep 13 18:03:11 2012 (r39527) +++ projects/sgml2xml/en_US.ISO8859-1/books/fdp-primer/see-also/chapter.sgml Fri Sep 14 08:32:33 2012 (r39528) @@ -35,7 +35,7 @@ See Also This document is deliberately not an exhaustive discussion of - SGML, the DTDs listed, and the FreeBSD Documentation Project. For + XML, the DTDs listed, and the FreeBSD Documentation Project. For more information about these, you are encouraged to see the following web sites. @@ -55,20 +55,13 @@ - - SGML + + XML - The - SGML/XML web page, a comprehensive SGML - resource - - - - Gentle - introduction to SGML + W3C's XML page + SGML/XML web page Modified: projects/sgml2xml/en_US.ISO8859-1/books/fdp-primer/sgml-markup/chapter.sgml ============================================================================== --- projects/sgml2xml/en_US.ISO8859-1/books/fdp-primer/sgml-markup/chapter.sgml Thu Sep 13 18:03:11 2012 (r39527) +++ projects/sgml2xml/en_US.ISO8859-1/books/fdp-primer/sgml-markup/chapter.sgml Fri Sep 14 08:32:33 2012 (r39528) @@ -31,8 +31,8 @@ $FreeBSD$ --> - - SGML Markup + + XML Markup This chapter describes the two markup languages you will encounter when you contribute to the FreeBSD documentation @@ -63,46 +63,49 @@ line break (and other processing) when it is encountered. - - HTML + + XHTML - HTML, the HyperText Markup Language, is the markup language + 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 . - HTML is used to markup pages on the FreeBSD web site. It + 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 HTML pages + 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, - and the latest, 4.0 (available in both - strict and loose + 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 HTML DTDs are available from the Ports Collection - in the textproc/html port. + 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 HTML FPIs, depending upon the - version (also known as the level) of HTML that you want to + 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 HTML documents on the FreeBSD web site - comply with the loose version of HTML 4.0. + The majority of XHTML documents on the FreeBSD web site + comply with the transitional version of XHTML 1.0. - PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" + PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" Sectional Elements - An HTML document is normally split into two sections. The + 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 @@ -115,9 +118,9 @@ html element. - Normal HTML Document Structure + Normal XHTML Document Structure - <html> + <html xmlns="http://www.w3.org/1999/xhtml"> <head> <title>The Document's Title</title> </head> @@ -137,7 +140,7 @@ Headings - HTML allows you to denote headings in your document, at + XHTML allows you to denote headings in your document, at up to six different levels. The largest and most prominent heading is @@ -169,7 +172,7 @@ ]]> - Generally, an HTML page should have one first level + Generally, an HXTML 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 @@ -198,7 +201,7 @@ Paragraphs - HTML supports a single paragraph element, + XHTML supports a single paragraph element, p. @@ -493,7 +496,7 @@ Emphasizing Information - You have two levels of emphasis available in HTML, + You have two levels of emphasis available in XHTML, em and strong. em is for a normal level of emphasis and strong indicates stronger @@ -502,7 +505,10 @@ 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. + 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 @@ -516,22 +522,6 @@ </sect3> <sect3> - <title>Bold and Italics - - Because HTML includes presentational markup, you can - also indicate that particular content should be rendered in - bold or italic. The elements are b and - i respectively. - - - <sgmltag>b</sgmltag> and <sgmltag>i</sgmltag> - - This is in bold, while this is - in italics.

]]> - - - - Indicating Fixed-Pitch Text If you have content that should be rendered in a fixed @@ -548,65 +538,13 @@ nik@FreeBSD.org.

]]> - - - Content Size - - You can indicate that content should be shown in a - larger or smaller font. There are three ways of doing - this. - - - - Use big and - small around the content you wish to - change size. These tags can be nested, so - <big><big>This is much - bigger</big></big> is - possible. - - - - Use font with the - size attribute set to - +1 or -1 - respectively. This has the same effect as using - big or small. - However, the use of this approach is deprecated. - - - - Use font with the - size attribute set to a number - between 1 and 7. - The default font size is 3. This - approach is deprecated. - - - - - <sgmltag>big</sgmltag>, <sgmltag>small</sgmltag>, and - <sgmltag>font</sgmltag> - - The following fragments all do the same thing. - - This text is slightly smaller. But - this text is slightly bigger.

- -

This text is slightly smaller. But - this text is slightly bigger.

- -

This text is slightly smaller. But - this text is slightly bigger.

]]> - - Links - Links are also in-line elements. + Links are also inline elements. @@ -644,20 +582,20 @@ anchors that you can link to. Anchors are indicated with a and the - name attribute instead of + id attribute instead of href. - Using <literal><a name="..."></literal> + Using <literal><a id="..."></literal> Use: - This paragraph can be referenced + 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 name of the anchor + link to that document, but include the id of the anchor after a # symbol. @@ -691,7 +629,7 @@ - + DocBook DocBook was originally developed by HaL Computer Systems and @@ -703,7 +641,7 @@ Since 1998 it is maintained by the DocBook Technical Committee. As such, and unlike - LinuxDoc and HTML, DocBook is very heavily oriented towards + LinuxDoc and XHTML, DocBook is very heavily oriented towards markup that describes what something is, rather than describing how it should be presented. @@ -760,7 +698,7 @@ for DocBook customizations, the FPI for the FreeBSD extended DocBook DTD is: - PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" + PUBLIC "-//FreeBSD//DTD DocBook V4.2-Based Extension//EN" @@ -1804,7 +1742,7 @@ This is the file called 'foo2' manual page section. This can be cumbersome to write, and so a series of - general + general entities have been created to make this easier. Each entity takes the form &man.manual-page.manual-section;. @@ -2568,7 +2506,7 @@ IMAGES+= fig3.png You must be careful when you separate your documentation into smaller files (see - ) in + ) in different directories. Suppose you have a book with three chapters, and the Modified: projects/sgml2xml/en_US.ISO8859-1/books/fdp-primer/sgml-primer/chapter.sgml ============================================================================== --- projects/sgml2xml/en_US.ISO8859-1/books/fdp-primer/sgml-primer/chapter.sgml Thu Sep 13 18:03:11 2012 (r39527) +++ projects/sgml2xml/en_US.ISO8859-1/books/fdp-primer/sgml-primer/chapter.sgml Fri Sep 14 08:32:33 2012 (r39528) @@ -31,20 +31,20 @@ $FreeBSD$ --> - - SGML Primer + + XML Primer The majority of FDP documentation is written in applications - of SGML. This chapter explains exactly what that means, how to + of XML. This chapter explains exactly what that means, how to read and understand the source to the documentation, and the sort - of SGML tricks you will see used in the documentation. + of XML tricks you will see used in the documentation. Portions of this section were inspired by Mark Galassi's Get Going With DocBook. - + Overview Way back when, electronic text was simple to deal with. @@ -127,26 +127,28 @@ is a first language that you use to write these other markup languages. A meta markup language. - This is exactly what the Standard Generalized Markup - Language (SGML) is. Many markup languages have been written in - SGML, including the two most used by the FDP, HTML and + This is exactly what the eXtensible Markup + Language (XML) is. Many markup languages have been written in + XML, including the two most used by the FDP, XHTML and DocBook. - Each language definition is more properly called a Document - Type Definition (DTD). The DTD specifies the name of the - elements that can be used, what order they appear in (and + Each language definition is more properly called a grammar, + vocabulary, schema or Document Type Definition (DTD). There + are various languages to specify an XML grammar, for example, + DTD (yes, it also means the specification language itself), + XML Schema (XSD) or RELANG NG. The schema specifies the name + of the elements that can be used, what order they appear in (and whether some markup can be used inside other markup) and related - information. A DTD is sometimes referred to as an - application of SGML. + information. - A DTD is a + A schema is a complete specification of all the elements that are allowed to appear, the order in which they should appear, which elements are mandatory, which are optional, and so - forth. This makes it possible to write an SGML - parser which reads in both the DTD and a - document which claims to conform to the DTD. The parser can - then confirm whether or not all the elements required by the DTD + forth. This makes it possible to write an XML + parser which reads in both the schema and a + document which claims to conform to the schema. The parser can + then confirm whether or not all the elements required by the vocabulary are in the document in the right order, and whether there are any errors in the markup. This is normally referred to as validating the document. @@ -154,27 +156,27 @@ This processing simply confirms that the choice of elements, their ordering, and so on, conforms to that listed - in the DTD. It does not check that you + in the grammar. It does not check that you have used appropriate markup for the content. If you tried to mark up all the filenames in your document as function names, the parser would not flag this as - an error (assuming, of course, that your DTD defines elements + an error (assuming, of course, that your schema defines elements for filenames and functions, and that they are allowed to appear in the same place). It is likely that most of your contributions to the Documentation Project will consist of content marked up in - either HTML or DocBook, rather than alterations to the DTDs. + either XHTML or DocBook, rather than alterations to the schemas. For this reason this book will not touch on how to write a - DTD. + vocabulary. - + Elements, Tags, and Attributes - All the DTDs written in SGML share certain characteristics. - This is hardly surprising, as the philosophy behind SGML will + All the vocabularies written in XML share certain characteristics. + This is hardly surprising, as the philosophy behind XML will inevitably show through. One of the most obvious manifestations of this philosophy is that of content and elements. @@ -201,20 +203,20 @@ character names, and so on. Notice how you can make this differentiation between - different elements of the content without resorting to any SGML + different elements of the content without resorting to any XML terms. It really is surprisingly straightforward. You could do this with a highlighter pen and a printout of the book, using different colors to indicate different chunks of content. Of course, we do not have an electronic highlighter pen, so we need some other way of indicating which element each piece of - content belongs to. In languages written in SGML (HTML, + content belongs to. In languages written in XML (XHTML, DocBook, et al) this is done by means of tags. A tag is used to identify where a particular element starts, and where the element ends. The tag is not part of - the element itself. Because each DTD was normally + the element itself. Because each grammar was normally written to mark up specific types of information, each one will recognize different elements, and will therefore have different names for the tags. @@ -229,10 +231,9 @@ Using an Element (Start and End Tags) - HTML has an element for indicating that the content + XHTML has an element for indicating that the content enclosed by the element is a paragraph, called - p. This element has both start and end - tags. + p. This is a paragraph. It starts with the start tag for the 'p' element, and it will end with the end tag for the 'p' @@ -241,22 +242,35 @@

This is another paragraph. But this one is much shorter.

]]> - Not all elements require an end tag. Some elements have no - content. For example, in HTML you can indicate that you want a - horizontal line to appear in the document. Obviously, this line - has no content, so just the start tag is required for this - element. + Some elements have no + content. For example, in XHTML you can indicate that you want a + horizontal line to appear in the document. + + For such elements, that have no content at all, XML introduced + a shorthand form, which is ccompletely equivalent to the above + form: + + ]]> - Using an Element (Start Tag Only) + Using an Element (Without Content) - HTML has an element for indicating a horizontal rule, + XHTML has an element for indicating a horizontal rule, called hr. This element does not wrap - content, so only has a start tag. + content, so it looks like this. + + One paragraph.

+ +

This is another paragraph. A horizontal rule separates this + from the previous paragraph.

]]> - This is a paragraph.

+ For such elements, that have no content at all, XML introduced + a shorthand form, which is ccompletely equivalent to the above + form: -

+ One paragraph.

This is another paragraph. A horizontal rule separates this from the previous paragraph.

]]> @@ -274,7 +288,7 @@ of the words have been emphasized.

]]> - The DTD will specify the rules detailing which elements can + The grammar will specify the rules detailing which elements can contain other elements, and exactly what they can contain. @@ -288,7 +302,7 @@ element starts and end. When this document (or anyone else knowledgeable about - SGML) refers to the p tag + XML) refers to the p tag they mean the literal text consisting of the three characters <, p, and >. But the phrase the @@ -310,11 +324,11 @@ take the form attribute-name="attribute-value". - In sufficiently recent versions of HTML, the + In XHTML, the p element has an attribute called align, which suggests an alignment (justification) for the paragraph to the program displaying the - HTML. + XHTML. The align attribute can take one of four defined values, left, @@ -333,9 +347,7 @@ Some attributes will only take specific values, such as left or justify. Others - will allow you to enter anything you want. If you need to - include quotes (") within an attribute then - use single quotes around the attribute value. + will allow you to enter anything you want. Single Quotes Around Attributes @@ -343,16 +355,17 @@ I am on the right!

]]> - Sometimes you do not need to use quotes around attribute - values at all. However, the rules for doing this are subtle, - and it is far simpler just to always quote - your attribute values. + XML requires you to quote each attribute value with either + single or double quotes. It is more habitual to use double quotes + but you may use single quotes, as well. Using single quotes is + practical if you want to include double quotes in the attribute + value. The information on attributes, elements, and tags is stored - in SGML catalogs. The various Documentation Project tools use + in XML catalogs. The various Documentation Project tools use these catalog files to validate your work. The tools in textproc/docproj include a - variety of SGML catalog files. The FreeBSD Documentation + variety of XML catalog files. The FreeBSD Documentation Project includes its own set of catalog files. Your tools need to know about both sorts of catalog files. @@ -380,7 +393,7 @@ to substitute the correct directory for your language.) - + <filename>.profile</filename>, for &man.sh.1; and &man.bash.1; Users @@ -415,14 +428,14 @@ setenv SGML_CATALOG_FILES /usr/doc/en_US - Create example.sgml, and enter + Create example.xml, and enter the following text: - + - + - An Example HTML File + An Example XHTML File @@ -436,30 +449,20 @@ setenv SGML_CATALOG_FILES /usr/doc/en_US - Try to validate this file using an SGML parser. + Try to validate this file using an XML parser. Part of textproc/docproj is - the onsgmls - validating - parser. Normally, onsgmls - reads in a document marked up according to an SGML DTD and - returns a copy of the document's Element Structure - Information Set (ESIS, but that is not important right - now). - - However, when onsgmls is given the - parameter, onsgmls - will suppress its normal output, and just print error - messages. This makes it a useful way to check to see if - your document is valid or not. + the xmllint + validating + parser. - Use onsgmls to check that your - document is valid: + Use xmllint in the following way to + check that your document is valid: - &prompt.user; onsgmls -s example.sgml + &prompt.user; xmllint --valid --noout example.xml - As you will see, onsgmls returns + As you will see, xmllint returns without displaying any output. This means that your document validated successfully. @@ -470,91 +473,18 @@ setenv SGML_CATALOG_FILES /usr/doc/en_US /title tags, and re-run the validation. - &prompt.user; onsgmls -s example.sgml -onsgmls:example.sgml:5:4:E: character data is not allowed here -onsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished - - The error output from onsgmls is - organized into colon-separated groups, or columns. - - - - - - Column - Meaning - - - - - - 1 - The name of the program generating the error. - This will always be - onsgmls. - - - - 2 - The name of the file that contains the - error. - - - - 3 - Line number where the error appears. - - - - 4 - Column number where the error - appears. - - - - 5 - - A one letter code indicating the nature of - the message. I indicates an - informational message, W is for - warnings, and E is for errors - It is not always the fifth column - either. onsgmls -sv - displays onsgmls:I: "OpenSP" version - "1.5.2" (depending on the - installed version). As you can see, this is - an informational message., - and X is for - cross-references. As you can see, these messages - are errors. - - - - 6 - The text of the message. - - - - - - Simply omitting the title tags has - generated 2 different errors. - - The first error indicates that content (in this case, - characters, rather than the start tag for an element) has - occurred where the SGML parser was expecting something - else. In this case, the parser was expecting to see one - of the start tags for elements that are valid inside - head (such as - title). - - The second error is because head - elements must contain a - title element. Because it does not - onsgmls considers that the element has - not been properly finished. However, the closing tag - indicates that the element has been closed before it has - been finished. + &prompt.user; xmllint --valid --noout example.xml +example.xml:5: element head: validity error : Element head content does not follow the DTD, expecting ((script | style | meta | link | object | isindex)* , ((title , (script | style | meta | link | object | isindex)* , (base , (script | style | meta | link | object | isindex)*)?) | (base , (script | style | meta | link | object | isindex)* , title , (script | style | meta | link | object | isindex)*))), got () + + This line tells you that the validation error comes from + the fifth line of the + example.xml file and that the + content of the head is the part, which + does not follow the rules described by the XHTML grammar. + + Below this line xmllint will show you + the line where the error has been found and will also mark the + exact character position with a ^ sign. @@ -565,21 +495,20 @@ onsgmls:example.sgml:6:8:E: end tag for - + The DOCTYPE Declaration - The beginning of each document that you write must specify - the name of the DTD that the document conforms to. This is so - that SGML parsers can determine the DTD and ensure that the - document does conform to it. - - This information is generally expressed on one line, in the - DOCTYPE declaration. + The beginning of each document that you write may specify + the name of the DTD that the document conforms to in case you use + the DTD specification language. Other specification languages, like + XML Schema and RELAX NG are not referred in the source document. + This DOCTYPE declaration serves the XML parsers so that they can + determine the DTD and ensure that the document does conform to it. A typical declaration for a document written to conform with - version 4.0 of the HTML DTD looks like this: + version 1.0 of the XHTML DTD looks like this: - ]]> + ]]> That line contains a number of different components. @@ -589,7 +518,7 @@ onsgmls:example.sgml:6:8:E: end tag for Is the indicator that indicates - that this is an SGML declaration. This line is declaring + that this is an XML declaration. This line is declaring the document type. @@ -598,7 +527,7 @@ onsgmls:example.sgml:6:8:E: end tag for DOCTYPE - Shows that this is an SGML declaration for the + Shows that this is an XML declaration for the document type. @@ -608,29 +537,36 @@ onsgmls:example.sgml:6:8:E: end tag for Names the first - element that + element that will appear in the document. - PUBLIC "-//W3C//DTD HTML - 4.0//EN" + PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" Lists the Formal Public Identifier (FPI) Formal Public Identifier - for the DTD that this document conforms to. Your SGML + for the DTD that this document conforms to. Your XML parser will use this to find the correct DTD when processing this document. PUBLIC is not a part of the FPI, - but indicates to the SGML processor how to find the DTD - referenced in the FPI. Other ways of telling the SGML + but indicates to the XML processor how to find the DTD + referenced in the FPI. Other ways of telling the XML parser how to find the DTD are shown later. + linkend="xml-primer-fpi-alternatives">later. + + + + + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" + + + A local filename or an URL to find the DTD. @@ -651,7 +587,7 @@ onsgmls:example.sgml:6:8:E: end tag for You do not need to know this, but it is useful - background, and might help you debug problems when your SGML + background, and might help you debug problems when your XML processor can not locate the DTD you are using. @@ -673,7 +609,8 @@ onsgmls:example.sgml:6:8:E: end tag for Symbols//EN" lists ISO 8879:1986 as being the owner for the set of entities for Greek symbols. ISO 8879:1986 is - the ISO number for the SGML standard. + the ISO number for the SGML standard, the predecessor + (and a superset) of XML. Otherwise, this string will either look like -//Owner @@ -715,7 +652,7 @@ onsgmls:example.sgml:6:8:E: end tag for used only for DTD files, ELEMENT is usually used for DTD fragments that contain only entity or element declarations. TEXT is - used for SGML content (text and tags). + used for XML content (text and tags). @@ -726,7 +663,7 @@ onsgmls:example.sgml:6:8:E: end tag for Any description you want to supply for the contents of this file. This may include version numbers or any short text that is meaningful to you and unique for the - SGML system. + XML system. @@ -745,7 +682,7 @@ onsgmls:example.sgml:6:8:E: end tag for <filename>catalog</filename> Files If you use the syntax above and process this document - using an SGML processor, the processor will need to have + using an XML processor, the processor will need to have some way of turning the FPI into the name of the file on your computer that contains the DTD. @@ -754,17 +691,19 @@ onsgmls:example.sgml:6:8:E: end tag for contains lines that map FPIs to filenames. For example, if the catalog file contained the line: - PUBLIC "-//W3C//DTD HTML 4.0//EN" "4.0/strict.dtd" + + + PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "1.0/transitional.dtd" - The SGML processor would know to look up the DTD from - strict.dtd in the - 4.0 subdirectory of whichever directory + The XML processor would know to look up the DTD from + transitional.dtd in the + 1.0 subdirectory of whichever directory held the catalog file that contained that line. Look at the contents of - /usr/local/share/sgml/html/catalog. - This is the catalog file for the HTML DTDs that will have + /usr/local/share/xml/dtd/xhtml/catalog.xml. + This is the catalog file for the XHTML DTDs that will have been installed as part of the textproc/docproj port. @@ -773,7 +712,7 @@ onsgmls:example.sgml:6:8:E: end tag for <envar>SGML_CATALOG_FILES</envar> In order to locate a catalog file, *** DIFF OUTPUT TRUNCATED AT 1000 LINES ***