* release of groffer 1.0.0

Changements of the shell version since 0.9.31

* shell/groffer.sh: Use version.sh in the upper directory.


The groffer versions 1.* have two kinds of program, a shell
version and a Perl version.

The shell version is kept from the old shell only versions of
groffer 0.*.  Most of the former files in the main groffer
directory are now moved to the subdirectoy shell/.

The Perl version of groffer is a complete rewrite; most of its
files are found in the subdirectory perl/.

The Makefile.sub decides whether the shell or Perl version of
groffer is installed.  This is done by the program perl_test.pl.

In the following, all files in the groffer directory tree are
mentioned.

* ChangeLog: This file.  It contains information for groffer
versions >= 1.0.0 with shell and Perl kinds.  For older groffer
versions, see shell/ChangeLog.0 which contains information for the
shell only versions of groffer 0.*.

* Makefile.sub: The old Makefile.sub was extended to support the
shell and the Perl version of groffer at the same time.  If the
test of perl_test.pl succeeds the groffer Perl version will be
installed, otherwise the shell version is used.

* perl_test.pl: This is used by Makefile.sub and installed with
the Perl version of groffer.  It is a test of the installed perl
version.  The installed Perl version should be greater or equal
than the version that is required by this file.

* version.sh: This is the old file kept from the shell version of
groffer.  It stores the groffer version, the date of the last
update, and the groff version.  It is used and installed for the
shell and Perl version of groffer.

* README: This is the old README file extended by information on
the shell and Perl kinds of groffer.

* perl/: Subdirectory for the Perl version of groffer.

* perl/groffer.pl: This is the groffer script of the Perl
version, a Perl source file that handles the complete groffer
functionality.

* perl/man.pl: This is the collection of functions that are
related to man pages, apropos, and whatis.  It is loaded by
perl/groffer.pl.

* perl/func.pl: This is the collection of miscellaneous functions.
It is loaded by perl/groffer.pl.

* perl/split_env.sh: A shell script that is used by
perl/groffer.pl to split a large shell environment variable to a
Perl array.

* perl/groffer.man: This is the man page of the Perl version of
groffer.  It is derived from groffer.man of the shell version.  It
will only be installed when the Makefile.sub chooses to install
the Perl version of groffer instead of the shell version.

* perl/README_PERL: This file contains information of the Perl
compatibility and details that are special to the Perl version.

* shell/: Subdirectory for the shell version of groffer.

* shell/ChangeLog.0: The former ChangeLog file of the groffer
versions 0.* was moved to this file.  It contains information of
the shell only version of groffer 0.*.

* shell/groffer.sh: This is the old groffer.sh file of the shell
version.

* shell/groffer2.sh: This is the old groffer2.sh file of the shell
version.

* shell/groffer.man: This is the old man page groffer.man of the
shell version.  The shell version keeps its own man page.  It will
only be installed when the Makefile.sub chooses to install the
shell version instead of the Perl version.

* shell/README_SH: This is the old README_SH file of the shell
version containing information of the shell compatibility.

1 files changed, 296 insertions, 0 deletions

