====================
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.
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:
>
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
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
-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
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.
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:
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