Node: Top How2 - The front-end to GNU/Linux HOWTO help documents

how2 - The LDP HOWTO Node Front-end

Latest version is 2.0.1 - see the README text or readme.html for more information.

The how2 front-end compiles your LDP HOWTO Html Nodes (downloadable from www.biblio.org)
so that they can be viewed and queried in an RPM-q fashion while supporting direct text search on
documents with keywords.

The HOWTO Nodes or any ASCII text are parsed, formatted and optionally compressed by makehow2,
inserting hyperlinks to other HOWTO Nodes that your WWW browser can use.

Minimum System Requirements

A GNU/Unix or Cygwin (Sh/Bash) shell must be present on the system.
A Web-Server must be installed and running for the program to work.
Perl 5.x.x or later must be installed for Perl/CGI scripts to run.

Installation and Configuration

The following steps are necessary before running how2:

Choose any directory name for decompressing the How2-xxx.ZIP archive in.
Create this directory and "cd" into it.
Extract the zip-file how2.zip in this directory
Open a shell console, change to that directory, become root, and type:
``make install'' or ``make all''
This installs default How2 documentation in /usr/doc and calls the shell script
`makehow2 --config' for pre-configuring scripts before they are installed;
it then installs them to destination directories.
When called with --config, makehow2 asks for certain parameters that you must supply
(or insert into a configuration file with the --auto/--quasi switch) if you don't want
to get into the trouble of typing configuration data directly inside scripts:
- Domain and/or IP to run as (default: localhost@127.0.0.1)
- Path to cgi-bin/DOCS directory
- Path to public-html/DOCS directory
- Program to compress your documents with (if left blank, no compression)
- Suffix (.ext) of files to be processed (default: html)
- Whether CGI support is required (answer: y/n)

It is recommended that these information be prepared in advance of starting.
Should you wish to change any of the values supplied during configuration, you may do so
in the last step by aborting the configuration. In such event you will have to start over.

Compilation

Compiling with ``How2'' has nothing to do with GCC; it is meant in the librarian's sense.

Change to your INSTALL directory - e.g. ~/home/how2-2.0.1.
cd ~/home/how2-2.0.1 (i.e. the install directory)
Proceed as described in the following steps:
- install or move all your docs here & in any subdirs
- run ``makehow2'' with or without options and flags

Hint: For Html/ASCII HOWTO docs, use one of the following actions and flags:

auto	->	edit an ``about2.config'' file to suit your needs and run
 		./makehow2 --config --auto about2.config
quasi 	->	./makehow2 -c --quasi --CGIBIN=/var/www/cgi-bin/how2 \
		--HTMLDIR=/var/www/htdocs/how2 --ZPROG=gzip --NOCGI=0
manual 	->	./makehow2 --config (Note: ``--manual'' is not an action)

manify  	-> ./makehow2 --manify (standalone after any of above)
manify=sec	-> as above plus building the "mansec" alphabetical index
manify=whatis	-> as above plus building the "manwhatis" descriptions index
manify=all 	-> same as above, plus building both indices

How It Works

The ``How2'' core is made of two scripts, makehow2 and how2. The first is used
for compilation/indexing, the second is a search/query interface.

``makehow2'' features the following actions:

The --config action is used for configuration -- it comprises several options both
for configuration and for pre-establishing the processing sequence;
--dbmake action is used for converting the HOWTO-INDEX (howtos.html)
into a flat data-base file for simplifying `grep' operations;
--top/--nav actions are used for inserting top header and/or navigation links;
--charset is run for supporting Non-English Character Sets;
--index action optionally builds an abstract of document nodes in Info format;
--update action allows to reconfigure the How2 frontend using different settings;
--manify generates abstracts of DOCS in nroff format stored under /usr/man/man0; it
accepts values of ``=sec'', ``=whatis''. and ``=all''
for indexing these abstracts as Html files under /var/help/man.

Note: Actions are not combinable but sequential. First one must --config;
--config has in-built options for pre-establishing execution sequence; else
the sequence can only be:

dbmake->charset->top->manify OR dbmake->charset->nav->index->manify.

Documents that have been compiled using the procedure described above are
browseable either through their own navigation links (when compiled with --top
action) or with nav links inserted (when compiled with --nav action) using any browser
running under a Webserver or through the Info and Man utilities.

Using how2

The ``How2'' font-end has a Web and a CL interface. Both are briefly described below,
including browsing, searching and quering features:

Query the Index

To get a listing of all your documents currently compiled, run ``how2'' from
the console without arguments.

To query the database (index), please run ``how2'' script on the command
line with a [browser] and [keyword] argument as follows:

how2 --find - SOME-TOPIC		(V-Terminal)
how2 --find --netscape SOME-TOPIC	(X-Window)

To query the Index directly from the browser, please call the ``how2qry''
Perl script on the browser's address bar with a keyword, as follows:

