Merge changes from CUPS 1.4svn-r8252.
git-svn-id: svn+ssh://src.apple.com/svn/cups/easysw/current@1123 a1ca3aef-8c08-0410-bb20-df032aa958be
diff --git a/doc/Makefile b/doc/Makefile
index bf8bca0..0c894af 100644
--- a/doc/Makefile
+++ b/doc/Makefile
@@ -104,6 +104,7 @@
help/ref-snmp-conf.html \
help/ref-subscriptions-conf.html \
help/security.html \
+ help/sharing.html \
help/spec-banner.html \
help/spec-browsing.html \
help/spec-cmp.html \
diff --git a/doc/help/api-array.html b/doc/help/api-array.html
index f7373e3..1916f3d 100644
--- a/doc/help/api-array.html
+++ b/doc/help/api-array.html
@@ -388,8 +388,8 @@
<li><a href="#cupsArrayNext" title="Get the next element in the array.">cupsArrayNext</a></li>
<li><a href="#cupsArrayPrev" title="Get the previous element in the array.">cupsArrayPrev</a></li>
<li><a href="#cupsArrayRemove" title="Remove an element from the array.">cupsArrayRemove</a></li>
-<li><a href="#cupsArrayRestore" title="Reset the current element to the last <a href="#cupsArraySave"><code>cupsArraySave</code></a>.">cupsArrayRestore</a></li>
-<li><a href="#cupsArraySave" title="Mark the current element for a later <a href="#cupsArrayRestore"><code>cupsArrayRestore</code></a>.">cupsArraySave</a></li>
+<li><a href="#cupsArrayRestore" title="Reset the current element to the last cupsArraySave.">cupsArrayRestore</a></li>
+<li><a href="#cupsArraySave" title="Mark the current element for a later cupsArrayRestore.">cupsArraySave</a></li>
<li><a href="#cupsArrayUserData" title="Return the user data for an array.">cupsArrayUserData</a></li>
</ul></li>
<li><a href="#TYPES">Data Types</a><ul class="code">
diff --git a/doc/help/api-ppd.html b/doc/help/api-ppd.html
index 3da1d96..98b81f3 100644
--- a/doc/help/api-ppd.html
+++ b/doc/help/api-ppd.html
@@ -375,6 +375,7 @@
<li><a href="#ATTRIBUTES">Attributes</a></li>
</ul></li>
<li><a href="#FUNCTIONS">Functions</a><ul class="code">
+<li><a href="#cupsGetConflicts" title="Get a list of conflicting options in a marked PPD.">cupsGetConflicts</a></li>
<li><a href="#cupsMarkOptions" title="Mark command-line options in a PPD file.">cupsMarkOptions</a></li>
<li><a href="#cupsResolveConflicts" title="Resolve conflicts in a marked PPD.">cupsResolveConflicts</a></li>
<li><a href="#ppdClose" title="Free all memory used by the PPD file.">ppdClose</a></li>
@@ -689,6 +690,39 @@
puts(attr->value);
</pre>
<h2 class="title"><a name="FUNCTIONS">Functions</a></h2>
+<h3 class="function"><span class="info"> CUPS 1.4 </span><a name="cupsGetConflicts">cupsGetConflicts</a></h3>
+<p class="description">Get a list of conflicting options in a marked PPD.</p>
+<p class="code">
+int cupsGetConflicts (<br>
+ <a href="#ppd_file_t">ppd_file_t</a> *ppd,<br>
+ const char *option,<br>
+ const char *choice,<br>
+ cups_option_t **options<br>
+);</p>
+<h4 class="parameters">Parameters</h4>
+<dl>
+<dt>ppd</dt>
+<dd class="description">PPD file</dd>
+<dt>option</dt>
+<dd class="description">Option to test</dd>
+<dt>choice</dt>
+<dd class="description">Choice to test</dd>
+<dt>options</dt>
+<dd class="description">Conflicting options</dd>
+</dl>
+<h4 class="returnvalue">Return Value</h4>
+<p class="description">Number of conflicting options</p>
+<h4 class="discussion">Discussion</h4>
+<p class="discussion">This function gets a list of options that would conflict if "option" and
+"choice" were marked in the PPD. You would typically call this function
+after marking the currently selected options in the PPD in order to
+determine whether a new option selection would cause a conflict.<br>
+<br>
+The number of conflicting options are returned with "options" pointing to
+the conflicting options. The returned option array must be freed using
+<a href="#cupsFreeOptions"><code>cupsFreeOptions</code></a>.
+
+</p>
<h3 class="function"><a name="cupsMarkOptions">cupsMarkOptions</a></h3>
<p class="description">Mark command-line options in a PPD file.</p>
<p class="code">
diff --git a/doc/help/ref-cupsd-conf.html.in b/doc/help/ref-cupsd-conf.html.in
index 33b6693..6c51b9d 100644
--- a/doc/help/ref-cupsd-conf.html.in
+++ b/doc/help/ref-cupsd-conf.html.in
@@ -559,7 +559,9 @@
BrowseLocalProtocols cups
BrowseLocalProtocols dnssd
BrowseLocalProtocols ldap
+BrowseLocalProtocols lpd
BrowseLocalProtocols slp
+BrowseLocalProtocols smb
BrowseLocalProtocols cups dnssd
</PRE>
@@ -568,7 +570,7 @@
<P>The <CODE>BrowseLocalProtocols</CODE> directive specifies the
protocols to use when advertising local shared printers on the
network. Multiple protocols can be specified by separating them
-with spaces. The default is <CODE>@CUPS_BROWSE_REMOTE_PROTOCOLS@</CODE>.</P>
+with spaces. The default is "<CODE>@CUPS_BROWSE_LOCAL_PROTOCOLS@</CODE>".</P>
<H2 CLASS="title"><A NAME="BrowseOrder">BrowseOrder</A></H2>
@@ -652,7 +654,9 @@
BrowseProtocols cups
BrowseProtocols dnssd
BrowseProtocols ldap
+BrowseProtocols lpd
BrowseProtocols slp
+BrowseProtocols smb
BrowseProtocols cups dnssd
</PRE>
@@ -662,9 +666,9 @@
protocols to use when showing and advertising shared printers on
the local network. Multiple protocols can be specified by
separating them with spaces. The default protocol is
-<CODE>@CUPS_BROWSE_LOCAL_PROTOCOLS@</CODE> for
+"<CODE>@CUPS_BROWSE_LOCAL_PROTOCOLS@</CODE>" for
<A HREF="#BrowseLocalProtocols"><CODE>BrowseLocalProtocols</CODE></A> and
-<CODE>@CUPS_BROWSE_REMOTE_PROTOCOLS@</CODE> for
+"<CODE>@CUPS_BROWSE_REMOTE_PROTOCOLS@</CODE>" for
<A HREF="#BrowseRemoteProtocols"><CODE>BrowseRemoteProtocols</CODE></A>.</P>
<BLOCKQUOTE><B>Note:</B>
@@ -736,10 +740,8 @@
BrowseRemoteProtocols all
BrowseRemoteProtocols none
BrowseRemoteProtocols cups
-BrowseRemoteProtocols dnssd
BrowseRemoteProtocols ldap
BrowseRemoteProtocols slp
-BrowseRemoteProtocols cups dnssd
</PRE>
<H3>Description</H3>
@@ -747,7 +749,7 @@
<P>The <CODE>BrowseRemoteProtocols</CODE> directive specifies the
protocols to use when finding remote shared printers on the
network. Multiple protocols can be specified by separating them
-with spaces. The default is <CODE>@CUPS_BROWSE_REMOTE_PROTOCOLS@</CODE>.</P>
+with spaces. The default is "<CODE>@CUPS_BROWSE_REMOTE_PROTOCOLS@</CODE>".</P>
<H2 CLASS="title"><A NAME="BrowseShortNames">BrowseShortNames</A></H2>
diff --git a/doc/help/sharing.html b/doc/help/sharing.html
new file mode 100644
index 0000000..29bb757
--- /dev/null
+++ b/doc/help/sharing.html
@@ -0,0 +1,181 @@
+<html>
+<!-- SECTION: Getting Started -->
+<head>
+ <title>Printer Sharing</title>
+</head>
+<body>
+
+<p>This document discusses several ways to configure printer sharing.</p>
+
+<h2><a name="BASICS">The Basics</h2>
+
+<p>A "server" is any machine that communicates directly to a printer. A "client"
+is any machine that sends print jobs to a server for final printing. Clients can
+also be servers if they communicate directly with any printers of their own.</p>
+
+<p>By default, CUPS uses the Internet Printing Protocol (IPP) to send jobs from
+a client to a server. When printing to legacy print servers you may also use the
+Line Printer Daemon (LPD) when printing to older UNIX-based servers or Server
+Message Block (SMB) when printing to Windows<sup>®</sup> servers.</p>
+
+<p>Clients can automatically discover and access shared printers via CUPS
+browsing, IPP, Service Location Protocol (SLP), and Lightweight Directory Access
+Protocol (LDAP). DNS Service Discovery (DNS-SD a.k.a. Bonjour<sup>®</sup>)
+and SMB browsing can also be used to manually discover and access shared
+printers.</p>
+
+
+<h2><a name="SERVER_CONFIG">Configuring the Server</a></h2>
+
+<p>You must enable printer sharing on the server before clients can print
+through it. The simplest way to do this is to use the
+<a href="man-cupsctl.html">cupsctl(8)</a> command on the server:</p>
+
+<pre class="command">
+cupsctl --share-printers
+</pre>
+
+<p>By default, the above command will allow printing from other clients on the
+same subnet as your server. To allow printing from any subnet, use the following
+command instead:</p>
+
+<pre class="command">
+cupsctl --share-printers --remote-any
+</pre>
+
+<p>Next, you need to choose which protocols to use for printer sharing. The
+default is CUPS browsing and DNS-SD on Mac OS X and CUPS browsing alone on
+other platforms. To set the sharing protocols, run the <b>cupsctl</b> command
+to set the
+<a href="ref-cupsd-conf.html#BrowseLocalProtocols">BrowseLocalProtocols</a>
+value. For example, run the following command to allow shared printing via
+CUPS, DNS-SD, LPD, and SMB:</p>
+
+<pre class="command">
+cupsctl 'BrowseLocalProtocols="cups dnssd lpd smb"'
+</pre>
+
+
+<h2><a name="AUTO_CUPS">Automatic Configuration using CUPS Browsing</a></h2>
+
+<p>CUPS browsing works by periodically broadcasting information about printers
+that are being shared to client systems on the same subnet. Each client
+maintains its own list of shared printers, and when more than one server shares
+the same printer (or the same kind of printer) the client uses all of the
+servers and printers to provide high-availability and failsafe printing.</p>
+
+<p>To configure printers on the same subnet, <em>do nothing</em>. Each client
+should see the available printers within 30 seconds automatically. The printer
+and class lists are updated automatically as printers and servers are added or
+removed.</p>
+
+<blockquote><b>Note:</b>
+
+<p>Due to user interface changes in Mac OS X 10.5, CUPS shared printers will not
+automatically appear in the print dialog. Instead, you must first run the
+following command to enable CUPS browsing on your system:</p>
+
+<pre class="command">
+cupsctl BrowseRemoteProtocols=cups
+</pre>
+
+<p>Then choose each of the CUPS shared printers you want to see in the print
+dialog by adding them, either from the <var>Add Printer...</var> item in the
+print dialog or from the <var>Print & Fax</var> preference pane in the
+<var>System Preferences</var> window.</p>
+
+</blockquote>
+
+<h3><a name="BROWSE_POLL">Seeing Printers on Other Subnets</a></h3>
+
+<p>You can automatically access printers on other subnets by adding
+<a href="ref-cupsd-conf.html#BrowsePoll"><code>BrowsePoll</code></a> lines
+to the <var>cupsd.conf</var> file on your local system. For a single
+server you can use the <b>cupsctl</b> command:</p>
+
+<pre class="command">
+cupsctl BrowsePoll=server:port
+</pre>
+
+<p>For multiple servers, use the CUPS web interface (http://localhost:631/admin)
+to edit the configuration file instead. Enter one <code>BrowsePoll</code> line
+per server at the bottom of the file, as follows:</p>
+
+<pre class="example">
+BrowsePoll server1:port
+BrowsePoll server2:port
+BrowsePoll server3:port
+</pre>
+
+<p>If you have more than one client on your subnet that wants to see the
+printers on those servers, add a
+<a href="ref-cupsd-conf.html#BrowseRelay"><code>BrowseRely</code></a> line
+to the <var>cupsd.conf</var> file on your local system using the <b>cupsctl</b>
+command:</p>
+
+<pre class="command">
+cupsctl 'BrowseRelay="127.0.0.1 @LOCAL"'
+</pre>
+
+<p>or CUPS web interface (again, at the bottom of the file):</p>
+
+<pre class="example">
+BrowseRelay 127.0.0.1 @LOCAL
+</pre>
+
+
+<h2><a name="AUTO_IPP">Automatic Configuration using IPP</a></h2>
+
+<p>CUPS can be configured to run without a local spooler and send all jobs to a
+single server. However, if that server goes down then all printing will be
+disabled. Use this configuration only as absolutely necessary.</p>
+
+<p>The default server is normally the local system ("localhost"). To override
+the default server create a file named <var>/etc/cups/client.conf</var> with a
+line as follows:</p>
+
+<pre class='example'>
+ServerName <em>server</em>
+</pre>
+
+<p>The <var>server</var> name can be the hostname or IP address of the default
+server. If the server is not using the default IPP port (631), you can add the
+port number at the end like this:</p>
+
+<pre class='example'>
+ServerName <em>server:port</em>
+</pre>
+
+<p>The default server can also be customized on a per-user basis. To set a
+user-specific server create a file named <var>~/.cups/client.conf</var> instead.
+The user <var>client.conf</var> file takes precedence over the system one.</p>
+
+<p>Finally, you can set the <code>CUPS_SERVER</code> environment variable to
+override the default server for a single process, for example:</p>
+
+<pre class='command'>
+CUPS_SERVER=server:port firefox http://www.cups.org
+</pre>
+
+<p>will run the Firefox web browser pointed to the specified server and
+port. The environment variable overrides both the user and system
+<var>client.conf</var> files, if any.</p>
+
+
+<h2><a name="MANUAL">Manual Configuration of Print Queues</a></h2>
+
+<p>The most tedious method of configuring client machines is to configure
+each remote queue by hand using the <a href="man-lpadmin.html">lpadmin(8)</a>
+command:</p>
+
+<pre class='command'>
+lpadmin -p <em>printer</em> -E -v ipp://<em>server</em>/printers/<em>printer</em>
+</pre>
+
+<p>The <var>printer</var> name is the name of the printer on the server machine.
+The <var>server</var> name is the hostname or IP address of the server machine.
+Repeat the <b>lpadmin</b> command for each remote printer you wish to use.</p>
+
+
+</body>
+</html>
diff --git a/doc/help/spec-ipp.html b/doc/help/spec-ipp.html
index 70db037..70a3031 100644
--- a/doc/help/spec-ipp.html
+++ b/doc/help/spec-ipp.html
@@ -438,7 +438,7 @@
<dd>The required authentication information.
-</dl
+</dl>
<h3 class='title'><span class='info'>CUPS 1.1</span><a name='CREATE_JOB'>Create-Job Operation</a></h3>
@@ -543,7 +543,7 @@
<dd>The required authentication information.
-</dl
+</dl>
<h3 class='title'><a name='CANCEL_JOB'>Cancel Job Operation</a></h3>
@@ -1867,7 +1867,7 @@
<dd>The required authentication information.
-</dl
+</dl>
<h3 class='title'><span class='info'>CUPS 1.3</span><a name='CUPS_GET_PPD'>CUPS-Get-PPD Operation</a></h3>
