Update the cups-files.conf and cupsd.conf file documentation for missing

directives (Issue #5084)

CHANGES.md

@@ -26,6 +26,8 @@ CHANGES IN CUPS V2.2.5
   values (Issue #5074)
 - The scheduler now creates a PID file when not running on demand with a modern
   service launcher (Issue #5080)
+- Updated the cups-files.conf and cupsd.conf file documentation for missing
+  directives (Issue #5084)
 - Fixed an Avahi-related crash bug in the scheduler (Issue #5085, Issue #5086)
 - The IPP Everywhere PPD generator now sorts the supported resolutions before
   choosing them for draft, normal, and best quality modes (Issue #5091)

doc/help/man-cups-files.conf.html

@@ -36,6 +36,9 @@ <h3><a name="DIRECTIVES">Directives</a></h3>
 
 </pre>
 The default is "/var/log/cups/access_log".
+<dt><a name="CacheDir"></a><b>CacheDir </b><i>directory</i>
+<dd style="margin-left: 5.0em">Specifies the directory to use for long-lived temporary (cache) files.
+The default is "/var/spool/cups/cache" or "/var/cache/cups" depending on the platform.
 <dt><a name="ConfigFilePerm"></a><b>ConfigFilePerm </b><i>mode</i>
 <dd style="margin-left: 5.0em">Specifies the permissions for all configuration files that the scheduler writes.
 The default is "0644" on macOS and "0640" on all other operating systems.
@@ -137,6 +140,9 @@ <h3><a name="DIRECTIVES">Directives</a></h3>
 <dt><a name="ServerRoot"></a><b>ServerRoot </b><i>directory</i>
 <dd style="margin-left: 5.0em">Specifies the directory containing the server configuration files.
 The default is "/etc/cups".
+<dt><a name="StateDir"></a><b>StateDir </b><i>directory</i>
+<dd style="margin-left: 5.0em">Specifies the directory to use for PID and local certificate files.
+The default is "/var/run/cups" or "/etc/cups" depending on the platform.
 <dt><a name="SyncOnClose"></a><b>SyncOnClose Yes</b>
 <dd style="margin-left: 5.0em"><dt><b>SyncOnClose No</b>
 <dd style="margin-left: 5.0em">Specifies whether the scheduler calls
@@ -147,12 +153,35 @@ <h3><a name="DIRECTIVES">Directives</a></h3>
 <dd style="margin-left: 5.0em">Specifies the group(s) to use for <i>@SYSTEM</i> group authentication.
 The default contains "admin", "lpadmin", "root", "sys", and/or "system".
 <dt><a name="TempDir"></a><b>TempDir </b><i>directory</i>
-<dd style="margin-left: 5.0em">Specifies the directory where temporary files are stored.
+<dd style="margin-left: 5.0em">Specifies the directory where short-term temporary files are stored.
 The default is "/var/spool/cups/tmp".
 <dt><a name="User"></a><b>User </b><i>username</i>
 <dd style="margin-left: 5.0em">Specifies the user name or ID that is used when running external programs.
 The default is "lp".
 </dl>
+<h3><a name="DEPRECATED_DIRECTIVES">Deprecated Directives</a></h3>
+The following directives are deprecated and will be removed from a future version of CUPS:
+<dl class="man">
+<dt><a name="FontPath"></a><b>FontPath </b><i>directory[:...:directoryN]</i>
+<dd style="margin-left: 5.0em">Specifies a colon separated list of directories where fonts can be found.
+On Linux the
+<b>font-config</b>(1)
+mechanism is used instead.
+On macOS the Font Book application manages system-installed fonts.
+<dt><a name="LPDConfigFile"></a><b> LPDConfigFile </b><i>filename</i>
+<dd style="margin-left: 5.0em">Specifies the LPD service configuration file to update.
+<dt><a name="Printcap"></a><b>Printcap </b><i>filename</i>
+<dd style="margin-left: 5.0em">Specifies a file that is filled with a list of local print queues.
+<dt><a name="PrintcapFormat"></a><b>PrintcapFormat bsd</b>
+<dd style="margin-left: 5.0em"><dt><b>PrintcapFormat plist</b>
+<dd style="margin-left: 5.0em"><dt><b>PrintcapFormat solaris</b>
+<dd style="margin-left: 5.0em">Specifies the format to use for the Printcap file.
+"bsd" is the historical LPD printcap file format.
+"plist" is the Apple plist file format.
+"solaris" is the historical Solaris LPD printcap file format.
+<dt><a name="SMBConfigFile"></a><b>SMBConfigFile </b><i>filename</i>
+<dd style="margin-left: 5.0em">Specifies the SMB service configuration file to update.
+</dl>
 <h2 class="title"><a name="SEE_ALSO">See Also</a></h2>
 <a href="man-classes.conf.html?TOPIC=Man+Pages"><b>classes.conf</b>(5),</a>
 <a href="man-cups.html?TOPIC=Man+Pages"><b>cups</b>(1),</a>

doc/help/man-cupsd.conf.html

@@ -56,16 +56,6 @@ <h3><a name="TOP_LEVEL_DIRECTIVES">Top-level Directives</a></h3>
 <dd style="margin-left: 5.0em"><br>
 Specifies whether shared printers are advertised.
 The default is "No".
-<dt><a name="Classification"></a><b>Classification </b><i>banner</i>
-<dd style="margin-left: 5.0em"><br>
-Specifies the security classification of the server.
-Any valid banner name can be used, including "classified", "confidential", "secret", "topsecret", and "unclassified", or the banner can be omitted to disable secure printing functions.
-The default is no classification banner.
-<dt><a name="ClassifyOverride"></a><b>ClassifyOverride Yes</b>
-<dd style="margin-left: 5.0em"><dt><b>ClassifyOverride No</b>
-<dd style="margin-left: 5.0em"><br>
-Specifies whether users may override the classification (cover page) of individual print jobs using the "job-sheets" option.
-The default is "No".
 <dt><a name="DefaultAuthType"></a><b>DefaultAuthType Basic</b>
 <dd style="margin-left: 5.0em"><dt><b>DefaultAuthType Negotiate</b>
 <dd style="margin-left: 5.0em"><br>
@@ -230,24 +220,6 @@ <h3><a name="TOP_LEVEL_DIRECTIVES">Top-level Directives</a></h3>
 <dt><a name="MultipleOperationTimeout"></a><b>MultipleOperationTimeout </b><i>seconds</i>
 <dd style="margin-left: 5.0em">Specifies the maximum amount of time to allow between files in a multiple file print job.
 The default is "300" (5 minutes).
-<dt><a name="PageLogFormat"></a><b>PageLogFormat </b><i>format-string</i>
-<dd style="margin-left: 5.0em">Specifies the format of PageLog lines.
-Sequences beginning with percent (%) characters are replaced with the corresponding information, while all other characters are copied literally.
-The following percent sequences are recognized:
-<pre class="man">
-
-    "%%" inserts a single percent character.
-    "%{name}" inserts the value of the specified IPP attribute.
-    "%C" inserts the number of copies for the current page.
-    "%P" inserts the current page number.
-    "%T" inserts the current date and time in common log format.
-    "%j" inserts the job ID.
-    "%p" inserts the printer name.
-    "%u" inserts the username.
-
-</pre>
-The default is the empty string, which disables page logging.
-The string "%p %u %j %T %P %C %{job-billing} %{job-originating-host-name} %{job-name} %{media} %{sides}" creates a page log with the standard items.
 <dt><a name="PassEnv"></a><b>PassEnv </b><i>variable </i>[ ... <i>variable </i>]
 <dd style="margin-left: 5.0em">Passes the specified environment variable(s) to child processes.
 <dt><a name="Policy"></a><b>&lt;Policy </b><i>name</i><b>> </b>... <b>&lt;/Policy></b>
@@ -270,9 +242,6 @@ <h3><a name="TOP_LEVEL_DIRECTIVES">Top-level Directives</a></h3>
 <dt><a name="ReloadTimeout"></a><b>ReloadTimeout </b><i>seconds</i>
 <dd style="margin-left: 5.0em">Specifies the amount of time to wait for job completion before restarting the scheduler.
 The default is "30".
-<dt><a name="RIPCache"></a><b>RIPCache </b><i>size</i>
-<dd style="margin-left: 5.0em">Specifies the maximum amount of memory to use when converting documents into bitmaps for a printer.
-The default is "128m".
 <dt><a name="ServerAdmin"></a><b>ServerAdmin </b><i>email-address</i>
 <dd style="margin-left: 5.0em">Specifies the email address of the server administrator.
 The default value is "root@ServerName".
@@ -567,6 +536,41 @@ <h3><a name="DIRECTIVES_VALID_WITHIN_POLICY_SECTIONS">Directives Valid Within Po
 <dd style="margin-left: 5.0em">Specifies the list of subscription values to make private.
 The "default" values are "notify-events", "notify-pull-method", "notify-recipient-uri", "notify-subscriber-user-name", and "notify-user-data".
 </dl>
+<h3><a name="DEPRECATED_DIRECTIVES">Deprecated Directives</a></h3>
+The following directives are deprecated and will be removed in a future release of CUPS:
+<dl class="man">
+<dt><a name="Classification"></a><b>Classification </b><i>banner</i>
+<dd style="margin-left: 5.0em"><br>
+Specifies the security classification of the server.
+Any valid banner name can be used, including "classified", "confidential", "secret", "topsecret", and "unclassified", or the banner can be omitted to disable secure printing functions.
+The default is no classification banner.
+<dt><a name="ClassifyOverride"></a><b>ClassifyOverride Yes</b>
+<dd style="margin-left: 5.0em"><dt><b>ClassifyOverride No</b>
+<dd style="margin-left: 5.0em"><br>
+Specifies whether users may override the classification (cover page) of individual print jobs using the "job-sheets" option.
+The default is "No".
+<dt><a name="PageLogFormat"></a><b>PageLogFormat </b><i>format-string</i>
+<dd style="margin-left: 5.0em">Specifies the format of PageLog lines.
+Sequences beginning with percent (%) characters are replaced with the corresponding information, while all other characters are copied literally.
+The following percent sequences are recognized:
+<pre class="man">
+
+    "%%" inserts a single percent character.
+    "%{name}" inserts the value of the specified IPP attribute.
+    "%C" inserts the number of copies for the current page.
+    "%P" inserts the current page number.
+    "%T" inserts the current date and time in common log format.
+    "%j" inserts the job ID.
+    "%p" inserts the printer name.
+    "%u" inserts the username.
+
+</pre>
+The default is the empty string, which disables page logging.
+The string "%p %u %j %T %P %C %{job-billing} %{job-originating-host-name} %{job-name} %{media} %{sides}" creates a page log with the standard items.
+<dt><a name="RIPCache"></a><b>RIPCache </b><i>size</i>
+<dd style="margin-left: 5.0em">Specifies the maximum amount of memory to use when converting documents into bitmaps for a printer.
+The default is "128m".
+</dl>
 <h2 class="title"><a name="CONFORMING_TO">Conforming To</a></h2>
 The <b>cupsd.conf</b> file format is based on the Apache HTTP Server configuration file format.
 <h2 class="title"><a name="EXAMPLES">Examples</a></h2>

man/cups-files.conf.man.in

@@ -1,7 +1,7 @@
 .\"
 .\" cups-files.conf man page for CUPS.
 .\"
-.\" Copyright 2007-2016 by Apple Inc.
+.\" Copyright 2007-2017 by Apple Inc.
 .\" Copyright 1997-2006 by Easy Software Products.
 .\"
 .\" These coded instructions, statements, and computer programs are the
@@ -10,7 +10,7 @@
 .\" which should have been included with this file.  If this file is
 .\" file is missing or damaged, see the license at "http://www.cups.org/".
 .\"
-.TH cups-files.conf 5 "CUPS" "19 September 2016" "Apple Inc."
+.TH cups-files.conf 5 "CUPS" "28 August 2017" "Apple Inc."
 .SH NAME
 cups\-files.conf \- file and directory configuration file for cups
 .SH DESCRIPTION
@@ -45,6 +45,11 @@ The server name may be included in filenames using the string "%s", for example:
 
 .fi
 The default is "/var/log/cups/access_log".
+.\"#CacheDir
+.TP 5
+\fBCacheDir \fIdirectory\fR
+Specifies the directory to use for long-lived temporary (cache) files.
+The default is "/var/spool/cups/cache" or "/var/cache/cups" depending on the platform.
 .\"#ConfigFilePerm
 .TP 5
 \fBConfigFilePerm \fImode\fR
@@ -193,6 +198,11 @@ macOS uses its keychain database to store certificates and keys while other plat
 \fBServerRoot \fIdirectory\fR
 Specifies the directory containing the server configuration files.
 The default is "/etc/cups".
+.\"#StateDir
+.TP 5
+\fBStateDir \fIdirectory\fR
+Specifies the directory to use for PID and local certificate files.
+The default is "/var/run/cups" or "/etc/cups" depending on the platform.
 .\"#SyncOnClose
 .TP 5
 \fBSyncOnClose Yes\fR
@@ -210,13 +220,46 @@ The default contains "admin", "lpadmin", "root", "sys", and/or "system".
 .\"#TempDir
 .TP 5
 \fBTempDir \fIdirectory\fR
-Specifies the directory where temporary files are stored.
+Specifies the directory where short-term temporary files are stored.
 The default is "/var/spool/cups/tmp".
 .\"#User
 .TP 5
 \fBUser \fIusername\fR
 Specifies the user name or ID that is used when running external programs.
 The default is "lp".
+.SS DEPRECATED DIRECTIVES
+The following directives are deprecated and will be removed from a future version of CUPS:
+.\"#FontPath
+.TP 5
+\fBFontPath \fIdirectory[:...:directoryN]\fR
+Specifies a colon separated list of directories where fonts can be found.
+On Linux the
+.BR font-config (1)
+mechanism is used instead.
+On macOS the Font Book application manages system-installed fonts.
+.\"#LPDConfigFile
+.TP 5
+\fB LPDConfigFile \fIfilename\fR
+Specifies the LPD service configuration file to update.
+.\"#Printcap
+.TP 5
+\fBPrintcap \fIfilename\fR
+Specifies a file that is filled with a list of local print queues.
+.\"#PrintcapFormat
+.TP 5
+\fBPrintcapFormat bsd\fR
+.TP 5
+\fBPrintcapFormat plist\fR
+.TP 5
+\fBPrintcapFormat solaris\fR
+Specifies the format to use for the Printcap file.
+"bsd" is the historical LPD printcap file format.
+"plist" is the Apple plist file format.
+"solaris" is the historical Solaris LPD printcap file format.
+.\"#SMBConfigFile
+.TP 5
+\fBSMBConfigFile \fIfilename\fR
+Specifies the SMB service configuration file to update.
 .SH SEE ALSO
 .BR classes.conf (5),
 .BR cups (1),

man/cupsd.conf.man.in

@@ -10,7 +10,7 @@
 .\" which should have been included with this file.  If this file is
 .\" file is missing or damaged, see the license at "http://www.cups.org/".
 .\"
-.TH cupsd.conf 5 "CUPS" "26 June 2017" "Apple Inc."
+.TH cupsd.conf 5 "CUPS" "28 August 2017" "Apple Inc."
 .SH NAME
 cupsd.conf \- server configuration file for cups
 .SH DESCRIPTION
@@ -77,21 +77,6 @@ The default is "No".
 .br
 Specifies whether shared printers are advertised.
 The default is "No".
-.\"#Classification
-.TP 5
-\fBClassification \fIbanner\fR
-.br
-Specifies the security classification of the server.
-Any valid banner name can be used, including "classified", "confidential", "secret", "topsecret", and "unclassified", or the banner can be omitted to disable secure printing functions.
-The default is no classification banner.
-.\"#ClassifyOverride
-.TP 5
-\fBClassifyOverride Yes\fR
-.TP 5
-\fBClassifyOverride No\fR
-.br
-Specifies whether users may override the classification (cover page) of individual print jobs using the "job-sheets" option.
-The default is "No".
 .\"#DefaultAuthType
 .TP 5
 \fBDefaultAuthType Basic\fR
@@ -357,26 +342,6 @@ The default is "1048576" (1MB).
 \fBMultipleOperationTimeout \fIseconds\fR
 Specifies the maximum amount of time to allow between files in a multiple file print job.
 The default is "300" (5 minutes).
-.\"#PageLogFormat
-.TP 5
-\fBPageLogFormat \fIformat-string\fR
-Specifies the format of PageLog lines.
-Sequences beginning with percent (%) characters are replaced with the corresponding information, while all other characters are copied literally.
-The following percent sequences are recognized:
-.nf
-
-    "%%" inserts a single percent character.
-    "%{name}" inserts the value of the specified IPP attribute.
-    "%C" inserts the number of copies for the current page.
-    "%P" inserts the current page number.
-    "%T" inserts the current date and time in common log format.
-    "%j" inserts the job ID.
-    "%p" inserts the printer name.
-    "%u" inserts the username.
-
-.fi
-The default is the empty string, which disables page logging.
-The string "%p %u %j %T %P %C %{job-billing} %{job-originating-host-name} %{job-name} %{media} %{sides}" creates a page log with the standard items.
 .\"#PassEnv
 .TP 5
 \fBPassEnv \fIvariable \fR[ ... \fIvariable \fR]
@@ -415,11 +380,6 @@ The default is "Yes".
 \fBReloadTimeout \fIseconds\fR
 Specifies the amount of time to wait for job completion before restarting the scheduler.
 The default is "30".
-.\"#RIPCache
-.TP 5
-\fBRIPCache \fIsize\fR
-Specifies the maximum amount of memory to use when converting documents into bitmaps for a printer.
-The default is "128m".
 .\"#ServerAdmin
 .TP 5
 \fBServerAdmin \fIemail-address\fR
@@ -848,6 +808,48 @@ file.
 \fBSubscriptionPrivateValues \fIattribute-name \fR[ ... \fIattribute-name \fR]
 Specifies the list of subscription values to make private.
 The "default" values are "notify-events", "notify-pull-method", "notify-recipient-uri", "notify-subscriber-user-name", and "notify-user-data".
+.SS DEPRECATED DIRECTIVES
+The following directives are deprecated and will be removed in a future release of CUPS:
+.\"#Classification
+.TP 5
+\fBClassification \fIbanner\fR
+.br
+Specifies the security classification of the server.
+Any valid banner name can be used, including "classified", "confidential", "secret", "topsecret", and "unclassified", or the banner can be omitted to disable secure printing functions.
+The default is no classification banner.
+.\"#ClassifyOverride
+.TP 5
+\fBClassifyOverride Yes\fR
+.TP 5
+\fBClassifyOverride No\fR
+.br
+Specifies whether users may override the classification (cover page) of individual print jobs using the "job-sheets" option.
+The default is "No".
+.\"#PageLogFormat
+.TP 5
+\fBPageLogFormat \fIformat-string\fR
+Specifies the format of PageLog lines.
+Sequences beginning with percent (%) characters are replaced with the corresponding information, while all other characters are copied literally.
+The following percent sequences are recognized:
+.nf
+
+    "%%" inserts a single percent character.
+    "%{name}" inserts the value of the specified IPP attribute.
+    "%C" inserts the number of copies for the current page.
+    "%P" inserts the current page number.
+    "%T" inserts the current date and time in common log format.
+    "%j" inserts the job ID.
+    "%p" inserts the printer name.
+    "%u" inserts the username.
+
+.fi
+The default is the empty string, which disables page logging.
+The string "%p %u %j %T %P %C %{job-billing} %{job-originating-host-name} %{job-name} %{media} %{sides}" creates a page log with the standard items.
+.\"#RIPCache
+.TP 5
+\fBRIPCache \fIsize\fR
+Specifies the maximum amount of memory to use when converting documents into bitmaps for a printer.
+The default is "128m".
 .SH CONFORMING TO
 The \fBcupsd.conf\fR file format is based on the Apache HTTP Server configuration file format.
 .SH EXAMPLES