Take the 2-minute tour ×
Ask Ubuntu is a question and answer site for Ubuntu users and developers. It's 100% free, no registration required.

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.

share|improve this question
    
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 '11 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 '11 at 5:05
    
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 '11 at 6:43
    
    
askubuntu.com/questions/24072/…. I think this is the best solution over all one setup and it works there after. –  nelaar Mar 11 '11 at 11:30
add comment

6 Answers

up vote 6 down vote accepted

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.

share|improve this answer
    
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 9:23
add comment

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.

share|improve this answer
1  
Check out my solution, I think you will be impressed. askubuntu.com/questions/24072/… –  nelaar 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: askubuntu.com/a/52419/11015 –  MestreLion May 2 '12 at 21:41
    
@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 '12 at 15:47
add comment

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.

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

share|improve this answer
    
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 2 '12 at 6:17
add comment

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. from

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 Stackoverflow to get a way to use the apache to show the content of *.gz documents in the /usr/share/doc/ directory. This is what was posted as possible solution.

apache-gz-gzip-content-handler-for-linux-documentation-usr-share-doc-and-localh

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/ "user/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>   

$ sudo apache2ctl restart

share|improve this answer
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. –  nelaar 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 localhost/doc/ , localhost/doc will not work. –  MestreLion Jun 19 '11 at 20:26
add comment

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
share|improve this answer
    
On recent systems, I've not had to specify zless, as less will handle it automatically. –  belacqua May 3 '12 at 15:45
    
@belacqua True, I do the same nowadays. I guess it has something to do with the LESSOPEN and LESSCLOSE environment variables. –  Lekensteyn May 3 '12 at 20:38
add comment

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.

share|improve this answer
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 '11 at 19:44
add comment

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.