- Simplify <URL: link> notation
- Capitalize and add non-breakable spaces to "Ports Collection" - s/of/or in "number of rows of columns" - Mark up some attributes and literals with <literal> elements - Eliminate first-person narration - Add more generalization to the text, refer to the Handbook as an example - Update path names of the Handbook sources - Add missing text to the <blockquote> example - Add a table with borders to the examples - Simplify some parts of the manual page markup example - Fix all sendmail-related manual page sections - Fix example of <hostid> - Remove <informalexample> tags from the <screen> example - Add missing parentheses Reviewed by: gabor, manolis, rene Obtained from: The FreeBSD Hungarian Documentation Project
This commit is contained in:
Gabor Pali
parent
4bd036779d
commit
97a6f5b924
Notes:
svn2git
2020-12-08 03:00:23 +00:00
svn path=/head/; revision=33364
1 changed files with 30 additions and 35 deletions
|
|
@ -64,7 +64,7 @@
|
|||
|
||||
<para>HTML, the HyperText Markup Language, is the markup language of
|
||||
choice on the World Wide Web. More information can be found at
|
||||
<URL:<ulink url="http://www.w3.org/"></ulink>>.</para>
|
||||
<ulink url="http://www.w3.org/"></ulink>.</para>
|
||||
|
||||
<para>HTML is used to markup pages on the FreeBSD web site. It should not
|
||||
(generally) be used to mark up other documentation,
|
||||
|
|
@ -77,7 +77,7 @@
|
|||
latest, 4.0 (available in both <emphasis>strict</emphasis> and
|
||||
<emphasis>loose</emphasis> variants).</para>
|
||||
|
||||
<para>The HTML DTDs are available from the ports collection in the
|
||||
<para>The HTML DTDs are available from the Ports Collection in the
|
||||
<filename role="package">textproc/html</filename> port. They are automatically
|
||||
installed as part of the <filename role="package">textproc/docproj</filename>
|
||||
port.</para>
|
||||
|
|
@ -392,7 +392,7 @@
|
|||
|
||||
<para>A cell can span multiple rows and columns. To indicate this,
|
||||
add the <literal>rowspan</literal> and/or <literal>colspan</literal>
|
||||
attributes, with values indicating the number of rows of columns
|
||||
attributes, with values indicating the number of rows or columns
|
||||
that should be spanned.</para>
|
||||
|
||||
<example>
|
||||
|
|
@ -555,7 +555,7 @@
|
|||
|
||||
<listitem>
|
||||
<para>Use <sgmltag>font</sgmltag> with the <literal>size</literal>
|
||||
attribute set to a number between 1 and 7. The default font size
|
||||
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>
|
||||
|
|
@ -570,7 +570,7 @@
|
|||
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>
|
||||
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>
|
||||
|
|
@ -689,7 +689,7 @@
|
|||
title.</para>
|
||||
</note>
|
||||
|
||||
<para>The DocBook DTD is available from the ports collection in the
|
||||
<para>The DocBook DTD is available from the Ports Collection in the
|
||||
<filename role="package">textproc/docbook</filename> port. It is automatically
|
||||
installed as part of the <filename role="package">textproc/docproj</filename>
|
||||
port.</para>
|
||||
|
|
@ -717,8 +717,8 @@
|
|||
touch with &a.doceng;.</para>
|
||||
</note>
|
||||
|
||||
<para>The FreeBSD extensions are not (currently) in the ports
|
||||
collection. They are stored in the FreeBSD CVS tree, as <ulink
|
||||
<para>The &os; extensions are not (currently) in the Ports Collection.
|
||||
They are stored in the &os; CVS tree, as <ulink
|
||||
url="http://www.FreeBSD.org/cgi/cvsweb.cgi/doc/share/sgml/freebsd.dtd">doc/share/sgml/freebsd.dtd</ulink>.</para>
|
||||
</sect2>
|
||||
|
||||
|
|
@ -742,7 +742,7 @@
|
|||
<para>A book is organized into <sgmltag>chapter</sgmltag>s. This is a
|
||||
mandatory requirement. There may be <sgmltag>part</sgmltag>s between
|
||||
the book and the chapter to provide another layer of organization.
|
||||
The Handbook is arranged in this way.</para>
|
||||
For example, the Handbook is arranged in this way.</para>
|
||||
|
||||
<para>A chapter may (or may not) contain one or more sections. These
|
||||
are indicated with the <sgmltag>sect1</sgmltag> element. If a section
|
||||
|
|
@ -770,7 +770,7 @@
|
|||
document, the <ulink url="&url.books.faq;/index.html">FreeBSD
|
||||
FAQ</ulink>, and the <ulink
|
||||
url="&url.books.handbook;/index.html">FreeBSD Handbook</ulink> are
|
||||
all marked up as books.</para>
|
||||
all marked up as books, for example.</para>
|
||||
|
||||
<sect3>
|
||||
<title>Starting a Book</title>
|
||||
|
|
@ -1055,6 +1055,8 @@
|
|||
|
||||
<para>Appearance:</para>
|
||||
|
||||
<para>A small excerpt from the US Constitution:</para>
|
||||
|
||||
<blockquote>
|
||||
<title>Preamble to the Constitution of the United States</title>
|
||||
|
||||
|
|
@ -1120,6 +1122,7 @@
|
|||
</warning>]]></programlisting>
|
||||
</example>
|
||||
|
||||
<para>Appearance:</para>
|
||||
<!-- Need to do this outside of the example -->
|
||||
<warning>
|
||||
<para>Installing FreeBSD may make you want to delete Windows from
|
||||
|
|
@ -1390,7 +1393,7 @@ main(void)
|
|||
|
||||
<para>Use:</para>
|
||||
|
||||
<programlisting><![ CDATA [<informaltable frame="none" pgwide="1">
|
||||
<programlisting><![ CDATA [<informaltable pgwide="1">
|
||||
<tgroup cols="2">
|
||||
<thead>
|
||||
<row>
|
||||
|
|
@ -1415,7 +1418,7 @@ main(void)
|
|||
|
||||
<para>Appearance:</para>
|
||||
|
||||
<informaltable frame="none" pgwide="1">
|
||||
<informaltable pgwide="1">
|
||||
<tgroup cols="2">
|
||||
<thead>
|
||||
<row>
|
||||
|
|
@ -1703,7 +1706,7 @@ This is the file called 'foo2'</screen>
|
|||
<title>Applications, Commands, Options, and Cites</title>
|
||||
|
||||
<para>You will frequently want to refer to both applications and
|
||||
commands when writing for the Handbook. The distinction between
|
||||
commands when writing documentation. The distinction between
|
||||
them is simple: an application is the name for a suite (or possibly
|
||||
just 1) of programs that fulfil a particular task. A command is the
|
||||
name of a program that the user can run.</para>
|
||||
|
|
@ -1780,7 +1783,7 @@ This is the file called 'foo2'</screen>
|
|||
<citerefentry>
|
||||
<refentrytitle>sendmail</refentrytitle>
|
||||
<manvolnum>8</manvolnum>
|
||||
</citerefentry>, &man.mailq.8;, and &man.newaliases.8;
|
||||
</citerefentry>, &man.mailq.1;, and &man.newaliases.1;
|
||||
programs.</para>
|
||||
|
||||
<para>One of the command line parameters to <citerefentry>
|
||||
|
|
@ -1799,13 +1802,7 @@ This is the file called 'foo2'</screen>
|
|||
<citerefentry>
|
||||
<refentrytitle>sendmail</refentrytitle>
|
||||
<manvolnum>8</manvolnum>
|
||||
</citerefentry>, <citerefentry>
|
||||
<refentrytitle>mailq</refentrytitle>
|
||||
<manvolnum>8</manvolnum>
|
||||
</citerefentry>, and <citerefentry>
|
||||
<refentrytitle>newaliases</refentrytitle>
|
||||
<manvolnum>8</manvolnum>
|
||||
</citerefentry> programs.</para>
|
||||
</citerefentry>, &man.mailq.1;, and &man.newaliases.1; programs.</para>
|
||||
|
||||
<para>One of the command line parameters to <citerefentry>
|
||||
<refentrytitle>sendmail</refentrytitle>
|
||||
|
|
@ -1833,8 +1830,8 @@ This is the file called 'foo2'</screen>
|
|||
<para>Use:</para>
|
||||
|
||||
<programlisting><![ CDATA [<para>The SGML source for the Handbook in English can be
|
||||
found in <filename class="directory">/usr/doc/en/handbook/</filename>. The first
|
||||
file is called <filename>handbook.sgml</filename> in that
|
||||
found in <filename class="directory">/usr/doc/en_US.ISO8859-1/books/handbook/</filename>. The first
|
||||
file is called <filename>book.sgml</filename> in that
|
||||
directory. You should also see a <filename>Makefile</filename>
|
||||
and a number of files with a <filename>.ent</filename>
|
||||
extension.</para>]]></programlisting>
|
||||
|
|
@ -1955,11 +1952,11 @@ This is the file called 'foo2'</screen>
|
|||
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term>No role attribute, or
|
||||
<term>No <literal>role</literal> attribute, or
|
||||
<literal>role="hostname"</literal></term>
|
||||
|
||||
<listitem>
|
||||
<para>With no role attribute (i.e.,
|
||||
<para>With no <literal>role</literal> attribute (i.e.,
|
||||
<sgmltag>hostid</sgmltag>...<sgmltag>/hostid</sgmltag>) the
|
||||
marked up information is the simple hostname, such as
|
||||
<literal>freefall</literal> or <literal>wcarchive</literal>.
|
||||
|
|
@ -2037,13 +2034,13 @@ This is the file called 'foo2'</screen>
|
|||
<para>The <hostid role="domainname">FreeBSD.org</hostid> domain
|
||||
contains a number of different hosts, including
|
||||
<hostid role="fqdn">freefall.FreeBSD.org</hostid> and
|
||||
<hostid role="fqdn">bento.FreeBSD.org</hostid>.</para>
|
||||
<hostid role="fqdn">pointyhat.FreeBSD.org</hostid>.</para>
|
||||
|
||||
<para>When adding an IP alias to an interface (using
|
||||
<command>ifconfig</command>) <emphasis>always</emphasis> use a
|
||||
netmask of <hostid role="netmask">255.255.255.255</hostid>
|
||||
(which can also be expressed as <hostid
|
||||
role="netmask">0xffffffff</hostid>.</para>
|
||||
role="netmask">0xffffffff</hostid>).</para>
|
||||
|
||||
<para>The MAC address uniquely identifies every network card
|
||||
in existence. A typical MAC address looks like <hostid
|
||||
|
|
@ -2064,7 +2061,7 @@ This is the file called 'foo2'</screen>
|
|||
<command>ifconfig</command>) <emphasis>always</emphasis> use a
|
||||
netmask of <hostid role="netmask">255.255.255.255</hostid> (which
|
||||
can also be expressed as <hostid
|
||||
role="netmask">0xffffffff</hostid>.</para>
|
||||
role="netmask">0xffffffff</hostid>).</para>
|
||||
|
||||
<para>The MAC address uniquely identifies every network card in
|
||||
existence. A typical MAC address looks like <hostid
|
||||
|
|
@ -2161,8 +2158,8 @@ This is the file called 'foo2'</screen>
|
|||
<title>Literal Text</title>
|
||||
|
||||
<para>You will often need to include <quote>literal</quote> text in the
|
||||
Handbook. This is text that is excerpted from another file, or
|
||||
which should be copied from the Handbook into another file
|
||||
documentation. This is text that is excerpted from another file, or
|
||||
which should be copied from the documentation into another file
|
||||
verbatim.</para>
|
||||
|
||||
<para>Some of the time, <sgmltag>programlisting</sgmltag> will be
|
||||
|
|
@ -2210,9 +2207,7 @@ This is the file called 'foo2'</screen>
|
|||
|
||||
<para>Use:</para>
|
||||
|
||||
<programlisting><![ CDATA [<informalexample>
|
||||
<screen>&prompt.user; <userinput>man <replaceable>command</replaceable></userinput></screen>
|
||||
</informalexample>]]></programlisting>
|
||||
<programlisting><![ CDATA [<screen>&prompt.user; <userinput>man <replaceable>command</replaceable></userinput></screen>]]></programlisting>
|
||||
|
||||
<para>Appearance:</para>
|
||||
|
||||
|
|
@ -2279,7 +2274,7 @@ This is the file called 'foo2'</screen>
|
|||
|
||||
<important>
|
||||
<para>Image support in the documentation is currently extremely
|
||||
experimental. I think the mechanisms described here are unlikely to
|
||||
experimental. The mechanisms described here are unlikely to
|
||||
change, but that is not guaranteed.</para>
|
||||
|
||||
<para>You will also need to install the
|
||||
|
|
@ -2464,7 +2459,7 @@ IMAGES+= fig3.png
|
|||
<filename>chapter1/chapter.sgml</filename>,
|
||||
<filename>chapter2/chapter.sgml</filename>, and
|
||||
<filename>chapter3/chapter.sgml</filename>. If each chapter has
|
||||
images associated with it, I suggest you place those images in each
|
||||
images associated with it, it is suggested to place those images in each
|
||||
chapter's subdirectory (<filename>chapter1/</filename>,
|
||||
<filename>chapter2/</filename>, and
|
||||
<filename>chapter3/</filename>).</para>
|
||||
|
|
|
|||
Loading…
Reference in a new issue