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.

ændrük
  • 76,794
  • 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 01 '11 at 04: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 01 '11 at 05: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 01 '11 at 06:43
  • 1
    http://stackoverflow.com/questions/5242106/apache-gz-gzip-content-handler-for-linux-documentation-usr-share-doc-and-localh/5242150#5242150 – nelaaro Mar 11 '11 at 11:10
  • 1
    http://askubuntu.com/questions/24072/how-are-typical-users-expected-to-read-the-documentation-in-usr-share-doc/29768#29768. I think this is the best solution over all one setup and it works there after. – nelaaro Mar 11 '11 at 11:30
  • from firefox (50.1) it is possible to just open .gz file directly by gedit via 'open with' (without middle archive step). Apparently gedit will recognize archive and show the content directly. Caveat here is that at first you need to explain to firefox to use gedit as it will not recognize gz extension and would default to download the file – Lj MT Jan 22 '17 at 20:05
  • If you would tell the full path to the file examples/letter.tex.gz we could find out what package it belongs to. Based on the name it is probably some example file. To look at the TeX/LaTeX source code you can use zless examples/letter.tex.gz. If you would use the file, e.g. for processing it with TeX or LaTeX, you should probably copy it to your home directory. Ther you can use gunzip without problems. – Bodo Dec 06 '21 at 16:13

7 Answers7

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.

belacqua
  • 23,120
  • 1
    Check out my solution, I think you will be impressed. http://askubuntu.com/questions/24072/how-are-typical-users-expected-to-read-the-documentation-in-usr-share-doc/29768#29768 – nelaaro Mar 11 '11 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 '11 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: http://askubuntu.com/a/52419/11015 – MestreLion May 02 '12 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 03 '12 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!

MestreLion
  • 20,086
  • 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. – Curious Apprentice May 02 '12 at 06:17
  • 1
    For future visitors, note that this requires enabling CGI and restarting Apache service: https://askubuntu.com/questions/581118/i-cant-get-dwww-to-work-keeps-getting-404-not-found – Sergiy Kolodyazhnyy Feb 04 '19 at 00: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 '20 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
Community
  • 1
nelaaro
  • 10,028
  • 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 '11 at 10:00
  • @Alain, no it is not a different solution this is essentially what I am doing. – nelaaro Mar 22 '11 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 '11 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 http://localhost/doc// , http://localhost/doc will not work. – MestreLion Jun 19 '11 at 20:26
  • Actually, apache2-doc has nothing to do with this solution, it is just the local documentation for apache ^^ – xeruf Sep 28 '21 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.

Taz8du29
  • 307
Takkat
  • 142,284
  • Wonderful solution. This is indeed why people use things like Ubuntu, Gnome, etc.. This kind of task is made easier. – belacqua Jan 31 '11 at 09: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
Lekensteyn
  • 174,277
  • 1
    On recent systems, I've not had to specify zless, as less will handle it automatically. – belacqua May 03 '12 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 03 '12 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

donkihott
  • 48
  • 5
-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.

przemo_li
  • 143
  • 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 '11 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 07 '21 at 13:22