From 5bbb3c8791ae81f6c45608df525932b0e74b367a Mon Sep 17 00:00:00 2001 From: Warren Block Date: Fri, 12 Jul 2013 03:21:55 +0000 Subject: [PATCH] Edit for clarity and style. Try to persuade the hippo and the pogo stick that they are not good for each other. --- .../books/fdp-primer/xml-primer/chapter.xml | 471 +++++++++--------- 1 file changed, 225 insertions(+), 246 deletions(-) diff --git a/en_US.ISO8859-1/books/fdp-primer/xml-primer/chapter.xml b/en_US.ISO8859-1/books/fdp-primer/xml-primer/chapter.xml index 53098b1911..cf58ff3e2d 100644 --- a/en_US.ISO8859-1/books/fdp-primer/xml-primer/chapter.xml +++ b/en_US.ISO8859-1/books/fdp-primer/xml-primer/chapter.xml @@ -34,10 +34,10 @@ XML Primer - The majority of FDP documentation is written in applications - of XML. This chapter explains exactly what that means, how to - read and understand the source to the documentation, and the sort - of XML tricks you will see used in the documentation. + Most FDP documentation is written with markup languages based + on XML. This chapter explains what that means, how to + read and understand the documentation source, and the + XML techniques used. Portions of this section were inspired by Mark Galassi's Overview - Way back when, electronic text was simple to deal with. - Admittedly, you had to know which character set your document - was written in (ASCII, EBCDIC, or one of a number of others) but + In the original days of computers, electronic text was simple. + + There were a few character sets like ASCII or EBCDIC, but that was about it. Text was text, and what you saw really was what you got. No frills, no formatting, no intelligence. - Inevitably, this was not enough. Once you have text in a - machine-usable format, you expect machines to be able to use it - and manipulate it intelligently. You would like to indicate + Inevitably, this was not enough. When text is in a + machine-usable format, machines are expected to be able to use + and manipulate it intelligently. Authors want to indicate that certain phrases should be emphasized, or added to a - glossary, or be hyperlinks. You might want filenames to be + glossary, or made into hyperlinks. Filenames could be shown in a typewriter style font for viewing on screen, but as italics when printed, or any of a myriad of other options for presentation. It was once hoped that Artificial Intelligence (AI) would - make this easy. Your computer would read in the document and + make this easy. The computer would read the document and automatically identify key phrases, filenames, text that the reader should type in, examples, and more. Unfortunately, real - life has not happened quite like that, and our computers require - some assistance before they can meaningfully process our + life has not happened quite like that, and computers still require + assistance before they can meaningfully process text. More precisely, they need help identifying what is what. - Let's look at this text: + Consider this text:
To remove /tmp/foo use @@ -100,42 +100,40 @@ document must typically be done by a person—after all, if computers could recognize the text sufficiently well to add the markup then there would be no need to add it in the first place. - This increases the cost (i.e., the effort + This increases the cost (the effort required) to create the document. The previous example is actually represented in this document like this: - To remove /tmp/foo use &man.rm.1;. + paraTo remove filename/tmp/foofilename use &man.rm.1;.para -&prompt.user; rm /tmp/foo]]> +screen&prompt.user; userinputrm /tmp/foouserinputscreen - As you can see, the markup is clearly separate from the + The markup is clearly separate from the content. - Obviously, if you are going to use markup you need to define - what your markup means, and how it should be interpreted. You - will need a markup language that you can follow when marking up - your documents. + Markup languages define what + what the markup means and how it should be interpreted. Of course, one markup language might not be enough. A markup language for technical documentation has very different - requirements than a markup language that was to be used for + requirements than a markup language that is intended for cookery recipes. This, in turn, would be very different from a - markup language used to describe poetry. What you really need - is a first language that you use to write these other markup + markup language used to describe poetry. What is really needed + is a first language used to write these other markup languages. A meta markup language. This is exactly what the eXtensible Markup - Language (XML) is. Many markup languages have been written in - XML, including the two most used by the FDP, XHTML and + Language (XML) is. Many markup languages have been written in + XML, including the two most used by the FDP, XHTML and DocBook. Each language definition is more properly called a grammar, - vocabulary, schema or Document Type Definition (DTD). There - are various languages to specify an XML grammar, for example, - DTD (yes, it also means the specification language itself), - XML Schema (XSD) or RELANG NG. The schema specifies the name + 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. @@ -144,7 +142,7 @@ complete specification of all the elements that are allowed to appear, the order in which they should appear, which elements are mandatory, which are optional, and so - forth. This makes it possible to write an XML + 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 @@ -155,34 +153,34 @@ This processing simply confirms that the choice of elements, their ordering, and so on, conforms to that listed - 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 schema defines elements + in the grammar. It does not check whether + appropriate markup has been used for the + content. If all the filenames in a + document were marked up as function names, the parser would not flag this as + an error (assuming, of course, that the schema defines elements for filenames and functions, and that they are allowed to appear in the same place). - It is likely that most of your contributions to the - Documentation Project will consist of content marked up in - either XHTML or DocBook, rather than alterations to the schemas. - For this reason this book will not touch on how to write a + It is likely that most contributions to the + Documentation Project will be content marked up in + either XHTML or DocBook, rather than alterations to the schemas. + For this reason, this book will not touch on how to write a vocabulary. Elements, Tags, and Attributes - All the vocabularies written in XML share certain characteristics. - This is hardly surprising, as the philosophy behind XML will + 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. - Your documentation (whether it is a single web page, or a - lengthy book) is considered to consist of content. This content - is then divided (and further subdivided) into elements. The + Documentation, whether it is a single web page, or a + lengthy book, is considered to consist of content. This content + is then divided and further subdivided into elements. The purpose of adding markup is to name and identify the boundaries of these elements for further processing. @@ -195,21 +193,21 @@ that was direct speech, or the name of a character in the story. - You might like to think of this as chunking - content. At the very top level you have one chunk, the book. - Look a little deeper, and you have more chunks, the individual + It may be helpful to think of this as chunking + content. At the very top level is one chunk, the book. + Look a little deeper, and there are more chunks, the individual chapters. These are chunked further into paragraphs, footnotes, character names, and so on. - Notice how you can make this differentiation between - 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 + Notice how this differentiation between + different elements of the content can be made without resorting to any XML + terms. It really is surprisingly straightforward. This could be done + with a highlighter pen and a printout of the book, using different colors to indicate different chunks of content. Of course, we do not have an electronic highlighter pen, so we need some other way of indicating which element each piece of - content belongs to. In languages written in XML (XHTML, + content belongs to. In languages written in XML (XHTML, DocBook, et al) this is done by means of tags. @@ -223,59 +221,54 @@ For an element called element-name the start tag will normally look like - element-name. The + element-name. The corresponding closing tag for this element is - /element-name. + element-name. Using an Element (Start and End Tags) - XHTML 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 is a paragraph. It starts with the start tag for + pThis is a paragraph. It starts with the start tag for the 'p' element, and it will end with the end tag for the 'p' - element.

+ element.p -

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

]]> +pThis is another paragraph. But this one is much shorter.p 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: - - ]]> + content. For example, in XHTML, a + horizontal line can be included in the document. + For these empty elements, XML introduced + a shorthand form that is completely equivalent to the two-tag + version: - Using an Element (Without Content) + Using an Element Without Content - XHTML 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 it looks like this. + content, so it looks like this: - One paragraph.

