How are typical users expected to read the documentation in /usr/share/doc?

There are at least two issues here:

  1. reading the .gz files painlessly
  2. permissions on the directories
  3. (optional for tex files)

For #1, there are a number of applications that will cope with the gzipped files seamlessly. A couple that you could use are less and vim .

 less README.gz 
 vim -R README.Debian.gz
 view Important.bits.gz

view is an alias for vim -R, which just says to open the file read-only.

In the old days, before less was installed on my system, I would use gzcat and pipe the output to another utility. Apparently, it is only called zcat now on Ubuntu, but you would use it like this, e.g.:

 /usr/share/doc/xpdf$ zcat changelog.Debian.gz  | more

zcat is still available, and using it to pipe compressed contents somewhere can be useful in some cases. (For situations with .bz2 files, bzcat is available.)

For #2, all of the files that I've seen under /usr/share/doc are in directories with other+rx permissions, meaning that all users can search the directories (e.g., list contents) and read files inside. What you can't do (since only root has write permission by default), is to create files. Because you are attempting to unzip into that directory, I imagine it is giving you permission denied because you have read but not write permissions by default.

For #3, I'm guessing you use .tex files more than I do. But here's one way to deal with them without copying to home or a temp file. For this, you are going to create a named pipe, but you can reuse that for your other tex piping and processing needs. It should go like this:

  • zcat or gzcat the text
  • ... and pipe that to your TeX processor
  • ... and send that to your Named Pipe (here, I'll call him pipey)
  • ... and then in a separate screen grab your output from pipey
  • ... and send that to a dvi display process.

You can obviously alter these steps if you use different or better utilities than the ones here.

My example will use the mkfifo utility to create the named pipe, pipey . The target file to process is /usr/share/doc/gdb/refcard.tex.gz . You'll need two shell command lines available (via terminal, Alt+F2, or however).

You'll type in terminal one:

mkfifo pipey

You now have a persistent named pipe. You can use ls -l to peek at it.

zcat /usr/share/doc/gdb/refcard.tex.gz | tex > pipey

Notice that this command will not return until you do something with the output that's gone to the named pipe.

Now, in terminal two, you'll type: tex pipey | xdvi

And it works (well, here anyway). The process can be refined for prettier output, but if you're looking for quick and relatively mess-free, that's one way to do it.


Maybe that's too late to answer, but I've found the best solution (both ease of use and completeness)

  • Install dwww install dwww

A typical Linux system has documentation in many formats (manual pages, Info files, READMEs, and so on). dwww makes it possible to access all of these via the same interface, a WWW browser. This makes it easier to use the documentation.

dwww is a web interface to all on-line documentation on a Debian system. It builds some web pages that list all installed documents, and converts all documents to HTML. The conversion is done when the user requests the document.

  • Enable the CGI module, which is no longer enabled by default in recent Ubuntu/Apache:

    sudo a2enmod cgi
    sudo service apache2 restart
    
  • Open your browser and point to: http://localhost/dwww/

  • Done!

All your info pages, man pages, /usr/share/doc files and package description in a single place! Your personal documentation website!


Most has been said and very nicely explained by jgbelacqua for use in terminal. Just adding this for people that are on a desktop manager:

From a graphical desktop (here GNOME) the easiest way to read docs from /usr/share/doc is to (double-)click open the zipped files with your standard archive manager (here File Roller) from where you can (double-)click open and read them in your standard editor (here Gedit). No write permissions needed as long as you don't unzip the files.