- Partly update the fdp-primer for the new, XML-based documentation

Approved by:	doceng (implicit)
This commit is contained in:
Gabor Kovesdan 2012-09-14 08:32:33 +00:00
parent d0231cb6fe
commit 6d02b0b3de
Notes: svn2git 2020-12-08 03:00:23 +00:00
svn path=/projects/sgml2xml/; revision=39528
10 changed files with 393 additions and 565 deletions
en_US.ISO8859-1/books/fdp-primer
doc-build
examples
overview
see-also
sgml-markup
sgml-primer
structure
stylesheets
the-website
tools

View file

@ -46,7 +46,7 @@
<listitem>
<para>Know what you need to build the FDP documentation, in
addition to those mentioned in the
<link linkend="tools">SGML tools chapter</link>.</para>
<link linkend="tools">XML tools chapter</link>.</para>
</listitem>
<listitem>

View file

@ -34,7 +34,7 @@
<appendix id="examples">
<title>Examples</title>
<para>This appendix contains example SGML files and command lines
<para>This appendix contains example XML files and command lines
you can use to convert them from one output format to another. If
you have successfully installed the Documentation Project tools
then you should be able to use these examples directly.</para>
@ -42,7 +42,7 @@
<para>These examples are not exhaustive&mdash;they do not contain
all the elements you might want to use, particularly in your
document's front matter. For more examples of DocBook markup you
should examine the SGML source for this and other documents,
should examine the XML source for this and other documents,
available in the <application>svn</application>
<literal>doc</literal> repository, or available online starting at
<ulink url="http://svnweb.FreeBSD.org/doc/"></ulink>.</para>
@ -60,7 +60,8 @@
<example>
<title>DocBook <sgmltag>book</sgmltag></title>
<programlisting><![CDATA[<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
<programlisting><![CDATA[<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<book lang='en'>
<bookinfo>
@ -112,7 +113,8 @@
<example>
<title>DocBook <sgmltag>article</sgmltag></title>
<programlisting><![CDATA[<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
<programlisting><![CDATA[<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<article lang='en'>
<articleinfo>
@ -269,7 +271,7 @@
<example id="examples-docbook-postscript">
<title>Converting DocBook to Postscript</title>
<para>The source SGML file must be converted to a &tex;
<para>The source XML file must be converted to a &tex;
file.</para>
<screen>&prompt.user; <userinput>jade -V tex-backend \ <co id="examples-co-jade-3-tex-backend"/>

View file

@ -63,7 +63,7 @@
</listitem>
<listitem>
<para>Be able to read and understand the SGML source code for
<para>Be able to read and understand the XML source code for
the documentation maintained by the FDP.</para>
</listitem>

View file

@ -35,7 +35,7 @@
<title>See Also</title>
<para>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.</para>
@ -55,20 +55,13 @@
</itemizedlist>
</sect1>
<sect1 id="see-also-sgml">
<title>SGML</title>
<sect1 id="see-also-xml">
<title>XML</title>
<itemizedlist>
<listitem>
<para><ulink url="http://www.oasis-open.org/cover/">The
SGML/XML web page</ulink>, a comprehensive SGML
resource</para>
</listitem>
<listitem>
<para><ulink
url="http://www-sul.stanford.edu/tools/tutorials/html2.0/gentle.html">Gentle
introduction to SGML</ulink></para>
<para><ulink url="http://www.w3.org/XML/">W3C's XML page
SGML/XML web page</ulink></para>
</listitem>
</itemizedlist>
</sect1>

View file

@ -31,8 +31,8 @@
$FreeBSD$
-->
<chapter id="sgml-markup">
<title>SGML Markup</title>
<chapter id="xml-markup">
<title>XML Markup</title>
<para>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.</para>
</note>
<sect1 id="sgml-markup-html">
<title>HTML</title>
<sect1 id="xml-markup-xhtml">
<title>XHTML</title>
<para>HTML, the HyperText Markup Language, is the markup language
<para>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 <ulink url="http://www.w3.org/"></ulink>.</para>
<para>HTML is used to markup pages on the FreeBSD web site. It
<para>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.</para>
<para>HTML has gone through a number of versions, 1, 2, 3.0, 3.2,
and the latest, 4.0 (available in both
<emphasis>strict</emphasis> and <emphasis>loose</emphasis>
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
<emphasis>strict</emphasis> and <emphasis>transitional</emphasis>
variants).</para>
<para>The HTML DTDs are available from the Ports&nbsp;Collection
in the <filename role="package">textproc/html</filename> port.
<para>The XHTML DTDs are available from the Ports&nbsp;Collection
in the <filename role="package">textproc/xhtml</filename> port.
They are automatically installed as part of the <filename
role="package">textproc/docproj</filename> port.</para>
<sect2>
<title>Formal Public Identifier (FPI)</title>
<para>There are a number of HTML FPIs, depending upon the
version (also known as the level) of HTML that you want to
<para>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.</para>
<para>The majority of HTML documents on the FreeBSD web site
comply with the loose version of HTML 4.0.</para>
<para>The majority of XHTML documents on the FreeBSD web site
comply with the transitional version of XHTML 1.0.</para>
<programlisting>PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting>
<programlisting>PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"</programlisting>
</sect2>
<sect2>
<title>Sectional Elements</title>
<para>An HTML document is normally split into two sections. The
<para>An XHTML document is normally split into two sections. The
first section, called the <emphasis>head</emphasis>, 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 @@
<sgmltag>html</sgmltag> element.</para>
<example>
<title>Normal HTML Document Structure</title>
<title>Normal XHTML Document Structure</title>
<programlisting>&lt;html>
<programlisting>&lt;html xmlns="http://www.w3.org/1999/xhtml">
&lt;head>
&lt;title><replaceable>The Document's Title</replaceable>&lt;/title>
&lt;/head>
@ -137,7 +140,7 @@
<sect3>
<title>Headings</title>
<para>HTML allows you to denote headings in your document, at
<para>XHTML allows you to denote headings in your document, at
up to six different levels.</para>
<para>The largest and most prominent heading is
@ -169,7 +172,7 @@
<!-- Content for the second section goes here -->]]></programlisting>
</example>
<para>Generally, an HTML page should have one first level
<para>Generally, an HXTML page should have one first level
heading (<sgmltag>h1</sgmltag>). This can contain many
second level headings (<sgmltag>h2</sgmltag>), which can in
turn contain many third level headings. Each
@ -198,7 +201,7 @@
<sect3>
<title>Paragraphs</title>
<para>HTML supports a single paragraph element,
<para>XHTML supports a single paragraph element,
<sgmltag>p</sgmltag>.</para>
<example>
@ -493,7 +496,7 @@
<sect3>
<title>Emphasizing Information</title>
<para>You have two levels of emphasis available in HTML,
<para>You have two levels of emphasis available in XHTML,
<sgmltag>em</sgmltag> and <sgmltag>strong</sgmltag>.
<sgmltag>em</sgmltag> is for a normal level of emphasis and
<sgmltag>strong</sgmltag> indicates stronger
@ -502,7 +505,10 @@
<para>Typically, <sgmltag>em</sgmltag> is rendered in italic
and <sgmltag>strong</sgmltag> is rendered in bold. This is
not always the case, however, and you should not rely on
it.</para>
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.</para>
<example>
<title><sgmltag>em</sgmltag> and
@ -515,22 +521,6 @@
</example>
</sect3>
<sect3>
<title>Bold and Italics</title>
<para>Because HTML includes presentational markup, you can
also indicate that particular content should be rendered in
bold or italic. The elements are <sgmltag>b</sgmltag> and
<sgmltag>i</sgmltag> respectively.</para>
<example>
<title><sgmltag>b</sgmltag> and <sgmltag>i</sgmltag></title>
<programlisting><![CDATA[<p><b>This</b> is in bold, while <i>this</i> is
in italics.</p>]]></programlisting>
</example>
</sect3>
<sect3>
<title>Indicating Fixed-Pitch Text</title>
@ -548,65 +538,13 @@
<tt>nik@FreeBSD.org</tt>.</p>]]></programlisting>
</example>
</sect3>
<sect3>
<title>Content Size</title>
<para>You can indicate that content should be shown in a
larger or smaller font. There are three ways of doing
this.</para>
<orderedlist>
<listitem>
<para>Use <sgmltag>big</sgmltag> and
<sgmltag>small</sgmltag> around the content you wish to
change size. These tags can be nested, so
<literal>&lt;big&gt;&lt;big&gt;This is much
bigger&lt;/big&gt;&lt;/big&gt;</literal> is
possible.</para>
</listitem>
<listitem>
<para>Use <sgmltag>font</sgmltag> with the
<literal>size</literal> attribute set to
<literal>+1</literal> or <literal>-1</literal>
respectively. This has the same effect as using
<sgmltag>big</sgmltag> or <sgmltag>small</sgmltag>.
However, the use of this approach is deprecated.</para>
</listitem>
<listitem>
<para>Use <sgmltag>font</sgmltag> with the
<literal>size</literal> attribute set to a number
between <literal>1</literal> and <literal>7</literal>.
The default font size is <literal>3</literal>. This
approach is deprecated.</para>
</listitem>
</orderedlist>
<example>
<title><sgmltag>big</sgmltag>, <sgmltag>small</sgmltag>, and
<sgmltag>font</sgmltag></title>
<para>The following fragments all do the same thing.</para>
<programlisting><![CDATA[<p>This text is <small>slightly smaller</small>. But
this text is <big>slightly bigger</big>.</p>
<p>This text is <font size="-1">slightly smaller</font>. But
this text is <font size="+1">slightly bigger</font>.</p>
<p>This text is <font size="2">slightly smaller</font>. But
this text is <font size="4">slightly bigger</font>.</p>]]></programlisting>
</example>
</sect3>
</sect2>
<sect2>
<title>Links</title>
<note>
<para>Links are also in-line elements.</para>
<para>Links are also inline elements.</para>
</note>
<sect3>
@ -644,20 +582,20 @@
anchors that you can link to.</para>
<para>Anchors are indicated with <sgmltag>a</sgmltag> and the
<literal>name</literal> attribute instead of
<literal>id</literal> attribute instead of
<literal>href</literal>.</para>
<example>
<title>Using <literal>&lt;a name="..."&gt;</literal></title>
<title>Using <literal>&lt;a id="..."&gt;</literal></title>
<para>Use:</para>
<programlisting><![CDATA[<p><a name="para1">This</a> paragraph can be referenced
<programlisting><![CDATA[<p><a id="para1">This</a> paragraph can be referenced
in other links with the name <tt>para1</tt>.</p>]]></programlisting>
</example>
<para>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 <literal>#</literal> symbol.</para>
<example>
@ -691,7 +629,7 @@
</sect2>
</sect1>
<sect1 id="sgml-markup-docbook">
<sect1 id="xml-markup-docbook">
<title>DocBook</title>
<para>DocBook was originally developed by HaL Computer Systems and
@ -703,7 +641,7 @@
Since 1998 it is maintained by the <ulink
url="http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=docbook">
DocBook Technical Committee</ulink>. 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 <emphasis>what</emphasis> something is,
rather than describing <emphasis>how</emphasis> it should be
presented.</para>
@ -760,7 +698,7 @@
for DocBook customizations, the FPI for the FreeBSD extended
DocBook DTD is:</para>
<programlisting>PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN"</programlisting>
<programlisting>PUBLIC "-//FreeBSD//DTD DocBook V4.2-Based Extension//EN"</programlisting>
</sect2>
<sect2>
@ -1804,7 +1742,7 @@ This is the file called 'foo2'</screen>
manual page section.</para>
<para>This can be cumbersome to write, and so a series of
<link linkend="sgml-primer-general-entities">general
<link linkend="xml-primer-general-entities">general
entities</link> have been created to make this easier.
Each entity takes the form
<literal>&amp;man.<replaceable>manual-page</replaceable>.<replaceable>manual-section</replaceable>;</literal>.</para>
@ -2568,7 +2506,7 @@ IMAGES+= fig3.png
<para>You must be careful when you separate your documentation
into smaller files (see
<xref linkend="sgml-primer-include-using-gen-entities"/>) in
<xref linkend="xml-primer-include-using-gen-entities"/>) in
different directories.</para>
<para>Suppose you have a book with three chapters, and the

File diff suppressed because it is too large Load diff

View file

@ -83,7 +83,7 @@
subdirectories to further categorize the information. For
example, the files that comprise the &man.make.1;
infrastructure are in <filename>share/mk</filename>, while
the additional SGML support files (such as the FreeBSD
the additional XML support files (such as the FreeBSD
extended DocBook DTD) are in
<filename>share/sgml</filename>.</seg>
</seglistitem>
@ -124,7 +124,7 @@
<seg>Documentation marked up as a DocBook
<sgmltag>article</sgmltag> (or equivalent). Reasonably
short, and broken up into sections. Normally only available
as one HTML file.</seg>
as one XHTML file.</seg>
</seglistitem>
<seglistitem>
@ -133,7 +133,7 @@
<seg>Documentation marked up as a DocBook
<sgmltag>book</sgmltag> (or equivalent). Book length, and
broken up into chapters. Normally available as both one
large HTML file (for people with fast connections, or who
large XHTML file (for people with fast connections, or who
want to print it easily from a browser) and as a collection
of linked, smaller files.</seg>
</seglistitem>
@ -195,7 +195,7 @@
<title><filename>Makefile</filename></title>
<para>The <filename>Makefile</filename> defines some
variables that affect how the SGML source is converted to
variables that affect how the XML source is converted to
other formats, and lists the various source files that
make up the Handbook. It then includes the standard
<filename>doc.project.mk</filename> file, to bring in the
@ -208,16 +208,16 @@
<para>This is the top level document in the Handbook. It
contains the Handbook's <link
linkend="sgml-primer-doctype-declaration">DOCTYPE
linkend="xml-primer-doctype-declaration">DOCTYPE
declaration</link>, as well as the elements that
describe the Handbook's structure.</para>
<para><filename>book.sgml</filename> uses <link
linkend="sgml-primer-parameter-entities">parameter
linkend="xml-primer-parameter-entities">parameter
entities</link> to load in the files with the
<filename>.ent</filename> extension. These files
(described later) then define <link
linkend="sgml-primer-general-entities">general
linkend="xml-primer-general-entities">general
entities</link> that are used throughout the rest of the
Handbook.</para>
</sect4>
@ -246,7 +246,7 @@
the entire contents of the chapter will be held in this
file.</para>
<para>When the HTML version of the Handbook is produced,
<para>When the XHTML version of the Handbook is produced,
this will yield <filename>kernelconfig.html</filename>.
This is because of the <literal>id</literal> value, and is
not related to the name of the directory.</para>
@ -260,7 +260,7 @@
Handbook chapter are stored within <filename
class="directory">share/images/books/handbook</filename>.
Note that localized version of these images should be
placed in the same directory as the SGML sources for each
placed in the same directory as the XML sources for each
chapter. Namespace collisions would be inevitable, and it
is easier to work with several directories with a few
files in them than it is to work with one directory that
@ -283,12 +283,12 @@
</important>
<para>Each <filename>chapter.sgml</filename> file will not
be a complete SGML document. In particular, they will not
be a complete XML document. In particular, they will not
have their own DOCTYPE lines at the start of the
files.</para>
<para>This is unfortunate as it makes it impossible to treat
these as generic SGML files and simply convert them to
these as generic XML files and simply convert them to
HTML, RTF, PS, and other formats in the same way the main
Handbook is generated. This <emphasis>would</emphasis>
force you to rebuild the Handbook every time you want to

View file

@ -40,7 +40,7 @@
Panorama, SPICE, JSSS, FOSI, CSS, and DSSSL.</para>
<para>For DocBook, we are using stylesheets written in DSSSL. For
HTML we are using CSS.</para>
XHTML we are using CSS.</para>
<sect1 id="stylesheets-dsssl">
<title>* DSSSL</title>
@ -69,7 +69,7 @@
<para>Cascading Stylesheets (CSS) are a mechanism for attaching
style information (font, weight, size, color, and so forth) to
elements in an HTML document without abusing HTML to do
elements in an XHTML document without abusing XHTML to do
so.</para>
<sect2>
@ -77,10 +77,10 @@
<para>The FreeBSD DSSSL stylesheets include a reference to a
stylesheet, <filename>docbook.css</filename>, which is
expected to appear in the same directory as the HTML files.
expected to appear in the same directory as the XHTML files.
The project-wide CSS file is copied from
<filename>doc/share/misc/docbook.css</filename> when documents
are converted to HTML, and is installed automatically.</para>
are converted to XHTML, and is installed automatically.</para>
</sect2>
</sect1>
</chapter>

View file

@ -39,7 +39,7 @@
<para>Use a disk with sufficient free space. You may need
anything from 200&nbsp;MB to over 500&nbsp;MB, depending on the
method you choose. This space will hold the SGML tools, a
method you choose. This space will hold the XML tools, a
subset of the <application>svn</application> tree, temporary
build space and the installed web pages.</para>

View file

@ -81,7 +81,7 @@
These slave ports define the <makevar>JADETEX</makevar> variable
for you, therefore they will install the same suite of
applications on your machine. Note that you can produce only
HTML or ASCII text output if you do not install
XHTML or ASCII text output if you do not install
<application>JadeTeX</application>. PostScript or PDF output
requires &tex;.</para>
</tip>
@ -94,7 +94,7 @@
<para>These programs are required before you can usefully work
with the FreeBSD documentation, and they will allow you to
convert the documentation to HTML, plain text, and RTF
convert the documentation to XHTML, plain text, and RTF
formats. They are all included in <filename
role="package">textproc/docproj</filename>.</para>
@ -115,8 +115,8 @@
(<filename role="package">www/tidy</filename>)</term>
<listitem>
<para>An HTML <quote>pretty printer</quote>, used to
reformat some of the automatically generated HTML so
<para>An (X)HTML <quote>pretty printer</quote>, used to
reformat some of the automatically generated pages so
that it is easier to follow.</para>
</listitem>
</varlistentry>
@ -127,7 +127,7 @@
<listitem>
<para>A text-mode WWW browser that can also convert
HTML files to plain text.</para>
XHTML files to plain text.</para>
</listitem>
</varlistentry>
@ -154,11 +154,11 @@
<variablelist>
<varlistentry>
<term>HTML DTD (<filename
role="package">textproc/html</filename>)</term>
<term>XHTML DTD (<filename
role="package">textproc/xhtml</filename>)</term>
<listitem>
<para>HTML is the markup language of choice for the World
<para>XHTML is the markup language of choice for the World
Wide Web, and is used throughout the FreeBSD web
site.</para>
</listitem>
@ -282,7 +282,7 @@
</variablelist>
<para>If anyone has recommendations for other software that is
useful when manipulating SGML documents, please let &a.doceng;
useful when manipulating XML documents, please let &a.doceng;
know, so they can be added to this list.</para>
</sect2>
</sect1>