-
+ pOne paragraph.p +hrhr -

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

]]> +pThis is another paragraph. A horizontal rule separates this + from the previous paragraph.p - For such elements, that have no content at all, XML introduced - a shorthand form, which is ccompletely equivalent to the above - form: + The shorthand version consists of a single tag: - One paragraph.

-
+ pOne paragraph.p +hr -

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

]]> +pThis is another paragraph. A horizontal rule separates this + from the previous paragraph.p - If it is not obvious by now, elements can contain other + As shown above, elements can contain other elements. In the book example earlier, the book element contained all the chapter elements, which in turn contained all the paragraph elements, and so on. @@ -283,11 +276,11 @@ Elements within Elements; <sgmltag>em</sgmltag> - This is a simple paragraph where some - of the words have been emphasized.

]]> + pThis is a simple emparagraphem where some + of the emwordsem have been ememphasizedem.p - The grammar will specify the rules detailing which elements can + The grammar consists of rules that describe which elements can contain other elements, and exactly what they can contain. @@ -298,10 +291,10 @@ An element is a conceptual part of your document. An element has a defined start and end. The tags mark where the - element starts and end. + element starts and ends. When this document (or anyone else knowledgeable about - XML) 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 @@ -323,13 +316,13 @@ take the form attribute-name="attribute-value". - In XHTML, the + In XHTML, the p element has an attribute called - align, which suggests an alignment + align, which suggests an alignment (justification) for the paragraph to the program displaying the - XHTML. + XHTML. - The align attribute can take one of four + The align attribute can take one of four defined values, left, center, right and justify. If the attribute is not specified @@ -338,59 +331,57 @@ Using An Element with An Attribute - The inclusion of the align attribute - on this paragraph was superfluous, since the default is left.

