Description of groffer.sh, the shell version of groffer

Display groff files and man pages on X or tty, even when compressed.


Usage

Input comes from either standard input or command line parameters that
represent names of exisiting roff files or standardized specifications
for searching man pages.  All of these can be compressed in a format
that is decompressible by `gzip', including `.gz', `bz2', and `.Z'.

The following displaying modes are available:
- Display formatted input with the X roff viewer `gxditview',
- with a Prostcript viewer,
- with a dvi viewer,
- with a web browser.
- Display formatted input in plain text mode.
- Run a pager on the formatted input in a text terminal (tty).
- Generate output for some groff device on stdout without a viewer.
- Output only the source code without any groff processing.
- Generate the troff intermediate output on standard output
  without groff postprocessing.
By default, the program tries to display with `gxditview' as graphical
device, `tty' mode with a pager is tried as text display.


Several File Arguments

So far, `groffer' bundles all filespec parameters into a single output
file in the same way as `groff'.  The disadvantage of this is that all
file name arguments must have the same groff language.

To change this, the option parsing must be revised for large parts.
It seems that this would create incompatibilities, so the actual
option strategy is kept.


Error Handling

Error handling and exit behavior is complicated by the fact that
`exit' can only escape from the current shell; trouble occurs in
subshells.  This was solved by sending kill signals, see $_PROCESS_ID
and error().


Shell Compatibility

This shell script is compatible to the both the GNU and the POSIX
shell and utilities.  Care was taken to restrict the programming
technics used here in order to achieve POSIX compatibility as far back
as POSIX P1003.2 Draft 11.2 of September 1991.

The only non-builtin used here is POSIX `sed'.  This script was tested
under `bash', `ash', and `ksh'.  The speed under `ash' is more than
double when compared to the larger shells.  The new version of `ash'
taken from `dash' produces strange errors, so the automatic call of
`ash' was removed.

This script provides its own option parser.  It is compatible to the
usual GNU style command line (option clusters, long options, mixing of
options and non-option file names), except that it is not possible to
abbreviate long option names.

The flexible mixing of options and file names in GNU style is always
possible, even if the environment variable `$POSIXLY_CORRECT' is set
to a non-empty value.  This disables the rather wicked POSIX behavior
to terminate option parsing when the first non-option command line
argument is found.


Survey of Functions defined in groffer.sh

The elements specified within paranthesis `(<>)' give hints to what
the arguments are meant to be; the argument names are irrelevant.
<>?     0 or 1
<>*     arbitrarily many such arguments, incl. none
<>+     one or more such arguments
<>      exactly 1

A function that starts with an underscore `_' is an internal function
for some function.  The internal functions are defined just after
their corresponding function; they are not mentioned in the following.

abort (text>*)
base_name (path)
catz (<file>)
clean_up ()
diag (text>*)
dirname_append (<path> [<dir...>])
dirname_chop (<path>)
do_filearg (<filearg>)
do_nothing ()
echo2 (<text>*)
echo2n (<text>*)
error (<text>*)
get_first_essential (<arg>*)
is_dir (<name>)
is_empty (<string>)
is_equal (<string1> <string2>)
is_file (<name>)
is_non_empty_file (<name>)
is_not_dir (<name>)
is_not_empty (<string>)
is_not_equal (<string1> <string2>)
is_not_file (<name>)
is_not_prog (<name>)
is_not_writable (<name>)
is_not_yes (<string>)
is_prog (<name>)
is_yes (<string>)
leave ()
landmark (<text>)
list_append (<list> <element>...)
list_from_cmdline (<pre_name_of_opt_lists> [<cmdline_arg>...])
list_from_split (<string> <separator>)
list_get (<list>)
list_has (<list> <element>)
list_has_not (<list> <element>)
main_*(), see after the functions
man_do_filespec (<filespec>)
man_setup ()
man_register_file (<file> [<name> [<section>]])
man_search_section (<name> <section>)
man_set()
manpath_add_lang(<path> <language>)
manpath_add_system()
manpath_from_path ()
normalize_args (<shortopts> <longopts> <arg>*)
path_chop (<path>)
path_clean (<path>)
path_contains (<path> <dir>)
path_not_contains (<path> <dir>)
path_split (<path>)
register_file (<filename>)
register_title (<filespec>)
res (<var_name> <function_name> <arg>...)
reset ()
save_stdin ()
string_contains (<string> <part>)
string_not_contains (<string> <part>)
tmp_cat ()
tmp_create (<suffix>?)
to_tmp (<filename>)
trap_clean ()
trap_set (<functionname>)
usage ()
version ()
warning (<string>)
whatis (<filename>)
where (<program>)


External non-groffer Environment Variables

If these variables are exported in the script the `ash' shell coughs
when calling `groff' in `main_display()'.

external system environment variables that are explicitly used
$DISPLAY:		Presets the X display.
$LANG:			For language specific man pages.
$LC_ALL:		For language specific man pages.
$LC_MESSAGES:		For language specific man pages.
$PAGER:			Paging program for tty mode.
$PATH:			Path for the programs called (: list).

groffer native environment variables
$GROFFER_OPT		preset options for groffer.

all groff environment variables are used, see groff(1)
$GROFF_BIN_PATH:	Path for all groff programs.
$GROFF_COMMAND_PREFIX:	'' (normally) or 'g' (several troffs).
$GROFF_FONT_PATH:	Path to non-default groff fonts.
$GROFF_TMAC_PATH:	Path to non-default groff macro files.
$GROFF_TMPDIR:		Directory for groff temporary files.
$GROFF_TYPESETTER:	Preset default device.

all GNU man environment variables are used, see man(1).
$MANOPT:		Preset options for man pages.
$MANPATH:		Search path for man pages (: list).
$MANROFFSEQ:		Ignored because of grog guessing.
$MANSECT:		Search man pages only in sections (:).
$SYSTEM:		Man pages for different OS's (, list).


Object-oriented Functions

The groffer script provides an object-oriented construction (OOP).  In
object-oriented terminology, a type of object is called a `class'; a
function that handles objects from a class is named `method'.

In the groffer script, the object is a variable name whose content is
the object's data.  Methods are functions that have an object as first
argument.

The basic functions for object handling are obj_*().

The class `list' represents an array structure, see list_*().


####### License

Copyright (C) 2003,2004 Free Software Foundation, Inc.
Written by Bernd Warken

This file is part of groffer, which is part of groff.

groff is free software; you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2, or (at your option)
any later version.

groff is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public
License for more details.

You should have received a copy of the GNU General Public License
along with groff; see the files COPYING and LICENSE in the top
directory of the groff source.  If not, write to the Free Software
Foundation, 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
