head	1.14;
access;
symbols
	groff-1_20_1_real:1.14
	groff-1_20_1:1.14
	groff-1_20:1.14
	groff-1_19_2:1.7
	FDL:1.3
	groff-1_19_1:1.2
	groff-1_19:1.1;
locks; strict;
comment	@# @;


1.14
date	2009.01.05.20.10.39;	author wl;	state Exp;
branches;
next	1.13;
commitid	LOYcfESGVCXMFixt;

1.13
date	2009.01.04.14.50.56;	author wl;	state Exp;
branches;
next	1.12;
commitid	RfDBP1nYqohhW8xt;

1.12
date	2006.11.07.00.35.27;	author bwarken;	state Exp;
branches;
next	1.11;

1.11
date	2006.10.14.05.59.54;	author wl;	state Exp;
branches;
next	1.10;

1.10
date	2006.09.11.16.06.18;	author bwarken;	state Exp;
branches;
next	1.9;

1.9
date	2006.07.28.16.36.02;	author bwarken;	state Exp;
branches;
next	1.8;

1.8
date	2005.09.14.01.11.28;	author bwarken;	state Exp;
branches;
next	1.7;

1.7
date	2005.08.03.06.32.11;	author wl;	state Exp;
branches;
next	1.6;

1.6
date	2005.07.02.17.37.54;	author wl;	state Exp;
branches;
next	1.5;

1.5
date	2005.05.26.21.01.57;	author wl;	state Exp;
branches;
next	1.4;

1.4
date	2005.05.20.06.12.24;	author wl;	state Exp;
branches;
next	1.3;

1.3
date	2004.06.04.22.42.34;	author wlemb;	state Exp;
branches;
next	1.2;

1.2
date	2004.05.04.04.46.54;	author wlemb;	state Exp;
branches;
next	1.1;

1.1
date	2002.10.19.09.56.36;	author wlemb;	state Exp;
branches;
next	;


desc
@@


1.14
log
@Update copyright year.
@
text
@README

The `groffer' program is the easiest way to read documents written in
some `roff' language, such as the `man pages', the manual pages in
many operating systems.  All `roff' preprocessors, such as `chem', are
detected and executed automatically.


Source files in this directory

ChangeLog	information on all changements for groffer versions 1.*
Makefile.sub	make file used by groff
README		this file, general description of the program
version.sh	information on version number and last update
perl_test.pl	test whether perl has a suitable version
perl/		subdirectory for the Perl version, see perl/README_PERL
shell/		subdirectory for the shell version, see shell/README_SH


Input

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' or `bzip2', including `.gz', `bz2',
and `.Z'.

`groffer' has many built-in `man' functionalities to find and read the
manual pages on UNIX and similar operating systems.  It accepts the
information from an installed `man' program, but tries to find a man
path by itself.

`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 use 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.


Output

All input is first sent to `grog' to determine the necessary `groff'
command and then to `groff' together with all necessary preprocessors.
So no special `groff' arguments must be given.  But all `groff'
options can be specified when this seems to be appropriate.

The following displaying modes for the output are available:
- Display formatted input with
-- a PDF viewer,
-- a Postcript viewer,
-- a web browser,
-- the X `roff' viewer `gxditview',
-- a DVI viewer,
-- a pager in a text terminal (tty).
- Generate `groff' output on stdout without a viewer.
- Generate the `groff intermediate output' on standard output without
  postprocessing.
- Output the source code without any `groff' processing.
- There are some information outputs without `groff' processing, such
  as by option `-V' and the `man' like `whatis' and `apropos'
  outputs.

By default, the program tries to display a graphical device in X; on
non-X text terminals, the `tty' text mode with a pager is tried by
default.


File access

The shell and the Perl version of groffer now use umask of 077.  This
is a very strict security issue.  It allows only access of the
temporary files by the file owner.


Compatibility

`groffer' is compatible with the `man' program.  It supports .so
requests based on the man path and compressed files.  That's more than
`groff' does.


Mailing lists

For reporting bugs of `groffer', groff's free mailing list
<bug-groff@@gnu.org> can be used.

