aboutsummaryrefslogtreecommitdiff
path: root/en_US.ISO_8859-1/books/fdp-primer/sgml-primer/chapter.sgml
diff options
context:
space:
mode:
authorNik Clayton <nik@FreeBSD.org>1999-04-29 20:07:56 +0000
committerNik Clayton <nik@FreeBSD.org>1999-04-29 20:07:56 +0000
commit2e9532f58851dcde8223f2adbd1792cd4b679419 (patch)
tree9b116b44a140f1dc7c232668b30a21b0a0b5b891 /en_US.ISO_8859-1/books/fdp-primer/sgml-primer/chapter.sgml
parentd3d908e6058daa5e54dacf86930cc387b529bbf8 (diff)
downloaddoc-2e9532f58851dcde8223f2adbd1792cd4b679419.tar.gz
doc-2e9532f58851dcde8223f2adbd1792cd4b679419.zip
Fix typos, rewrite a couple of paragraphs, add some new paragraphs to be
a bit cleaer on some things.
Notes
Notes: svn path=/head/; revision=4776
Diffstat (limited to 'en_US.ISO_8859-1/books/fdp-primer/sgml-primer/chapter.sgml')
-rw-r--r--en_US.ISO_8859-1/books/fdp-primer/sgml-primer/chapter.sgml124
1 files changed, 71 insertions, 53 deletions
diff --git a/en_US.ISO_8859-1/books/fdp-primer/sgml-primer/chapter.sgml b/en_US.ISO_8859-1/books/fdp-primer/sgml-primer/chapter.sgml
index c25bacf1f1..f181ce5dc9 100644
--- a/en_US.ISO_8859-1/books/fdp-primer/sgml-primer/chapter.sgml
+++ b/en_US.ISO_8859-1/books/fdp-primer/sgml-primer/chapter.sgml
@@ -31,10 +31,10 @@
<chapter id="sgml-primer">
<title>SGML Primer</title>
- <para>The Documentation Project makes heavy use of the Standard Generalized
- Markup Language (SGML). This chapter describes what SGML is, how to read
- and understand markup, and some of the SGML tricks you will see used in
- the FAQ, Handbook, and website.</para>
+ <para>The majority of FDP documentation is written in applications of
+ SGML. 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.</para>
<para>Portions of this section were inspired by Mark Galassi's <ulink
url="http://nis-www.lanl.gov/~rosalia/mydocs/docbook-intro/docbook-intro.html">Get Going With DocBook</ulink>.</para>
@@ -49,7 +49,7 @@
formatting, no intelligence.</para>
<para>Inevitably, this was not enough. Once you have text in a
- machine-usable format, you expect machines to be able to use it, and
+ machine-usable format, you expect machines to be able to use it and
manipulate it intelligently. You would like to indicate that certain
phrases should be emphasised, or added to a glossary, or be hyperlinks.
You might want filenames to be shown in a &ldquo;typewriter&rdquo; style
@@ -57,10 +57,10 @@
or any of a myriad of other options for presentation.</para>
<para>It was once hoped that Artificial Intelligence (AI) would make this
- easy. Your computer would read in the document, and automatically
+ easy. Your computer would read in 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 the can
+ like that, and our computers require some assistance before they can
meaningfully process our text.</para>
<para>More precisely, they need help identifying what is what. You or I
@@ -69,7 +69,7 @@
<blockquote>
<para>To remove <filename>/tmp/foo</filename> use &man.rm.1;.</para>
- <para><command>rm /tmp/foo</command></para>
+ <screen>&prompt.user; <command>rm /tmp/foo</command></screen>
</blockquote>
and easily see which parts are filenames, which are commands to be typed
@@ -83,7 +83,7 @@
in the document, distinguished from the document's content in some way,
so that programs that process the document can read the markup and use
it when making decisions about the document. Editors can hide the
- markup from the user, so they are not distracted by it.</para>
+ markup from the user, so the user is not distracted by it.</para>
<para>The extra information stored in the markup <emphasis>adds
value</emphasis> to the document. Adding the markup to the document
@@ -107,30 +107,32 @@
your markup means, and how it should be interpreted. You will need a
markup language that you can follow when marking up your
documents.</para>
-
- <para>SGML is <emphasis>not</emphasis> a markup langugage. Instead, SGML
- is <emphasis>the language in which you write markup
- languages</emphasis>. There have been many markup languages written
- using SGML. HTML and DocBook are two of these.</para>
-
- <para>This is an important point to understand. Most of the time you are
- not writing SGML documents. Instead, you are writing documents in a
- particular markup language. The definition of the markup language you
- are using is written in SGML.</para>
-
- <para>Each language definition (which is written in SGML) 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 whether
- some markup can be used inside other markup) and related
- information.</para>
+
+ <para>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 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 languages. A <emphasis>meta markup
+ language</emphasis>.</para>
+
+ <para>This is exactly what the Standard Generalised Markup Language (SGML)
+ is. Many markup languages have been written in SGML, including the two
+ most used by the FDP, HTML and DocBook.</para>
+
+ <para>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 whether some markup can be used
+ inside other markup) and related information. A DTD is sometimes
+ referred to as an <emphasis>application</emphasis> of SGML.</para>
<para id="sgml-primer-validating">A DTD is a <emphasis>complete</emphasis>
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 a
- <emphasis>parser</emphasis> which reads in 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 are in the document in the
+ optional, and so forth. This makes it possible to write an SGML
+ <emphasis>parser</emphasis> 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 are in the document in the
right order, and whether there are any errors in the markup. This is
normally referred to as <quote>validating the document</quote>.</para>
@@ -155,7 +157,7 @@
<title>Elements, tags, and attributes</title>
<para>All the DTDs written in SGML share certain characteristics. This is
- hardly surprising, as the philisophy behind SGML will inevitably show
+ hardly surprising, as the philosophy behind SGML will inevitably show
through. One of the most obvious manifestations of this philisophy is
that of <emphasis>content</emphasis> and
<emphasis>elements</emphasis>.</para>
@@ -184,15 +186,15 @@
elements of the content without resorting to any SGML terms. It really
is surprisingly straightforward. You could do this with a highlighter
pen and a printout of the book, using different colours to indicate
- different types of content.</para>
+ different chunks of content.</para>
- <para>Of course, we don't have an electronic highlighter pen, so we need
+ <para>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, DocBook, et al) this is done by
means of <emphasis>tags</emphasis>.</para>
<para>A tag is used to identify where a particular element starts, and
- where the ends. <emphasis>The tag is not part of the element
+ where the element ends. <emphasis>The tag is not part of the element
itself</emphasis>. Because each DTD was normally written to mark up
specific types of information, each one will recognise different
elements, and will therefore have different names for the tags.</para>
@@ -516,13 +518,13 @@ nsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished</screen>
<para>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 the
+ can determine the DTD and ensure that the document does conform to
it.</para>
<para>This information is generally expressed on one line, in the DOCTYPE
declaration.</para>
- <para>A typical declaration for document written to conform with version
+ <para>A typical declaration for a document written to conform with version
4.0 of the HTML DTD looks like this;</para>
<programlisting>
@@ -895,17 +897,21 @@ PUBLIC "-//W3C//DTD HTML 4.0//EN" "4.0/strict.dtd"</programlisting>
<sect1>
<title>Entities</title>
- <para>Entities are an SGML term. You might feel more comfortable thinking
- of them as variables. There are two types of entity in SGML, general
- entities and parameter entities.</para>
+ <para>Entities are a mechanism for assigning names to chunks of
+ content. As an SGML parser processes your document, any entities
+ it finds are replaced by the content of the entity.</para>
+
+ <para>This is a good way to have re-usable, easily changeable chunks
+ of content in your SGML documents. It is also the only way to
+ include one marked up file inside another using SGML.</para>
+
+ <para>There are two types of entities which can be used in two
+ different situations; <emphasis>general entities</emphasis> and
+ <emphasis>parameter entities</emphasis>.</para>
<sect2 id="general-entities">
<title>General Entities</title>
- <para>General entities are a way of assigning names to chunks of text,
- and reusing that text (which may contain markup) throughout your
- document.</para>
-
<para>You can not use general entities in an SGML context (although you
define them in one). They can only be used in your document. Contrast
this with <link linkend="parameter-entities">parameter
@@ -928,11 +934,11 @@ PUBLIC "-//W3C//DTD HTML 4.0//EN" "4.0/strict.dtd"</programlisting>
document.</para>
<para>You can also use general entities to enter characters that you
- could not normally include in an SGML document. For example, &lt; and
- &amp; can not normally appear in an SGML document. Normally, when the
- SGML processor sees a &lt; symbol it assumes that a tag (either a start
- tag or an end tag) is about to appear, and when it sees a &amp; symbol
- it assumes the next text will be the name of an entity.</para>
+ could not otherwise include in an SGML document. For example, &lt;
+ and &amp; can not normally appear in an SGML document. When the SGML
+ parser sees the &lt; symbol it assumes that a tag (either a start tag
+ or an end tag) is about to appear, and when it sees the &amp; symbol it
+ assumes the next text will be the name of an entity.</para>
<para>Fortunately, you can use the two general entities &amp;lt; and
&amp;amp; whenever you need to include one or other of these </para>
@@ -1040,7 +1046,7 @@ PUBLIC "-//W3C//DTD HTML 4.0//EN" "4.0/strict.dtd"</programlisting>
<para>Unless your browser is very advanced, you won't see the entity
reference <literal>&amp;version;</literal> replaced with the
version number. Most web browsers have very simplistic parsers
- which don't do proper SGML<footnote>
+ which do not handle proper SGML<footnote>
<para>This is a shame. Imagine all the problems and hacks (such
as Server Side Includes) that could be avoided if they
did.</para>
@@ -1049,8 +1055,11 @@ PUBLIC "-//W3C//DTD HTML 4.0//EN" "4.0/strict.dtd"</programlisting>
<step>
<para>The solution is to <emphasis>normalise</emphasis> your
- document. Normalising it involves converting all the entity
- references to the values of those entities.</para>
+ document using an SGML normaliser. The normaliser reads in valid
+ SGML and outputs equally valid SGML which has been transformed in
+ some way. One of the ways in which the normaliser transforms the
+ SGML is to expand all the entity references in the document,
+ replacing the entities with the text that they represent.</para>
<para>You can use &man.sgmlnorm.1; to do this.</para>
@@ -1078,8 +1087,8 @@ PUBLIC "-//W3C//DTD HTML 4.0//EN" "4.0/strict.dtd"</programlisting>
<title>Using entities to include files</title>
<para>Entities (both <link linkend="general-entities">general</link> and
- <link linkend="parameter-entities">parameter</link>) come into their own
- when you realise they can be used to include other files.</para>
+ <link linkend="parameter-entities">parameter</link>) are particularly
+ useful when used to include one file inside another.</para>
<sect2 id="include-using-gen-entities">
<title>Using general entities to include files</title>
@@ -1344,7 +1353,7 @@ PUBLIC "-//W3C//DTD HTML 4.0//EN" "4.0/strict.dtd"</programlisting>
model</emphasis>, and allow you to change it from the
default.</para>
- <para>When an SGML processor is processing a document, it keeps track
+ <para>When an SGML parser is processing a document, it keeps track
of what is called the &ldquo;content model&rdquo;.</para>
<para>Briefly, the content model describes what sort of content the
@@ -1540,6 +1549,15 @@ PUBLIC "-//W3C//DTD HTML 4.0//EN" "4.0/strict.dtd"</programlisting>
</procedure>
</sect2>
</sect1>
+
+ <sect1>
+ <title>Conclusion</title>
+
+ <para>That is the conclusion of this SGML primer. For reasons of space
+ and complexity several things have not been covered in depth (or at
+ all). However, the previous sections cover enough SGML for you to be
+ able to follow the organisation of the FDP documentation.</para>
+ </sect1>
</chapter>
<!--