POST Method: http://localhost/cgi-bin/.../how2qry (Fill in the form)
GET Method: http://localhost/cgi-bin/.../how2qry?keyword

Search from console

To perform text search on your installed documents from the terminal,
please run ``how2 --search'' with a pattern, [path], and [interface]
argument; if the last two optional args are not supplied, search is
done on default path of your documents, and results go to STDOUT; e.g:

how2 --search SOME-TOPIC SOME-PATH -x

output options are -x (=Xterm, results to browser); defaults to VT.

Search from browser

To perform text search on documents from the browser, please call the
``how2cgi'' shell script on the browser's address bar, as follows:

POST Method: http://localhost/cgi-bin/.../how2cgi (Fill in the form)
GET Method: http://localhost/cgi-bin/.../how2cgi?search_path+keyword

For Web queries, the how2qry Perl script can also be called from the browser's address bar (a)
or via the hyperlink (b). The format of the calling statement for queries is as follows:

a) lynx http://localhost/cgi-bin/DOCS/how2qry?SOME-DOCS-TOPIC
b) <a href="/cgi-bin/DOCS/how2qry?SOME-DOCS-TOPIC">Get It</a>

where the character ? is the query separator, while the keyword SOME-DOCS-TOPIC is
passed to the Perl script how2qry with the "GET" method.

The results returned by such call is a formatted Web-pabe with links to the matching topics.

From this point on, internal navigation of your documents and linking takes effect via the
how2www cgi (see ``how2www'' documentation.)

Browse and view with Info/Man:

To use the Info program for browsing documents and viewing the Index,
please call the ``how2'' script on the console with the --info switch
or call ``info'' itself with appropriate arguments:

	how2 --find -- SOME-TOPIC-FILENAME --info

	info --file SOME-TOPIC-FILENAME
OR
	info --directory PATH-TO-TOPICS

Use the Man utility with ``0" as section argument to get Abstracts for
DOCS compiled with How2 and stored in nroff format under /usr/man/man0:


	how2 --find -- SOME-EXACT-TOPIC-NAME+SECTION --man
OR
	man SECTION SOME-EXACT-TOPIC-NAME

Note that Info-style hyperlinks inserted at compile-time are fully operational
when using the Info program for both plain text and Html document browsing. Such a
functionality is equally supported by the ``man2html'' and ``man2cgi'' CGIs for
nroff-formatted DOCS.

Therefore, the above commands have the same effect as when called from the browser:

	http://localhost/cgi-bin/man2html?SOME-MAN-PAGE+SECTION
	http://localhost/cgi-bin/man2cgi?SOME-EXACT-TOPIC-NAME+SECTION

If the Abstract of your topic is not returned, consider reconfiguring with --manify.

Query the apropos/whatis database:

Using the ``apropos`` and ``whatis'' utilities you get pretty similar results:

	how2 --query --apropos A-NAME	or
	how2 --query --whatis A-KEYWORD

because the whatis database has meanwhile been rebuilt.

Testing

Tested on the following machines with the full range of HOWTOs (English version
ca. 7000 files) on Windows and Linux (desktop environment Xterm) the time taken
to complete all compilation steps outlined above, including "manifying" docs was:

                CPU1:   Pentium-MMX, RAM<16Mb 
                                -- Cygwin: over an hour
                                -- Linux: less than 20 min.
                CPU2:   Celeron, RAM=192Mb 
                                -- Cygwin: ca. half an hour
                                -- Linux: less than 10 min.

Compile-time on Linux was dramatically reduced (5-10 min.) when run from a VT.

The How2 front-end was tested -- and worked -- on the following Linux distributions:
OpenLinux v.2.3, Knoppix v.2.78, Fedora v.9, Slackware v.10.

If How2 runs successfully on your system, the author would appreciate being informed.
(Please e-mail the author with How2-Success/Failure as subject, and your system
with version somewhere in the message.)

History

This program was not expressly designed for Ldp/Linux HOWTOs.
How2 is merely exemplified in such a way as to be useful to all users by supplying
Info/Man-like query and browsing functionality for HOWTO documents.

It was developed from a HOWTO Tip ("2.2 Script to view those compressed
HOWTOs by Didier Juges", Tips-HOWTO-2.html) that suggested to place all
HOWTO documents into a separate directory, compress them and use the `less'
command for viewing (it worked--for ASCII texts!). Quoting:

#!/bin/sh
if [ "$1" = "" ]; then
ls /usr/doc/faq/howto | less
else
gunzip -c /usr/doc/faq/howto/$1-HOWTO.gz | less
fi

Well, how2 goes much further.

Downloads

The How2 project is kindly hosted by SoureForge.net.
Official releases are available on the projects group page.

Source Code

You can use a web interface to browse the How2 CVS repository.

Enjoy It Somehow!