Fix some doc bugs found during its translation:

- Disable TOC generation in Makefile because in the original version it
  does not make too much sense to have a one-item TOC
- Change structure of sections, move all the sect2 to level sect1; this
  results shorter high-level sections, but it gives a more normal layout
- Mark up CUPS ports with <filename role="package"> to add Ports
  Collection links for them
- Mark up group "cups" with <groupname>
- Fix a <programlisting> within a <para> situation
- Replace <filename> tags with <ulink> for local CUPS web interface
  links
- Replace <literal> tags with <hostid> for "localhost"
- Mark up menu items with <quote> rather than <literal>
- Use <replaceable> elements where applicable
- Fix spelling
- Remove all verbatim quote symbols, replace them with <quote> elements
- Mark up make variables with <makevar> elements
- Mark up make targets with <maketarget> elements

Reviewed by:	Chess Griffin <chess (at) chessgriffin (dot) com>

en_US.ISO8859-1/articles/cups/Makefile

@@ -6,7 +6,6 @@
 DOC?= article
 
 FORMATS?= html
-WITH_ARTICLE_TOC?= YES
 
 INSTALL_COMPRESSED?=gz
 INSTALL_ONLY_COMPRESSED?=

en_US.ISO8859-1/articles/cups/article.sgml

@@ -11,7 +11,7 @@
     <authorgroup>
       <author>
 	<firstname>Chess</firstname>
-	<surname>Grifin</surname>
+	<surname>Griffin</surname>
 	<affiliation>
 	  <address><email>chess@chessgriffin.com</email></address>
 	</affiliation>
@@ -55,8 +55,9 @@
 
     <para>The main site for <application>CUPS</application> is <ulink
 	url="http://www.cups.org/"></ulink>.</para>
+  </sect1>
 
-    <sect2 id="printing-cups-install">
+    <sect1 id="printing-cups-install">
       <title>Installing the CUPS Print Server</title>
 
       <para><application>CUPS</application> can be installed from ports
@@ -73,15 +74,15 @@
       <screen>&prompt.root; <userinput>pkg_add -r cups</userinput></screen>
 
       <para>Other optional, but recommended, ports or packages are
-	<application>print/gutenprint-cups</application> and
+	<filename role="package">print/gutenprint-cups</filename> and
-	<application>print/hplip</application>, both of which add
+	<filename role="package">print/hplip</filename>, both of which add
 	drivers and utilities for a variety of printers.  Once
 	installed, the <application>CUPS</application> configuration
 	files can be found in the directory
 	<filename>/usr/local/etc/cups</filename>.</para>
-    </sect2>
+    </sect1>
 
-    <sect2 id="printing-cups-configuring-server">
+    <sect1 id="printing-cups-configuring-server">
       <title>Configuring the CUPS Print Server</title>
 
       <para>After installation, a few files must edited in order to
@@ -89,7 +90,7 @@
 	create or modify, as the case may be, the file
 	<filename>/etc/devfs.rules</filename> and add the following
 	information to set the proper permissions on all potential
-	printer devices and to associate printers with the cups user
+	printer devices and to associate printers with the <groupname>cups</groupname> user
 	group:</para>
 
       <programlisting>[system=10]
@@ -108,10 +109,12 @@ devfs_system_ruleset="system"</programlisting>
 	the local devfs rule created above, respectively.</para>
 
       <para>In order to enable <application>CUPS</application> printing
-	under certain &microsoft.windows; clients, the line
+	under certain &microsoft.windows; clients, the line below
-	<programlisting>application/octet-stream</programlisting> should be
+	should be
 	uncommented in <filename>/usr/local/etc/cups/mime.types</filename>
-	and <filename>/usr/local/etc/cups/mime.convs</filename>.</para>
+	and <filename>/usr/local/etc/cups/mime.convs</filename>:</para>
+
+      <programlisting>application/octet-stream</programlisting>
 
       <para>Once these changes have been made, the &man.devfs.8; and
 	<application>CUPS</application> systems must both be restarted,
@@ -121,9 +124,9 @@ devfs_system_ruleset="system"</programlisting>
       <screen>&prompt.root; <userinput>/etc/rc.d/devfs restart</userinput>
 &prompt.root; <userinput>/usr/local/etc/rc.d/cupsd restart</userinput></screen>
 
-    </sect2>
+    </sect1>
 
