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

I recently learned that there is a huge pile of documentation in /usr/share/doc.

It seems like much of it is gzipped so that it is not directly accessible without administrative privileges:

$ gunzip examples/letter.tex.gz 
gzip: examples/letter.tex: Permission denied

While one solution to this would be for every user to duplicate each item in their home directory just to read it, this arrangement hardly seems conducive to regular browsing.

How do normal people read this documentation?

I am not inclined to believe that the typical user is expected to install and maintain a web server just to read local text documentation.

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

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!

First install apache2

sudo apt-get install apache2 apache2-doc  

apache2-doc is the special case here. It allows you to browse your documentation /usr/share/doc/ through your web browser. fro http://localhost/doc/.

This does not work out right though. You need to change the configuration of Apache to get it to decompress and show the *.gz files as plain text.

I posted on Stack Overflow to get a way to use Apache to show the content of *.gz documents in the /usr/share/doc/ directory. This is what was posted as possible solution.

Here are those instructions in brief. It tells Apache how to deal with .gz files to process them as plain text and send them to the browser as plain text.

sudo a2enmod headers   
sudo a2enmod deflate  
gksu gedit /etc/apache2/sites-enabled/000-default 

Go to the bottom of the file and find the section with Alias /doc/ "/usr/share/doc/" and change it to look like this.

Alias /doc/ "/usr/share/doc/"
<Directory /usr/share/doc>
    Options Indexes MultiViews FollowSymLinks
    AllowOverride None
    Order deny,allow
    Deny from all
    Allow from 127.0.0.0/255.0.0.0 ::1/128

    AddEncoding gzip gz
    <FilesMatch "\.gz$">
      ForceType text/plain
      Header set Content-Encoding: gzip
    </FilesMatch>
</Directory>   

Then restart Apache:

sudo apache2ctl restart