==== How2 - The front-end to GNU/Linux HOWTO help documents ====
== AUTHOR ==
Vangelis Eustratius
== VERSION ==
*2.0.1*
== SOURCE ==
http://lynxx.org/ranerox/downloads/how2.zip
http://prdownloads.sourceforge.net/how-2/how2-2.0.1.zip?download
== DESCRIPTION ==
This is a simple, powerful, flexible and efficient program for
compressing, compiling, browsing and querying ASCII document nodes. It
is exemplified on the Linux HOWTO Html/ASCII documentation (LDP) but is
not limited to it. In fact, it can be used on any set of plain text
documents provided they are numbered nodes of the same file name so as
to insert Info-style navigation links. Navigation, then, takes effect
via a cgi script or "info". All references to "HOWTO docs" or "Html
docs" below are applicable to any set of ASCII text documents.
In this version the program flow after configuration is automated, and
configuration complexity has been reduced to the likes of the whatis /
makewhatis duo. It has also become extensively well-documented.
In the How2 front-end, definition of program setup variables are
controlled by a configuration function. Installation is easy. No need to
modify any scripts other than a couple of config parameters, which have
been clearly documented, in order to make the How2 front-end working on
your system. While you don't need to know Shell, Perl or CGI
programming, we suggest that you should know the basics of Html and Perl
scripting for understanding and/or further developing the main program
in other (than HOWTO Html/ASCII documentation) scopes.
== PROGRAM RUNTIME ENVIRONMENT ==
Runs on any Unix or Linux Operating System (including Cygwin on MS
Windows); provides WWW access; Supports Perl, cgi-bin and the Sh/Bash
Shell; allows searching of files and directories by cgi and shell
scripts.
== MINIMUM SYSTEM REQUIREMENTS ==
* The 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.
== COPYRIGHT NOTICE ==
The How2 software is a product of RanErox Soft. All rights reserved.
This is free software under the GNU GPL; see the source for copying
terms.
This software was written by Vangelis Eustratius .
Permission is granted to copy, distribute and/or modify the code or
scripts under the terms of the GNU Free Documentation License, Version
1.1 or any later version published by the Free Software Foundation; with
no Invariant Sections, no Front-Cover Texts and no Back-Cover Texts.
== DISCLAIMER ==
These Scripts are provided on a "As Is" basis. RanErox Soft
will not be liable (nor responsible) whatsoever for any direct
or indirect damages caused by the use of this Software
(or Scripts). Please use this software at your own risk.
There is NO warranty; either for MERCHANTABILITY nor FITNESS
FOR A PARTICULAR PURPOSE.
************************************************************
Please read the following paragraphs carefully. This is essential for a
smooth and successful installation. If you don't have the time for it,
skip to the last Section N.
== TABLE OF CONTENTS ==
* A. Contents in Distribution Archive
* B. Pros and Cons of Use / LDP issues / Preparing for Installation
* C. Local Installation Procedures / WWW Installation
* D. Configuration Parameters and Script Functions
* E. Cgi-bin/html_public Directory Structure
* F. Running the How2 Front-end
* G. Building the "index.info" and "mansec/manwhatis" indices
* H. Calling the CGI Programs by "GET Method"
* I. Customizing the How2 Front-end
* J. ToDo (Support for .DVI, .PS, .PDF, .HLP etc. formats)
* K. Supporting Non-English Character Sets
* L. Remarks on Large Number of Files/Folders and Recursion
* M. Troubleshooting Installation / Compilation Problems
* N. Quick Overview
==== A. Contents in Distribution Archive ====
You should have at least the following files for a standard version of
the How2 front-end (for complete list s. MANIFEST):
# Archive Description
____________________________________________________________________________
(1) display.pl - Simple Perl script to display ASCII docs -
used in place of "how2www" if no CGI support
is requested; called with absolute or relative
path to file to be displayed as query string
(2) fix_dos - Takes care DOS EndOfLine char for Unix
(3) fmt.vim - A "Vi" command-file for formatting
(4) how.cnf - Sample configuration file - overwritten
each time "--config" is run
(5) how2 - Shell script to search, find, and list the
contents of installed documents and send
the results to a browser by making their
specially formatted content available to
viewer/browsers; functionality described below;
main functions described in Section D;
(6) how2cgi - Shell script for Text-based Search on
installed HOWTO documents using "grep" with
links to files matching the keyword entered.
Currently configured only for POST Method.
When called from the browser's address bar,
this CGI can perform generic search on any
file on the system matching $ext[ension]
with a path and keyword argument as follows:
http://localhost/cgi-bin/how2cgi?path+keyword.
(7) how2_query - Perl script using "index.info" as data-base
for displaying available DOCs topics with
links to those installed while supporting
Text-based Search directly on these; modelled
after rpm -q switch with output formatting
options; supplied only w/commercial release
(8) how2qry - Perl script used to query and list the
summary (index) of installed DOCs and
link the HOWTO documents thru "how2www"
(9) how2view.pl - Perl script to view available HOWTOs;
to be called directly from the browser
(not all of the topics may be on your system)
(10) how2www - CGI script "info2www" remastered for
querying HOWTOs; originally written by
Eelco van Asperen and Roar Smith.
Script was reverse-engineered so as to
properly display compressed HTML docs
with/without their own navigation and still
browse Info nodes without formatting them.
(11) howtos - Last updated listing of available HOWTOs
from LDP (Aug 2004); flat db file put
together using "sorted_howtos" (under
"howtos.d" in LDP tree) and "howtos.html"
(formerly HOWTO-INDEX-3.html); customized
(12) html2txt - Perl script, converts html files into ascii
by just stripping anything between < and >
while preserving mailto: & http: Html links
(13) html2wiki.m4 - M4 macro script, converts html files into Wiki
while preserving Text and Html features such
as B, P, LI, DT, HR, HREF, etc, some UTF chars,
and by stripping anything between < and >
(14) info2www - Gateway between GNU Info nodes and hypertext
markup (pre-configured)
(15) makehow2 - Shell-Perl-m4 script used for configuring
the How2 frontend; contains the main
commands for compiling documents that in
pre-2.0.0 versions were standalone scripts;
main functions described in Section D;
its functionality briefly described below
(16) Makefile - File required by "make" for installation;
installs after passing an "md5" checksum.
(17) man2cgi - Gateway between manual pages and Html markup
(old version of "man2html", #18) -- used to
access manpages under man0 ("man2html" won't)
(18) man2html - Gateway between manual pages and hypertext
markup (configurable via switches)
(19) mansec - Awk script used to generate an index into
a manual section by using GNU "find" utility;
running this subroutine with --manify option
allows for indexing any DOCs compiled w/How2
and placed under /usr/man/man0
(20) manwhatis - Awk script used to generate a whatis index
into the manual pages by GNU "find" util;
running this subroutine with --manify option
allows for indexing any DOCs compiled w/How2
and placed under /usr/man/man0
(21) test.cgi - CGI script to display the absolute pathname
of the Home Directory and several Server
Environment variables.
==== B. Pros and Cons of Use / LDP issues / Preparing for Installation ====
== Pros and Cons of Use ==
The basic advantage of using How2 is that Html/Text documents can be
optionally compressed and still be browseable by means of a CGI script
or the Info program; this is done by inserting the "magic" info byte and
node identifier on top of all documents (with ``--top'' or ``--nav'').
Secondly, the insertion of a navigation form in all nodes (if numbered)
facilitates linking docs without navigation in a Prev-Next fashion. On
the other hand, Linux HOWTO docs have their own navigation so there is
no need to insert links for inter-document navigation. Thirdly, the How2
front-end provides a consistent interface for search and query
operations both from the console (through the Info program) and any
browser.
Alternatively, ASCII data type HOWTO documents can be directly accessed
by the Info program -- after being processed with ``--top'' for
inserting the "magic" info byte -- if they are in the INFOPATH (see Info
help on how to do it). Further support is not foreseen in the How2
front-end for the scheme of calling "info" to view ASCII HOWTO texts
other than the creation of "index.info". This file can be easily
appended to default "dir" file (the Info index in the Info install
directory) or be conveniently renamed to something like "dir.info" with
only one link to it from "dir" itself. The ``how2'' script supports
minimally such a scheme with the --info option, while trying to render
HTML in AsCii, but such conversion compromises it. Besides, there isn't
much point in viewing Html docs using "info".
Finally, How2 supports an RPM-like query on Html/ASCII documentation
that facilitates cross-reference and quick access of topics that are not
formally linked in separate documents. This is done by using the the
built Index (a flat database converted from a HOWTO-INDEX file) and
searching it to return query results with links to DOCs topics as well
as a linked listing of installed files refering to the query keywords.
Disk space is no longer an issue with most PCs, and therefore
compression is redundant. But having a search and query possibility for
documents that are vital for operating and trimming a system such as
Linux is not luxury; all the more so, since it is a long way until Linux
will dispose of an M$-Windows-style Help System based on searchable .CHM
e-books that are regularly updated.
== LDP and HOWTO-related issues ==
The How2 front-end is mostly compatible with the old node-based format
of the Linux Documentation Project. The new 2003 scheme (shown below) is
visually more readable, but hardly more informative.
Moreover, it has the disadvantage of mixing node-based and
directory-based filenames, which doesn't make it easily portable to
batch treatment. The tree sketch below may be used to clarify the
difference between the old and new LDP Html scheme:
OLD SCHEME (Linux HOWTOs) NEW SCHEME (Linux Dox Pro)
---------------------------- -----------------------------------
HOWTO_html/ HOWTO_html/
| |
SOME-HOWTO.html SOME-HOWTO/
SOME-HOWTO-1.html | |
... | Intro.html
SOME-HOWTO-n.html ... ...
OTHER-HOWTO.html | End.html
OTHER-HOWTO-1.html OTHER-HOWTO/
... | |
... | Intro.html
OTHER-HOWTO-n.html ... ...
| | End.html
... |
| MORE-HOWTO.html
| MORE-HOWTO-1.html
... ...
| MORE-HOWTO-n.html
... ...
| |
mini/ mini/
| |
SOME-mini-HOWTO.html SOME-mini-HOWTO/
SOME-mini-HOWTO-1.html | |
... | Intro.html
SOME-mini-HOWTO-n.html ... ...
OTHER-mini-HOWTO.html | End.html
OTHER-mini-HOWTO-1.html |
... OTHER-mini-HOWTO/
OTHER-mini-HOWTO-n.html | |
... ... ...
| MORE-mini-HOWTO.html
... ...
---------------------------- -----------------------------------
In 2004 the HOWTOs maintainer seemed trying to abolish the 'mini'
directory altogether, and place a "mini-TOPIC-index.html" in HOWTO root
linking to resp. topics in mini-HOWTOs subtrees. This will make How2's
requirement for one-layer-deep tree structure fully compatible with the
front-end's processing capability but not for inserting nav links since
several files in subdirectories are not numbered nodes. Overall, this
poses no problem; and because the HOWTO format in all Linux distributions
has not yet tuned-in to this scheme, there is no need to implemented it
yet.
The How2 front-end can successfully deal with this structure
nevertheless. Sample configuration settings for Html/ASCII HOWTO docs
are displayed in Section N, "Quick Overview".
Since the new LDP Html HOWTO format does not support numbered nodes,
How2 cannot be directly implemented for inserting navigation links.
However, its structure can be reduced to the node-structure so as to
implement How2. This should be done either manually, by checking (in our
example above) if Intro.html=nodeNr.1... End.html=Nr.N etc., and
renaming them under the same filename-- or programmatically, by
inventing a Sed or Vim script that extracts e.g. Section numbers from
the HTML code that are uniquely identifiable as node numbering and
appends them to the filename. In either way, one must seriously consider
that one deals with processing several thousands of documents (for more
details, see Section I, Hint 2).
== Preparing for Installation ==
When you read this file, we know that you have successfully decompressed
the ZIP archive using a PKZIP/WinZip (or equivalent) program and already
seriously considering for an installation. Read INSTALL file for
details.
To proceed, two directories need to be created: one in the "html_public"
directory and another one in the "cgi-bin" directory; you may call them
both DOCS for ease of identification. If you choose not to create these
at all or not at these locations, the post-install configuration routine
with ``--config'' switch will prompt you for creating them.
==== C. Local Installation Procedures / WWW Installation ====
== I. Local Installation ==
I.1) Download the how2.zip distribution archive from
http://www.lynxx.org/.
I.2) To install How2 locally, decompress the 32 bit How2 ZIP file using
PKZIP/WinZip (available from http://www.shareware.com/) or Unix "zip".
I.3) Read this README.TXT and the description section of all CGI and
Shell scripts carefully. Do not change the contents of the cgi or shell
script codes unless you have backed them up.
I.4) 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
action ``--config'' for pre-configuring scripts before they are
installed; it then installs them to destination directories.
The ``--config'' action facilitates the configuration of Awk, Perl and Shell
scripts for running ``how2''. For example, it will let you probe for
directories called "cgi-bin" or "DOCS" that are present on your system;
so you'll have a clue as to where these are located.
You may run it now or later or manually configure these scripts by
opening them in a text editor and following the configuration
instructions that are presented as comments.
When called, ``--config'' asks for certain parameters that must be
supplied--on the command line or from a configuration file with the
"auto" switch--for successfully installing and running How2. These are:
1 - Set DOCs generic name (default: HOWTO)
2 - Whether new format is requested (y/n)
3 - Whether to insert navigation (y/n)
4 - Whether to Build index (y/n)
5 - Whether CGI support is required (y/n)
6 - Domain and/or IP to run as
(default: localhost@127.0.0.1)
7 - Path to cgi-bin/DOCS directory
8 - Path to public-html/DOCS directory
9 - Program to compress your documents with
(if left blank or 0, no compression)
10- Suffix (.ext) of files to be processed
(default: html)
I.5) Define these parameters in aid of the script's dialog.
If correctly answered, default How2 Html/Text documents will be placed
in the "html_public" directory, CGI scripts in the "cgi-bin" directory,
and the selected compression program will be (optionally) used for
zipping DOCs. Compression can be in the following formats: bzip2,
ncompress, gzip, zip.
Setting "new format" to No pre-establishes the program flow to execute
the following sequence of actions: dbmake->top. Setting "new format" to
Yes will pre-establish the sequence: dbmake->nav->index.
Choosing "No CGI support" means that docs will NOT be navigable if they
do not have their own nav links and will NOT be moved to cgi-bin/DOCS
dir.
If finished running ``--config'', configuration will be completed and
you can skip the following Section D, but it is recommended to review it
once for reference and clarification purposes.
== II. WWW Installation ==
II.1) In order to explain the WWW installation clearly, we have assumed
the following directory structures:
/base_dir/
--> Full directory pathname, relative to the ROOT directory
of your server
/base_dir/DOCS/
--> chmod 0777 /base_dir/DOCS/.
--> stores installed How2 front-end during install
--> Note: If your site does not support
this directory, install How2 front-end to
your Html directory
/base_dir/cgi-bin/
--> cgi scripts, chmod 0755
/base_dir/cgi-bin/DOCS
--> How2 front-end cgis: how2qry, how2www etc..
/base_dir/html/
--> Base Html directory storing
Web Pages of your site
/base_dir/html/DOCS/
--> Stores DOCS Html files for compilation
/base_dir/html/DOCS/subdir1/
--> Stores further-DOCS Html files
for compilation
Your site structures could be different from the above. If you
experience problems with installing the Software on your site, please
consult your admin or a person knowledgable in WWW and CGIs. We do not
provide technical assistance.
II.2) Create any necessary directories/subdirectories on your server for
storing How2 front-end files and DOCs Html files. This can be done via
Telnet or FTP.
``For Example:''
-- You can store your DOCs Html files (HOWTO Html files
that come with the RPM package) on a directory called "HOWTO"
created under your main Html directory.
-- You can store your How2 front-end cgis on a directory
also called "HOWTO" created outside your Html directory.
II.3) Adjust system configuration parameters on the cgi and shell
scripts (see the listing in Section D) to match with your server and
system environment. (This must be done carefully.)
II.4) Connect via Telnet/SSH to the Internet and open a shell console to
run the How2 Front-end.
II.5) Check the permissions of cgi, perl and shell scripts how2,
how2qry, how2www etc.. Use Unix "chmod" command to change their access
modes to 0755, i.e. rwxr_xr_x . This can be done via Telnet or FTP.
II.6) See Section M for Troubleshooting Server and Path-related
problems.
II.7) Proceed as described in Section E.
==== D. Configuration Parameters and Script Functions ====
With ``--config'' action there should normally be no need for changing
anything in the Scripts by editing them manually. Otherwise you will
have to modify a number of Program Configurations Parameters before you
can execute scripts to compile your documents. These parameters are CGI
and Shell script specific, therefore you should read the following
sections or the comments in the scripts carefully if planning to modify
them. Variables with the Dollar prefix are in (or destined for) Perl
scripts; variables without the Dollar-sign prefix are in Shell scripts.
# Parameter Where Description
____________________________________________________________________________
(1) $COURIERize how2www Var not explicitly stated, but if so
and initialized ($COURIERize=1;) all
docs are displayed in Courier font
(needed only with .txt or .info docs
that otherwise remain unformatted
when embedded in HTML without
tags) -- unnecessary for Html docs.
(2) $HOW2CGI_DIR how2cgi Path to cgi-bin/DOCS directory
how2 (see Section E for details)
(3) $HOW2CGI_URL how2 Url of cgi-bin/DOCS directory
(see Section E for details)
(4) $HOW2CGIPATH how2qry Path to cgi-bin/DOCS directory
makehow2 (see Section E for details)
how2www
(5) $HOW2DOX_DIR how2 Path to public-html/DOCS directory
how2cgi (see Section E for details)
(6) $HOW2DOXPATH how2qry Path to public-html/DOCS directory
makehow2 (see Section E for details)
how2www
(7) $INPUTFORM how2www specifies whether to have an input
info2www form for going to an Info/HOWTO node
(8) $domain how2 Host Domain; default is "localhost"
how2cgi
how2qry
makehow2
(9) $ip makehow2 Host IP; default is "127.0.0.1"
(10) $NAVFORM how2www specifies whether to have navigation
info2www links on all your Info/Html documents
(11) $QUERYFORM how2qry specifies whether to have an input
query form for going to a DOCs node
(12) $ZPROG display.pl Program to compress your documents with;
how2 Options are: ncompress, bzip2, gzip,
how2www zip; set to 0 for no compression
how2cgi
makehow2
(13) @HOW2DIRS how2www Subdirectories in which to search for
DOCs node files; default is "mini"
(14) @INFOPATH how2www Path of directories in which to search
for Info/Html DOCs files.
(15) charset how2char Code of language Character Set
(16) cgibin how2 Path to cgi-bin/DOCS directory
how2cgi (see Section E for details)
makehow2
(17) cgi_bin_dir how2 merely checks that the "cgi-bin"
how2cgi directory is properly called so,
makehow2 and not, for example, "cgi_bin"
(18) docs how2 generic name for the documents
how2cgi (e.g. HOWTO)
how2qry
how2www
makehow2
(19) ext how2 Extension of documents (files) to be
how2cgi processed by How2: default is "html";
makehow2 what matters, however, is the
file format; other options are "info"
"txt" etc..; files are always assumed
to be in ASCII Text data type
(20) GETIT how2cgi GET Method to use w/this CGI (please
edit manually if mostly not using forms)
(21) htmldir how2 Path to public-html/DOCS directory
how2cgi (see Section E for details)
makehow2
(22) how2home how2 Path to source directory (where the
makehow2 program gets unpacked)
(23) infonav makehow2 variable for default format of Info-
style navigation links;
comment for use w/html extension
(24) nocgi how2cgi variable for configuring CGI support
makehow2 or not -- values are 0=yes, 1=no
(25) POSTIT how2cgi POST Method to use w/this CGI (default)
(26) zhtml makehow2 default variable for Sed substitution
cmd file for docs w/html extension;
comment/edit for use w/info extension
(27) zprog how2 Program to compress your documents with;
how2cgi Options are: ncompress, bzip2, gzip,
how2qry zip; set to 0 for no compression
how2www
makehow2
____________________________________________________________________________
Note that it may look a bit confusing, but most of script parameters are
just Path variables for a couple of directories: cgi-bin & html_public.
The "how2" script is split into the following major functions
(originally standalone scripts):
# Function Description
____________________________________________________________________________
(1) ascii4html - Function used to recursively convert Html
files under the CWD into Ascii plain text;
called with the --asc4htm switch
(2) how2find - Main script's function for search and query;
--find switch results in calling the following:
1. how2qry Perl script for DOCs (default)
2. info Program for AsCii DOCs (-i switch)
3. man2cgi CGI for man0-pages (-m switch)
4. info2www CGI for Info-pages (-i2 switch)
5. man2html CGI for man-pages (-m2 switch)
(3) how2query - Shell function directly invoking the "apropos"
"whatis" utilities for querying the database;
called resp. with the -a and -w switches
(4) how2search - Shell text-search function using "grep" to
find matching keywords in installed DOCs
and send the results either to a browser or
to the terminal (default: --term switch);
works for browser in X-Window (--gui switch)
by preparing a Web page with highlighted
results and links to matching documents:
only called from the command-line; please
use "how2cgi" (#6) to search directly
from the browser's address bar.
(5) how2x - Shell function that finds any file on the
system matching the keyword $DOCs or
actually any file matching a shell RegExp
(6) node4file - Function used to split demarkated ASCII/Html
file(s) into corresponding numbered nodes,
while inserting navigation links (--nod4fil)
The "makehow2" script is split into the following major functions
(originally standalone scripts):
# Function Description
____________________________________________________________________________
(1) catibyte - Function used to insert a binary ("magic")
byte (^_) in header line of Info files as
delimiter and for navigation (required
by "how2www" CGI script)
(2) fix4index - Function executed by main function "navmake"
in order to prepare intermediary
files that are used by "mkindex" function
--optionally run--to build overview file
"index.info".
(3) fixdb_sed - Sed batch command func used to process
HOWTO-INDEX-5.htm for converting HTML into
flat database file
(4) how2_pl - Perl function to parse a sample "index.info"
from updated listing of available HOWTOs
(not all of the topics may be on your system)
(5) how2_plx - Perl script to parse "howtos" flat db for
generating nroff abstracts of HOWTOs under
/usr/man/man0
(6) how2char - Shell function to insert the language
Character Set in tag of all DOCs
node-files recursively under the current
directory for enabling Html document
browsing in Non-English languages;
also inserts a Stylesheet tag
(7) how2config - Shell function to semi-automatically
perform post-install configuration
routines for the How2 compilation script
set; uses dialogue (manual config)
or a configuration file supplied
on the command line (auto config)
(8) how2info_pl - Perl function reading a pair of data files to
extract information relating to a group
of filespec archivers, and write out a
browseable listing of those archivers;
used to dynamically build "index.info"
only with the --pedantic switch from
"--index" opt which takes long to complete
(9) how2make - Shell function used to insert Info headerline
in all DOCs node-files recursively under the
the current directory for document formatting
routines with the How2 front-end scripts.
Insertion indispensible for rendering
HTML files in Info format and making them
available to a browser through "how2www".
(10) makedb - Shell function converting HTML into flat data-
base file for simplifying "grep" operations
(11) how2setup - Shell function corrolary to "how2config";
carries out setup routines after answering
to dialogues or when a configuration file
is supplied on the command line
(12) html_sed - A "sed" command function for substitutions
(13) htmlnav_sed - A "sed" command function for substitutions
(14) info_sed - A "sed" command function for substitutions
(15) infonav_sed - A "sed" command function for substitutions
(16) manify - Function used to index alphabetically the
sections/descriptions of Unix manuals
in Html format including DOCS pages
(under default path: /var/help/man) --
uses 'mansec' and 'manwhatis' awk scripts
(17) mkwhatis - Shell function used to create the whatis.how2
database (simplified version of makewhatis);
this database is then appended to "whatis"
(18) mkindex - Shell function using a converted flat
database file and a pair of input files
(as output by "fix4index" script) to
prepare three files which, in their turn,
are automatically parsed by archiver Perl
routine "how2info_pl" to build a summary
"index.info" file. It lists files actually
existing while cross-checking with the db.
(19) my1st - Shell function fixing first header line and
several links in "index.info"
(20) navmake - Shell function using a flat database file,
converted from Html or plain-text
numbered nodefiles, to insert Info-style
or HTML navigation links in all nodes;
checking for filenodes integrity;
creating summary 0-nodes for each group
of same-named files; preparing for summary
index.info; processing any number of files
(by default up to 99 nodes) in any number of
subdirs, one-layer-deep from top directory;
easily customizable for use in other scopes.
This is a recursive version of "how2make".
(21) titleget_html_sed - A "sed" command function for substitutions
(22) titlepat_html_grp - A "grep" pattern-file
(23) topfield_html_sed - A "sed" command function for substitutions
(24) update - Function allowing to reconfigure the How2
frontend using different settings
==== E. Cgi-bin/html_public Directory Structure ====
It is now time to install the howto-[lang]-html-xxxxxxxx-x.i386.rpm or
.tgz on your system or copy/move the HOWTO Html/Text documents already
installed to the "INSTALL/" (e.g. "HOWTO") directory.
This directory must have the following structure:
.../HOWTO
.../HOWTO/mini
and it should contain the relevant Html/Text documents.
The "makehow2" script exits if it finds a structure not conforming to
its requirements, i.e. folders deeper than one-layer from DOCS (HOWTO),
or prompts for removing them.
``NOTE:''
*In several Linux distributions these documents are installed in
disparate locations such as "/usr/doc/HOWTO/other-formats/html" and
"/usr/doc/HOWTO/mini/other-formats/html" by the rpm program. For the
How2 compilation to succeed, it is required that mini-HOWTO docs are
contained in the "mini" directory and that this latter is a subdirectory
of the top "HOWTO" directory.*
The "INSTALL/" (e.g. "HOWTO") directory can be anywhere on the system
provided it has adequate privilages for user "root" (read/write).
The "public-html/DOCS" directory does not need special permissions other
than the default ones.
On the other hand, the "cgi-bin/DOCS" directory should have write and
execute permissions for the user it runs under.
==== F. Running the How2 Front-end ====
To run How2, please open a shell console, change to the created
"public-html/DOCS" directory, verify that all scripts are in place and
make sure the HOWTO dirs have the correct structure (Section E). Verify
that a document with filename ``howtos'' is present either in the
current working or in the "mini" directory.
The first step is to configure the How2 frontend; it pre-establishes
program flow, so that the remaining steps are executed automatically;
else the sequence is:
(1) ./makehow2 --config
The second step is to build a flat database from generated file
``howtos.htm'':
(2) ./makehow2 --dbmake
The third (optional) step is to define your language CharSet code:
(3) ./makehow2 --charset
There are two ways to proceed for compling in the last step:
(4) run: ./makehow2 --top - insert only required "Node: Top"
in all documents recursively under the
current working DOCS directory
or: ./makehow2 --nav - insert full Info-style navs
in all documents recursively under the
current working DOCS dir and any subdir
that is one-layer deep from top
Unless "No CGI support" is explicitly requested during configuration,
all documents (whether compressed or not) are moved to "cgi-bin/DOCS"
directory for being made available to the CGIs. This has its Pros and
Cons. Pros: Docs are additionally secured from arbitrary browsing
through the "cgi-bin" directory permissions. Cons: Docs are not
available for normal browsing -- due to "cgi-bin" directory perms.
When processing completes, documents can be made available for querying,
searching and browsing through ``how2qry'', ``how2cgi'' and ``how2www''
CGIs.
==== G. Building the "index.info" and "mansec/manwhatis" indices ====
1) The first procedure is optional and only required if the
``how2_query'' Perl script is installed (yet in draft). Running:
./makehow2 --index or ./makehow2 --index --full
will build the overview file "index.info", which is basically identical
in content to the "howtos.html" mini-HOWTO file, but has a database
format that can be used for querying and displaying available HOWTO
topics with direct links to those installed while supporting Text-based
Search directly on these. The Index is an abstract of documents
currently compiled in Info format and can be viewed with the "info"
program.
2) The second procedure is also optional but overall useful for having
an alphabetical index of compiled DOCS at hand since sorting is not
supported:
--manify or -m
will generate abstracts in nroff format stored under /usr/man/man0.
When supplied with values, it builds the "section", "whatis" or both
indices, which are listings of alphabetically sorted nodes and
descriptions of DOCS and manpages respectively:
--manify=sec --manify=whatis --manify=all
To view these indices, simply call them on your browser. These are
normal Html pages, but links from them call the GCIs ``man2html'' or
``man2cgi'' for all manpages and man0-pages respectively, and are
therefore only accessible by using the "GET" Method described in the
next Section.
For details on use, please see "Contents", Sect. A.
To view the latest available listing of HOWTOs from LDP (Aug 2004) a
sample file is included (``howtos'') that can be called on the browser
with ``how2view.pl''.
==== H. Calling the CGI Programs by "GET" Method ====
If you have experience in CGI programming, you may appreciate that there
is another method of calling a cgi program other than using the POST
Form method. This is known as the GET method.
With the "GET" method, you have the advantage of calling a cgi program
directly from the command line, the browser's address bar (example i.)
or via the hyperlink (example ii.). The form of the calling statement
for queries is as follows:
Example i)
lynx http://localhost/cgi-bin/DOCS/how2qry?SOME-DOCS-TOPIC
Example ii)
<a href="/cgi-bin/DOCS/how2qry?SOME-DOCS-TOPIC">Get It</a>
where the character ? is the query separator with SOME-DOCS-TOPIC as
keyword.
This has been formalized in the ``how2'' Shell script, which does
precisely the same but in abbreviated form. You may now query for DOCs
topics from the command line by typing e.g.:
how2 --find --netscape SOME-DOCS-TOPIC
This opens the selected browser (default is Lynx) with the appropriate
protocol, path and query arguments on the browser's address bar.
(Please type "how2 --help" for more information on usage.)
The results returned by such call is a formatted Web-pabe with links to
the matching topics. From this point, internal navigation of your
documents and linking takes effect via the ``how2www'' CGI, which is
basically the ``info2www'' CGI, reverse-engineered so as to properly
display compressed Html docs with their own navigation, and still browse
Info nodes without formatting them.
However, the form of the calling statement for queries with ``info2www''
is peculiar to this CGI. Only when supplied with the full "nodename" or
"(filename)"--in parentheses--or "(filename)nodename" will this script
return results. This is because it complies with the Info arg FILENAME.
A good example (typed in the browser's address bar) is:
http://localhost/cgi-bin/DOCS/how2www?/usr/doc/how2-2.0.1/README
OR
http://localhost/cgi-bin/DOCS/how2www?(mini/HOWTO-INDEX-5.html)
Text and Info files (.txt, .info extension) are called similarly.
Here's an example:
http://localhost/cgi-bin/DOCS/how2www?index.info
In such situation, setting the $COURIERize variable to "1" will allow
the .info or .txt page to be displayed formatted even if all characters
are set in Courier font also for Html web-pages.
To test the difference in performance between ``how2www'' and
``info2www'', just configure $INFOPATH in ``info2www'' to include the
path where your HOWTO Html docs are placed (instead of default Info
nodes), and call it, as in the following examples:
http://localhost/cgi-bin/DOCS/info2www?mini/HOWTO-INDEX-5.html
http://localhost/cgi-bin/DOCS/info2www?how2.info
You will see the Html document in a "View Source" mode--full with HTML
tags. Please read the documentation on ``info2www'' for more
information.
Another example of GET is viewing the updated database of available
HOWTOs supplied from LDP (Aug 2004) with the Perl script
``how2view.pl''. It can be called directly from the browser with GET
method:
http://localhost/cgi-bin/DOCS/how2view.pl
(Not all of the topics shown may be included in your
howto-xxx-yyy-zzz.rpm.)
One more example is performing text-search with the ``how2cgi'', which
also has a calling statement of its own:
http://localhost/cgi-bin/how2cgi?/full/path/to/search/in+KEYWORD
where the character + is a query/command separator (with
full/path/to/etc fed to "find" and KEYWORD fed to "grep"); KEYWORD can
only be a full word. Note also that it is a shell script called from the
browser.
A last example is GETting the "mansec" and "manwhatis" indices:
http://localhost/cgi-bin/DOCS/mansec?SECTION
http://localhost/cgi-bin/DOCS/manwhatis?SECTION
No need to remember these paths since there are links to them in
``how2qry''.
Last, not least, DOCS abstracts in nroff format and man-pages are
likewise accessible from the browser through the ``man2html'' GCI:
http://localhost/cgi-bin/man2html?SOME-MAN-PAGE+SECTION
http://localhost/cgi-bin/man2html?whatis+1
http://localhost/cgi-bin/man2cgi?SOME-EXACT-TOPIC-NAME+SECTION
==== I. Customizing the How2 Front-end ====
Customization means modifying or trimming a program so that it performs
other functions than it was designed for. Certain directions in which to
modify the How2 Front-end are mentioned only as clues, and need detailed
scripting for a successful customization.
== Hint 1. How to compile .txt and .info files with How2 ==
Since any ASCII text can be made navigable in conjuction with the
``how2www'' cgi, using a How2 compilation procedure (Node:Top insertion
etc.) is recommended. Only certain variables (e.g. $ext) need
modification in the scripts, and auxiliary files (i.e. sed command
scripts) need switching to the related extension. This is done by choice
during configuration (e.g. setting ext=txt), and applies to the LDP
AsCii HOWTO only for inserting a "Node:Top" header because HOWTO ASCII
documents are not split in nodes.
If planning to customize the How2 Front-end for use with absolutely any
ASCII document, however, the following must be additionally taken into
consideration:
(a) Changing stream-editor commands embedded in the scripts that
apply only to Linux HOWTOs (expressly commented in scripts).
(b) Rewritting sed commands that apply only to HTML docs (simple).
(c) Resolving issues such as what is "title" or "database field"
in a plain text file without any tags or related tokens; etc.
Pragmatic considerations and practical limitations, on the other hand,
are a real impediment to further pursuing such a course: Why bother
compiling documents with How2 when software such as MS CHM or TeTeX can
perform the same feat almost perfectly? --The answer is in the music.
== Hint 2. How to implement How2 on the new LDP Html scheme ==
The solution is already hinted at (Section B). Just by reducing the new
scheme to the old one--after renaming verbose filenames to nodes--the
How2 Front-end can be successfully run. For RegExp-based,
bulk-file-renaming, try using renamer.sourceforge.net.
However, reduction must be done in two separate configuration steps,
because in the new LDP Html scheme directories are two layers deep:
a) When running C<--config> in the first round, the html_public
should be set to e.g. html_public/HOW2. All subdirectories of
HOWTOs (new LDP Html scheme) may be installed, _except_ the "mini"
subdir with its subdirectories. All steps will be followed,
starting from the install directory, as delineated in Section N.
At this stage, if an index.info overview file is required it must
be built and renamed to something like "index.info.1" (it is
placed by default in the cgi-bin/HOW2 directory).
b) In the second round, starting from the install directory again,
another configuration will have to be performed -- this time with
the html_public set to html_public/HOW2/mini and all "mini" HOWTOs
installed in the "mini" subdir with its subdirectories. Processing
will be repeated to the end. The new "index.info" will be renamed
again so that it can be appended to "index.info.1" with something
like cat index.info.1 + cat index.info.2 > index.info.
== Hint 3. How to incorporate How2 in the howto-[lang]-[format]-etc.rpm ==
Well, not actually, but here's a draft for Red-Hats to build an RPM
package:
< # Note that this is a relocatable package
< %define ver 2.0.1
< %define RELEASE1
< %define rel %{?CUSTOM_RELEASE} %{!?CUSTOM_RELEASE:%RELEASE}
< %define localstatedir /usr/doc/DOCS
< %define _prefix /usr/local
<
< Summary: The LDP HOWTO Node Front-end
< Name: how2
< Version: %ver
< Release: %rel
< Copyright: GPL
< Group: Applications/Viewers
< Source: http://prdownloads.sourceforge.net/how-2/how2-%{ver}.zip?download
< BuildRoot: /var/tmp/%{name}-%{version}-root
< URL: http://lynxx.org
< Prefix: %{_prefix}
< #Prereq: /sbin/install-info
< #Requires: howto-[lang]-[format]-etc.rpm
< #Requires: Perl >'= 5.x.x
< #Requires: httpd >'= 1.3.x
< #BuildRequires:
<
< %description
< A Linux HOWTO front-end for document compilation and query which has
< the following features:
< - Runs on any Unix/Linux Operating System (including Cygwin on MS Windowze)
< - Supports multiple languages and Character Sets
< - Allows searching of files and directories by cgi, perl and shell scripts.
< - Makes any ASCII document set navigable provided they are numbered nodes
< - Provides WWW access; Uses cgi for querying linked documents
<
< This front-end is basically inspired by the project of a Linux Help System,
< and should be useful to all users.
<
< %prep
< %setup -q
<
< %build
< ./configure --prefix'=%{_prefix}
< --bindir'=%{_bindir} --mandir'=%{_mandir}
< --localstatedir'=%{localstatedir} --libdir'=%{_libdir}
< --datadir'=%{_datadir} --includedir'=%{_includedir}
< --sysconfdir'=%{_sysconfdir}
<
< CFLAGS'="$RPM_OPT_FLAGS" make
<
<
< %install
< [ -n "$RPM_BUILD_ROOT" -a "$RPM_BUILD_ROOT" !'= / ] && rm -rf $RPM_BUILD_ROOT
<
< make prefix'=$RPM_BUILD_ROOT%{_prefix} bindir'=$RPM_BUILD_ROOT%{_bindir}
< mandir'=$RPM_BUILD_ROOT%{_mandir} libdir'=$RPM_BUILD_ROOT%{_libdir}
< localstatedir'=$RPM_BUILD_ROOT%{localstatedir}
< datadir'=$RPM_BUILD_ROOT%{_datadir}
< includedir'=$RPM_BUILD_ROOT%{_includedir}
< sysconfdir'=$RPM_BUILD_ROOT%{_sysconfdir} install
<
<
< %clean
< [ -n "$RPM_BUILD_ROOT" -a "$RPM_BUILD_ROOT" !'= / ] && rm -rf $RPM_BUILD_ROOT
<
< %post
< #-->run script to auto-detect PUBLIC_HTML & CGI-BIN path <--
< if which HOWTO-update>/dev/null 2>&1; then HOWTO-update; fi
< chown root%{_sbindir}/HOW2
< chmod g+s %{_sbindir}/HOW2
<
< %postun
< #-->run uninstall.sh<--
< if which HOWTO-update>/dev/null 2>&1; then HOWTO-update; fi
<
< %files
< %doc BUGS CHANGES COPYING INSTALL MANIFEST
< %defattr (-, root, root)
< %{_bindir}/*
< %attr(6755,root,tty) %{_sbindir}/DOCS-update
< %{_datadir}/HOW2/*
< %{_sysconfdir}/*
< %{_mandir}/*/*
< %{_datadir}/pixmaps/*
< %{_datadir}/how2www/apps/System/*
<
< %changelog
< * Thu Jun 24 2004 Vangelis Eustratius
< - Added RPM-build draft.
< * Mon Jun 21 2004 Vangelis Eustratius
< - Built 2.0.1 Release
and a draft of Makefile.am:
< SUBDIRS = \
< pixmaps\
< how2\
< idl\
< omf-install\
< po \
< intl
<
< infodir = $(datadir)/gnome/help/how2/C
< info_DATA = ChangeLog NEWS
<
< EXTRA_DIST = \
< LICENSE \
< applet-docs.make \
< how2.spec.in \
< how2.spec \
< sgmldocs.make\
< app-docs.make\
< intltool-extract.in \
< intltool-merge.in \
< intltool-update.in \
< ChangeLog \
< NEWS
<
< ## to automatically rebuild aclocal.m4 if any of the macros in "macros/" change
< @MAINT@include macros/macros.dep
< @MAINT@macros/macros.dep: macros/Makefile.am
< @MAINT@ cd macros && $(MAKE) macros.dep
``CAUTION:''
*When modifying the How2 front-end scripts, care must be taken so that
the scripts are edited only with a binary-enabled text editor (such as
Vim or Emacs); otherwise a couple of binary characters (Tab \t, Newline
\n etc.) will be washed away, ruining the entire program.*
==== J. ToDo (Support for .DVI, .PS, .PDF, .HLP etc. formats) ====
A "how2conv" conversion script to ASCII can take care of that -- not
released yet for this package, but several are available on the Web or
even as system binaries and scripts.
As is well known, the particularity of these formats is that they are
pre-compiled non-text documents. However, all are convertible to HTML
while preserving most all of their formatting features (styles etc.).
This way they can be supported and used by the How2 front-end.
Still more interesting is the conversion of DOCs compiled with "How2"
(i.e. having nav links) into Windows Help files. This involves recursive
transformation of DOCs into .tex format ('X2tex' script). These are
easily convertible into .rtf format by using makertf.sourceforge.net to
get the input files for the MS native software ("Windows Help Compiler",
ftp://ftp.microsoft.com/Softlib/MSLFILES/hcwsetup.exe). See e.g. the
WinHelp file for Perl: http://code-genie.com/ufiles/help_perl5.zip.
Makertf is a program that converts "Texinfo" files into "Rich Text
Format" (RTF) files. It can be used to make WinHelp Files from GNU
manuals and other documentation written in Texinfo. Makertf is derived
from GNU Makeinfo, part of the GNU Texinfo documentation system.
The input for MS .CHM ("Compliled Hypertext Markup") help files are
plain HTML fed to the Compiler (MS Help Workshop v. 4+). See e.g. the
.chm for glibc-2.2.3: http://code-genie.com/ufiles/help_glibc-2.2.3.zip.
Windows-help (.chm) are also convertible into MS Reader eBooks (.lit).
For details go to a shareware app: CHM2LIT at http://www.dolit.com.
Another ToDo in developing How2 would obviously be to reconsider and
re-write patches for implementing layer-independent recursion into
subdirectories. This is possible, but isn't really so pressing an issue.
``REMARK:''
*By the way, How2 was not expressly designed for Ldp/Linux HOWTOs. It is
merely exemplified in a way as to be useful to all users, by supplying
Info/Man-like query and browsing functionality for HOWTO documents.*
==== K. Supporting Non-English Character Sets ====
The procedure mentioned in this section is optional. It is useful only
if your language version of the howto-[lang]-html-xxxxxxxx-x.i386.rpm
contains non-English (local) characters, eg. Chinese, Korean, Japanese,
Greek, German, French, etc..
Under this situation, it is better to preset the character set in the
output Html pages so that the language characters can be properly
displayed by the browser.
If you don't perform this procedure, you will have to configure your
browser manually each time in order to see the characters properly.
The procedure involved is quite simple. Just set the $charset parameter
with the ``--charset'' switch to the correct language code and then run:
./makehow2 --charset
This will insert the selected language Character Set into a tag
in all DOCs node-files (see also installation procedures above).
Here is what the tag will look like after processing completes:
Here are the charset codes for some languages:
Chinese Simplified (China) : gb2312
Chinese Traditional (HK & Taiwan) : Big5
English (US_ISO) : iso-8859-1
Greek (Modern) : iso-8859-7
For other languages, please check your local documentation.
Additionally, how2char inserts a Stylesheet tag that allows
you to stylize your documents the way you like. Default filename of
stylesheet is how2.css; by editing this file you may change the looks of
DOCs pages.
==== L. Remarks on Large Number of Files/Folders and Recursion ====
Because a security issue emerged, we make the following remarks that
should normally belong to customization:
(i) The How2 Front-end by default processes up to 99 files in a nodefile
group (topics set) for ca. 999 topics. This can be easily changed in a
loop of ``navmake'' and ``mkindex'' functions, but is not recommended to
increase the count on low-memory machines or thin shells. The loop
merely checks node count, creating a default page for missing ones.
There is currently no HOWTO topic having 50 nodes and there aren't more
than 500 topics.
(ii) The How2 Front-end is so designed as to process any number of
nodefile groups in any number of subdirectories, provided they are
one-layer-deep from top dir. An English HOWTO version, for example,
comprises over 7000 files. This takes some time, but is not guaranteed
to work on all systems (see "WARNING" at end of Section M). Therefore,
it is strongly recommended to test-run this program with only a couple
of dozen documents in a first round to see if it works on your system.
(iii) The ``navmake'' shell function in "makehow2" operates worm-like
(by reproducing itself in subdirectories to be processed); normally
there is just one: "mini". This is in itself harmless, but a possible
error when modifying it may result in the reproductive loop not to be
removed, as designed, so that script is forced to recursively process
all subdirectories at any level deeper than 1 from top (if existing);
this can be easily turned into a system nightmere, such as loosing the
entire "home" filesystem on Linux or the whole Cygwin program installed
on MS Windows--or whatever. This is due to the following string being
formed and evaluated somewhere along the way: rm -rf /.
Therefore, please refrain from modifications if not knowing what you are
doing. You have been warned!
==== M. Troubleshooting Installation / Compilation Problems ====
After configuration is finished, the program runs virtually hands-off.
Yet, if you encounter problems during installation, please check the
following:
(1) If you have Server Error messages displayed on the screen during
execution of your CGI scripts:
* check if mod_perl is compiled in httpd as a module (Unix: Apache) --
if not you must reinstall Apache,
* check if mod_cgi is compiled in Perl (Unix/Win32) -- if not reinstall
Perl,
* check if CGI/Perl extensions are enabled for execution (Win32: IIS) --
see Perl documentation on how to associate and execute Perl/CGI scripts
on IIS,
* check if you have uploaded the scripts to your server using ASCII
transfer mode,
* check if the Perl location defined on the 1st line of your scripts is
correct,
* check if you have modified the scripts incorrectly. Modification can
only be carried out and saved via an ASCII text editor.
(2) If your cgi scripts have problems to display the Html files on the
screen, check the settings of parameters requiring the absolute
pathnames, i.e. @HOW2DIRS, $HOW2CGIPATH, $HOW2DOXPATH, $HOW2CGI_DIR,
$HOW2DOX_DIR, @INFOPATH, cgibin, cgi_bin_dir, htmldir etc.
You can install the ``test.cgi'' script that comes with this software on
your "cgi-bin" directory and execute this script through your browser to
display the absolute pathname of your Home Directory and related Server
Environment variables.
````test.cgi'' script installation procedure:''
* change the 1st line of the script to reflect correct location of Perl
* upload the script to your cgi-bin directory using ASCII transfer mode
* apply chmod 0755 on test.cgi to allow for script execution
If the URL of your HOWTO directory is http://yourdomain.com/DOCS/
and the output of C is /home/xyz/public_html/, the setting
of your $htmldir should be "/home/xyz/public_html/DOCS".
(3) If your cgi scripts have problems to run, check and -- if necessary
-- change the permissions (this is normally not needed since the
``--config'' action takes care of permissions as well.)
Use Unix "chmod" command to change the access mode of the affected
directory (i.e. public_html/DOCS and/or cgi-bin/DOCS) to 0777
or 775. Then change the access mode of the How2 scripts contained therein
to 0777 or 775 respectively.
``Examples of how to manually change permissions:''
(i) Use Unix "chmod" command to change the access mode of the
cgi-bin/DOCS (i.e. the directory containing your Perl & Shell scripts)
to 0755. Then change the access mode of the How2 Frontent Script files
to 0755.
``Example:''
cd /home/xyz/cgi-bin/DOCS (some shells use a different command)
chmod 0755 how2www
chmod 0755 how2qry
chmod 0755 man2cgi
...
(ii) Use Unix "chmod" command to change the access mode of the
public_html/DOCS (i.e. the directory containing your DOCs Html files) to
0777. Then change the access mode of the DOCs Html files to 0777.
``Example:''
cd /home/xyz/public_html/DOCS (some shells use a different command)
chmod 0777 .
chmod 0777 *.html
cd mini
chmod 0777 .
chmod 0777 *.html
(4) If you still can't solve the problems, contact a programmer or
WWW-guru.
-- ATTENCION -- WARNING -- ATTENTION -- WARNUNG -- ATTENZIONE --
Installation of the software package requires that system commands are
fully operational; this is not the case in certain Linux distibutions.
These are obviously stripped-down or altered distros of GNU/Linux
programs.
In this case installation/configuration will fail ungracefully. Sorry!
==== N. Quick Overview ====
== INSTALL ==
After decompressing the how2.zip archive to a temporary folder, proceed
as described in the following steps:
0- cd HOW2_HOMEDIR/ (i.e. the install directory)
1- install or move all your docs here & in any subdirs
2- 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
== USING ==
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
/man/man0; it accepts values of "=sec", "=whatis". and "=all" for
indexing these abstracts as Html files under public_html/DOCS/.
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.
``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 ``--search'' action with a pattern, [path], and [interface]
argument; if the last two optional args are omitted, 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 HOWTOs/DOCs 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
This cgi is currently configured for POST Method and for HOWTO docs
matching their extension (edit script to change method or extension).
``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.
== TESTS ==
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: ca. one 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.)
************************************************************
Note that this software was developed on MS Windowze with a
minimal (10Mb) Cygwin installation and then ported to Linux.
************************************************************
*A Courtesy of RanErox Software, (c) 2004, www.lynxx.org*