+ p align="left"The inclusion of the align attribute + on this paragraph was superfluous, since the default is left.p -

This may appear in the center.

]]> +p align="center"This may appear in the center.p - Some attributes will only take specific values, such as + Some attributes only take specific values, such as left or justify. Others - will allow you to enter anything you want. + allow any value. Single Quotes Around Attributes - I am on the right!

]]> + p align='right'I am on the right!p - 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. + Attribute values in XML must be enclosed + in either single or double quotes. Double quotes are + traditional. Single quotes are useful when the attribute + value contains double quotes. - The information on attributes, elements, and tags is stored - 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 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. + Information about attributes, elements, and tags is stored + in catalog files. The Documentation Project uses standard + DocBook catalogs and includes additional catalogs for + &os;-specific features. Paths to the catalog files are defined + in an environment variable so they can be found by the document + build tools. - For You to Do… + To Do… - In order to run the examples in this document you will - need to install some software on your system and ensure that - an environment variable is set correctly. + Before running the examples in this document, + application software must be installed and the catalog + environment variable configured. - Download and install + Install textproc/docproj from - the FreeBSD ports system. This is a - meta-port that should download and - install all of the programs and supporting files that are - used by the Documentation Project. + the &os; Ports Collection. This is a + meta-port that downloads and + installs the standard programs and supporting files needed + by the Documentation Project. - Add lines to your shell startup files to set - SGML_CATALOG_FILES. (If you are not working - on the English version of the documentation, you will want - to substitute the correct directory for your - language.) + Add lines to the shell startup files to set + SGML_CATALOG_FILES. When working on non-English + versions of the documentation, replace + en_US.ISO8859-1 with the appropriate directory for the + target language. <filename>.profile</filename>, for &man.sh.1; and @@ -402,7 +393,7 @@ SGML_CATALOG_FILES=${SGML_ROOT}/docbook/4.1/catalog:$SGML_CATALOG_FILES SGML_CATALOG_FILES=${SGML_ROOT}/html/catalog:$SGML_CATALOG_FILES SGML_CATALOG_FILES=${SGML_ROOT}/iso8879/catalog:$SGML_CATALOG_FILES SGML_CATALOG_FILES=/usr/doc/share/xml/catalog:$SGML_CATALOG_FILES -SGML_CATALOG_FILES=/usr/doc/en_US.ISO8859-1/share/xml/catalog:$SGML_CATALOG_FILES +SGML_CATALOG_FILES=/usr/doc/<replaceable>en_US.ISO8859-1</replaceable>/share/xml/catalog:$SGML_CATALOG_FILES export SGML_CATALOG_FILES</programlisting> </example> @@ -416,11 +407,11 @@ setenv SGML_CATALOG_FILES ${SGML_ROOT}/docbook/4.1/catalog:$SGML_CATALOG_FILES setenv SGML_CATALOG_FILES ${SGML_ROOT}/html/catalog:$SGML_CATALOG_FILES setenv SGML_CATALOG_FILES ${SGML_ROOT}/iso8879/catalog:$SGML_CATALOG_FILES setenv SGML_CATALOG_FILES /usr/doc/share/xml/catalog:$SGML_CATALOG_FILES -setenv SGML_CATALOG_FILES /usr/doc/en_US.ISO8859-1/share/xml/catalog:$SGML_CATALOG_FILES</programlisting> +setenv SGML_CATALOG_FILES /usr/doc/<replaceable>en_US.ISO8859-1</replaceable>/share/xml/catalog:$SGML_CATALOG_FILES</programlisting> </example> - <para>Then either log out, and log back in again, or run - those commands from the command line to set the variable + <para>After making these changes, either log out and log back in again, or run + the commands from the command line to set the variable values.</para> </step> </procedure> @@ -428,67 +419,65 @@ setenv SGML_CATALOG_FILES /usr/doc/en_US.ISO8859-1/share/xml/catalog:$SGML_CATAL <procedure> <step> <para>Create <filename>example.xml</filename>, and enter - the following text:</para> + this text:</para> - <programlisting><![CDATA[<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + <programlisting><sgmltag class="starttag">!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"</sgmltag> -<html xmlns="http://www.w3.org/1999/xhtml"> - <head> - <title>An Example XHTML File - +html xmlns="http://www.w3.org/1999/xhtml" + head + titleAn Example XHTML Filetitle + head - -

This is a paragraph containing some text.

+ body + pThis is a paragraph containing some text.p -

This paragraph contains some more text.

+ pThis paragraph contains some more text.p -

This paragraph might be right-justified.

- -]]> + p align="right"This paragraph might be right-justified.p + body +html - Try to validate this file using an XML parser. + Try to validate this file using an XML parser. - Part of - textproc/docproj is + textproc/docproj includes the xmllint validating parser. - Use xmllint in the following way to - check that your document is valid: + Use xmllint to + validate the document: &prompt.user; xmllint --valid --noout example.xml - As you will see, xmllint returns - without displaying any output. This means that your + xmllint returns + without displaying any output, showing that the document validated successfully. See what happens when required elements are omitted. - Try removing the title and - /title tags, and re-run the + Delete the line with the title and + /title tags, and re-run the validation. &prompt.user; xmllint --valid --noout example.xml example.xml:5: element head: validity error : Element head content does not follow the DTD, expecting ((script | style | meta | link | object | isindex)* , ((title , (script | style | meta | link | object | isindex)* , (base , (script | style | meta | link | object | isindex)*)?) | (base , (script | style | meta | link | object | isindex)* , title , (script | style | meta | link | object | isindex)*))), got () - This line tells you that the validation error comes from + This shows that the validation error comes from the fifth line of the example.xml file and that the - content of the head is the part, which - does not follow the rules described by the XHTML grammar. + content of the head is the part which + does not follow the rules of 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. + Then xmllint shows + the line where the error was found and marks the + exact character position with a ^ sign. - Put the title element back - in. + Replace the title element. @@ -497,17 +486,15 @@ example.xml:5: element head: validity error : Element head content does not foll 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. + The beginning of each document can specify + the name of the DTD to which the document conforms. + This DOCTYPE declaration is used by XML parsers to + identify the DTD and ensure that the document does conform to it. A typical declaration for a document written to conform with - version 1.0 of the XHTML DTD looks like this: + version 1.0 of the XHTML DTD looks like this: - ]]> + !DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" That line contains a number of different components. @@ -516,9 +503,8 @@ example.xml:5: element head: validity error : Element head content does not foll <! - Is the indicator that indicates - that this is an XML declaration. This line is declaring - the document type. + The indicator shows + this is an XML declaration. @@ -526,7 +512,7 @@ example.xml:5: element head: validity error : Element head content does not foll DOCTYPE - Shows that this is an XML declaration for the + Shows that this is an XML declaration of the document type. @@ -545,18 +531,18 @@ example.xml:5: element head: validity error : Element head content does not foll PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" - Lists the Formal Public Identifier (FPI) + Lists the Formal Public Identifier (FPI) Formal Public Identifier - for the DTD that this document conforms to. Your XML - parser will use this to find the correct DTD when + for the DTD to which this document conforms. The XML + parser uses this to find the correct DTD when processing this document. - PUBLIC is not a part of the FPI, - but indicates to the XML processor how to find the DTD - referenced in the FPI. Other ways of telling the XML - parser how to find the DTD are shown PUBLIC is not a part of the FPI, + but indicates to the XML processor how to find the DTD + referenced in the FPI. Other ways of telling the XML + parser how to find the DTD are shown later. @@ -565,7 +551,7 @@ example.xml:5: element head: validity error : Element head content does not foll "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" - A local filename or an URL to find the DTD. + A local filename or a URL to find the DTD. @@ -573,25 +559,24 @@ example.xml:5: element head: validity error : Element head content does not foll > - Returns to the document. + Ends the declaration and returns to the document. - Formal Public Identifiers (FPIs) + <title>Formal Public Identifiers (<acronym>FPI</acronym>s) <indexterm significance="preferred"> <primary>Formal Public Identifier</primary> </indexterm> - You do not need to know this, but it is useful - background, and might help you debug problems when your XML - processor can not locate the DTD you are using. + It is not necessary to know this, but it is useful + background, and might help debug problems when the XML + processor can not locate the DTD. - FPIs must follow a specific syntax. This syntax is as - follows: + FPIs must follow a specific syntax: "Owner//Keyword Description//Language" @@ -600,16 +585,16 @@ example.xml:5: element head: validity error : Element head content does not foll Owner - This indicates the owner of the FPI. + The owner of the FPI. - If this string starts with ISO then - this is an ISO owned FPI. For example, the FPI + The beginning of the string identifies the owner + of the FPI. For example, the FPI "ISO 8879:1986//ENTITIES Greek Symbols//EN" lists ISO 8879:1986 as being the owner for - the set of entities for Greek symbols. ISO 8879:1986 is - the ISO number for the SGML standard, the predecessor - (and a superset) of XML. + the set of entities for Greek symbols. ISO 8879:1986 is + the International Organization for Standardization (ISO) number for the SGML standard, the predecessor + (and a superset) of XML. Otherwise, this string will either look like -//Owner @@ -620,21 +605,21 @@ example.xml:5: element head: validity error : Element head content does not foll If the string starts with - then the owner information is unregistered, with a - + it identifies it as being + + identifying it as registered. - ISO 9070:1991 defines how registered names are - generated; it might be derived from the number of an ISO - publication, an ISBN code, or an organization code - assigned according to ISO 6523. In addition, a + ISO 9070:1991 defines how registered names are + generated. It might be derived from the number of an ISO + publication, an ISBN code, or an organization code + assigned according to ISO 6523. Additionally, a registration authority could be created in order to - assign registered names. The ISO council delegated this + assign registered names. The ISO council delegated this to the American National Standards Institute - (ANSI). + (ANSI). - Because the FreeBSD Project has not been registered - the owner string is -//FreeBSD. And - as you can see, the W3C are not a registered owner + Because the &os; Project has not been registered, + the owner string is -//&os;. As + seen in the example, the W3C are not a registered owner either. @@ -648,10 +633,10 @@ example.xml:5: element head: validity error : Element head content does not foll keywords are DTD, ELEMENT, ENTITIES, and TEXT. DTD is - used only for DTD files, ELEMENT is - usually used for DTD fragments that contain only entity + used only for DTD files, ELEMENT is + usually used for DTD fragments that contain only entity or element declarations. TEXT is - used for XML content (text and tags). + used for XML content (text and tags). @@ -659,10 +644,10 @@ example.xml:5: element head: validity error : Element head content does not foll Description - Any description you want to supply for the contents + Any description can be given for the contents of this file. This may include version numbers or any - short text that is meaningful to you and unique for the - XML system. + short text that is meaningful and unique for the + XML system. @@ -670,7 +655,7 @@ example.xml:5: element head: validity error : Element head content does not foll Language - This is an ISO two-character code that identifies + An ISO two-character code that identifies the native language for the file. EN is used for English. @@ -680,48 +665,45 @@ example.xml:5: element head: validity error : Element head content does not foll <filename>catalog</filename> Files - If you use the syntax above and process this document - 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. - - In order to do this it can use a catalog file. A + With the syntax above, + an XML processor needs to have + some way of turning the FPI into the name of the file + containing the DTD. A catalog file (typically called catalog) - contains lines that map FPIs to filenames. For example, if + contains lines that map FPIs to filenames. For example, if the catalog file contained the line: PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "1.0/transitional.dtd" - The XML processor 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. + The XML processor knows that the DTD is + called transitional.dtd in the + 1.0 subdirectory of the directory that + held the catalog file. - Look at the contents of + Examine the contents of /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 XHTML DTDs that was + installed as part of the textproc/docproj port. <envar>SGML_CATALOG_FILES</envar> - In order to locate a catalog file, - your XML processor will need to know where to look. Many - of them feature command line parameters for specifying the + To locate a catalog file, + the XML processor must know where to look. Many + feature command line parameters for specifying the path to one or more catalogs. - In addition, you can set - SGML_CATALOG_FILES to point to the files. - This environment variable should consist of a + In addition, + SGML_CATALOG_FILES can be set to point to the files. + This environment variable consists of a colon-separated list of catalog files (including their full path). - Typically, you will want to include the following + Typically, the list includes these files: @@ -742,33 +724,30 @@ example.xml:5: element head: validity error : Element head content does not foll - You should already - have done this. + This was done earlier. - Alternatives to FPIs + Alternatives to <acronym>FPI</acronym>s - Instead of using an FPI to indicate the DTD that the - document conforms to (and therefore, which file on the system - contains the DTD) you can explicitly specify the name of the - file. + Instead of using an FPI to indicate the DTD to which + the document conforms (and therefore, which file on the system + contains the DTD), the filename can be explicitly specified. - The syntax for this is slightly different: + The syntax is slightly different: - ]]> + !DOCTYPE html SYSTEM "/path/to/file.dtd" The SYSTEM keyword indicates that the - XML processor should locate the DTD in a system specific - fashion. This typically (but not always) means the DTD will + XML processor should locate the DTD in a system specific + fashion. This typically (but not always) means the DTD will be provided as a filename. - Using FPIs is preferred for reasons of portability. You - do not want to have to ship a copy of the DTD around with your - document, and if you used the SYSTEM - identifier then everyone would need to keep their DTDs in the - same place. + Using FPIs is preferred for reasons of portability. + If the SYSTEM + identifier is used, then the DTD must be provided and kept in the same location + for everyone.