Author: wblock
Date: Sun Dec 8 22:15:15 2013
New Revision: 43309
URL: http://svnweb.freebsd.org/changeset/doc/43309
Log:
Improve examples of filename and package tag use.
Modified:
head/en_US.ISO8859-1/books/fdp-primer/docbook-markup/chapter.xml
Modified: head/en_US.ISO8859-1/books/fdp-primer/docbook-markup/chapter.xml
==============================================================================
--- head/en_US.ISO8859-1/books/fdp-primer/docbook-markup/chapter.xml Sun Dec 8 20:39:07 2013 (r43308)
+++ head/en_US.ISO8859-1/books/fdp-primer/docbook-markup/chapter.xml Sun Dec 8 22:15:15 2013 (r43309)
@@ -1558,28 +1558,30 @@ This is the file called 'foo2'</screen>
<title>Files, Directories, Extensions</title>
<para>To refer to the name of a file, a directory, or a file
- extension, use <tag>filename</tag>.</para>
+ extension, use <tag>filename</tag>. For directory names, set
+ the <literal>class</literal> attribute to
+ <literal>directory</literal>.</para>
<example>
<title><tag>filename</tag></title>
<para>Usage:</para>
- <programlisting><tag class="starttag">para</tag>The XML source for the Handbook in English is
- found in <tag class="starttag">filename class="directory"</tag>/usr/doc/en_US.ISO8859-1/books/handbook/<tag class="endtag">filename</tag>. The first
- file is called <tag class="starttag">filename</tag>book.xml<tag class="endtag">filename</tag> in that
- directory. There is also a <tag class="starttag">filename</tag>Makefile<tag class="endtag">filename</tag>
- and a number of files with a <tag class="starttag">filename</tag>.ent<tag class="endtag">filename</tag>
- extension.<tag class="endtag">para</tag></programlisting>
+ <programlisting><tag class="starttag">para</tag>The source for the Handbook in English is found in
+ <tag class="starttag">filename
+ class="directory"</tag>/usr/doc/en_US.ISO8859-1/books/handbook/<tag class="endtag">filename</tag>.
+ The main file is called <tag class="starttag">filename</tag>book.xml<tag class="endtag">filename</tag>.
+ There is also a <tag class="starttag">filename</tag>Makefile<tag class="endtag">filename</tag> and a
+ number of files with a <tag class="starttag">filename</tag>.ent<tag class="endtag">filename</tag> extension.<tag class="endtag">para</tag></programlisting>
<para>Appearance:</para>
- <para>The XML source for the Handbook in English can be
- found in <filename>/usr/doc/en/handbook/</filename>. The
- first file is called <filename>handbook.xml</filename> in
- that directory. There is also a
- <filename>Makefile</filename> and a number of files with a
- <filename>.ent</filename> extension.</para>
+ <para>The source for the Handbook in English is found in
+ <filename
+ class="directory">usr/doc/en_US.ISO8859-1/books/handbook/</filename>.
+ The main file is called <filename>book.xml</filename>.
+ There is also a <filename>Makefile</filename> and a number
+ of files with a <filename>.ent</filename> extension.</para>
</example>
</sect2>
@@ -1596,22 +1598,35 @@ This is the file called 'foo2'</screen>
<para>To include the name of a program from the &os;
Ports Collection in the document, use the
- <tag>package</tag> tag. Since ports can be installed in
+ <tag>package</tag> tag. Since the Ports Collection can be installed in
any number of locations, only include the category and the
port name; do not include
<filename>/usr/ports</filename>.</para>
+ <para>By default, <tag>package</tag> refers to a binary package.
+ To refer to a port that will be built from source, set the
+ <literal>role</literal> attribute to
+ <literal>port</literal>.</para>
+
<example>
<title><tag>package</tag> Tag</title>
<para>Usage:</para>
- <programlisting><tag class="starttag">para</tag>Install the <tag class="starttag">package</tag>net/wireshark<tag class="endtag">package</tag> port to view network traffic.<tag class="endtag">para</tag></programlisting>
+ <programlisting><tag class="starttag">para</tag>Install the <tag class="starttag">package</tag>net/wireshark<tag class="endtag">package</tag> binary
+ package to view network traffic.<tag class="endtag">para</tag>
+
+<tag class="starttag">para</tag><tag class="starttag">package role="port"</tag>net/wireshark<tag class="endtag">package</tag> can also be
+ built and installed from the Ports Collection.<tag class="endtag">para</tag></programlisting>
<para>Appearance:</para>
- <para>Install the <package>net/wireshark</package> port to
+ <para>Install the <package>net/wireshark</package> binary
+ package to
view network traffic.</para>
+
+ <para><package role="port">net/wireshark</package> can also be
+ built and installed from the Ports Collection.</para>
</example>
</sect2>
@@ -2330,7 +2345,7 @@ IMAGES+= fig3.png
names in the <varname>IMAGES</varname> variable in the
<filename>Makefile</filename>, <emphasis>and</emphasis>
including the directory name in the <tag>imagedata</tag>
- element in the document document.</para>
+ element in the document.</para>
<para>For example, if the book has
<filename>chapter1/fig1.png</filename>, then