diff --git a/contrib/groffer/shell/README_SH b/contrib/groffer/shell/README_SH
new file mode 100644
index 00000000..b84be986
--- /dev/null
+++ b/contrib/groffer/shell/README_SH
@@ -0,0 +1,296 @@
+README_SH
+
+Special description for the shell version of `groffer'
+
+
+The files related to the shell version are
+
+shell/groffer.sh	starting script of groffer
+shell/groffer2.sh	main script of groffer
+shell/groffer.man	manual page of groffer
+shell/README_SH		description of the shell version of the program
+shell/ChangeLog.0	information on all changements of groffer versions 0.*
+version.sh		script that handles the version information
+
+
+Scripts
+
+The shell version of `groffer' contains two files, `groffer.sh' and
+`groffer2.sh'.
+
+`groffer.sh' is a short introductory script without any functions.  I
+can be run with a very poor Bourne shell.  It just contains some basic
+variables, the reading of the configuration files, and the
+determination of the shell for `groffer2.sh'.  This script is
+transformed by `make' into `groffer' which will be installed into
+@bindir@, which is usually /usr/local/bin.
+
+`groffer2.sh' is a long main script with all functions; it is called
+by `groffer.sh' (`groffer' after installation).  It is installed
+unchanged into @libdir@/groff/groffer, which is usually
+/usr/local/lib/groff/groffer.  This script can be called with a
+different shell, using the `groffer' option `--shell'.
+
+
+Options
+
+The `groffer' script provides its own option parser.  It is compatible
+to the usual GNU style command line This includes long option names
+with two signs such as `--option', clusters of short options, the
+mixing of options and non-option file names, the option `--' to close
+the option handling, and it is possible to abbreviate the long option
+names.  The abbreviation of long options is enhanced by letting each
+internal `-' sign generate a new center of abbreviation.  So each
+command line argument starting with `--' can represent a multiple set
+of abbreviations.
+
+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.
+
+
+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 adding a temporary error file that is
+tested by function exit_test() and by replacing `var=$(...)' by
+function obj_from_output().
+
+
+Function Definitions in `groffer2.sh'
+
+Each funtion in groffer2.sh has a description that starts with the
+function name and symbols for its arguments in paranthesis `()'.  Each
+`<>' construction gives an argument name that just gives a hint on
+what the argument is meant to be; these argument names are otherwise
+irrelevant.  The `>' sign can be followed by another character that
+shows how many of these arguments are possible.
+
+<arg>      exactly 1 of this argument
+<arg>?     0 or 1 of these arguments
+<arg>*     arbitrarily many such arguments, incl. none
+<arg>+     one or more such arguments
+<arg>...   one or more such arguments
+[...]      optional arguments
+
+A function that starts with an underscore `_' is an internal function
+for some other function.  The internal functions are defined just
+after their corresponding function.
+
+
+External Environment Variables
+
+The groffer.sh script uses the following external system variables.
+It is supposed that these variables are already exported outside of
+groffer.sh; otherwise they do not have a value within the script.
+
+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 (`:' separated 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_*().
+
+
+Speed
+
+The major speed gain is the disabling of all debug features.  This is
+the default for the installed version of `groffer'.  Before the run of
+`make', the debug feature of $_DEBUG_FUNC_CHECK, corresponding to
+option --debug-func, is enabled by default.  The resulting heavy
+slowing down should be regarded as a temporary feature.
+
+Another increase of speed was the replacement of the many `ls' calls
+by analysing a `find' of manpath with `grep'.
+
+
+Shell Compatibility
+
+The `groffer' shell scripts are compatible to 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.  This draft is
+available at http://www.funet.fi/pub/doc/posix/p1003.2/d11.2 in the
+internet.
+
+The POSIX draft does not include `local' variables for functions.  So
+this concept was replaced by global variables with a prefix that
+differs for each function.  The prefix is chosen from the function
+name.  These quasi-local variables are unset before each return of the
+function.
+
+The `groffer' scripts were tested under the shells `ash', `bash',
+`bash-minimal', `dash', 'ksh', `mksh', `pdksh', 'posh', and `zsh'
+without problems in Linux Debian.  A shell can be tested by the
+`groffer' option `--shell', but that will run only with groffer2.sh.
+To start it directly from the beginning under this shell the following
+command can be used.
+
+  <shell-name> groffer.sh --shell=<shell-name> <argument>...
+
+
+Some shells are not fully POSIX compatible.  For them the following
+restrictions were done.  For more information look at the
+documentation `Portable shells' in the `info' page of `autoconf'
+(look-up in Emacs-Help-Manuals_Info).
+
+- The command parts `then', `else', and `do' must be written each on a
+  line of their own.
+
+- Replace `for i in "$@"' by `for i' and remove internal `;' (kah).
+
+- Replace `set -- ...' by `set x ...; shift'.  After the first
+  non-option argument, all arguments including those starting with `-'
+  are accepted as non-option.  For variables or `$()' constructs with
+  line-breaks, use `eval set' without quotes.  That transforms a
+  line-break within a variable to a space.
+
+- The name of the variable in `for' is chosen as a single character
+  (old ash).  The content of such variables is not safe because it can
+  also occur in other functions.  So it is often stored in an
+  additional quasi-local variable.
+
+- `echo' is not portable on options; some `echo' commands have many
+  options, others have none.  So `echo -n' cannot be used, such that
+  the output of each function has complete lines.  There are two
+  methods to avoid having `-' as the first character of any argument.
+  Either a character such as `x' can be prepended to the argument;
+  this must later on be removed by `sed'.  Otherwise, `echo' can be
+  replaced by `cat <<EOF'.
+
+- `ls' has problems.  Old UNIX systems echoed the error message to
+  standard output.  So handle the output with `sed'.  If the output
+  contains `not found' map it to an empty string.
+
+- As `test -e' is not available in Solaris 2.5 replace it by
+  `test -f || test -d'.
+
+- As `unset' is not supported by all shells replace it by `eval
+  ${_UNSET}' where this variable is `unset' if it exists and `:'
+  otherwise.
+
+- Some shells have problems with options in `eval'.  So quoting must
+  be done right to hide the options from `eval'.
+
+- In backquote calls `` avoid the backquote ` in comments.
+
+- Replace `true' by `:', `false' isn't used.
+
+- Do not redefine builtins as functions (ash).
+
+- Avoid `[^...]' in `case' patterns (ash).
+
+- `trap' does not allow error code 127.
+
+The scripts call the following commands with all options used:
+.
+:
+apropos
+break
+bzip2 -c -d -t
+cat
+catz
+cd
+continue
+echo
+eval
+expr
+grep
+groff -v
+grog -T -X -Z
+gs -c -d -f -q -s
+gzip -c -d -f
+less -r -R
+ls
+man -k --apropos
+mkdir
+mv
+pwd
+return
+rm -f -r
+rmdir
+sed -e -n
+set -e
+sh -c
+shift
+test -c -d -f -r -s -w -x
+trap
+umask
+unset
+
+
+Bugs
+
+If the `groffer' run is interrupted by Crtl-C the clean up is not done
+by all shells.  The `trap' commands work for the shells `bash',
+`bash-minimal', and 'ksh'; they do not work for `ash', `dash',
+`pdksh', `posh', and `zsh'.
+
+
+####### License
+
+Last update: 28 Jul 2006
+
+Copyright (C) 2003,2004,2005,2006 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, 51 Franklin St - Fifth Floor, Boston, MA 02110-1301, USA.
+
+
+####### Emacs settings
+
+Local Variables:
+mode: text
+End: