Wrap long lines, properly indent tags, capitalizations, and other fixes for
issues that textproc/igor reported.
This commit is contained in:
Benedict Reuschling
parent
ecbc8b3022
commit
8ffacca1e1
Notes:
svn2git
2020-12-08 03:00:23 +00:00
svn path=/head/; revision=52151
8 changed files with 108 additions and 72 deletions
|
|
@ -417,10 +417,10 @@
|
|||
<para>The <link xlink:href="&url.base;/docs.html">&os;
|
||||
tutorials</link> are all marked up as articles, while this
|
||||
document, the <link
|
||||
xlink:href="&url.books.faq;/index.html">FAQ</link>,
|
||||
and the <link
|
||||
xlink:href="&url.books.handbook;/index.html">Handbook</link> are all marked up as books, for
|
||||
example.</para>
|
||||
xlink:href="&url.books.faq;/index.html">FAQ</link>, and the
|
||||
<link
|
||||
xlink:href="&url.books.handbook;/index.html">Handbook</link>
|
||||
are all marked up as books, for example.</para>
|
||||
|
||||
<sect2 xml:id="docbook-markup-starting-a-book">
|
||||
<title>Starting a Book</title>
|
||||
|
|
@ -1000,11 +1000,10 @@
|
|||
</variablelist>
|
||||
</example>
|
||||
|
||||
<para>A <tag>procedure</tag> shows a series of
|
||||
<tag>step</tag>s, which may in turn
|
||||
consist of more <tag>step</tag>s or
|
||||
<tag>substep</tag>s. Each <tag>step</tag>
|
||||
contains block elements and may include an optional title.</para>
|
||||
<para>A <tag>procedure</tag> shows a series of <tag>step</tag>s,
|
||||
which may in turn consist of more <tag>step</tag>s or
|
||||
<tag>substep</tag>s. Each <tag>step</tag> contains block
|
||||
elements and may include an optional title.</para>
|
||||
|
||||
<para>Sometimes, steps are not sequential, but present a choice:
|
||||
do <emphasis>this</emphasis> or do <emphasis>that</emphasis>,
|
||||
|
|
@ -1309,7 +1308,8 @@ main(void)
|
|||
<literal>informaltable frame="none"</literal>.</para>
|
||||
|
||||
<example>
|
||||
<title>Table with <literal>frame="none"</literal> Example</title>
|
||||
<title>Table with <literal>frame="none"</literal>
|
||||
Example</title>
|
||||
|
||||
<para>Appearance:</para>
|
||||
|
||||
|
|
@ -1962,7 +1962,7 @@ This is the file called 'foo2'</screen>
|
|||
|
||||
<para>Occasionally it is useful to show a
|
||||
Uniform Resource Identifier (<acronym>URI</acronym>) without
|
||||
making it an active hyperlink. The <tag>uri</tag> element
|
||||
making it an active hyperlink. The <tag>uri</tag> element
|
||||
makes this possible:</para>
|
||||
|
||||
<example>
|
||||
|
|
@ -2641,18 +2641,18 @@ IMAGES= chapter1/fig1.png
|
|||
Web</title>
|
||||
|
||||
<para>The link element described here allows the writer to
|
||||
define the link text. When link text is used, it is very important to be descriptive
|
||||
to give the reader an idea of where the link goes.
|
||||
Remember that DocBook can be rendered to multiple
|
||||
types of media. The reader might be looking at a printed book
|
||||
or other form of media where there are no links. If the link
|
||||
text is not descriptive enough, the reader might not be able to
|
||||
locate the linked section.</para>
|
||||
define the link text. When link text is used, it is very
|
||||
important to be descriptive to give the reader an idea of
|
||||
where the link goes. Remember that DocBook can be rendered to
|
||||
multiple types of media. The reader might be looking at a
|
||||
printed book or other form of media where there are no links.
|
||||
If the link text is not descriptive enough, the reader might
|
||||
not be able to locate the linked section.</para>
|
||||
|
||||
<para>The <literal>xlink:href</literal> attribute
|
||||
is the <acronym>URL</acronym> of the page,
|
||||
and the content of the element is the text that
|
||||
will be displayed for the user to activate.</para>
|
||||
<para>The <literal>xlink:href</literal> attribute is the
|
||||
<acronym>URL</acronym> of the page, and the content of the
|
||||
element is the text that will be displayed for the user to
|
||||
activate.</para>
|
||||
|
||||
<para>In many situations, it is preferable to show the actual
|
||||
<acronym>URL</acronym> rather than text. This can be done by
|
||||
|
|
|
|||
|
|
@ -29,7 +29,9 @@
|
|||
POSSIBILITY OF SUCH DAMAGE.
|
||||
|
||||
-->
|
||||
<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="stylesheets">
|
||||
<chapter xmlns="http://docbook.org/ns/docbook"
|
||||
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
|
||||
xml:id="stylesheets">
|
||||
<title>Style Sheets</title>
|
||||
|
||||
<para><acronym>XML</acronym> is concerned with content, and says
|
||||
|
|
|
|||
|
|
@ -29,7 +29,9 @@
|
|||
POSSIBILITY OF SUCH DAMAGE.
|
||||
|
||||
-->
|
||||
<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="the-website">
|
||||
<chapter xmlns="http://docbook.org/ns/docbook"
|
||||
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
|
||||
xml:id="the-website">
|
||||
<title>The Website</title>
|
||||
|
||||
<para>The &os; web site is part of the &os; documents. Files for
|
||||
|
|
@ -129,11 +131,12 @@
|
|||
<para>Having obtained the documentation and web site source files,
|
||||
the web site can be built.</para>
|
||||
|
||||
<para>An actual installation of the web site is run as the <systemitem class="username">root</systemitem>
|
||||
user because the permissions on the web server directory will
|
||||
not allow files to be installed by an unprivileged user.
|
||||
For testing, it can be useful to install the files as a normal
|
||||
user to a temporary directory.</para>
|
||||
<para>An actual installation of the web site is run as the
|
||||
<systemitem class="username">root</systemitem> user because the
|
||||
permissions on the web server directory will not allow files to
|
||||
be installed by an unprivileged user. For testing, it can be
|
||||
useful to install the files as a normal user to a temporary
|
||||
directory.</para>
|
||||
|
||||
<para>In these examples, the web site files are built by user
|
||||
<systemitem class="username">jru</systemitem> in their home
|
||||
|
|
@ -143,9 +146,10 @@
|
|||
<tip>
|
||||
<para>The web site build uses the <filename>INDEX</filename>
|
||||
from the Ports Collection and might fail if that file or
|
||||
<filename>/usr/ports</filename> is not
|
||||
present. The simplest approach is to install the <link xlink:href="&url.books.handbook;/ports.html#ports-tree">Ports
|
||||
Collection</link>.</para>
|
||||
<filename>/usr/ports</filename> is not present. The simplest
|
||||
approach is to install the <link
|
||||
xlink:href="&url.books.handbook;/ports.html#ports-tree">Ports
|
||||
Collection</link>.</para>
|
||||
</tip>
|
||||
|
||||
<example xml:id="the-website-examples-build">
|
||||
|
|
@ -241,10 +245,10 @@ Include etc/apache24/Includes/*.conf</programlisting>
|
|||
|
||||
<screen>&prompt.root; <userinput>service apache24 onestart</userinput></screen>
|
||||
|
||||
<para>The web site can be viewed at
|
||||
<link xlink:href="http://localhost"/>. Be aware that many
|
||||
links refer to the real &os; site by name, and those links
|
||||
will still go to the external site instead of the local test
|
||||
<para>The web site can be viewed at <link
|
||||
xlink:href="http://localhost"/>. Be aware that many links
|
||||
refer to the real &os; site by name, and those links will
|
||||
still go to the external site instead of the local test
|
||||
version. Fully testing the local site will require
|
||||
temporarily setting <acronym>DNS</acronym> so
|
||||
<literal>www.FreeBSD.org</literal> resolves to
|
||||
|
|
|
|||
|
|
@ -29,7 +29,9 @@
|
|||
POSSIBILITY OF SUCH DAMAGE.
|
||||
|
||||
-->
|
||||
<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="tools">
|
||||
<chapter xmlns="http://docbook.org/ns/docbook"
|
||||
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
|
||||
xml:id="tools">
|
||||
<title>Tools</title>
|
||||
|
||||
<para>Several software tools are used to manage the FreeBSD
|
||||
|
|
@ -72,7 +74,8 @@
|
|||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>DocBook <acronym>DTD</acronym> (<package>textproc/docbook-xml</package>)</term>
|
||||
<term>DocBook <acronym>DTD</acronym>
|
||||
(<package>textproc/docbook-xml</package>)</term>
|
||||
|
||||
<listitem>
|
||||
<para>DocBook is designed for marking up technical
|
||||
|
|
|
|||
|
|
@ -26,7 +26,9 @@
|
|||
EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
||||
|
||||
-->
|
||||
<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="working-copy">
|
||||
<chapter xmlns="http://docbook.org/ns/docbook"
|
||||
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
|
||||
xml:id="working-copy">
|
||||
<title>The Working Copy</title>
|
||||
|
||||
<para>The <emphasis>working copy</emphasis> is a copy of the &os;
|
||||
|
|
@ -40,8 +42,11 @@
|
|||
for temporary files and test versions of various output
|
||||
formats.</para>
|
||||
|
||||
<para><link xlink:href="&url.books.handbook;/svn.html"><application>Subversion</application></link>
|
||||
is used to manage the &os; documentation files. It is obtained by installing the <application>Subversion</application> package:</para>
|
||||
<para><link
|
||||
xlink:href="&url.books.handbook;/svn.html"><application>Subversion</application></link>
|
||||
is used to manage the &os; documentation files. It is obtained by
|
||||
installing the <application>Subversion</application>
|
||||
package:</para>
|
||||
|
||||
<screen>&prompt.root; <userinput>pkg install subversion</userinput></screen>
|
||||
|
||||
|
|
@ -148,8 +153,9 @@
|
|||
documentation tree.</para>
|
||||
|
||||
<para>If the diff file is to be submitted with the web
|
||||
<quote><link xlink:href="https://bugs.FreeBSD.org/bugzilla/enter_bug.cgi">Submit a &os;
|
||||
problem report</link></quote> interface, add a
|
||||
<quote><link
|
||||
xlink:href="https://bugs.FreeBSD.org/bugzilla/enter_bug.cgi">Submit
|
||||
a &os; problem report</link></quote> interface, add a
|
||||
<filename>.txt</filename> extension to give the earnest and
|
||||
simple-minded web form a clue that the contents are plain
|
||||
text.</para>
|
||||
|
|
@ -169,8 +175,10 @@
|
|||
|
||||
<para>These examples show very basic usage of
|
||||
<application>Subversion</application>. More detail is available
|
||||
in the <link xlink:href="http://svnbook.red-bean.com/">Subversion Book</link>
|
||||
and the <link xlink:href="http://subversion.apache.org/docs/">Subversion
|
||||
in the <link
|
||||
xlink:href="http://svnbook.red-bean.com/">Subversion
|
||||
Book</link> and the <link
|
||||
xlink:href="http://subversion.apache.org/docs/">Subversion
|
||||
documentation</link>.</para>
|
||||
</sect1>
|
||||
</chapter>
|
||||
|
|
|
|||
|
|
@ -29,7 +29,9 @@
|
|||
POSSIBILITY OF SUCH DAMAGE.
|
||||
|
||||
-->
|
||||
<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="writing-style">
|
||||
<chapter xmlns="http://docbook.org/ns/docbook"
|
||||
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
|
||||
xml:id="writing-style">
|
||||
<title>Writing Style</title>
|
||||
|
||||
<sect1 xml:id="writing-style-tips">
|
||||
|
|
@ -59,7 +61,7 @@
|
|||
Avoid empty phrases like <quote>in order to</quote>, which
|
||||
usually just means <quote>to</quote>. Avoid potentially
|
||||
patronizing words like <quote>basically</quote>. Avoid Latin
|
||||
terms like <quote>i.e.</quote> or <quote>cf.</quote>, which
|
||||
terms like <quote>i.e.,</quote> or <quote>cf.</quote>, which
|
||||
may be unknown outside of academic or scientific
|
||||
groups.</para>
|
||||
|
||||
|
|
@ -248,7 +250,8 @@
|
|||
</varlistentry>
|
||||
</variablelist>
|
||||
|
||||
<para>For more information about writing style, see <link xlink:href="http://www.bartleby.com/141/">Elements of
|
||||
<para>For more information about writing style, see <link
|
||||
xlink:href="http://www.bartleby.com/141/">Elements of
|
||||
Style</link>, by William Strunk.</para>
|
||||
</sect1>
|
||||
|
||||
|
|
@ -504,12 +507,16 @@ GB. Hardware compression …</literallayout>
|
|||
<row>
|
||||
<entry>CD-ROM</entry>
|
||||
|
||||
<entry><tag class="starttag">acronym</tag><literal>CD-ROM</literal><tag class="endtag">acronym</tag></entry>
|
||||
<entry><tag
|
||||
class="starttag">acronym</tag><literal>CD-ROM</literal><tag
|
||||
class="endtag">acronym</tag></entry>
|
||||
</row>
|
||||
|
||||
<row>
|
||||
<entry>DoS (Denial of Service)</entry>
|
||||
<entry><tag class="starttag">acronym</tag><literal>DoS</literal><tag class="endtag">acronym</tag></entry>
|
||||
<entry><tag
|
||||
class="starttag">acronym</tag><literal>DoS</literal><tag
|
||||
class="endtag">acronym</tag></entry>
|
||||
</row>
|
||||
|
||||
<row>
|
||||
|
|
@ -573,7 +580,9 @@ GB. Hardware compression …</literallayout>
|
|||
<entry><tag class="starttag">application</tag><literal>Subversion</literal><tag class="endtag">application</tag></entry>
|
||||
<entry>Do not refer to the Subversion application as
|
||||
<literal>SVN</literal> in upper case. To refer to the
|
||||
command, use <tag class="starttag">command</tag><literal>svn</literal><tag class="endtag">command</tag>.</entry>
|
||||
command, use <tag
|
||||
class="starttag">command</tag><literal>svn</literal><tag
|
||||
class="endtag">command</tag>.</entry>
|
||||
</row>
|
||||
|
||||
<row>
|
||||
|
|
|
|||
|
|
@ -29,7 +29,9 @@
|
|||
POSSIBILITY OF SUCH DAMAGE.
|
||||
|
||||
-->
|
||||
<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="xhtml-markup">
|
||||
<chapter xmlns="http://docbook.org/ns/docbook"
|
||||
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
|
||||
xml:id="xhtml-markup">
|
||||
<title><acronym>XHTML</acronym> Markup</title>
|
||||
|
||||
<sect1 xml:id="xhtml-markup-introduction">
|
||||
|
|
@ -41,7 +43,8 @@
|
|||
<para><acronym>XHTML</acronym> is the <acronym>XML</acronym>
|
||||
version of the HyperText Markup Language, the markup language of
|
||||
choice on the World Wide Web. More information can be found at
|
||||
<uri xlink:href="http://www.w3.org/">http://www.w3.org/</uri>.</para>
|
||||
<uri
|
||||
xlink:href="http://www.w3.org/">http://www.w3.org/</uri>.</para>
|
||||
|
||||
<para><acronym>XHTML</acronym> is used to mark up pages on the
|
||||
&os; web site. It is usually not used to mark up other
|
||||
|
|
@ -59,8 +62,9 @@
|
|||
|
||||
<para>The <acronym>XHTML</acronym> <acronym>DTDs</acronym> are
|
||||
available from the Ports Collection in
|
||||
<package>textproc/xhtml</package>. They are
|
||||
automatically installed by the <package>textproc/docproj</package> port.</para>
|
||||
<package>textproc/xhtml</package>. They are automatically
|
||||
installed by the <package>textproc/docproj</package>
|
||||
port.</para>
|
||||
|
||||
<note>
|
||||
<para>This is <emphasis>not</emphasis> an exhaustive list of
|
||||
|
|
@ -460,7 +464,8 @@
|
|||
<sect1 xml:id="xhtml-markup-inline-elements">
|
||||
<title>In-line Elements</title>
|
||||
|
||||
<sect2 xml:id="xhtml-markup-inline-elements-emphasizing-information">
|
||||
<sect2
|
||||
xml:id="xhtml-markup-inline-elements-emphasizing-information">
|
||||
<title>Emphasizing Information</title>
|
||||
|
||||
<para>Two levels of emphasis are available in
|
||||
|
|
|
|||
|
|
@ -29,7 +29,9 @@
|
|||
POSSIBILITY OF SUCH DAMAGE.
|
||||
|
||||
-->
|
||||
<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="xml-primer">
|
||||
<chapter xmlns="http://docbook.org/ns/docbook"
|
||||
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
|
||||
xml:id="xml-primer">
|
||||
<title>XML Primer</title>
|
||||
|
||||
<para>Most <acronym>FDP</acronym> documentation is written with
|
||||
|
|
@ -38,8 +40,8 @@
|
|||
documentation source, and the <acronym>XML</acronym> techniques
|
||||
used.</para>
|
||||
|
||||
<para>Portions of this section were inspired by Mark Galassi's
|
||||
<link xlink:href="http://www.galassi.org/mark/mydocs/docbook-intro/docbook-intro.html">Get
|
||||
<para>Portions of this section were inspired by Mark Galassi's <link
|
||||
xlink:href="http://www.galassi.org/mark/mydocs/docbook-intro/docbook-intro.html">Get
|
||||
Going With DocBook</link>.</para>
|
||||
|
||||
<sect1 xml:id="xml-primer-overview">
|
||||
|
|
@ -219,8 +221,10 @@
|
|||
|
||||
<para>For an element called
|
||||
<replaceable>element-name</replaceable> the start tag will
|
||||
normally look like <tag class="starttag"><replaceable>element-name</replaceable></tag>.
|
||||
The corresponding closing tag for this element is <tag class="endtag"><replaceable>element-name</replaceable></tag>.</para>
|
||||
normally look like <tag
|
||||
class="starttag"><replaceable>element-name</replaceable></tag>.
|
||||
The corresponding closing tag for this element is <tag
|
||||
class="endtag"><replaceable>element-name</replaceable></tag>.</para>
|
||||
|
||||
<example>
|
||||
<title>Using an Element (Start and End Tags)</title>
|
||||
|
|
@ -360,14 +364,13 @@
|
|||
<title>To Do…</title>
|
||||
|
||||
<para>Before running the examples in this document, install
|
||||
<package>textproc/docproj</package> from
|
||||
the &os; Ports Collection. This is a
|
||||
<emphasis>meta-port</emphasis> that downloads and installs
|
||||
the standard programs and supporting files needed by the
|
||||
Documentation Project. &man.csh.1; users must use
|
||||
<command>rehash</command> for the shell to recognize new
|
||||
programs after they have been installed, or log out
|
||||
and then log back in again.</para>
|
||||
<package>textproc/docproj</package> from the &os; Ports
|
||||
Collection. This is a <emphasis>meta-port</emphasis> that
|
||||
downloads and installs the standard programs and supporting
|
||||
files needed by the Documentation Project. &man.csh.1; users
|
||||
must use <command>rehash</command> for the shell to recognize
|
||||
new programs after they have been installed, or log out and
|
||||
then log back in again.</para>
|
||||
|
||||
<procedure>
|
||||
<step>
|
||||
|
|
@ -486,7 +489,8 @@ example.xml:5: element head: validity error : Element head content does not foll
|
|||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><literal>PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"</literal></term>
|
||||
<term><literal>PUBLIC "-//W3C//DTD XHTML 1.0
|
||||
Transitional//EN"</literal></term>
|
||||
|
||||
<listitem>
|
||||
<para>Lists the Formal Public Identifier
|
||||
|
|
@ -505,7 +509,8 @@ example.xml:5: element head: validity error : Element head content does not foll
|
|||
<acronym>DTD</acronym> referenced in the
|
||||
<acronym>FPI</acronym>. Other ways of telling the
|
||||
<acronym>XML</acronym> parser how to find the
|
||||
<acronym>DTD</acronym> are shown <link linkend="xml-primer-fpi-alternatives">later</link>.</para>
|
||||
<acronym>DTD</acronym> are shown <link
|
||||
linkend="xml-primer-fpi-alternatives">later</link>.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
|
|
@ -539,7 +544,7 @@ example.xml:5: element head: validity error : Element head content does not foll
|
|||
<note>
|
||||
<para>It is not necessary to know this, but it is useful
|
||||
background, and might help debug problems when the
|
||||
<acronym>XML</acronym> processor can not locate the
|
||||
<acronym>XML</acronym> processor cannot locate the
|
||||
<acronym>DTD</acronym>.</para>
|
||||
</note>
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue