| 1 |
jfs |
607 |
|
| 2 |
|
|
This is a simple INSTALL description of how to setup a |
| 3 |
|
|
manpages.debian.net server. |
| 4 |
|
|
|
| 5 |
|
|
The man.cgi script serves manpages that have been previously extracted from a |
| 6 |
|
|
local Debian mirror, in order to set it up you need to take the following |
| 7 |
|
|
steps: |
| 8 |
|
|
|
| 9 |
|
|
- Extract the manpages using the manpages extractor available in |
| 10 |
|
|
the 'extractor' directory. You can either follow the steps in the |
| 11 |
|
|
README or run (after adjusting it) the generate-manpages-archive.sh |
| 12 |
|
|
script. |
| 13 |
|
|
|
| 14 |
|
|
Notice that this will consume around 1 GB of data for an archive containing |
| 15 |
|
|
sid, unstable, Debian 4.0 'etch' and Debian 3.1 'sarge'. |
| 16 |
|
|
|
| 17 |
|
|
- Setup a cronjob to rerun the manpage generation at least monthly, that way |
| 18 |
|
|
the manpages associated with the 'unstable' and 'testing' distribution get |
| 19 |
|
|
updated: |
| 20 |
|
|
|
| 21 |
|
|
------------------------------------------------------------------- |
| 22 |
|
|
# m h dom mon dow command |
| 23 |
|
|
0 3 1 * * /home/jfs/manpages/extractor/generate-manpages-archive.sh |
| 24 |
|
|
# |
| 25 |
|
|
------------------------------------------------------------------- |
| 26 |
|
|
|
| 27 |
|
|
- Install the 'ps2pdf' utility, available in Debian in the 'gs-common' package. |
| 28 |
|
|
This is necessary in order for the interface to provide printable copies |
| 29 |
|
|
of the manpages. |
| 30 |
|
|
|
| 31 |
|
|
- Generate (in Debian using 'dpkg-reconfigure locales') the locales for all |
| 32 |
|
|
the localisations manpages are available in. |
| 33 |
|
|
|
| 34 |
|
|
Make sure you do this or users asking for translated manpages will not |
| 35 |
|
|
get them in the proper encoding. |
| 36 |
|
|
|
| 37 |
|
|
- Create a virtual host for manpages.debian.net and configure it |
| 38 |
|
|
to serve a specific HTML page that redirects to the CGI interface |
| 39 |
|
|
or redirect using the server itself. |
| 40 |
|
|
|
| 41 |
|
|
For lighttpd you do not need to enable mod_simple_vhost, just add |
| 42 |
|
|
this to the configuration file: |
| 43 |
|
|
|
| 44 |
jfs |
610 |
------------------------------------------------------------------------ |
| 45 |
|
|
$HTTP["host"] == "manpages.debian.net" { |
| 46 |
|
|
server.document-root = "/var/www/manpages" |
| 47 |
|
|
server.errorlog = "/var/log/lighttpd/manpages-error.log" |
| 48 |
|
|
accesslog.filename = "/var/log/lighttpd/manpages-access.log" |
| 49 |
|
|
url.rewrite-once = ( |
| 50 |
|
|
"(?i)^/man/([0-9])/([[:alnum:]_-]*)$" => "/cgi-bin/man.cgi?query=$2&sektion=$1&apropos=0&manpath=Debian+Sid&locale" , |
| 51 |
|
|
"(?i)^/man/([[:alnum:]_-]*)$" => "/cgi-bin/man.cgi?query=$1&apropos=1&manpath=Debian+Sid&format=html&locale=en" |
| 52 |
|
|
) |
| 53 |
|
|
url.redirect = ( "^/$" => "/cgi-bin/man.cgi" ) |
| 54 |
|
|
} |
| 55 |
|
|
------------------------------------------------------------------------ |
| 56 |
|
|
|
| 57 |
|
|
Notice that there are rewriting rules in place so that users can directly go |
| 58 |
|
|
to http://manpages.debian.net/man/1/bash or |
| 59 |
|
|
http://manpages.debian.net/man/bash. In both cases users are redirect to the |
| 60 |
|
|
latest Debian manpages (i.e. Sid's) |
| 61 |
jfs |
607 |
|
| 62 |
jfs |
610 |
|
| 63 |
jfs |
607 |
- Install the man.cgi script in your server's CGI directory. This will |
| 64 |
|
|
typically be /usr/lib/cgi-bin/ |
| 65 |
|
|
(unless you setup a different location for the manpages.debian.net |
| 66 |
|
|
vhost cgis) |
| 67 |
|
|
|
| 68 |
|
|
Make sure you adjust the location of the $manLocalDir variable to where |
| 69 |
|
|
the manpages where extracted. |
| 70 |
jfs |
7313 |
|
| 71 |
|
|
Make sure the man.cgi script is executable |
| 72 |
jfs |
607 |
|
| 73 |
|
|
- Install a simple index.html script that redirects to the manpage interface |
| 74 |
|
|
in the server's document root. This is useful for people that go to |
| 75 |
|
|
the index instead of to the server itself. Those going directly to the |
| 76 |
|
|
server could be easily redirected with a redirect rule (as show above |
| 77 |
|
|
for lighttpd) |
| 78 |
|
|
|
| 79 |
|
|
- Install a robots.txt file similar to the following: |
| 80 |
|
|
---------------------------------------- |
| 81 |
|
|
# Please don't hammer the server, thanks |
| 82 |
|
|
User-agent: * |
| 83 |
|
|
Disallow: / |
| 84 |
|
|
---------------------------------------- |
| 85 |
|
|
|
| 86 |
|
|
The reason for this is that the man.cgi provides heavily hyperlinked manpages |
| 87 |
|
|
indexes. Since every call to a manpage demands CPU cycles of the server it is |
| 88 |
|
|
running on it wouldn't be fun if a robot is sent to try to go through all the |
| 89 |
|
|
information offered through this interface. |
| 90 |
|
|
|
| 91 |
|
|
- Install Debian's favicon.ico file in the document root |
| 92 |
|
|
|
| 93 |
|
|
- Test the interface asking for a translated manpage (such as 'dpkg') and |
| 94 |
|
|
browse the translations to make sure that encodings get properly converted. |
| 95 |
|
|
|
| 96 |
|
|
|
| 97 |
|
|
That's it! |
| 98 |
|
|
|
| 99 |
|
|
HINT |
| 100 |
|
|
---- |
| 101 |
|
|
|
| 102 |
|
|
The total number of manpages per distribution as of december 2007 was: |
| 103 |
|
|
|
| 104 |
|
|
sarge: 53678 |
| 105 |
|
|
sarge-proposed-updates: 3592 |
| 106 |
|
|
etch: 66370 |
| 107 |
|
|
etch-proposed-updates: 3315 |
| 108 |
|
|
lenny: 71873 |
| 109 |
|
|
lenny-proposed-updates: 3179 |
| 110 |
|
|
sid: 76042 |
| 111 |
|
|
experimental: 4465 |
| 112 |
|
|
|
| 113 |
|
|
Sample /etc/locale.gen file: |
| 114 |
|
|
-------------------------- |
| 115 |
|
|
es_ES@euro ISO-8859-15 |
| 116 |
|
|
es_ES ISO-8859-1 |
| 117 |
|
|
es_ES.UTF-8 UTF-8 |
| 118 |
|
|
cs_CZ ISO-8859-2 |
| 119 |
|
|
cs_CZ.UTF-8 UTF-8 |
| 120 |
|
|
de_DE ISO-8859-1 |
| 121 |
|
|
de_DE.UTF-8 UTF-8 |
| 122 |
|
|
de_DE@euro ISO-8859-15 |
| 123 |
|
|
fi_FI ISO-8859-1 |
| 124 |
|
|
fi_FI.UTF-8 UTF-8 |
| 125 |
|
|
fi_FI@euro ISO-8859-15 |
| 126 |
|
|
fr_FR ISO-8859-1 |
| 127 |
|
|
fr_FR.UTF-8 UTF-8 |
| 128 |
|
|
fr_FR@euro ISO-8859-15 |
| 129 |
|
|
ja_JP.EUC-JP EUC-JP |
| 130 |
|
|
ja_JP.UTF-8 UTF-8 |
| 131 |
|
|
ko_KR.EUC-KR EUC-KR |
| 132 |
|
|
ko_KR.UTF-8 UTF-8 |
| 133 |
|
|
nl_NL ISO-8859-1 |
| 134 |
|
|
nl_NL.UTF-8 UTF-8 |
| 135 |
|
|
nl_NL@euro ISO-8859-15 |
| 136 |
|
|
pl_PL ISO-8859-2 |
| 137 |
|
|
pl_PL.UTF-8 UTF-8 |
| 138 |
|
|
pt_BR ISO-8859-1 |
| 139 |
|
|
pt_BR.UTF-8 UTF-8 |
| 140 |
|
|
pt_PT ISO-8859-1 |
| 141 |
|
|
pt_PT.UTF-8 UTF-8 |
| 142 |
|
|
pt_PT@euro ISO-8859-15 |
| 143 |
|
|
ru_RU ISO-8859-5 |
| 144 |
|
|
ru_RU.CP1251 CP1251 |
| 145 |
|
|
ru_RU.KOI8-R KOI8-R |
| 146 |
|
|
ru_RU.UTF-8 UTF-8 |
| 147 |
|
|
ru_UA KOI8-U |
| 148 |
|
|
ru_UA.UTF-8 UTF-8 |
| 149 |
|
|
sv_FI ISO-8859-1 |
| 150 |
|
|
sv_FI.UTF-8 UTF-8 |
| 151 |
|
|
sv_FI@euro ISO-8859-15 |
| 152 |
|
|
sv_SE ISO-8859-1 |
| 153 |
|
|
sv_SE.ISO-8859-15 ISO-8859-15 |
| 154 |
|
|
sv_SE.UTF-8 UTF-8 |
| 155 |
|
|
-------------------------- |
Parent Directory
| 
Revision Log