Mantis - cupsclient
Viewing Issue Advanced Details
4532 packaging major always 2010-08-27 19:18 2011-08-03 12:01
phil  
maciej  
normal  
closed  
no change required  
none    
none  
0004532: cupsclient lacks docs
I decided to try switching to using "cupsclient" for printing.
Installed the package... and was left scratching my head.
the postinstall mentions "/etc/opt/csw/cups".
Which only contents "client.conf.CSW".
Which mentioned "man client.conf". Which is similarly unhelpful.
Looked in /opt/csw/share/doc/cupsclient.
Only thing there is the license file.

Please add some level of documentation to address,
"here's what you do if you actually want to print to something".


What would be helpful, would be two things:
1. mention of "how do I set up a printer"?
2. mention of "what do I do instead of the usual 'lp' ?"

Issue History
2010-08-27 19:18 phil New Issue
2011-05-11 10:31 maciej Note Added: 0009037
2011-05-12 20:21 phil Note Added: 0009038
2011-06-12 17:36 maciej Note Added: 0009111
2011-06-12 19:25 phil Note Added: 0009112
2011-06-12 21:42 maciej Status new => assigned
2011-06-12 21:42 maciej Assigned To => maciej
2011-06-12 21:45 maciej Note Added: 0009113
2011-06-12 21:45 maciej Status assigned => resolved
2011-06-12 21:45 maciej Resolution open => no change required
2011-06-13 00:08 phil Note Added: 0009114
2011-06-19 15:56 maciej Note Added: 0009123
2011-06-19 17:24 phil Note Added: 0009124
2011-08-03 12:01 maciej Note Added: 0009215
2011-08-03 12:01 maciej Status resolved => closed

Notes
(0009037)
maciej   
2011-05-11 10:31   
To address the specific points:

ad 1. With the cups client, you don't set up a printer.
ad 2. You do the usual lp.

More generally, CUPS documentation is in the cupsdoc package. Would a file saying "Please see CSWcupsdoc" help?
(0009038)
phil   
2011-05-12 20:21   
Hi Maciej,

oopsie on missing the CSWcupsdoc package. So yes, a file saying "Please see that" would help.
However... cups is supposed to be (the wonderful new, easy printing system that doesnt need manuals).
As such, seems like it would be rather nice to have some very brief "quickstart" file. I'm imagining it would only be a few lines?
ie:
  "cups is administered via local web server ONLY. Go to port xyz with your browser and follow the directions ...."
?
(0009111)
maciej   
2011-06-12 17:36   
Updated cupsclient package is available from experimental:

http://buildfarm.opencsw.org/experimental.html#cups [^]

Is the README file helpful?

By the way, it's not true that CUPS is administered by a local web server only. The lpadmin command allows to query and modify cupsd configuration.
(0009112)
phil   
2011-06-12 19:25   
I'm afraid I dont find a "documentation" file that says "go read the REAL documentation" to be very helpful.
It's "better than nothing", but I thought cups was supposed to be so wonderfully easy to use?
(I dont use it, which is why I found myself in need of documentation.. and then said "the heck with this" when I did not fight straightforward docs for it)


If it's so wonderfully easy, shouldnt it be "easy" for you to throw together a couple of lines saying, "here are the steps you need to do to point your cupsclient at a working cupsd back end" ?

I dunno whether it is or not, I still havent figured out a simple way to use it :p

(and as a reply to your last comment: I vaguely recall lpadmin not functioning as normal, which is why I tore the packages off my workstation, after giving it an initial try. but that was some time ago.)
(0009113)
maciej   
2011-06-12 21:45   
It seems to me that the bug report has been opened for the purpose of ranting, without any serious indication of an actual issue with the package itself. Closing.
(0009114)
phil   
2011-06-13 00:08   
What the heck Maciej... how do you pass off my bug report as "ranting" ?
To me, this seems like another example of, "ignore something, *just because its Phil saying it*".
Or is it that because I described a large difficulty I had using the package in the past, you describe it as "ranting"? So users need to be careful not to describe having large difficulties with packages, or you'll close the bug?


"How do I use this thing", is a very normal concern.
The more complex or non standard a thing is, the more important it is for us to provide a carefully marked pointer to a trail.
You just writing "read the docs" for a complex package, leaves a gap in the user experience


If there was a nice straightforward preexisting guide of "here's how to get started with minimum hassle", then it would be fine for you to provide a url, or file reference.
But you didnt. Maybe because, last time I checked, there isnt one.

If you *know* of one, please reference it.
If there isnt... then could you please take 5 minutes to help out new users to get started with cups client?

You seem to imply this should be configurable without the web interface, and usable via lpadmin.
So how about just putting in a ONE LINE example that, according to you, should work?

I previously tried it. it didnt work for me. which is why as an "opencsw user", I asked you, the package maintainer, for a better (specific) reference for use of the client package.
(0009123)
maciej   
2011-06-19 15:56   
http://lmgtfy.com/?q=how+to+set+up+cups+on+solaris [^]
(0009124)
phil   
2011-06-19 17:24   
Congratulations! You win an "BOFH" award!
Your oh-so-cleverly-disguised [google it] reference, exactly justified my complaint here.
The first hit, points to a fairly long document,
http://blogs.oracle.com/DanX/entry/using_cups_print_server_for [^]

which **does not tell you how to set up cupsclient** without also having the full webserver admin thing.

Nor does the second hit.

So are you going to include actually useful documentation in the cupsclient package now?

If you want to actually be helpful to our users, it would be good to either have the readme say, "you need to install [the cups webadmin package] to do stuff", or provide a simple example/link on how to admin cupsclient from the command line.
Just saying "use lpadmin" would not be very helpful, since most new solaris users have difficulty using it, and need a concise example/reference to use it.
(0009215)
maciej   
2011-08-03 12:01   
The cups package build description can be found here:

http://gar.svn.sourceforge.net/svnroot/gar/csw/mgar/pkg/cups/trunk/ [^]

Patches (e.g. with additional documentation) are welcome.