r10316 - /man-cgi/extractor/README
Author: jfs
Date: Tue Nov 5 00:21:22 2013
New Revision: 10316
URL: http://svn.debian.org/wsvn/?sc=1&rev=10316
Log:
Updated documentation and KNOWN bugs
Modified:
man-cgi/extractor/README
Modified: man-cgi/extractor/README
URL: http://svn.debian.org/wsvn/man-cgi/extractor/README?rev=10316&op=diff
==============================================================================
--- man-cgi/extractor/README (original)
+++ man-cgi/extractor/README Tue Nov 5 00:21:22 2013
@@ -4,40 +4,41 @@
This extractor should be used to build a manpages' pool for the man.cgi script.
-These are the steps to extract the manpages, you can execute them directly by
-first editing the variables in the 'config' file (adapt the variables to
-your local installation) and then running the generate-manpages-archive.sh script.
+The steps to extract the manpages are described below. You can execute them
+all directly by first editing the variables in the 'config' file (adapt the
+variables to your local installation) and then running the
+'generate-manpages-archive.sh' script.
-This is how the script works:
+This is how the scripts work:
-- First run manpage-extractor.pl by pointing it to a local mirror (on disk). It
+- Run manpage-extractor.pl by pointing it to a local mirror (on disk). It
will generate a 'manpages-files' directory with all the available manpages.
Each subdirectory is on a package+version format so that if it's run
in different times it will not extract packages already there and will
extract new packages in a way that they don't conflict.
NOTE: A full archive extraction of sid+previous releases is over
- one Gigabyte big.
+ 10 GB big.
-- Then run the 'files-release.pl' script by pointing it to a local mirror.
+- Run the 'files-release.pl' script by pointing it to a local mirror.
This script looks for available releases, parses their Packages.gz file
and generates a 'manpages-dists' which contains a subdirectory per
release. A release subdirectory contains the 'usr/X11R6/man' and
'usr/share/man' and all the available manpages extracted above
and appropiate for a release are symlinked there
-- The 'generate-indexes.sh' script will generate 'apropos' indexes that
- the man CGI script will use to do searchs. It just calls man -k for
- all the different releases availble.
+- Run the 'generate-indexes.sh' script will generate 'apropos' indexes that the
+ man CGI script will use to do searches. It just calls man -k for all the
+ different releases available.
NOTE: It does not do this for the different languages that might be
available.
-These scripts should be run manually at least once and the periodically
-through cron to update the manpages contents.
+These scripts should be run manually at least once to create the archive. After
+this, run them periodically through to update the manpages' archive contents
-A sample cron entry would be the following:
-(the location of the script needs to be adjusted)
+A sample cron entry to do this would be the following:
+(adjust the location of the script to where you installed it)
-------------------------------------------------------------------------
0 3 1 * * /srv/manpages.debian.org/extractor/generate-manpages-archive.sh
@@ -45,16 +46,56 @@
In addition, you can run the 'count-manpages-archive.sh' script to count the
number of manpages available (to make sure that the name increases and not
-decreases)
+decreases).
-Please notice that there's no script that will clean up old manpages, so be
-careful as you might end up consuming large amounts of space if you don't
-cleanup and regenerate the 'manpages-files' subdirectory from time to time.
+A sample output for the count-manpages-archive.sh is shown below
+(generated in paganini.debian.org in October 2013)
-This is specially the case if you extract manpages from 'unreleased' releases
-(sid, testing).
+-------------------------------------------------------------------------
+experimental 31362
+jessie 123847
+jessie-backports 0
+jessie-proposed-updates 875
+jessie-updates 0
+lenny 76657
+lenny-proposed-updates 4986
+sid 138581
+squeeze 102343
+squeeze-proposed-updates 9711
+squeeze-updates 14
+wheezy 124672
+wheezy-backports 7816
+wheezy-proposed-updates 6447
+wheezy-updates 14
+-------------------------------------------------------------------------
+
+
+KNOWN BUGS
+----------
+
+(Also documented in the scripts themselves)
+
+- The manpage-extractor.pl script extracts the manpages for all versions
+ found in the archive. If a new version appears for a given release (e.g. sid)
+ the previous version manpages' will not be removed and new manpages will be
+ extracted. (with, in some cases, exactly the same content)
+
+ Be careful with this, since the manpages might end up consuming large amounts
+ of space if you don't cleanup and regenerate the 'manpages-files'
+ subdirectory from time to time.
+
+ This is specially an issue if you extract manpages from 'unreleased' releases
+ (sid, testing) in which the packages change frequently.
+
+- If a package provides manpages that are not available under /usr/share/man
+ or /usr/X11R6/man (e.g. packages with manpages managed through alternatives)
+ they will not get extracted.
+
+- The script look for the manpages by 'brute-force'. They could determine which
+ packages have useful manpages by first going through the Contents.gz file
+ for a given distrbution.
---
Javier Fernandez-Sanguino <jfs@debian.org>
-Wed, 30 Oct 2013 02:15:28 +0100
+Tue, 05 Nov 2013 01:16:56 +0100
Reply to: