52

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.

7
  • Just to be clear, are you interested in dealing with any documents in the /usr/share/doc directories, or just the TeX/LaTeX ones?
    – belacqua
    Feb 1, 2011 at 4:46
  • OK, one more question -- do you need to process .tex files into dvi or whatever, or just look at the source code?
    – belacqua
    Feb 1, 2011 at 5:05
  • 1
    I'm asking about the documentation in /usr/share/doc in general and with special attention to the observation that much of it is stored in a compressed format. If there happens to be any documentation stored as un-typeset LaTeX, I have yet to encounter it. The particular example I referenced above is a LaTeX template from the package texlive-latex-extra-doc.
    – ændrük
    Feb 1, 2011 at 6:43
  • 1
  • 1
    askubuntu.com/questions/24072/…. I think this is the best solution over all one setup and it works there after.
    – nelaaro
    Mar 11, 2011 at 11:30

7 Answers 7

25

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.

4
  • 1
    Check out my solution, I think you will be impressed. askubuntu.com/questions/24072/…
    – nelaaro
    Mar 11, 2011 at 11:32
  • 1
    +1 for the detail. As for me, as also mentioned by @nelaar, I just add a few directives to the Apache <Directory "/usr/share/doc/"> directory declaration (usually in /etc/apache2/sites-enabled/000-default) and I believe decompression is handled by the browsers themselves. (AddEncoding x-gzip gz tgz and AddType text/plain .gz).
    – Delete
    Mar 22, 2011 at 10:07
  • Although this was an amazing and detailed lesson on many useful commands, this is hardly a good solution for how a typical user is expected to read the system documentation. For Ubuntu, Gnome's yelp or Debian's dwww is the most pain-free, easy method. My answer describes the latter: askubuntu.com/a/52419/11015
    – MestreLion
    May 2, 2012 at 21:41
  • 1
    @MestreLion A 'typical user' in the most realistic sense doesn't know that the files are even there. I think the easiest solution is the one I mentioned first -- using less . This has the additional advantage of being installed by default on every modern *nix system. For the user who knows the files are there and wants to refer to them more than a couple of times a year, installing something like dwww sounds like a great solution. Myself, in a pinch, I may not remember dwww, but I will remember basic commands like 'less'. Or, as Takkat said, Nautilus/fileroller/etc..
    – belacqua
    May 3, 2012 at 15:47
18

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

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!

3
  • Use this method. It is less pain full. And you can search things very fast as you are going to have a google like search box. May 2, 2012 at 6:17
  • 1
    For future visitors, note that this requires enabling CGI and restarting Apache service: askubuntu.com/questions/581118/… Feb 4, 2019 at 0:32
  • 2
    Thanks so much. This is by far the most useful tip I got in the last year on Linux. The ability to browse all local docs like this will stun many people on what they already have available in the system.
    – CatMan
    Jun 15, 2020 at 18:56
9

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   
5
  • 1
    I'm not too sure if this is a different solution. I've just added AddEncoding x-gzip gz tgz AddType text/plain .gz to my <Directory "/usr/share/doc/"> entry and I believe the decompression is actually handled on the client side.
    – Delete
    Mar 22, 2011 at 10:00
  • @Alain, no it is not a different solution this is essentially what I am doing.
    – nelaaro
    Mar 22, 2011 at 10:18
  • While I think this IS the best solution (nothing can beat using a browser to browse the docs), its a major overkill to install a whole web server just for that. I really wish Linux (yelp maybe?) had any out-of the box way to read the docs.
    – MestreLion
    Jun 19, 2011 at 20:12
  • Update: solution worked perfectly !!! mod "deflate" was already enabled out of the box, and I changed last line to sudo service apache2 restart for the sake of standartization. Last but not least, reades be aware of trailing "/": it must be localhost/doc/ , localhost/doc will not work.
    – MestreLion
    Jun 19, 2011 at 20:26
  • Actually, apache2-doc has nothing to do with this solution, it is just the local documentation for apache ^^
    – xeruf
    Sep 28, 2021 at 10:38
8

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.

1
  • Wonderful solution. This is indeed why people use things like Ubuntu, Gnome, etc.. This kind of task is made easier.
    – belacqua
    Jan 31, 2011 at 9:23
7

gunzip file.gz attempts to uncompress file.gz to file, removing file.gz. That is why you get a "Permission denied" error, you are not allowed to write in /usr/share/doc. To get the contents of a file, use gunzip -c file.gz or zcat file.gz.

Reading gzip-compressed textfiles can be done with zless. As it names might suggest, it is just less, but for gzip-compressed files.

Example usage:

zless /usr/share/doc/bash/NEWS.gz

The .gz suffix can be omitted as well:

zless /usr/share/doc/bash/NEWS
2
  • 1
    On recent systems, I've not had to specify zless, as less will handle it automatically.
    – belacqua
    May 3, 2012 at 15:45
  • 2
    @belacqua True, I do the same nowadays. I guess it has something to do with the LESSOPEN and LESSCLOSE environment variables.
    – Lekensteyn
    May 3, 2012 at 20:38
-1

I've been able to read such files with the man command on Debian Stretch (bind9 in my case)

man /usr/share/doc/bind9/README.Debian.gz

-5

Your should not read .tex files! It is in humand readable format, but it is designed to be processed before reanding. You can use tex2pdf tool to convert it to .pdf.

2
  • 1
    1) I want to read the LaTeX source. 2) The command is pdflatex. 3) This is tangential to the issue of needing to gunzip the file before reading it.
    – ændrük
    Jan 31, 2011 at 19:44
  • The file is probably an example that shows how to use a TeX/LaTeX package. In this case it is essential to read the source file, maybe in addition to generating output from the file.
    – Bodo
    Dec 7, 2021 at 13:22

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .