1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
|
1. Debian Online Help fetures
==============================================
Debian Online Help builds an index of all documentation in your system that
is registered with doc-base (and updates it when new packages are installed).
You can view this index with any web browser in two possible modes:
1. Offline, using the file:// protocol. Just use the command:
<your-browser> file:///usr/share/doc/HTML/index.html
2. Online, by installing a web server of your choice and opening the URL:
http://localhost/doc/HTML/index.html
You can start Debian Online Help using the command `dhelp'. It will detect
if you are using a web server and start in online mode, else it will start
in offline mode.
You can search for documentation relating to a particular query string using
the command `dhelp <query-string>', or use the search form if you have a web
server installed.
Debian Online Help tries hard to not carry with it excessive dependencies
in order to allow you to accommodate any software setup without bringing in
unneeded components. All optional components will be used if found, but the
core functionality will still be provided if they are missing. If they get
installed in the future, they will be available at the next index update.
The list below summarizes the available functionality in any possible setup.
Note that browsing offline through the file:/// protocol, as well as using
search through the `dhelp <query-string>' command remain functional in _all_
cases.
-- No web server installed:
Only offline mode works. Online mode and CGI scripts do not.
If you do not wish to install even a web browser, you can still use the
`html2text' package to view the text of the index pages from the console.
-- A web server that does not support CGI is installed:
Offline and online modes work (web server may need manual configuration,
cf. section 1 below). CGI scripts do not work (ie the links to man and
info pages, the online mode's links to the documentation and the search
web form).
-- A web server that supports CGI is installed, but man2html/info2www aren't
Offline and online modes work, as well as the the online mode's links to
the documentation and the search web form. The links to man/info pages
are inactive.
-- A web server that supports CGI as well as man2html/info2www are installed
The full functionality of Debian Online Help is available.
2. Configuring dhelp to work with a web server
==============================================
Debian Online Help comes pre-configured for quite a few web servers that
support aliases. If this is your case, then no further actions are needed
(you may have to issue the command `dpkg-reconfigure dhelp' in case you
are installing the web server _after_ dhelp has been installed).
For some web servers though that support aliases and for all web servers
that do not support them, it is required to do a few actions by hand in
order to finish dhelp configuration.
The following tables summarize the situation and gives instructions for
dhelp configuration with each web server:
Table #1: Web servers that _do not_ require manual configuration
------------------------------------------------------------------------------
boa : The default boa configuration has the /doc alias enabled.
------------------------------------------------------------------------------
lighttpd : A configuration snippet is installed during dhelp installation.
------------------------------------------------------------------------------
mathopd : The default mathopd configuration has the /doc alias enabled.
------------------------------------------------------------------------------
Table #2: Web servers that _may_ require manual configuration
------------------------------------------------------------------------------
apache2 : A configuration snippet is installed during dhelp installation.
For newer versions of the package (squeeze: >=2.2.16-6+squeeze7,
wheezy: >=2.2.22-4, all: >=2.4.1) you will have to enable the
/doc alias manually due to CVE-2012-0216.
Action : Uncomment the `Alias /doc/ ...' line inside the installed dhelp
configuration snippet for apache2. Its path depends on apache2
version.
< 2.4 : /etc/apache2/conf.d/dhelp.conf
>= 2.4 : /etc/apache2/conf-available/dhelp.conf
------------------------------------------------------------------------------
Table #3: Web servers that _do_ require manual configuration
------------------------------------------------------------------------------
bozohttpd : Does not support aliases. Action : cf. [1] below.
------------------------------------------------------------------------------
micro-httpd : Does not support aliases. Action : cf. [1] below.
------------------------------------------------------------------------------
mini-httpd : Does not support aliases. Action : cf. [1] below.
------------------------------------------------------------------------------
monkey : Does not support aliases.
[1] Action : Create a symlink named `doc' to `/usr/share/doc', inside
the web server's document root (Debian default is /var/www).
The command to create it is:
ln -s /usr/share/doc /var/www/doc
------------------------------------------------------------------------------
nginx : The default nginx configuration has the /doc alias enabled, but
the server does not support CGI scripts by default.
Action : Install the `fcgiwrap' package and copy the following line to
the `server {...}' block of the default virtual site (its path
is: /etc/nginx/sites-available/default):
include /usr/share/doc/fcgiwrap/examples/nginx.conf
------------------------------------------------------------------------------
yaws : An example configuration file for dhelp is provided at
`/usr/share/dhelp/config/yaws-dhelp.conf', but is not installed
in `/etc/yaws/conf.avail' because yaws does not allow overlayed
<server> directives.
In addition, the cgi scripts coming with dhelp cannot work as is
because they lack the `.cgi' extension.
Action : Use the supplied dhelp configuration snippet to manually edit
your configuration. To support the dhelp cgi scripts you need
to create a wrapper erlang appmode and edit the configuration
to load it.
------------------------------------------------------------------------------
Any web server not listed in the tables above will most probably require
manual configuration. The recipy in [1], above, will work with any web
server, so this is the first thing to try.
The dhelp configuration snippets provided at /usr/share/dhelp/config, as
`<webserver>-dhelp.conf' for each web server, list additional information
in case you would like to create a custom dhelp configuration.
3. Notes about indexing in dhelp
================================
3.1 How the indexer is run
==========================
The scheduling of the indexer process was completely redesigned in version
0.6.20, in order to solve the problem that the policy of index-when-installing-
packages creates (namely long delays in the overall installation of packages
when the size of installed documentation grows).
Now dhelp indexes even during installation, but in a deferred way. That is,
registration of new documents or even the pool-rebuild (issued by the commands
dhelp_parse -a <document-list>
and
dhelp_parse -r
respectively) does not start the indexer but instead writes the filenames of
the documents to be indexed in a cache list. This list is later reopened
(by a Dpkg post-install trigger) and fed to the indexer through a background
running process.
Note that the indexing during install is incremental by default, in order to
finish the indexing quicker. This does not hurt overall searching capabilities
since the index will be fully rebuilt anyway by the weekly cron job.
If for any reason the indexer does not run and you are left with a non-empty
cache file (it is located in /var/lib/dhelp/pending.list) you can start the
indexer manually, issuing the command:
sudo dhelp_parse -i
To force reindexing of all the currently installed documentation you can
either issue the sequence of commands:
sudo dhelp_parse -r
sudo dhelp_parse -i
or call the weekly cron job directly:
sudo /etc/cron.weekly/dhelp
To force (incremental) reindexing of certain packages you can use the utility
provided in the examples/ directory. You should use it like this:
sudo ruby /usr/share/doc/dhelp/examples/index_package_doc.rb <package> ...
3.2 Error reporting
===================
Up to version 0.6.19 error messages generated during indexing by the format
conversion tools where copied verbatim to the indexers error report. That
resulted in lengthy and hard to understand messages from the weekly cron job
in the cases where a package had registered a document that could not be
converted.
From version 0.6.20 and later, raw conversion error messages are hidden from
the indexer's error report; instead the full filename of the offending file is
printed, so that the source of the error can easily identified. You can then
manually try to convert the file in order to see the exact errors generated.
3.3 Log files
=============
From version 0.6.20 and above, the Dpkg post-install trigger as well as the
weekly cron job generate a log file with the output from the indexer process
inside directory /var/lib/dhelp/tmp.
The log filename contains the date that the process started as its first
component. If something does not work as expected, you can search for logs
with non-zero file size and view their content.
A monthly cron job deletes all but the five last logs, in order to keep under
control the size they occupy.
-- Esteban Manchado Velázquez <zoso@debian.org>
-- Georgios M. Zarkadas <gz@member.fsf.org>
|
