head	1.3;
access;
symbols
	groff-1_20_1_real:1.3
	groff-1_20_1:1.3
	groff-1_20:1.3;
locks; strict;
comment	@# @;


1.3
date	2009.01.05.20.10.39;	author wl;	state Exp;
branches;
next	1.2;
commitid	LOYcfESGVCXMFixt;

1.2
date	2009.01.04.14.50.56;	author wl;	state Exp;
branches;
next	1.1;
commitid	RfDBP1nYqohhW8xt;

1.1
date	2006.10.14.05.59.54;	author wl;	state Exp;
branches;
next	;


desc
@@


1.3
log
@Update copyright year.
@
text
@README_PERL

Special description for the Perl version of `groffer'

The files related to the Perl version are

perl/groffer.pl	  perl main source file for groffer
perl/func.pl	  selection of functions needed for groffer.pl
perl/man.pl	  selection of man functions needed for groffer.pl
perl/split_env.sh shell script called from groffer.pl to split a variable
perl/groffer.man  manual file rewritten for the perl version of groffer
perl/README_PERL  this file
perl_test.pl	  test whether perl has a suitable version
version.sh	  information on version number and last update


Compatibility

This is the Perl version of groffer.  It was written under Perl v5.8.8
and needs an installed Perl version of at least version 5.6.1.

It was written in Linux, but it seems to be independent of the
operating system.  At least no directory slashes are used.

For testing, `groffer.pl' may be used directly without a Makefile.  By
`make' this file will be transformed into the file `groffer' that will
be installed.

The following options were removed compared to the shell version of
groffer:

--shell --debug-func --debug-not_func --debug-lm --debug-shell
--debug-stacks --debug-user

They can be used, but they are just ignored.

Otherwise, the Perl version has the same functionality as the shell
version.


Temporary files