-    <sect2 id="printing-cups-configuring-printers">
+    <sect1 id="printing-cups-configuring-printers">
       <title>Configuring Printers on the CUPS Print Server</title>
 
       <para>After the <application>CUPS</application> system has been
@@ -137,11 +140,11 @@ devfs_system_ruleset="system"</programlisting>
       <para>The primary means for managing and administering the
 	<application>CUPS</application> server is through the web-based
 	interface, which can be found by launching a web browser and
-	entering <filename>http://localhost:631</filename> in the
+	entering <ulink url="http://localhost:631"></ulink> in the
 	browser's URL bar.  If the <application>CUPS</application>
 	server is on another machine on the network, substitute the
 	server's local <acronym>IP</acronym> addresss for
-	<literal>localhost</literal>. The <application>CUPS</application>
+	<hostid>localhost</hostid>. The <application>CUPS</application>
 	web interface is fairly self-explanatory, as there are sections
 	for managing printers and print jobs, authorizing users, and
 	more.  Additionally, on the right-hand side of the
@@ -153,21 +156,21 @@ devfs_system_ruleset="system"</programlisting>
 	privileges to the printers and print jobs.</para>
 
       <para>Adding a printer is generally as easy as clicking
-	<literal>Add Printer</literal> at the Administration screen of
+	<quote>Add Printer</quote> at the Administration screen of
 	the <application>CUPS</application> web interface, or clicking
-	one of the <literal>New Printers Found</literal> buttons also
+	one of the <quote>New Printers Found</quote> buttons also
 	at the Administration screen.  When presented with the
-	<literal>Device</literal> drop-down box, simply select the
+	<quote>Device</quote> drop-down box, simply select the
 	desired locally-attached printer, and then continue through the
 	process.  If one has added the
-	<application>print/gutenprint-cups</application> or
+	<filename role="package">print/gutenprint-cups</filename> or
-	<application>print/hplip</application> ports or packages as
+	<filename role="package">print/hplip</filename> ports or packages as
 	referenced above, then additional print drivers will be available
 	in the subsequent screens that might provide more stability or
 	features.</para>
-    </sect2>
+    </sect1>
 
-    <sect2 id="printing-cups-clients">
+    <sect1 id="printing-cups-clients">
       <title>Configuring CUPS Clients</title>
 
       <para>Once the <application>CUPS</application> server has been
@@ -178,7 +181,7 @@ devfs_system_ruleset="system"</programlisting>
 	desktop machine that is acting as both server and client, then
 	much of this information may not be needed.</para>
 
-      <sect3 id="printing-cups-clients-unix">
+      <sect2 id="printing-cups-clients-unix">
 	<title>&unix; Clients</title>
 
 	<para><application>CUPS</application> will also need to be
@@ -190,9 +193,9 @@ devfs_system_ruleset="system"</programlisting>
 	  <application>GNOME</application> or
 	  <application>KDE</application>.  Alternatively, one can access
 	  the local <application>CUPS</application> interface on the
-	  client machine at <filename>http://localhost:631</filename> and
+	  client machine at <ulink url="http://localhost:631"></ulink> and
-	  click on <literal>Add Printer</literal> in the Administration
+	  click on <quote>Add Printer</quote> in the Administration
-	  section.  When presented with the <literal>Device</literal>
+	  section.  When presented with the <quote>Device</quote>
 	  drop-down box, simply select the networked
 	  <application>CUPS</application> printer, if it was
 	  automatically discovered, or select <literal>ipp</literal> or
@@ -201,9 +204,9 @@ devfs_system_ruleset="system"</programlisting>
 	  <application>CUPS</application> printer, usually in one of the
 	  two following syntaxes:</para>
 
-	<programlisting>ipp://server-name-or-ip/printers/printername</programlisting>
+	<programlisting>ipp://<replaceable>server-name-or-ip</replaceable>/printers/<replaceable>printername</replaceable></programlisting>
 
-	<programlisting>http://server-name-or-ip:631/printers/printername</programlisting>
+	<programlisting>http://<replaceable>server-name-or-ip</replaceable>:631/printers/<replaceable>printername</replaceable></programlisting>
 
 	<para>If the <application>CUPS</application> clients have
 	  difficulty finding other <application>CUPS</application>
@@ -212,14 +215,14 @@ devfs_system_ruleset="system"</programlisting>
 	  <filename>/usr/local/etc/cups/client.conf</filename> with a
 	  single entry as follows:</para>
 
