Update top-level documentation files in preparation for the 2.3.0 release.

michaelrsweet · michaelrsweet · commit 69e37fbf5299 · 2019-08-21T08:22:43.000-04:00
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -2,13 +2,14 @@ Contributing to CUPS
 ====================
 
 CUPS is developed by Apple Inc. and distributed as open source software under
-the Apache License, Version 2.0.  Significant contributions to CUPS must be
-licensed to Apple using the Apple Contributor Agreement:
+the Apache License, Version 2.0 with exceptions to allow linking to GPL2/LGPL2
+code.  Significant contributions to CUPS must be licensed to Apple using the
+Apple Contributor Agreement:
 
     https://www.cups.org/AppleContributorAgreement_2011-03-10.pdf
 
-Contributions should be submitted as attachments to bug reports on the CUPS web
-site.  Changes to existing source files should be submitted as unified diffs
-(both Subversion and Git produce this format by default) while new source files
+Contributions should be submitted as attachments to bug reports on the
+[CUPS Github project](https://github.com/apple/cups).  Changes to existing
+source files should be submitted as unified diffs while new source files
 should be provided as-is or in an archive.  Github pull requests can also be
 used to submit changes.
diff --git a/CREDITS.md b/CREDITS.md
@@ -1,4 +1,4 @@
-CREDITS - 2017-05-01
+CREDITS - 2019-08-21
 ====================
 
 Few projects are completed by one person, and CUPS is no exception.  We'd like
diff --git a/DEVELOPING.md b/DEVELOPING.md
@@ -63,7 +63,9 @@ major, minor, and patch release numbers.  Major release numbers indicate large
 design changes or backwards-incompatible changes to the CUPS API or CUPS
 Imaging API.  Minor release numbers indicate new features and other smaller
 changes which are backwards-compatible with previous CUPS releases.  Patch
-numbers indicate bug fixes to the previous feature or patch release.
+numbers indicate bug fixes to the previous feature or patch release.  This
+version numbering scheme is consistent with the
+[Semantic Versioning](http://semver.org) specification.
 
 > Note:
 >
@@ -114,6 +116,10 @@ Contributed source code must follow the guidelines below.  While the examples
 are for C and C++ source files, source code for other languages should conform
 to the same guidelines as allowed by the language.
 
+Source code comments provide the reference portion of the CUPS Programming
+Manual, which is generated using the [codedoc](https://msweet.org/codedoc)
+software.
+
 
 ### Source Files
 
@@ -270,15 +276,17 @@ Return/output values are indicated using an "O" prefix, input values are
 indicated using the "I" prefix, and values that are both input and output use
 the "IO" prefix for the corresponding in-line comment.
 
-The Mini-XML documentation generator also understands the following special
-text in the function description comment:
+The [codedoc](https://msweet.org/codedoc) documentation generator also
+understands the following special text in the function description comment:
 
-    @deprecated@         - Marks the function as deprecated (not recommended
-                           for new development and scheduled for removal)
+    @deprecated@         - Marks the function as deprecated: not recommended
+                           for new development and scheduled for removal.
+    @link name@          - Provides a hyperlink to the corresponding function
+                           or type definition.
     @since CUPS version@ - Marks the function as new in the specified version
                            of CUPS.
-    @private@            - Marks the function as private (same as starting the
-                           function name with an underscore)
+    @private@            - Marks the function as private so it will not be
+                           included in the documentation.
 
 
 ### Variables
diff --git a/INSTALL.md b/INSTALL.md
@@ -1,4 +1,4 @@
-INSTALL - CUPS v2.3.0 - 2019-05-24
+INSTALL - CUPS v2.3.0 - 2019-08-21
 ==================================
 
 This file describes how to compile and install CUPS from source code. For more
diff --git a/README.md b/README.md
@@ -1,13 +1,9 @@
-README - CUPS v2.3.0 - 2019-05-24
+README - CUPS v2.3.0 - 2019-08-21
 =================================
 
-Looking for compile instructions?  Read the file `INSTALL.md` instead...
-
-
 INTRODUCTION
 ------------
 
-
 CUPS is a standards-based, open source printing system developed by Apple Inc.
 for macOS® and other UNIX®-like operating systems.  CUPS uses the Internet
 Printing Protocol ("IPP") and provides System V and Berkeley command-line
@@ -29,8 +25,21 @@ CUPS is licensed under the Apache License Version 2.0.  See the file
 READING THE DOCUMENTATION
 -------------------------
 
+Initial documentation to get you started is provided in the root directory of
+the CUPS sources:
+
+- `CHANGES.md`: A list of changes in the current major release of CUPS.
+- `CONTRIBUTING.md`: Guidelines for contributing to the CUPS project.
+- `CREDITS.md`: A list of past contributors to the CUPS project.
+- `DEVELOPING.md`: Guidelines for developing code for the CUPS project.
+- `INSTALL.md`: Instructions for building and installing CUPS.
+- `LICENSE`: The CUPS license agreement (Apache 2.0).
+- `NOTICE`: Copyright notices and exceptions to the CUPS license agreement.
+- `README.md`: This file.
+
 Once you have installed the software you can access the documentation (and a
-bunch of other stuff) online at <http://localhost:631/>.
+bunch of other stuff) online at <http://localhost:631/> and using the `man`
+command, for example `man cups`.
 
 If you're having trouble getting that far, the documentation is located under
 the `doc/help` and `man` directories.
@@ -76,22 +85,22 @@ printer at address 11.22.33.44:
 
 CUPS also includes several sample PPD files you can use for "legacy" printers:
 
-    Driver                         PPD Name
-    -----------------------------  ------------------------------
-    Dymo Label Printers            drv:///sample.drv/dymo.ppd
-    Intellitech Intellibar         drv:///sample.drv/intelbar.ppd
-    EPSON 9-pin Series             drv:///sample.drv/epson9.ppd
-    EPSON 24-pin Series            drv:///sample.drv/epson24.ppd
-    Generic PCL Laser Printer      drv:///sample.drv/generpcl.ppd
-    Generic PostScript Printer     drv:///sample.drv/generic.ppd
-    HP DeskJet Series              drv:///sample.drv/deskjet.ppd
-    HP LaserJet Series             drv:///sample.drv/laserjet.ppd
-    OKIDATA 9-Pin Series           drv:///sample.drv/okidata9.ppd
-    OKIDATA 24-Pin Series          drv:///sample.drv/okidat24.ppd
-    Zebra CPCL Label Printer       drv:///sample.drv/zebracpl.ppd
-    Zebra EPL1 Label Printer       drv:///sample.drv/zebraep1.ppd
-    Zebra EPL2 Label Printer       drv:///sample.drv/zebraep2.ppd
-    Zebra ZPL Label Printer        drv:///sample.drv/zebra.ppd
+   Driver                         | PPD Name
+   -----------------------------  | ------------------------------
+   Dymo Label Printers            | drv:///sample.drv/dymo.ppd
+   Intellitech Intellibar         | drv:///sample.drv/intelbar.ppd
+   EPSON 9-pin Series             | drv:///sample.drv/epson9.ppd
+   EPSON 24-pin Series            | drv:///sample.drv/epson24.ppd
+   Generic PCL Laser Printer      | drv:///sample.drv/generpcl.ppd
+   Generic PostScript Printer     | drv:///sample.drv/generic.ppd
+   HP DeskJet Series              | drv:///sample.drv/deskjet.ppd
+   HP LaserJet Series             | drv:///sample.drv/laserjet.ppd
+   OKIDATA 9-Pin Series           | drv:///sample.drv/okidata9.ppd
+   OKIDATA 24-Pin Series          | drv:///sample.drv/okidat24.ppd
+   Zebra CPCL Label Printer       | drv:///sample.drv/zebracpl.ppd
+   Zebra EPL1 Label Printer       | drv:///sample.drv/zebraep1.ppd
+   Zebra EPL2 Label Printer       | drv:///sample.drv/zebraep2.ppd
+   Zebra ZPL Label Printer        | drv:///sample.drv/zebra.ppd
 
 You can run the `lpinfo -m` command to list all of the available drivers:
 
@@ -151,9 +160,9 @@ LEGAL STUFF
 Copyright © 2007-2019 by Apple Inc.
 Copyright © 1997-2007 by Easy Software Products.
 
-CUPS is provided under the terms of the Apache License, Version 2.0.  A copy of
-this license can be found in the file `LICENSE`.  Additional legal information
-is provided in the file `NOTICE`.
+CUPS is provided under the terms of the Apache License, Version 2.0 with
+exceptions for GPL2/LGPL2 software.  A copy of this license can be found in the
+file `LICENSE`.  Additional legal information is provided in the file `NOTICE`.
 
 Unless required by applicable law or agreed to in writing, software distributed
 under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-CREDITS - 2017-05-01`
	`1`	`+CREDITS - 2019-08-21`
`2`	`2`	`====================`
`3`	`3`
`4`	`4`	`Few projects are completed by one person, and CUPS is no exception. We'd like`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-INSTALL - CUPS v2.3.0 - 2019-05-24`
	`1`	`+INSTALL - CUPS v2.3.0 - 2019-08-21`
`2`	`2`	`==================================`
`3`	`3`
`4`	`4`	`This file describes how to compile and install CUPS from source code. For more`