How to install and use Debian NewbieDOC documents on your computer

From NewbieDOC


Chris Lale
chrislale AT users DOT berlios DOT de

Go to NewbieDOC index

Revision History


Revision 1.0 28th November 2007 Revised by Chris Lale
Initial release.

Revision 1.1 26th September 2009 Revised by Chris Lale
Updated for Debian Squeeze.


Image:Newbiedoc-32.png Stable document
You can comment on this document by clicking on the discussion tab.

You can edit the live version of this document: How to install and use Debian NewbieDOC documents on your computer


Abstract

A snapshot of Debian NewbieDOC is available as a Debian package. You can install it on a Debian system and access the web pages using the "newbiedoc" command, from the Debian menu in X11 or using an online documentation reader such as "dhelp", "doccentral" or "dwww".


Contents


1 Install the newbiedoc package

1.1 Installing from the NewbieDOC project site

The newbiedoc package in the Debian Stable repository may be a little out of date. You can get the most recent version from http://developer.berlios.de/projects/newbiedoc/ .

First create a suitable directory (folder) in your Home directory for the downloaded file. If you are using the X Window System, you can do this with your file manager. Otherwise, use the command line in a terminal (or terminal window). Make the directory with mkdir.

$ mkdir -p ~/downloads/debs
 
Note
Note: 
The -p switch makes sure that any parent directories that don't exist are created. The tilde (~) starts the path at the root of your Home directory.
 

Visit the project site http://developer.berlios.de/projects/newbiedoc/ with your web browser to download the latest newbiedoc-deb release. The package file has the form newbiedoc_n.n.n-n_all.deb; for example, newbiedoc_0.7.0-1_all.deb. Download this file to the download directory you just created.

You must do the next bit from the command line. Change directory (cd) to the directory containing the downloaded .deb package.

 
Tip
Tip: 
You can use tab completion to fill in much of the path. Tap the "Tab" key after the first letter or two of each word in the path.
 
$ cd downloads/debs

Switch user (su) to user root.

$ su

Install the package using the Debian package manager dpkg.

 
Tip
Tip: 
You can use tab completion to fill in the package name.
 
# dpkg -i newbiedoc_0.7.0-1_all.deb

Selecting previously deselected package newbiedoc.
(Reading database ... 194453 files and directories currently installed.)
Unpacking newbiedoc (from newbiedoc_0.7.0-1_all.deb) ...
Setting up newbiedoc (0.7.0-1) ...
#
 
Important
Important: 
Switch back to normal user as soon as possible. This avoids accidental damage to your system.
# exit
 

The newbiedoc package is now installed. You can remove it with the usual tools (Apt, Aptitude or Synaptic), or you can use dpkg as user root.

# dpkg -r newbiedoc
 
Note
Note: 
To install the package with dpkg you supply the filename, to remove the package with dpkg you supply the package name.
 

2 Accessing the NewbieDOC documentation directly

You can see the NewbieDOC documents in a web browser. They are in the directory /usr/share/doc/newbiedoc. Use this URL:

file:///usr/share/doc/newbiedoc/newbiedoc.berlios.de/wiki/Index.html

There are a couple of shortcuts for doing this as follows.

2.1 From the command line

The newbiedoc command runs your favourite browser for X and opens the NewbieDOC Index file. If you are not using the X Window System, the newbiedoc command will open your favourite non-graphical browser instead.

$ newbiedoc
 
Tip
Tip: 
You can change your favourite browsers, as user root, using the commands update-alternatives --config x-www-browser and update-alternatives --config www-browser.
 

2.2 From the X Window System

You can run the newbiedoc command directly from the Debian menu. First make sure that the Debian menu is visible. You can do this in Gnome from The System menu:

System -> Preferences -Main Menu 

Make sure that Debian (in the Items list) is ticked. After this, Newbiedoc documents are always available from

Applications -> Debian -> Help -> NewbieDOC

3 Accessing the NewbieDOC documentation using online documentation systems

When you install the newbiedoc package, it registers the NewbieDOC documents with doc-base. The doc-base system makes documentation available to Debian's online documentation systems, currently doc-central, dhelp and dwww. Each of these systems depend on having a webserver (eg apache2) installed.

These online documentation systems allow you to view your Debian system's documentation (man pages, info files, READMEs, etc) in your web browser. All three systems have similar functionality. which one you use is a matter of personal preference. Only details for dwww are given here.

3.1 Using dwww

3.1.1 Installing the software

Install the dwww package using, for example, Apt, Aptitude or Synaptic. To be able to use dwww's search function, you must also install swish++ (the document indexing system). To install these packages from the command line you could enter this command as user root:

# aptitude install dwww swish++

3.1.2 Updating the database for dwww

You can index all the documentation registered with doc-base (including NewbieDOC) by running the dwww-index++ command as user root. This may take a while. The dwww-index++ command is also run automatically by cron every week.

# dwww-index++
 
Note
Note: 
Running dwww-index++ will not affect dwww's database of package information eg man pages. If you install new packages, update dwww's cache by running dwww-refresh-cache, as user root, to make sure that the package information is available.
# dwww-refresh-cache
 

3.1.3 Viewing the NewbieDOC documentation

Just as with the newbiedoc command, you can run dwww either from the command line

$ dwww

or from the Debian menu.

(Desktop's main menu) -> Debian -> Help -> Dwww

Your browser will display dwww's home page. You can find NewbieDOC documents in the registered documentation index.

For instance, to see a list of all NewbieDOC documents, type "newbiedoc" in the search box, select the last radio button ("registered documentation index") and click on the "Search" button.

dwww's home page.

Fig 1: dwww's home page.


4 Appendix A: Licence

Copyright (c) 2007-2009 Chris Lale. chrislale AT users DOT berlios DOT de.

GNU FDL Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License."


Go to NewbieDOC index

Content is available under GNU Free Documentation License 1.2, unless otherwise stated.