The Perl version keeps more files for debug mode than the shell
version.  The `file' and `so' temporaries are numbered and the files
with .so request are copied.  All .so requests are handled; this is an
extension to `man' that deals only with the first .so request.


Comparison of variable names in both groffer versions

shell				perl
=======================================================================
$GROFFER_OPT			$Env{GROFFER}
$PATH				@@Path
$_ADDOPTS_GROFF			@@Addopts_Groff
$_ALL_PARAMS			@@ARGV
$_APROPOS_PROG			$Apropos_Prog
$_APROPOS_SECTIONS		$Opt{APROPOS_SECTIONS}
$_AT				$at
$_AT_BINDIR_AT			$at_at{BINDIR}
$_AT_G_AT			$at_at{G}
$_AT_LIBDIR_AT			$at_at{LIBDIR}
$_BAD				-
$_BEFORE_MAKE			$before_make
$_CONF_FILES			@@Conf_Files
$_CONF_FILE_ETC			@@Conf_Files
$_CONF_FILE_HOME		@@Conf_Files
$_DEBUG_FUNC_CHECK		-
$_DEBUG_KEEP_FILES		@@Debug{KEEP}
$_DEBUG_LM			-
$_DEBUG_PRINT_FILENAMES		@@Debug{FILENAMES}
$_DEBUG_PRINT_PARAMS		@@Debug{PARAMS}
$_DEBUG_PRINT_SHELL		-
$_DEBUG_PRINT_TMPDIR		@@Debug{TMPDIR}
$_DEBUG_STACKS			-
$_DEBUG_USER_WITH_STACK		-
$_DEFAULT_MODES			$Default_Modes
$_DEFAULT_RESOLUTION		$Default_Resolution
$_DEFAULT_TTY_DEVICE		$Default_tty_Device
$_DISPLAY_ARGS			$Display{ARGS}
$_DISPLAY_MODE			$Display{MODE}
$_DISPLAY_PROG			$Display{PROG}
$_ERROR				-
$_FILEARGS			@@Filespecs
$_FILESPEC_ARG			$Filespec_Arg
$_FILESPEC_IS_MAN		$Filespec_Is_Man
$_FUNC_STACK			-
$_GOOD				-
$_GROFFER2_SH			-
$_GROFFER_LIBDIR		$groffer_libdir
$_GROFFER_SH			_
$_GROFF_VERSION			$Groff_Version
$_GROFF_VERSION_PRESET		$groff_version_preset
$_HAS_BZIP			$Has_bzip
$_HAS_COMPRESSION		$Has_Compression
$_LAST_UPDATE			$last_update
$_MACRO_PACKAGES		$Macro_Packages
$_MACRO_PKG			$Macro_Pkg
$_MANOPT_ALL			-
$_MANOPT_EXTENSION		-
$_MANOPT_LANG			-
$_MANOPT_PAGER			-
$_MANOPT_PATH			-
$_MANOPT_SEC			-
$_MANOPT_SYS			-
$_MAN_ALL			$Man{ALL}
$_MAN_AUTO_SEC_CHARS		$Man{AUTO_SEC_CHARS}
$_MAN_AUTO_SEC_LIST		@@{$Man{AUTO_SEC}}
$_MAN_ENABLE			$Man{ENABLE}
$_MAN_EXT			$Man{EXT}
$_MAN_FORCE			$Man{FORCE}
$_MAN_IS_SETUP			$Man{IS_SETUP}
$_MAN_LANG			$Man{LANG}
$_MAN_LANG2			$Man{LANG2}
$_MAN_PATH			@@{$Man{PATH}}
$_MAN_SEC			@@{$Man{SEC}}
$_MAN_SEC_CHARS			$Man{SEC_CHARS}
$_MAN_SEC_LIST			-
$_MAN_SYS			@@{$Man{SYS}}
$_NO				-
$_NO_FILESPECS			$No_Filespecs
$_NULL_DEV			$Dev_Null
$_OK				-
$_OPTS_CMDLINE_LONG_ARG		%Opts_Cmdline_Long with value 1
$_OPTS_CMDLINE_LONG_NA		%Opts_Cmdline_Long with value 0
$_OPTS_CMDLINE_SHORT_ARG	%Opts_Cmdline_Short with value 1
$_OPTS_CMDLINE_SHORT_NA		%Opts_Cmdline_Short with value 0
$_OPTS_GROFFER_LONG_ARG		-
$_OPTS_GROFFER_LONG_NA		-
$_OPTS_GROFFER_SHORT_ARG	-
$_OPTS_GROFFER_SHORT_NA		-
$_OPTS_GROFF_LONG_ARG		-
$_OPTS_GROFF_LONG_NA		-
$_OPTS_GROFF_SHORT_ARG		-
$_OPTS_GROFF_SHORT_NA		-
$_OPTS_MANOPT_LONG_ARG		-
$_OPTS_MANOPT_LONG_NA		-
$_OPTS_MANOPT_SHORT_ARG		-
$_OPTS_MANOPT_SHORT_NA		-
$_OPTS_MAN_LONG_ARG		-
$_OPTS_MAN_LONG_NA		-
$_OPTS_MAN_SHORT_ARG		-
$_OPTS_MAN_SHORT_NA		-
$_OPTS_X_LONG_ARG		-
$_OPTS_X_LONG_NA		-
$_OPTS_X_SHORT_ARG		-
$_OPTS_X_SHORT_NA		-
$_OPT_ALL			$Opt{ALL}
$_OPT_APROPOS			$Opt{APROPOS}
$_OPT_BD			$Opt{BD}
$_OPT_BG			$Opt{BG}
$_OPT_BW			$Opt{BW}
$_OPT_DEFAULT_MODES		$Opt{DEFAULT_MODES}
$_OPT_DEVICE			$Opt{DEVICE}
$_OPT_DISPLAY			$Opt{DISPLAY}
$_OPT_DO_NOTHING		$Opt{DO_NOTHING}
$_OPT_EXTENSION			$Opt{EXTENSION}
$_OPT_FG			$Opt{FG}
$_OPT_FN			$Opt{FN}
$_OPT_GEOMETRY			$Opt{GEOMETRY}
$_OPT_ICONIC			$Opt{ICONIC}
$_OPT_LANG			$Opt{LANG}
$_OPT_MANPATH			$Opt{MANPATH}
$_OPT_MODE			$Opt{MODE}
$_OPT_PAGER			$Opt{PAGER}
$_OPT_RESOLUTION		$Opt{RESOLUTION}
$_OPT_RV			$Opt{RV}
$_OPT_SECTIONS			$Opt{SECTIONS}
$_OPT_SYSTEMS			$Opt{SYSTEMS}
$_OPT_TEXT_DEVICE		$Opt{TEXT_DEVICE}
$_OPT_TITLE			$Opt{TITLE}
$_OPT_V				$Opt{V}
$_OPT_VIEWER_DVI		$Opt{VIEWER_DVI}
$_OPT_VIEWER_HTML		$Opt{VIEWER_HTML}
$_OPT_VIEWER_PDF		$Opt{VIEWER_PDF}
$_OPT_VIEWER_PS			$Opt{VIEWER_PS}
$_OPT_VIEWER_X			$Opt{VIEWER_X}
$_OPT_WHATIS			$Opt{WHATIS}
$_OPT_XRM			@@{$Opt{XRM}}
$_OPT_Z				$Opt{Z}
$_OUTPUT_FILE_NAME		$Output_File_Name
$_PDF_DID_NOT_WORK		$PDF_Did_Not_Work
$_PDF_HAS_GS			$PDF_Has_gs
$_PDF_HAS_PS2PDF		$PDF_Has_ps2pdf
$_PROCESS_ID			-
$_PROGRAM_VERSION		$program_version
$_REG_TITLE_LIST		@@Reg_Title
$_SHELL				-
$_SP				-
$_SPACE_CASE			-
$_SPACE_SED			-
$_SPECIAL_FILESPEC		$Special_Filespec
$_SPECIAL_SETUP			$Special_Setup
$_SQ				-
$_START_DIR			$Start_Dir
$_TAB				-
$_TMP_CAT			$fh_cat, $tmp_cat
$_TMP_DIR			$tmpdir
$_TMP_MAN			-
$_TMP_MANSPEC			$Manspec for @@{Man{MANSPEC}{$Manspec}}
$_TMP_STDIN			$fh_stdin, $tmp_stdin
$_UNSET				-
$_VIEWER_BACKGROUND		$Viewer_Background
$_VIEWER_DVI_TTY		$Viewer_tty{'DVI'}
$_VIEWER_DVI_X			$Viewer_X{'DVI'}
$_VIEWER_HTML_TTY		$Viewer_tty{'HTML'}
$_VIEWER_HTML_X			$Viewer_X{'HTML'}
$_VIEWER_PDF_TTY		$Viewer_tty{'PDF'}
$_VIEWER_PDF_X			$Viewer_X{'PDF'}
$_VIEWER_PS_TTY			$Viewer_tty{'PS'}
$_VIEWER_PS_X			$Viewer_X{'PS'}
$_VIEWER_TTY_TTY		-
$_VIEWER_TTY_X			-
$_VIEWER_X_TTY			$Viewer_tty{'X'}
$_VIEWER_X_X			$Viewer_X{'X'}
$_YES				-
$return_bad			-
$return_error			-
$return_good			-
$return_no			-
$return_ok			-
$return_var			-
$return_yes			-
-				@@ARGV
-				@@Manopt
-				$Opt{LOCATION}
-				$Opt{X}
-				$File_Split_Env
-				@@Options
-				@@StartingARGV
-				@@StartingConf
-				$Umask


####### License

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/>.

Last update: 5 Jan 2009


####### Emacs settings

Local Variables:
mode: text
End:
@


1.2
log
@

* */*: Update GPL2 to GPL3.
@
text
@d237 2
a238 1
Copyright (C) 2003,2004,2005,2006 Free Software Foundation, Inc.
d256 1
a256 1
Last update: 12 Oct 2006
@


1.1
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
@d244 2
a245 2
the Free Software Foundation; either version 2, or (at your option)
any later version.
d253 1
a253 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.
@