For a general discussion, the mailing list <groff@@gnu.org> is more
useful, but one has to subscribe to this list at
http://lists.gnu.org/mailman/listinfo/groff.

See the `README' file in the top directory of the `groff' source
package for more details on these mailing lists.


####### License

Last update: 5 Jan 2009

Copyright (C) 2003, 2004, 2005, 2006, 2009
  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 3 of the License, 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 this program. If not, see <http://www.gnu.org/licenses/>.


####### Emacs settings

Local Variables:
mode: text
End:
@


1.13
log
@

* */*: Update GPL2 to GPL3.
@
text
@d97 1
a97 1
Last update: 12 Oct 2006
d99 2
a100 1
Copyright (C) 2003,2004,2005,2006 Free Software Foundation, Inc.
@


1.12
log
@Update groffer-1.0.3
@
text
@d106 2
a107 2
the Free Software Foundation; either version 2, or (at your option)
any later version.
d115 1
a115 3
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.
@


1.11
log
@

* 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.
@
text
@d5 2
a6 1
many operating systems.
d43 3
a45 3
options and then to `groff'.  So no special `groff' arguments must be
given.  But all `groff' options can be specified when this seems to be
appropriate.
d63 3
a65 3
By default, the program tries to display with `gxditview' as graphical
device in X; on non-X text terminals, the `tty' text mode with a pager
is tried by default.
@


1.10
log
@Update groffer 0.9.25
@
text
@d8 1
a8 1
Source files
d10 2
a11 2
ChangeLog	information on all changements
Makefile.sub	groff make file
d13 4
a16 6
README_SH	description of the shell version of the program
TODO		information on what is left to be done
groffer2.sh	main script of groffer
groffer.man	manual page of groffer
groffer.sh	starting script of groffer
version.sh	script that handles the version information
d24 2
a25 1
that is decompressible by `gzip', including `.gz', `bz2', and `.Z'.
d48 3
a51 2
-- a Postcript viewer,
-- a PDF viewer,
a52 1
-- a web browser,
d67 7
a75 4
`groffer' consists of two shell scripts.  It should run on any POSIX
or Bourne style shell that supports shell functions.  See file
`README_SH' for more information.

d96 1
a96 1
Last update: 04 Sep 2006
@


1.9
log
@groffer update 0.9.24.
@
text
@d74 4
d94 1
a94 1
Last update: 28 Jul 2006
d97 1
a97 1
Written by Bernd Warken
@


1.8
log
@
Update groffer 0.9.23
@
text
@d8 13
d90 1
a90 1
Last update: 01 Sep 2005
d92 1
a92 1
Copyright (C) 2003,2004,2005 Free Software Foundation, Inc.
@


1.7
log
@

* release of groffer 0.9.21

### @@...@@ constructs

* groffer.sh:
- $_AT: New variable for `@@'.
- @@...@@: Replace the @@...@@ constructs by variables _AT_..._AT.
These constructs are transformed by `make' to useful information.
Keep all of these constructs in the first part of groffer.sh.  For
a run before a `make' call, the script sets these variables to
special values for testing purpose.
- $_GROFFER_LIBDIR: Variable pointing to the groffer library
directory @@libdir@@/groff/groffer.

### Configuration files

* groffer.sh:
- Add test for `$()' construct.
- Read and transform the configuration files and execute the
emerging commands.  The `sed' script was heavily enlarged to
handle line with spaces and quotes.  The emerging script is now
called by `eval', so no temporary file is needed.
- $_CONF_FILE_ETC, $_CONF_FILE_HOME: New variables for the config
files.
- $_SQ, $_SP: Move variables for characters before the handling of
the configuration files.  Rename $_SQUOTE to $_SQ and $_SPACE to
$_SP.
- $GROFFER_OPT: Remove cleaning of this variable before the
reading of the configuration files.

* groffer2.sh:
- main_init(): Remove the getting of the configuration files.

### Rewrite the shell determination

* groffer.sh:
- Get rid of all functions in `groffer.sh'.  Rewrite the shell
determination with `` and $().
- --shell: Shortest abbreviation is `--sh'.  Allow arguments for
the shell name.
- Allow an empty argument for --shell as shell name to overwrite a
specified shell; an empty shell name gets back to the default
shell.
- The shell determination now inludes the full handling of the
config files.  The `--shell' option needs no longer a line
starting with `-'.

### Test of unset

* groffer.sh:
- Remove test of `unset'.
- Remove all calls of `unset'.
- Use one character names for all variables that are meant to be
local in this script.

* groffer2.sh:
- Move the test of `unset' to the testing of rudimentary shell
functionality without change.

        ### Allow abbreviations for long options

* groffer2.sh:
- list_has_abbrev(): New function for checking a list having an
element with a given abbreviation.
- list_get_single_from_abbrev(): New function to retrieve the
element having a given abbreviation.
- list_from_cmd_line(): For an option abbreviation determine the
corresponding long option.
- From the man option lists remove the elements that are also in
a groffer list.
- Allow abbreviation for the early test of --debug.

* groffer.sh: Allow abbreviation for the early test on --shell.
- get_opt_shell(): Rewrite _get_opt_shell() and the shell test
around it.
- test_on_shell(): Rename function _test_on_shell().
- $_SHELL: global variable for the shell to run groffer2.sh.

### Get rid of `sh -c'

* groffer2.sh:
- main_display(), _do_display(): Remove the `sh -c' calls.  Make
the cleanup working without it.
- _do_display(): Extend _do_display() such thatit can be used for
the pdf mode as well.
- _make_pdf(): New subfunction of main_display() for running the
additional parts of pdf mode in _do_display().
- rm_file(), rm_file_with_debug(), rm_tree(): New functions for
removing files and directories.

### Change directory

* groffer2.sh:
- $_START_DIR: New variable to store the directory at the starting
time of the script.
- main_display(): Go to the groffer temporary directory to be able
to process internal `groff' data like pictures.
- clean_up(): Get back to the starting directory.

### Compatibility with strange shells

* groffer2.sh:
- clean_up(): `zsh' and `posh' had difficulties with `eval'.
- is_*(): Add test on empty argument.  Some shells return true on
`test -d' etc. with empty argument, while most shells return
false.
- echo1(); New function to print single line `cat <<EOF'.  Replace
all `echo x' by `echo1'.
- list_has_abbrev(), list_from_cmdline(): Correction.
- main_parse_MANOPT(): Repair and revise.
- --do-nothing: New option without output (for development).
- Rewrite rudimentary shell functionality near the beginning of
the script.

* groffer.sh, groffer2.sh:
- Remove `;' after the commands `if', `while', and `until'.

### Debugging information

* groffer2.sh:
- $_DEBUG_PRINT_PARAMS: New variable for printing all parameters
from the config files, $GROFFER_OPT, and command line after they
have been transformed.
- $_DEBUG_PRINT_SHELL: New variable for printing the name of the
shell found in groff.sh.
- main(): Move the landmarks of main-*() into main().

### Further checks and additions

* groffer.sh, groffer2.sh:
- $_PROGRAM_NAME: Replace this variable by `groffer'.  The program
name is now stable.
- $_GROFFER_RUN: Remove this variable.  As `groffer.sh' or
`groffer' is no longer rerun, this variable is not necessary any
more.

* groffer2.sh:
- main_set_resources(): Make the default viewers capable to use
arguments in the list.
- leave(): Add an argument for given exit code.  Use it where
suitable in main_*().
- do_filearg(): Add error messages for non-existing files and man
pages.
- _do_opt_V(): New subfunction of main_display() to handle the
output for option `-V'.  `groff -V' is greatly enlarged by
`groffer' specific information.
- register_title(): Handle file names with spaces.  Replace spaces
by `_'.
- is_existing(): Add `test -c' for special files.
- usage(): Add `=arg' to the options with an argument.  Add option
`--tty-viewer'.
- kghostview: In the default viewer list, add option
`--scale=1.45'.
- $_OPTS_CMDLINE_SHORT_NA: Correct a lacking space.

* Makefile.sub: Repair the installation instructions for
groffer2.sh.

* groffer.man:
- Add paragraph on option handling.
- Add option `--do-nothing'.
- Reorder option for development and `groff'.
- Rewrite documentation for option `-V'.
- Expand `--shell'.
- Reformulate sections CONFIGURATION FILES, COMPATIBILITY and SEE
ALSO.
- Make `man' italic where possible.
- .copyleft: Adjust the fonts.

* README: Update sections `Output' and `Compatibility'.

* README_SH:
- Add `mksh' as compatible shell.
- Add information on the scripts after the split.

* TODO: Remove some fulfilled parts.

* ChangeLog: Remove final spaces.
@
text
@d77 1
a77 1
Last update: 2 August 2005
@


1.6
log
@

* release of groffer 0.9.18

* groffer.sh: further shell compatibility
- `echo': Remove options and possible options of `echo' by
preceding the argument with a character `x' that is removed by
`sed' or replace `echo' by `cat <<EOF'.  `echo -n' seems to be not
portable, so it is omitted.
- `for': Remove `;' from within `for' (because of ksh).
- `ls': 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.
- `true': Replace `true' by command `:'.  Remove test of `true'
(because `ash' refuses the redefinition of builtins even in an
unreachable `if' branch).
- `false': Remove test of `false'; it isn't used any more.
- `test': As `test -e' does not exist in Solaris 2.5 replace it by
`test -f || test -d'.
- `unset': `unset' is said to be not portable.  As `ash' protests
against the definition of the function `unset()' in the test of
`unset' replace the test by defining `$unset' to `unset' if it
exists and to `:' otherwise.  Use `eval $unset' instead of the
direct command `unset'.
- _get_opt_shell(): Replace `for' loop with `shift' by `while'.
- man_search_section(): Replace `for f in filename*' by a test on
the existence of `filename*'.
- `zsh' interprets `$...' as `"$..."'.  So `eval' must be called;
This cannot be used in `for i in $f', so it must be rewritten as
`for i in $(eval set x $f; shift; echo "$@@")'

* groffer.sh:
- `--X', `--x', `--mode=X', `--mode=x': Make these options
equivalent to chosing an X device by setting `-TX75-12'.  `-X' is
still equivalent to `groff -X'.
- main_init(): Choose the name of the temporary file by adding a
number using `expr' if it exists and cannot be removed.
- main_parse_args():Repair some options by replacing `$mpa_mode'
by `$_OPT_MODE'.
- catz(): Rename it to cat_z() to avoid problem with existing
programs.
- where(): Rename to where_is().
- $_CONFFILES: Rename to $_CONF_FILES.
- $_HAS_BZIP: export and preset it.

* groffer.man:
- Document the `X mode' changes.
- Add `@@g@@' to `troff'.

* README, README_SH, TODO:
- Add date line `Latest update:'.
- Add `...' quoting to essential terms.
- Add Emacs mode at the end.

* README_SH:
- Add documentation on the above compatibility changes.
- Add documentation on used commands.
- Mention the tested shells.

* Makefile.sub:
Readd `@@g@@'.
@
text
@d37 1
a37 1
-- a Prostcript viewer,
d46 4
d57 3
a59 2
`groffer' is a shell script.  It should run on any POSIX or Bourne
style shell that supports shell functions.  See file `README_SH'.
d65 8
a72 5
<bug-groff@@gnu.org> can be used.  For a general discussion, the
mailing list <groff@@gnu.org> is more useful, but one has to subscribe
to this list at http://lists.gnu.org/mailman/listinfo/groff.  See the
`README' file in the top directory of the `groff' source package for
more details on these mailing lists.
d77 1
a77 1
Last update: 30 June 2005
d82 1
a82 1
This file is part of groffer, which is part of groff.
d84 1
a84 1
groff is free software; you can redistribute it and/or modify it
d89 4
a92 4
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.
d95 2
a96 2
along with groff; see the files COPYING and LICENSE in the top
directory of the groff source.  If not, write to the Free Software
@


1.5
log
@

* All affected files: Update postal address of FSF.
@
text
@d29 1
a29 1
All input is first sent to `grog' to determine the necessary groff
d36 1
a36 1
-- the X roff viewer `gxditview',
d42 2
a43 2
- Generate groff output on stdout without a viewer.
- Generate the troff intermediate output on standard output without
d45 1
a45 1
- Output the source code without any groff processing.
d54 1
a54 1
style shell that supports shell functions with local variables.
d61 4
a64 3
mailing list <groff@@gnu.org> is more useful; see the `README' file in
the top directory of the `groff' source package for more details on
these mailing lists.
d69 2
d90 7
@


1.4
log
@

* release of groffer 0.9.13

* groffer.sh:
- first line: Add space to `#! /bin/sh'.
- $_VIEWER_DVI: Add `kdvi'.
- $_VIEWER_PDF: Add `kghostview', `ggv', and `kpdf'.
- $_VIEWER_PS: Add `kghostview' and `ggv'.
- $_modefile: For the output file name, add extension .ps for ps
mode and .dvi for dvi mode.  This exists already for the html and
pdf modes.
- Update some parts of the documentation.

* README, README_SH:
- Move some parts on usage from README_SH to README.
- Reformulate several parts of both files.

* groffer.man: update
@
text
@d86 1
a86 1
Foundation, 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
@


1.3
log
@

* release of groffer 0.9.10

* groffer.sh:
- Remove automatic call of `ash' due to inconsistencies of
different ash versions.
- In the first run, add recognition of `--shell' lines in the
groffer configuration files.  To configure an external shell in
a configuration file, a line starting with `--shell' is
necessary.
- list_from_cmdline(): Simplify the arguments.
- As $POSIXLY_CORRECT is internally set to `y' by some GNU
`/bin/sh' shells the following 2 fixes are necessary:
-- `sed': Empty patterns are not allowed with $POSIXLY_CORRECT
set; so move the address information before the `s' command to the
pattern after the command, and write `.*' to the address field.
-- list_from_cmdline(): Remove the strange $POSIXLY_CORRECT style
to finish the option processing after the first non-option
argument; use the flexible GNU mixing of options and file names
instead.

* groffer.man:
- Remove any hints on `ash'.
- Add minus line behavior of `--shell' for configuration and add a
corresponding example.
- Update the information on $POSIXLY_CORRECT.
@
text
@d1 2
a6 8
All input is sent to `grog' and then to `groff' such that no special
`groff' arguments must be determined, but all `groff' options can be
specified.

`groffer' also has many built-in `man' functionalities to find and
read the manual pages on UNIX and similar operating systems.  It
accepts the information from an installed `man' program, but tries to
find a man path by itself.
d8 50
a57 2
So far, `groffer' is a shell script.  It should run on any POSIX or
Bourne style shell.
d68 1
a68 1
Copyright (C) 2003,2004 Free Software Foundation, Inc.
@


1.2
log
@

Update to groffer 0.9.7.
@
text
@d2 6
a7 3
some `groff' language, such as the `man pages', the manual pages in
many operating systems.  All input is sent to `grog' and then to
`groff' such that no special `groff' arguments must be determined.
d12 1
a12 1
find a man path by itself if there isn't any.
d15 1
a15 4
Bourne style shell, but it runs the fastest under the GNU `ash' shell.
If this shell is available, it is started automatically.  There are
efforts to port part of the shell script to C/C++ to increase the
speed independent of the shell.
d19 3
a21 3
<groff@@gnu.org> is more useful; see the `README' file in the top
directory of the `groff' source package for more details on this
mailing list.
@


1.1
log
@
* fixes of groffer 0.9.2

* groffer.sh:
Terminate main_parse_MANOPT() if $MANOPT is empty or consists
of space characters only.

* groffer.man: some fixes in "GROFFER OPTIONS"
- New macro ".Header_CB" for CB font in .TP headers; used for
definition of variables in option --mode.
- Fix some option references to refer to long options.

* README:
New file for general information on the groffer source; it is
not installed.
@
text
@d1 4
a4 3
The `groffer' program is the easiest way to read `groff' documents.
All input is sent to `grog' and then to `groff' such that no special
`groff' arguments must be determined.
d12 4
a15 4
Bourne style shell, but it runs the fastest if the `ash' shell is
installed on the system.  This shell is found out and started
automatically.  There are efforts to port part of the shell script to
C/C++ to increase the speed independent of the shell.
d23 22
a44 2
`groffer' is a `groff contrib' project that was written by Bernd
Warken <bwarken@@mayn.de>.
@

