[cups.general] CUPS help documentation, dropping cups "browsing"

[Michael Sweet]

Bob,

On 2012-11-26, at 6:56 PM, Bob R <br4email-cups at yahoo.com> wrote:
> I have decided to start a new message, discussing just the documentation (please). From a different message:
> 
>>>> Indeed, and with the exception of browsing and some charset issues I think our history of backwards compatibility has been great. But each of these things has known workarounds...
>>> 
>>> Where do I find the "known" workaround?
>> 
>> Search the message archives.
> 
> While I thank you for answering, this is not the way it should be. If there is a known incompatibility, and especially if it is intentional and planned, the fact the feature has been dropped AND "how to do it now" or the "recommended work around" should be discussed somewhere under ://localhost:631/help

I can appreciate that you want to see us document everything possible in CUPS, and maintain that documentation indefinitely. However, that is simply not feasible, and in many cases when we have tried documenting certain aspects of CUPS it has caused more confusion due to patches and configuration changes made by the Linux distributions.

Moreover, how confusing would it be to provide documentation for an older version of CUPS with the current release?

> Unfortunately, the old section "Autoconfiguration using CUPS Browsing" has been silently deleted in CUPS 1.6. I spent hours reading the documentation before finally doing side by side comparison of old and new, and noticing the differences in localhost:631/help/sharing.html on my different systems.

You can also look on the CUPS web site which provides archived versions of the CUPS documentation for each feature release. And the older documentation *does* document the BrowsePoll + BrowseRelay feature (primarily for crossing the subnet barrier...)

	http://www.cups.org/documentation.php/doc-1.5/sharing.html

> ...
> The help document still has a section called "Autoconfiguration using IPP" and then has a box saying "This" method of configuration does not work on OS X 10.7 and later... but doesn't say where to look to find *any* other method of auto configuration, or where to look or what how to do any configuration on OS X 10.7 and later systems. And when it says "This method..." what is it talking about, and as a server or client? The text only talks about a single spooler verses local spoolers, but I do not understand what that has to do with IPP. How many ways can one do configuration? If IPP is only one of several ways, where are the sections on the other ways?

More than likely the wording here is a holdover from the previous documentation and is unnecessarily confusing - it would be very helpful if you file bug reports for any documentation that you find lacking or confusing:

	http://www.cups.org/str.php

> Everything above said, the most immediate _document_ I want is one that tells me the "official" way to get things to work with cups 1.6 [installed on a Moc Mountain Lion client] with older versions of cups (1.4 in particular) on (linux) servers. If the recommended way is update the server to 1.6, fine, but then that should explicitly be in the document. If "Bonjour" or "dnssd" or whatever is how, then document what to do, and be clear about what to do where, on client vs server. [Don't tell me what to do here to get it to work in this message, I would like to discuss the documentation]

The CUPS documentation is the wrong place for this; first because OS X users go through System Preferences to add printers (which is documented already with the OS X built-in help system), and second because any server-side support for this is distribution-specific through early Avahi patches that were not part of the standard CUPS and were documented by the distributions themselves.

I know this isn't the ideal situation, but with literally hundreds of Linux distributions and no way to reference a stable Apple documentation link (because that link changes with every OS and web site update...), there is no good way to "fix" it...

> If cups 1.6 server is incompatible with previously released cups clients, ditto above, but I don't currently have that situation. I would think the usual situations would be printers are networked (which means they are really connected through a dedicated computer) or they are connected to the local machine or they are connected to old hardware in somewhere like the closet. When an individual buys a new computer or updates an old, it will most likely be a client, not a server.

I would agree, and fully support adding an optional helper daemon to the cups-filters project that acts as a bridge between old and new CUPS systems. Some of the existing cups-polld code from CUPS 1.5 can be used to support CUPS 1.5.x clients to CUPS 1.6.x servers, and the old cupsd code for managing remote queues can easily be incorporated (minus implicit class support) to support CUPS 1.6.x clients automatically discovering/adding queues on CUPS 1.5.x and earlier servers.

________________________________________________________________________
Michael Sweet, Senior Printing System Engineer, PWG Chair