-	<programlisting>ServerName (server-ip)</programlisting>
+	<programlisting>ServerName <replaceable>server-ip</replaceable></programlisting>
 
-	<para>In this case, (server-ip) would be replaced by the local
+	<para>In this case, <replaceable>server-ip</replaceable> would be replaced by the local
 	  <acronym>IP</acronym> address of the
 	  <application>CUPS</application> server on the network.</para>
-      </sect3>
+      </sect2>
 
-      <sect3 id="printing-cups-clients-windows">
+      <sect2 id="printing-cups-clients-windows">
 	<title>&windows; Clients</title>
 
 	<para>Versions of &windows; prior to XP did not have the
@@ -233,7 +236,7 @@ devfs_system_ruleset="system"</programlisting>
 	    Printer</literal> and then enter the <acronym>URI</acronym>
 	  in the following syntax:</para>
 
-	<programlisting>http://server-name-or-ip:631/printers/printername</programlisting>
+	<programlisting>http://<replaceable>server-name-or-ip</replaceable>:631/printers/<replaceable>printername</replaceable></programlisting>
 
 	<para>If one has an older version of &windows; without native
 	  <acronym>IPP</acronym> printing support, then the general
@@ -242,19 +245,19 @@ devfs_system_ruleset="system"</programlisting>
 	  <filename role="package">net/samba3</filename> and
 	  <application>CUPS</application> together, which is a topic
 	  outside the scope of this chapter.</para>
-      </sect3>
       </sect2>
+    </sect1>
 
-    <sect2 id="printing-cups-troubleshooting">
+    <sect1 id="printing-cups-troubleshooting">
       <title>CUPS Troubleshooting</title>
 
       <para>Difficulties with <application>CUPS</application> often lies
 	in permissions.  First, double check the &man.devfs.8;
 	permissions as outlined above.  Next, check the actual
-	permissions of the devices created in the filesystem.  It is
+	permissions of the devices created in the file system.  It is
 	also helpful to make sure your user is a member of the
-	<literal>cups</literal> group.  If the permissions check boxes
+	<groupname>cups</groupname> group.  If the permissions check boxes
-	in the <literal>Administration</literal> section of the
+	in the Administration section of the
 	<application>CUPS</application> web interface do not seem to be
 	working, another fix might be to manually backup the main
 	<application>CUPS</application> configuration file located at
@@ -348,32 +351,31 @@ CUPS-Delete-Class CUPS-Accept-Jobs CUPS-Reject-Jobs CUPS-Set-Default&gt;
     Order deny,allow
   &lt;/Limit&gt;
 &lt;/Policy&gt;</programlisting>
-    </sect2>
+    </sect1>
 
-    <sect2 id="printing-cups-ports-knobs">
+    <sect1 id="printing-cups-ports-knobs">
       <title>Fine Tuning CUPS-Related Ports</title>
 
       <para>If <application>CUPS</application> is going to serve as the
 	primary printing system, then one may choose to optionally add
 	certain knobs to <filename>/etc/make.conf</filename> that will
 	emphasize <application>CUPS</application> over other printing
-	options.  Some of these "knobs" that one may want to add
+	options.  Some of these <quote>knobs</quote> that one may want to add
 	are:</para>
 
       <programlisting>WITH_CUPS=YES
 CUPS_OVERWRITE_BASE=YES
 WITHOUT_LPR=YES</programlisting>
 
-      <para>The first knob, WITH_CUPS, adds
+      <para>The first knob, <makevar>WITH_CUPS</makevar>, adds
 	<application>CUPS</application> support to ports where
-	applicable.  The second knob, CUPS_OVERWRITE_BASE, will fix
+	applicable.  The second knob, <makevar>CUPS_OVERWRITE_BASE</makevar>, will fix
 	certain symlinks and paths that would otherwise apply to the
 	default &os; printing system, <application>LPR</application>,
 	and will prevent these fixes from being reverted upon the next
-	"buildworld" system upgrade.  The third knob, WITHOUT_LPR, will
+	<maketarget>buildworld</maketarget> system upgrade.  The third knob, <makevar>WITHOUT_LPR</makevar>, will
 	prevent <application>LPR</application> support from being added
 	to ports where applicable.</para>
-    </sect2>
     </sect1>
 </article>