From MAILER-DAEMON Mon Aug 05 08:14:35 2013
Received: from list by lists.gnu.org with archive (Exim 4.71)
	id 1V6JgI-0007Lc-Vt
	for mharc-groff-commit@gnu.org; Mon, 05 Aug 2013 08:14:35 -0400
Received: from eggs.gnu.org ([2001:4830:134:3::10]:37639)
	by lists.gnu.org with esmtp (Exim 4.71)
	(envelope-from <groff-bernd.warken-72@web.de>) id 1V6IPB-0003OK-TP
	for groff-commit@gnu.org; Mon, 05 Aug 2013 06:54:27 -0400
Received: from vcs.savannah.gnu.org ([140.186.70.72]:50135)
	by eggs.gnu.org with esmtp (Exim 4.71)
	(envelope-from <groff-bernd.warken-72@web.de>) id 1V6IPA-0007VE-Le
	for groff-commit@gnu.org; Mon, 05 Aug 2013 06:52:49 -0400
Received: from bwarken by vcs.savannah.gnu.org with local (Exim 4.72)
	(envelope-from <groff-bernd.warken-72@web.de>) id 1V6IP6-0001gV-Tp
	for groff-commit@gnu.org; Mon, 05 Aug 2013 10:52:45 +0000
Date: Mon, 05 Aug 2013 10:52:44 +0000
Message-Id: <E1V6IP6-0001gV-Tp@vcs.savannah.gnu.org>
To: groff-commit@gnu.org
From: Bernd Warken <groff-bernd.warken-72@web.de>
X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6.x
X-Mailman-Approved-At: Mon, 05 Aug 2013 08:14:32 -0400
Subject: [Groff-commit] groff/contrib RUNOFF/ChangeLog RUNOFF/Makefile....
X-BeenThere: groff-commit@gnu.org
X-Mailman-Version: 2.1.14
Precedence: list
List-Id: <groff-commit.gnu.org>
List-Unsubscribe: <https://lists.gnu.org/mailman/options/groff-commit>,
	<mailto:groff-commit-request@gnu.org?subject=unsubscribe>
List-Archive: <http://lists.gnu.org/archive/html/groff-commit>
List-Post: <mailto:groff-commit@gnu.org>
List-Help: <mailto:groff-commit-request@gnu.org?subject=help>
List-Subscribe: <https://lists.gnu.org/mailman/listinfo/groff-commit>,
	<mailto:groff-commit-request@gnu.org?subject=subscribe>
X-List-Received-Date: Mon, 05 Aug 2013 10:54:27 -0000

CVSROOT:	/cvsroot/groff
Module name:	groff
Changes by:	Bernd Warken <bwarken>	13/08/05 10:52:44

Removed files:
	contrib/RUNOFF : ChangeLog Makefile.sub groff_filenames.man 
	                 runoff.man 
	contrib/chem   : ChangeLog Makefile.sub README.txt chem.man 
	                 chem.pic chem.pl 
	contrib/chem/examples: README.txt atp.chem cholesterin.chem 
	                       ethamivan.chem lsd.chem morphine.chem 
	                       penicillin.chem reserpine.chem 
	contrib/chem/examples/122: README.txt ch2a_ethyl.chem 
	                           ch2b_benzene.chem 
	                           ch2c_benzene_right.chem 
	                           ch4a_stick.chem 
	                           ch4b_methyl_acetate.chem 
	                           ch4c_colon.chem ch4d_HCl.H2O.chem 
	                           ch4e_CaSO4.2H2O.chem ch4f_C.chem 
	                           ch4g_BP.chem ch4h_methacrylate.chem 
	                           ch4i_cyclo.chem ch4j_ring4.chem 
	                           ch4k_ring3.chem ch4l_vertex.chem 
	                           ch4m_double.chem ch4n_triple.chem 
	                           ch4o_aromatic.chem 
	                           ch4p_cholestanol.chem ch4q_rings.chem 
	                           ch4r_spiro.chem ch4s_heteroatoms.chem 
	                           ch4t_polycyclic.chem 
	                           ch4u_nicotine.chem 
	                           ch4v_histidine.chem ch4w_lsd.chem 
	                           ch4x_anisole.chem ch4y_reserpine.chem 
	                           ch4z1_eqn_glutamic.chem 
	                           ch4z2_text.chem ch5a_size.chem 
	                           ch6a_pic.chem ch6b_dna.chem 
	                           chAa_polymer.chem 
	                           chAb_vinyl_chloro.chem 
	                           chAc_morphine.chem 
	                           chAd_chlorophyll.chem chAe_chair.chem 
	                           chAf_arrow.chem chAg_circle.chem 
	                           chAh_brackets.chem 
	                           chAi_poly_vinyl_chloride.chem 
	                           chBa_jump.chem chBb_bonds.chem 
	                           chBc_rings.chem 
	contrib/glilypond: ChangeLog ChangeLog.0x Makefile.sub 
	                   README.txt args.pl glilypond.man glilypond.pl 
	                   oop_fh.pl subs.pl 
	contrib/groffer: ChangeLog Makefile.sub README roff2.man 
	                 version.sh 
	contrib/groffer/perl: README_PERL func.pl groffer.man groffer.pl 
	                      man.pl perl_test.pl roff2.pl split_env.sh 
	contrib/groffer/shell: ChangeLog.0 README_SH groffer.man 
	                       groffer.sh groffer2.sh roff2.sh 

Log message:
	Die Gedanken sind frei ... (thoughts are free - song of the original German freemasons). Free your mind.

CVSWeb URLs:
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/RUNOFF/ChangeLog?cvsroot=groff&r1=1.5&r2=0
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/RUNOFF/Makefile.sub?cvsroot=groff&r1=1.1&r2=0
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/RUNOFF/groff_filenames.man?cvsroot=groff&r1=1.3&r2=0
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/RUNOFF/runoff.man?cvsroot=groff&r1=1.3&r2=0
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/chem/ChangeLog?cvsroot=groff&r1=1.18&r2=0
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/chem/Makefile.sub?cvsroot=groff&r1=1.16&r2=0
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/chem/README.txt?cvsroot=groff&r1=1.5&r2=0
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/chem/chem.man?cvsroot=groff&r1=1.13&r2=0
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/chem/chem.pic?cvsroot=groff&r1=1.5&r2=0
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/chem/chem.pl?cvsroot=groff&r1=1.11&r2=0
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/chem/examples/README.txt?cvsroot=groff&r1=1.6&r2=0
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/chem/examples/atp.chem?cvsroot=groff&r1=1.4&r2=0
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/chem/examples/cholesterin.chem?cvsroot=groff&r1=1.4&r2=0
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/chem/examples/ethamivan.chem?cvsroot=groff&r1=1.4&r2=0
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/chem/examples/lsd.chem?cvsroot=groff&r1=1.4&r2=0
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/chem/examples/morphine.chem?cvsroot=groff&r1=1.4&r2=0
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/chem/examples/penicillin.chem?cvsroot=groff&r1=1.4&r2=0
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/chem/examples/reserpine.chem?cvsroot=groff&r1=1.5&r2=0
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/chem/examples/122/README.txt?cvsroot=groff&r1=1.2&r2=0
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/chem/examples/122/ch2a_ethyl.chem?cvsroot=groff&r1=1.4&r2=0
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/chem/examples/122/ch2b_benzene.chem?cvsroot=groff&r1=1.4&r2=0
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/chem/examples/122/ch2c_benzene_right.chem?cvsroot=groff&r1=1.4&r2=0
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/chem/examples/122/ch4a_stick.chem?cvsroot=groff&r1=1.4&r2=0
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/chem/examples/122/ch4b_methyl_acetate.chem?cvsroot=groff&r1=1.4&r2=0
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/chem/examples/122/ch4c_colon.chem?cvsroot=groff&r1=1.4&r2=0
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/chem/examples/122/ch4d_HCl.H2O.chem?cvsroot=groff&r1=1.4&r2=0
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/chem/examples/122/ch4e_CaSO4.2H2O.chem?cvsroot=groff&r1=1.4&r2=0
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/chem/examples/122/ch4f_C.chem?cvsroot=groff&r1=1.4&r2=0
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/chem/examples/122/ch4g_BP.chem?cvsroot=groff&r1=1.4&r2=0
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/chem/examples/122/ch4h_methacrylate.chem?cvsroot=groff&r1=1.4&r2=0
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/chem/examples/122/ch4i_cyclo.chem?cvsroot=groff&r1=1.4&r2=0
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/chem/examples/122/ch4j_ring4.chem?cvsroot=groff&r1=1.4&r2=0
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/chem/examples/122/ch4k_ring3.chem?cvsroot=groff&r1=1.4&r2=0
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/chem/examples/122/ch4l_vertex.chem?cvsroot=groff&r1=1.4&r2=0
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/chem/examples/122/ch4m_double.chem?cvsroot=groff&r1=1.4&r2=0
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/chem/examples/122/ch4n_triple.chem?cvsroot=groff&r1=1.4&r2=0
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/chem/examples/122/ch4o_aromatic.chem?cvsroot=groff&r1=1.4&r2=0
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/chem/examples/122/ch4p_cholestanol.chem?cvsroot=groff&r1=1.4&r2=0
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/chem/examples/122/ch4q_rings.chem?cvsroot=groff&r1=1.4&r2=0
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/chem/examples/122/ch4r_spiro.chem?cvsroot=groff&r1=1.4&r2=0
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/chem/examples/122/ch4s_heteroatoms.chem?cvsroot=groff&r1=1.4&r2=0
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/chem/examples/122/ch4t_polycyclic.chem?cvsroot=groff&r1=1.4&r2=0
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/chem/examples/122/ch4u_nicotine.chem?cvsroot=groff&r1=1.4&r2=0
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/chem/examples/122/ch4v_histidine.chem?cvsroot=groff&r1=1.4&r2=0
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/chem/examples/122/ch4w_lsd.chem?cvsroot=groff&r1=1.4&r2=0
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/chem/examples/122/ch4x_anisole.chem?cvsroot=groff&r1=1.4&r2=0
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/chem/examples/122/ch4y_reserpine.chem?cvsroot=groff&r1=1.5&r2=0
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/chem/examples/122/ch4z1_eqn_glutamic.chem?cvsroot=groff&r1=1.4&r2=0
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/chem/examples/122/ch4z2_text.chem?cvsroot=groff&r1=1.4&r2=0
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/chem/examples/122/ch5a_size.chem?cvsroot=groff&r1=1.4&r2=0
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/chem/examples/122/ch6a_pic.chem?cvsroot=groff&r1=1.5&r2=0
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/chem/examples/122/ch6b_dna.chem?cvsroot=groff&r1=1.5&r2=0
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/chem/examples/122/chAa_polymer.chem?cvsroot=groff&r1=1.4&r2=0
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/chem/examples/122/chAb_vinyl_chloro.chem?cvsroot=groff&r1=1.4&r2=0
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/chem/examples/122/chAc_morphine.chem?cvsroot=groff&r1=1.4&r2=0
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/chem/examples/122/chAd_chlorophyll.chem?cvsroot=groff&r1=1.4&r2=0
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/chem/examples/122/chAe_chair.chem?cvsroot=groff&r1=1.4&r2=0
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/chem/examples/122/chAf_arrow.chem?cvsroot=groff&r1=1.4&r2=0
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/chem/examples/122/chAg_circle.chem?cvsroot=groff&r1=1.5&r2=0
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/chem/examples/122/chAh_brackets.chem?cvsroot=groff&r1=1.4&r2=0
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/chem/examples/122/chAi_poly_vinyl_chloride.chem?cvsroot=groff&r1=1.5&r2=0
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/chem/examples/122/chBa_jump.chem?cvsroot=groff&r1=1.4&r2=0
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/chem/examples/122/chBb_bonds.chem?cvsroot=groff&r1=1.4&r2=0
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/chem/examples/122/chBc_rings.chem?cvsroot=groff&r1=1.4&r2=0
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/glilypond/ChangeLog?cvsroot=groff&r1=1.12&r2=0
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/glilypond/ChangeLog.0x?cvsroot=groff&r1=1.3&r2=0
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/glilypond/Makefile.sub?cvsroot=groff&r1=1.6&r2=0
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/glilypond/README.txt?cvsroot=groff&r1=1.2&r2=0
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/glilypond/args.pl?cvsroot=groff&r1=1.4&r2=0
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/glilypond/glilypond.man?cvsroot=groff&r1=1.2&r2=0
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/glilypond/glilypond.pl?cvsroot=groff&r1=1.7&r2=0
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/glilypond/oop_fh.pl?cvsroot=groff&r1=1.4&r2=0
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/glilypond/subs.pl?cvsroot=groff&r1=1.6&r2=0
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/groffer/ChangeLog?cvsroot=groff&r1=1.65&r2=0
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/groffer/Makefile.sub?cvsroot=groff&r1=1.33&r2=0
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/groffer/README?cvsroot=groff&r1=1.15&r2=0
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/groffer/roff2.man?cvsroot=groff&r1=1.6&r2=0
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/groffer/version.sh?cvsroot=groff&r1=1.21&r2=0
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/groffer/perl/README_PERL?cvsroot=groff&r1=1.4&r2=0
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/groffer/perl/func.pl?cvsroot=groff&r1=1.8&r2=0
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/groffer/perl/groffer.man?cvsroot=groff&r1=1.19&r2=0
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/groffer/perl/groffer.pl?cvsroot=groff&r1=1.15&r2=0
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/groffer/perl/man.pl?cvsroot=groff&r1=1.7&r2=0
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/groffer/perl/perl_test.pl?cvsroot=groff&r1=1.4&r2=0
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/groffer/perl/roff2.pl?cvsroot=groff&r1=1.6&r2=0
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/groffer/perl/split_env.sh?cvsroot=groff&r1=1.4&r2=0
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/groffer/shell/ChangeLog.0?cvsroot=groff&r1=1.3&r2=0
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/groffer/shell/README_SH?cvsroot=groff&r1=1.7&r2=0
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/groffer/shell/groffer.man?cvsroot=groff&r1=1.18&r2=0
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/groffer/shell/groffer.sh?cvsroot=groff&r1=1.5&r2=0
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/groffer/shell/groffer2.sh?cvsroot=groff&r1=1.7&r2=0
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/groffer/shell/roff2.sh?cvsroot=groff&r1=1.5&r2=0

Patches:
Index: RUNOFF/ChangeLog
===================================================================
RCS file: RUNOFF/ChangeLog
diff -N RUNOFF/ChangeLog
--- RUNOFF/ChangeLog	31 Jul 2013 05:42:07 -0000	1.5
+++ /dev/null	1 Jan 1970 00:00:00 -0000
@@ -1,48 +0,0 @@
-2013-07-31  Bernd Warken  <groff-bernd.warken-72@web.de>
-
-	Fix RUNOFF
-
-2013-06-17  Bernd Warken  <groff-bernd.warken-72@web.de>
-
-	Remove files *~
-
-2013-06-17  Bernd Warken  <groff-bernd.warken-72@web.de>
-
-	* groff_filenames.man: Corrections.
-
-2013-06-17  Bernd Warken  <groff-bernd.warken-72@web.de>
-
-	* groff_filenames.man: Extension.
-
-2013-05-14  Bernd Warken  <groff-bernd.warken-72@web.de>
-
-	* runoff.man: Major rewrite, due to good documentation of 1974,
-	especially for text lines.
-
-2013-05-05  Bernd Warken  <groff-bernd.warken-72@web.de>
-
-	New `groff' project: `RUNOFF', which is the predecessor of `roff'.
-
-	* ChangeLog: New file for the `contrib' source.
-
-	* Makefile.sub: New `make' file, so far only for 2 man-files.
-
-	* runoff.man: New file which documents the `RUNOFF' language from
-	the 1960s up to the 1980s.
-
-	* groff_filenames.man: New file about the file name extensions
-	since `RUNOFF'.
-
-########################################################################
-
-Copyright 2013
-  Free Software Foundation, Inc.
-
-Copying and distribution of this file, with or without modification,
-are permitted in any medium without royalty provided the copyright
-notice and this notice are preserved.
-
-Local Variables:
-version-control: never
-coding: utf-8
-End:

Index: RUNOFF/Makefile.sub
===================================================================
RCS file: RUNOFF/Makefile.sub
diff -N RUNOFF/Makefile.sub
--- RUNOFF/Makefile.sub	6 May 2013 00:00:32 -0000	1.1
+++ /dev/null	1 Jan 1970 00:00:00 -0000
@@ -1,41 +0,0 @@
-# Makefile.sub for `RUNOFF' (integration into the `groff' source tree)
-
-# File position: <groff-source>/contrib/RUNOFF/Makefile.sub
-
-# Copyright (C) 2013
-#   Free Software Foundation, Inc.
-#
-# Written by Bernd Warken <groff-bernd.warken-72@web.de>.
-
-# Last update: 6 May 2013
-
-# This file is part of `RUNOFF' 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/>.
-
-########################################################################
-
-MAN7=\
-  runoff.n \
-  groff_filenames.n
-
-MOSTLYCLEANADD=$(MAN7)
-
-########################################################################
-# Emacs settings
-########################################################################
-#
-# Local Variables:
-# mode: makefile
-# End:

Index: RUNOFF/groff_filenames.man
===================================================================
RCS file: RUNOFF/groff_filenames.man
diff -N RUNOFF/groff_filenames.man
--- RUNOFF/groff_filenames.man	27 Jun 2013 16:13:54 -0000	1.3
+++ /dev/null	1 Jan 1970 00:00:00 -0000
@@ -1,929 +0,0 @@
-.TH GROFF_FILENAMES @MAN7EXT@ "@MDATE@" "Groff Version @VERSION@"
-.SH NAME
-groff_filenames \- filename extensions for RUNOFF, roff and groff
-.
-.\" The .SH was moved to this place in order to appease `apropos'.
-.
-.\" --------------------------------------------------------------------
-.\" Legalese
-.\" --------------------------------------------------------------------
-.
-.de authors
-This file was written by Bernd Warken
-.MT groff-bernd.warken-72@web.de
-.ME .
-..
-.
-.
-.de copying
-Copyright \(co 2013
-.RS
-.ft CI
-Free Software Foundation, Inc.
-.ft R
-.RE
-.
-.
-.P
-Last update: 5 May 2013
-.
-.
-.P
-This file is part of
-.ft CI
-groff\\fR, a free software project.
-.
-.P
-You can redistribute it and/or modify it under the terms of the
-.nh
-.ft CI
-GNU General Public License
-.ft R
-.hy
-as published by the
-.nh
-.ft CI
-Free Software Foundation (FSF)\\fR,
-.hy
-either version 3 of the License, or (at your option) any later version.
-.
-.P
-You should have received a copy of the
-.nh
-.ft CI
-GNU General Public License
-.ft R
-.hy
-along with
-.ft CI
-groff\\fR,
-see the files
-.nh
-.ft CB
-COPYING
-.ft R
-and
-.ft CB
-LICENSE
-.ft R
-.hy
-in the top directory of the
-.ft CI
-groff
-.ft R
-source package.
-.
-.P
-You can also visit
-.UR http://\\:www.gnu.org/\\:licenses
-.UE .
-..
-.
-.\" --------------------------------------------------------------------
-.\" Setup
-.\" --------------------------------------------------------------------
-.
-.ds1 Ellipsis "\&.\|.\|.\&"
-.
-.\" --------------------------------------------------------------------
-.\" Macro definitions
-.\" --------------------------------------------------------------------
-.
-.\" --------------------------------------------------------------------
-.\" .FONT (<font name> <text> [<font name> <text> ...])
-.\"
-.\" Print in different fonts: R, I, B, CR, CI, CB
-.\"
-.de1 FONT
-.  if (\\n[.$] = 0) \{\
-.	nop \&\f[]\&
-.	return
-.  \}
-.  ds result \&
-.  while (\\n[.$] >= 2) \{\
-.	as result \,\f[\\$1]\\$2\f[]
-.	shift 2
-.  \}
-.  if (\\n[.$] = 1) .as result \,\f[\\$1]
-.  nh
-.  nop \\*[result]\&
-.  hy
-..
-.
-.\" --------------------------------------------------------------------
-.\" End of macro definitions
-.\" --------------------------------------------------------------------
-.
-.
-.\" --------------------------------------------------------------------
-.SH DESCRIPTION
-.\" --------------------------------------------------------------------
-.
-Since the evolution of
-.FONT CI RUNOFF
-in the 1960s and
-.FONT CI roff
-in the 1970s, a whole bunch of filename extensions for
-.FONT CI RUNOFF
-and
-.FONT CI roff
-files were used.
-.
-.
-.P
-The
-.FONT CI roff
-extensions refer to preprocessors or macro packages.
-.
-These extensions are fixed in all
-.FONT CI Unix R \-like
-operating systems.
-.
-.
-.P
-Later on,
-.FONT CR groff
-added some more extensions.
-.
-We will now write a
-.I man\-page about these filename extensions.
-.
-.
-.\" --------------------------------------------------------------------
-.SH HISTORICAL RUNOFF LANGUAGE
-.\" --------------------------------------------------------------------
-.
-The first text language that used the
-.FONT CB .COMMAND
-structure for defining commands is said to be the
-.FONT CI MEMO
-language with programs
-.FONT CB MODIFY
-and
-.FONT CB DITTO R .
-.
-It was used at
-.FONT CR MIT
-under the operating system
-.FONT CR CTSS
-in the years 1960\-63.
-.
-But there is no open documentation for this old text system, but it
-seems that there is 1 book about it in the non-public library at
-.FONT CB MIT R .
-.
-.
-.P
-The letter
-.FONT CB m
-taken from
-.FONT CI MEMO R / MODIFY
-is still active as the option
-.FONT CB -m
-for declaring a macro package in
-.FONT CB troff R / CB nroff R .
-.
-.
-.P
-The first documented
-.FONT CB .COMMAND
-text language was
-.FONT CI RUNOFF R ,
-see
-.BR runoff (@MAN7EXT@).
-.
-.
-.\" --------------------------------------------------------------------
-.SS RUNOFF Files
-.\" --------------------------------------------------------------------
-.
-All available
-.FONT CI RUNOFF
-files are now kept in the internet at an archive on
-.FONT CI github R .
-.
-Use the command-line call
-.RS
-.EX
-.FONT CR "$ " CB "git clone git@github.com:RUNOFF/RUNOFF.git"
-.EE
-.RE
-for getting this archive (without the leading dollar).
-.
-.
-.TP
-.FONT I <name> CB .RUNOFF
-.TQ
-.FONT I <name> CB .runoff
-were the oldest naming for files in the original
-.FONT CI RUNOFF
-format of the 1960s at
-.FONT CR "IBM 7090"
-and
-.FONT CR 7094
-with the operating system
-.FONT CR CTSS R .
-.
-.
-.TP
-.FONT I <name> CB .RUN
-.TQ
-.FONT I <name> CB .run
-This abbreviation was used for
-.FONT CI RUNOFF
-files on the
-.FONT CR CTSS
-and
-.FONT CR Multics
-operating system in the 1960s and later on.
-.
-.
-.TP
-.FONT I <name> CB .RNO
-.TQ
-.FONT I <name> CB .rno
-was used for normal
-.FONT CI RUNOFF
-text files, mostly on the
-.FONT CR "PDP10\-10 archive" R .
-.
-.
-.TP
-.FONT I <name> CB .RNH
-.TQ
-.FONT I <name> CB .rnh
-was used for help files written in the
-.FONT CI RUNOFF
-language on the
-.FONT CR "PDP10\-10 archive" R .
-.
-.
-.P
-.FONT CI RUNOFF
-files with the extensions
-.FONT CB .rnh R ,
-.FONT CB .rno R ,
-and
-.FONT CB .run
-are still available in the internet at several sites, mostly at the
-.FONT CR "DEC PDP\-10 archive" R .
-.
-See
-.nh
-.UR http://\:pdp\-10.trailing\-edge.com/\:cgi-bin/\:searchbyname?name=*.rnh
-RNH
-.UE ,
-.UR http://\:pdp\-10.trailing\-edge.com/\:cgi-bin/\:searchbyname?name=*.rno
-RNO
-.UE ,
-and
-.UR http://\:pdp\-10.trailing\-edge.com/\:cgi-bin/\:searchbyname?name=*.run
-RUN
-.UE  .
-.hy
-.
-.
-.\" --------------------------------------------------------------------
-.SS Processed RUNOFF Text Files
-.\" --------------------------------------------------------------------
-.
-Files written in the
-.FONT CI RUNOFF
-language were processed by the program
-.FONT CB RUNOFF R .
-.
-Only text files were produced by this step, because graphics was not
-available in the 1960s.
-.
-Today we would use the file name extension
-.FONT CI * CB .txt R .
-.
-That was not done in these early times.
-.
-Instead the following extensions were taken:
-.
-.
-.TP
-.FONT I <name> CB .DOC
-.TQ
-.FONT I <name> CB .doc
-Very often this naming was used for the output of the
-.FONT CB RUNOFF
-program.
-.
-It contained
-.I filled
-and
-.I hyphenated
-text, suitable for tty mode.
-.
-The extension
-.FONT CB .doc
-was later on taken by
-.FONT CR Microsoft
-for their
-.IR "office files" .
-.
-.
-.TP
-.FONT I <name> CB .MEM
-.TP
-.FONT I <name> CB .mem
-This often used extension was taken for
-.FONT CI RUNOFF
-files to refer to the ancient
-.FONT CI MEMO
-language.
-.
-.
-.TP
-.FONT I <name> CB .HLP
-.TQ
-.FONT I <name> CB .hlp
-The formatting of
-.FONT CI * CB .rnh
-files (help files) was stored under this extension.
-.
-.
-.P
-This ends the description of
-.FONT CI RUNOFF .R .
-.
-All following parts of this document refer to the
-.FONT CI roff
-language and the used file name extensions thereof.
-.
-.
-.\" --------------------------------------------------------------------
-.SH COMPRESSION OF ROFF FILES
-.\" --------------------------------------------------------------------
-.
-Each
-.FONT CI roff
-file can be optionally
-.IR compressed .
-.
-That means that the
-.I total filename
-ends with a
-.IR "compressor name" .
-.
-So the whole filename has the structure
-.IR <name> \f[CB].\fP <extension>[ \f[CB].\fP <compression>] .
-.
-.
-.P
-Mostly known are the
-.I compressor extensions
-.FONT CB .Z R ,
-.FONT CB .gz R ,
-and
-.FONT CB .bzip2 R .
-.
-Relatively new is
-.FONT CB .xz R .
-.
-.
-.P
-From now on, we will ignore the
-.I compressions
-and only comment the structure
-.IB <name> . <extension>\fR.\fP
-.
-.
-.\" --------------------------------------------------------------------
-.SH MAN\-PAGES
-.\" --------------------------------------------------------------------
-.
-The
-.FONT CR Unix
-.FONT CI "manual pages"
-are shortly named
-.FONT CI "man\-pages" R .
-.
-The
-.FONT CI man\-page
-style is the best known part of the
-.FONT CI roff
-language.
-.
-.
-.P
-The extensions for
-.FONT CI man
-should be better documented.
-.
-So this is documented here.
-.
-.
-.P
-Files written in the
-.FONT CI man
-language use the following extension:
-.IB * . <section>[<group>] .
-.
-.
-.\" --------------------------------------------------------------------
-.SS Man-page Sections
-.\" --------------------------------------------------------------------
-.
-The traditional
-.FONT I "man\-page " CI <section>
-is a digit from
-.FONT CB 1
-to
-.FONT CB 8 R .
-.
-.
-.TP
-.FONT I <name> CB .1
-.TQ
-.FONT I <name> CB .2
-.TQ
-.FONT I <name> CB .3
-.TQ
-.FONT I <name> CB .4
-.TQ
-.FONT I <name> CB .5
-.TQ
-.FONT I <name> CB .6
-.TQ
-.FONT I <name> CB .7
-.TQ
-.FONT I <name> CB .8
-Classic man\-page
-.IR sections .
-.
-.
-.P
-Linux added the section number
-.FONT CB 9
-for kernel man\-pages.
-.
-.
-.TP
-.FONT I <name> CB .9
-.I Linux
-kernel man-pages
-.
-.
-.P
-In older commercial
-.FONT CI Unix
-systems, the 3 characters
-.FONT CB l R ,
-.FONT CB n R ,
-and
-.FONT CB o
-were also used as
-.I section
-names.
-.
-This is today
-.IR deprecated ,
-but there are still documents in this format.
-.
-.
-.TP
-.FONT I <name> CB .l
-.TQ
-.FONT I <name> CB .n
-.TQ
-.FONT I <name> CB .o
-.I Deprecated
-old
-.IR "man\-page sections" .
-.
-.
-.\" --------------------------------------------------------------------
-.SS Man\-page Group Extensions
-.\" --------------------------------------------------------------------
-.
-The
-.I <group>
-extension in
-.FONT CB . I <section>[<group>]
-is optional, but it can be any string of word characters.
-.
-Usually programmers use a group name that is already used, e.g.
-.FONT CB x
-for
-.FONT CI "X Window System"
-documents or
-.FONT CB tk
-to refer to the
-.FONT CI tk
-programming language.
-.
-.
-.P
-Examples:
-.
-.
-.TP
-.FONT CB groff.1
-is the man-page for
-.FONT CB groff
-in
-.I section
-.FONT CB 1
-without a
-.I group
-.
-.
-.TP
-.FONT CB xargs.1posix.gz
-is the man\-page for the program
-.FONT CB xargs
-in
-.I section
-.FONT CB 1
-and
-.I group
-.FONT CB posix R ;
-moreover it is
-.I compressed
-with
-.FONT CB gz
-.FONT R ( CB gzip R ).
-.
-.
-.TP
-.FONT CB config.5ssl
-.FONT CI "OpenSSL CONF"
-library configuration files from
-.I section
-.FONT CB 5
-with
-.I group
-.FONT CB ssl R .
-.
-.
-.TP
-.FONT CB dpkg-reconfigure.8cdebconf
-man\-page for the program
-.FONT CB dpkg\-reconfigure
-in
-.I section
-.FONT CB 8
-and
-.I group
-.FONT CB cdebconf R .
-.
-.
-.\" --------------------------------------------------------------------
-.SS Source of Man\-pages
-.\" --------------------------------------------------------------------
-.
-There are 2
-.FONT CI roff
-languages for writing man\-pages:
-.FONT CB man
-and
-.FONT CB mdoc R .
-.
-.
-.P
-The names of these 2 styles are taken as
-.I extensions
-for the source code files of man\-pages in the
-.FONT CI groff
-package.
-.
-.
-.TP
-.FONT I <name> CB .man
-.I traditional
-Unix\-like man\-page format.
-.
-.
-.TP
-.FONT I <name> CB .mdoc
-additional BSD man-page format.
-.
-.
-.TP
-.FONT I <name> CB .mandoc
-Files using this extension recognize both man\-page formats in
-.FONT CB groff
-and other processors.
-.
-.
-.TP
-FONT I <name> CB .n
-A temporary man-page file produced by a run of
-.B make
-in the
-.CB groff
-source package.
-.
-.
-.\" --------------------------------------------------------------------
-.SH TRADITIONAL TROFF EXTENSIONS
-.\" --------------------------------------------------------------------
-.
-.\" --------------------------------------------------------------------
-.SS Files Using Macro Packages
-.\" --------------------------------------------------------------------
-.
-The
-.FONT CI "classical roff"
-languages were interpreted by the
-.FONT CB "traditional troff"
-and
-.FONT CB "nroff"
-programs.
-.
-.
-.P
-There were several
-.FONT CI roff
-languages, each represented by a
-.IR "macro-package" .
-.
-Each of these provided a suitable file name
-.IR extension :
-.
-.
-.TP
-.FONT I <name> CB .me
-.FONT CI roff
-file using the
-.FONT CB me
-.IR "macro package" .
-.
-.
-.TP
-.FONT I <name> CB .mm
-.FONT CI roff
-file using the
-.FONT CB mm
-.I macro package
-.
-.
-.TP
-.FONT I <name> CB .ms
-.FONT CI roff
-file using the
-.FONT CB ms
-.I macro package
-.
-.
-.P
-All of these classical
-.FONT CI roff
-languages and their extensions are still very active in
-.BR groff .
-.
-.
-.\" --------------------------------------------------------------------
-.SS Source Code for Macro Packages (TMAC Files)
-.\" --------------------------------------------------------------------
-.
-In traditional
-.FONT CI roff
-the source code for the macro packages was stored in
-.FONT CI TMAC
-files.
-.
-Their file names have the form:
-.
-.
-.TP
-.FONT CB tmac. I <package> R ,
-.I <package>
-is the name of the macro package without the leading
-.FONT CB m
-character, wich is reintegrated by the option
-.FONT CB -m R .
-.
-.
-.P
-For example,
-.FONT CB tmac.an
-is the source for the
-.FONT CB man
-macro package.
-.
-.
-.P
-In the
-.FONT CB groff
-source, more suitable file names were integrated, see later on.
-.
-.
-.\" --------------------------------------------------------------------
-.SS Preprocessors
-.\" --------------------------------------------------------------------
-.
-Moreover, the following
-.I preprocessors
-were used as filename extension:
-.
-.
-.TP
-.FONT I <name> CB .chem
-for the integration of chemical formulas
-.
-.
-.TP
-.FONT I <name> CB .eqn
-for the mathematical use of equations
-.
-.
-.TP
-.FONT I <name> CB .pic
-graphical tool
-.
-.
-.TP
-.FONT I <name> CB .tbl
-for tables with
-.FONT CI tbl
-.
-.
-.TP
-.FONT I <name> CB .ref
-for files using the
-.FONT CB prefer
-.I preprocesor
-.
-.
-.\" --------------------------------------------------------------------
-.SS Classical Roff Files
-.\" --------------------------------------------------------------------
-.
-.TP
-.FONT I <name> CB .t
-.TQ
-.FONT I <name> CB .tr
-for files using the
-.FONT CI roff
-language of any kind
-.
-.
-.\" --------------------------------------------------------------------
-.SH NEW GROFF EXTENSIONS
-.\" --------------------------------------------------------------------
-.
-.FONT CI "GNU roff"
-.FONT CB groff
-is the actual
-.FONT CI roff
-standard, both for classical
-.FONT CI roff
-and new extensions..
-.
-So even the used new extensions in the source code should be regarded
-as actual standard.
-.
-The following extensions are used instead of classical
-.FONT CB .t
-or
-.FONT CB .tr R :
-.
-.
-.TP
-.FONT I <name> CB .groff
-.TQ
-.FONT I <name> CB .roff
-general ending for files using the
-.FONT CI groff
-.I language
-.
-.
-.\" --------------------------------------------------------------------
-.SS Source Code for Macro Packages (TMAC Files)
-.\" --------------------------------------------------------------------
-.
-As the classical form
-.FONT CB tmac. I <package_without_m> R ,
-of the
-.FONT CI TMAC
-file names is quite strange,
-.
-CI groff
-added the following structures:
-.
-.
-.TP
-.FONT I <package_without_m> CB .tmac
-.TQ
-.FONT CB m I <package> CB .tmac
-.TQ
-.FONT CB groff_m I <package> CB .tmac
-.
-.
-.\" --------------------------------------------------------------------
-.SS Files Using new Macro Packages
-.\" --------------------------------------------------------------------
-.
-.FONT CI Groff
-uses the following new macro packages:
-.
-.
-.TP
-.FONT I <name> CB .mmse
-file with swedish
-.FONT CB mm
-.I makros
-for
-.B groff
-.
-.
-.TP
-.FONT I <name> CB .mom
-files written in the
-.FONT CI "groff macro package"
-.FONT CB mom
-.
-.
-.TP
-.FONT I <name> CB .www
-files written in
-.FONT CB HTML R \-like
-.FONT CI groff
-.IR macros .
-.
-.
-.\" --------------------------------------------------------------------
-.SS Preprocessors and Postprocessors
-.\" --------------------------------------------------------------------
-.
-.TP
-.FONT I <name> CB .hbtbl
-a new
-.FONT CI tbl
-format.
-.
-See
-.BR groff_hdtbl (@MAN7EXT@).
-.
-.
-.TP
-.FONT I <name> CB .grap
-files written for the graphical
-.FONT CB grap
-processor.
-.
-.
-.TP
-.FONT I <name> CB .grn
-for including
-.BR gremlin (@MAN1EXT@),
-pictures, see
-.BR grn (@MAN1EXT@).
-.
-.
-.TP
-.FONT I <name> CB .pdfroff
-transform this file with
-.FONT CB pdfroff
-of the
-.FONT CI groff
-system
-.
-.
-.\" --------------------------------------------------------------------
-.SH "SEE ALSO"
-.\" --------------------------------------------------------------------
-.
-.
-.TP
-History and future
-.BR runoff (@MAN7EXT@),
-.BR roff (@MAN7EXT@),
-.BR man\-pages (@MAN7EXT@),
-.BR groff_diff (@MAN7EXT@),
-.BR groff (@MAN7EXT@)
-.
-.
-.TP
-.I Compression
-.BR uncompress (1posix),
-.BR gzip2 (@MAN1EXT@),
-.BR bzip2 (@MAN1EXT@),
-.BR xz (@MAN1EXT@)
-.
-.
-.\" --------------------------------------------------------------------
-.SH "AUTHORS"
-.\" --------------------------------------------------------------------
-.
-.authors
-.
-.
-.\" --------------------------------------------------------------------
-.SH "COPYING"
-.\" --------------------------------------------------------------------
-.
-.copying
-.
-.
-.\" --------------------------------------------------------------------
-.\" Emacs settings
-.\" --------------------------------------------------------------------
-.
-.\" Local Variables:
-.\" mode: nroff
-.\" End:

Index: RUNOFF/runoff.man
===================================================================
RCS file: RUNOFF/runoff.man
diff -N RUNOFF/runoff.man
--- RUNOFF/runoff.man	31 Jul 2013 05:42:07 -0000	1.3
+++ /dev/null	1 Jan 1970 00:00:00 -0000
@@ -1,11247 +0,0 @@
-.\" t
-.TH RUNOFF @MAN7EXT@ "@MDATE@" "Groff Version @VERSION@"
-.SH NAME
-RUNOFF \[em] the predecessor of the \f[CI]roff\f[] langugage
-.
-.\" The .SH was moved to this place in order to appease `apropos'.
-.
-.\" --------------------------------------------------------------------
-.\" Legalese
-.\" --------------------------------------------------------------------
-.
-.de authors
-This file was written by Bernd Warken
-.MT groff\-bernd.warken\-72@web.de
-.ME .
-..
-.
-.
-.de copying
-Copyright \(co 2013
-.RS
-.ft CI
-Free Software Foundation, Inc.
-.ft R
-.RE
-.
-.P
-Last update: 14 May 2013
-.
-.P
-This file is part of
-.ft CI
-groff\\f[R], a free software project.
-.
-.P
-You can redistribute it and/or modify it under the terms of the
-.nh
-.ft CI
-GNU General Public License
-.ft R
-.hy
-as published by the
-.nh
-.ft CI
-Free Software Foundation (FSF)\\f[R],
-.hy
-either version 3 of the License, or (at your option) any later version.
-.
-.P
-You should have received a copy of the
-.nh
-.ft CI
-GNU General Public License
-.ft R
-.hy
-along with
-.ft CI
-groff\\f[R],
-see the files
-.nh
-.ft CB
-COPYING
-.ft R
-and
-.ft CB
-LICENSE
-.ft R
-.hy
-in the top directory of the
-.ft CI
-groff
-.ft R
-source package.
-.
-.P
-You can also visit
-.UR http://\\:www.gnu.org/\\:licenses
-.UE .
-..
-.
-.
-.\" --------------------------------------------------------------------
-.\" Setup
-.\" --------------------------------------------------------------------
-.
-.ds1 Ellipsis "\&.\|.\|.\&\"
-.
-.
-.\" --------------------------------------------------------------------
-.\" Macro definitions
-.\" --------------------------------------------------------------------
-.
-.\" --------------------------------------------------------------------
-.\" .FONT (<font name> <text> [<font name> <text> ...])
-.\"
-.\" Print in different fonts: R, I, B, CR, CI, CB
-.\"
-.de1 FONT
-.  if (\\n[.$] = 0) \{\
-.	nop \&\f[P]\&
-.	return
-.  \}
-.  ds result \&
-.  while (\\n[.$] >= 2) \{\
-.	as result \,\f[\\$1]\\$2
-.	if !"\\$1"P" .as result \f[P]
-.	shift 2
-.  \}
-.  if (\\n[.$] = 1) .as result \,\f[\\$1]
-.  nh
-.  nop \\*[result]\&
-.  hy
-..
-.
-.\" --------------------------------------------------------------------
-.\" .Topic  ([<indent>])
-.\"
-.\" A bulleted paragraph
-.\"
-.de Topic
-.  ie \\n[.$]=0 \
-.    ds @indent 2m\"
-.  el \
-.    ds @indent \\$1\"
-.  IP \[bu] \\*[@indent]
-.  rm @indent
-..
-.
-.\" --------------------------------------------------------------------
-.\" .UL (<text to underline> [<append>])
-.\"
-.\" Underline $1 and append $2 without underline
-.\"
-.de UL
-.  if t \}\
-.    nop \Z'\\$1'\v'.25m'\D'l \w'\\$1'u 0'\v'-.25m'\\$2
-.    return
-.  \}
-.  ul 1
-\\$1\c
-\\$2
-..
-.
-.\" --------------------------------------------------------------------
-.\" .TableHDTBL - table using hdtbl for troff
-.\"
-.de1 TableHDTBL eHDTBL
-.
-This list of commands is a table over 5 pages.
-.
-.
-.bp
-.
-.\" use groff_hdtbl
-.\" mso hdtbl.tmac
-.
-.
-.\" --------------------------------------------------------------------
-.\" hdtbl Table: List of Commands (Alphabetical) page 1/5
-.\" --------------------------------------------------------------------
-.
-.hy
-.fi
-.
-.TBL cols=3
-.TR hl=d ".TH colspan=2 Command or Abbreviation" ".TH Related Commands"
-.\" TR hl=d ".TD colspan=2 Command or Abbreviation" ".TD Related Commands"
-.
-.
-.nf
-.nh
-.
-.
-.\" A ==================================================================
-.
-.TR
-.TD
-.FONT CB ".AP"
-.TD
-.FONT R "(=" CB ".AUTOPARAGRAPH" R ")"
-.TD
-.
-.
-.TR
-.TD
-.FONT CB ".APPENDIX " I "text"
-.TD
-.FONT R "(=" CB ".AX" R ")"
-.TD
-.FONT CB ".NUMBER APPENDIX " I "a"
-.
-.TR
-.TD
-.FONT CB ".AX"
-.TD
-.FONT R "(=" CB ".APPENDIX" R ")"
-.TD
-.
-.TR hl=d
-.TD
-.FONT CB ".AUTOPARAGRAPH"
-.TD
-.FONT R "(=" CB ".AP" R ")"
-.TD
-.FONT CB ".NOAUTOPARAGRAPH"
-.br
-.FONT R "(" CB ".NAP" R ")"
-.
-.\" B ==================================================================
-.
-.TR
-.TD
-.FONT CB ".B"
-.TD
-.FONT R "(=" CB ".BLANK" R ")"
-.TD
-.
-.TR
-.TD
-.FONT CB ".BLANK" I " n"
-.TD
-.FONT  R "(=" CB ".B" R ")"
-.TD
-.FONT CB ".SKIP" I " n"
-.br
-.FONT R "(" CB ".S" R ")"
-.
-.TR
-.TD
-.FONT CB ".BR"
-.TD
-.FONT R "(=" CB ".BREAK" R ")"
-.TD
-.
-.TR hl=d
-.TD
-.FONT CB ".BREAK"
-.TD
-.FONT R "(" CB ".BR" R ")"
-.TD
-.
-.
-.\" C ==================================================================
-.
-.TR
-.TD
-.FONT CB ".C"
-.TD
-.FONT R "(=" CB ".CENTRE" R ")"
-.TD
-.
-.TR
-.TD
-.FONT CB ".CENTER"
-.TD
-.FONT R "(=" CB ".CENTRE" R ")"
-.TD
-.
-.TR
-.TD
-.FONT CB ".CENTRE" I " n" CB ";" I "text"
-.TD
-.FONT R "(=" CB ".C" R ")"
-.TD
-.
-.TR
-.TD
-.FONT CB ".CH"
-.TD
-.FONT R "(=" CB ".CHAPTER" R ")"
-.TD
-.
-.TR
-.TD
-.FONT CB ".CHAPTER" I " text"
-.TD
-.FONT R "(=" CB ".CH" R ")"
-.TD
-.FONT CB ".NUMBER CHAPTER" I " n"
-.
-.TR hl=d
-.TD
-.FONT CB ".COMMENT" I " text"
-.TD
-.TD
-.
-.
-.\" D ==================================================================
-.
-.TR
-.TD
-.FONT CB ".DO INDEX" I " text"
-.TD
-.FONT R "(=" CB ".DX" R ")"
-.TD
-.FONT CB ".PRINT INDEX"
-.br
-.FONT R "(" CB ".PX" R ")"
-.
-.TR hl=d
-.TD
-.FONT CB ".DX"
-.TD
-.FONT R "(=" CB ".DO INDEX" R ")"
-.TD
-.
-.
-.\" E ==================================================================
-.
-.TR
-.TD
-.FONT CB ".ELS"
-.TD
-.FONT R "(=" CB ".END LIST" R ")"
-.TD
-.
-.TR
-.TD
-.FONT CB ".EN"
-.TD
-.FONT R "(=" CB ".END NOTE" R ")"
-.TD
-.
-.TR
-.TD
-.FONT CB ".END LIST"
-.TD
-.FONT R "(=" CB ".ELS" R ")"
-.TD
-.FONT CB ".LIST " I "n"
-.br
-.FONT R "(" CB ".LS" R ")"
-.
-.TR
-.TD
-.FONT CB ".END LITERAL"
-.TD
-.FONT R "(=" CB ".ELI" R ")"
-.TD
-.FONT CB ".LITERAL"
-.FONT R "(" CB ".LIT" R ")"
-.
-.TR
-.TD
-.FONT CB ".END NOTE"
-.TD
-.FONT R "(=" CB ".EN" R ")"
-.TD
-.FONT CB ".NOTE " I "text"
-.br
-.FONT R "(" CB ".NT" R ")"
-.
-.TR hl=d
-.TD
-.FONT CB ".END SUBPAGE"
-.TD
-.TD
-.FONT CB ".SUBPAGE"
-.
-.
-.\" F ==================================================================
-.
-.TR
-.TD
-.FONT CB ".F"
-.TD
-.FONT R "(=" CB ".FILL" R ")"
-.TD
-.
-.TR
-.TD
-.FONT CB ".FG"
-.TD
-.FONT R "(=" CB ".FIGURE" R ")"
-.TD
-.
-.
-.ETB
-.
-.
-.bp
-.\" --------------------------------------------------------------------
-.\" hdtbl Table: List of Commands (Alphabetical) page 2/5
-.\" --------------------------------------------------------------------
-.
-.fi
-.hy
-.
-.TBL cols=3
-.TR hl=d ".TH colspan=2 Command or Abbreviation" ".TH Related Commands"
-.
-.
-.nf
-.nh
-.
-.
-.\" F2 =================================================================
-.
-.TR
-.TD
-.FONT CB ".FIGURE" I " n"
-.TD
-.FONT R "(=" CB ".FG" R ")"
-.TD
-.
-.TR
-.TD
-.FONT CB ".FILL"
-.TD
-.FONT R "(=" CB ".F" R ")"
-.TD
-.FONT CB ".NOFILL"
-.br
-.FONT R "(" CB ".NF" R ")"
-.
-.TR
-.TD
-.FONT CB ".FIRST TITLE" I " text"
-.TD
-.FONT R "(=" CB ".FT" R ")"
-.TD
-.FONT CB ".TITLE" I " text"
-.
-.TR
-.TD
-.FONT CB ".FLAGS CAPITALIZE"
-.TD
-.FONT R "(=" CB ".FL CAPITALIZE" R ")"
-.TD
-.FONT CB ".NO FLAGS CAPITALIZE"
-.br
-.FONT R "(" CB ".NFL" R ")"
-.
-.TR
-.TD
-.FONT CB ".FLAGS HYPHENATE"
-.TD
-.FONT R "(=" CB ".FL HYPHENATE" R ")"
-.TD
-.FONT CB ".NO FLAGS HYPHENATE"
-.br
-.FONT R "(" CB ".NFH" R ")"
-.
-.TR
-.TD
-.FONT CB ".FN"
-.TD
-.FONT R "(=" CB ".FOOTNOTE" R ")"
-.TD
-.
-.TR
-.TD
-.FONT CB ".FOOTNOTE" I " n"
-.TD
-.FONT R "(=" CB ".FN" R ")"
-.TD
-.
-.TR hl=d
-.TD
-.FONT CB ".FT"
-.TD
-.FONT R "(=" CB ".FIRST TITLE" R ")"
-.TD
-.
-.
-.\" G ==================================================================
-.\" H ==================================================================
-.
-.TR
-.TD
-.FONT CB ".HD"
-.TD
-.FONT R "(=" CB ".HEADER" R ")"
-.TD
-.
-.TR
-.TD
-.FONT CB ".HEADER" I " arg"
-.br
-.FONT R "[" I "arg" R "=" CB "UPPER" R ", " CB "LOWER" R ", or " CB "MIXED]"
-.TD
-.FONT R "(=" CB ".HD" R ")"
-.TD
-.FONT CB ".NOHEADER "
-.br
-.FONT R "(" CB ".NHD" R ")"
-.
-.TR
-.TD
-.FONT CB ".HEADER LEVEL" I " n text"
-.TD
-.FONT R "(=" CB ".HL" R ")"
-.TD
-.
-.TR
-.TD
-.FONT CB ".HL"
-.TD
-.FONT R "(=" CB ".HEADER LEVEL" R ")"
-.TD
-.
-.TR
-.TD
-.FONT CB ".HY"
-.TD
-.FONT R "(=" CB ".HYPHENATION" R ")"
-.TD
-.
-.TR hl=d
-.TD
-.FONT CB ".HYPHENATION"
-.TD
-.FONT R "(=" CB ".HY" R ")"
-.TD
-.FONT CB ".NO HYPHENATION"
-.br
-.FONT R "(" CB ".NHY" R ")"
-.
-.
-.\" I ==================================================================
-.
-.TR
-.TD
-.FONT CB ".I"
-.TD
-.FONT R "(=" CB ".INDENT" R ")"
-.TD
-.
-.TR
-.TD
-.FONT CB ".INDENT" I " n"
-.TD
-.FONT R "(=" CB ".I" R ")"
-.TD
-.
-.TR hl=d
-.TD
-.FONT CB ".INDEX" I " text"
-.TD
-.FONT R "(=" CB ".X" R ")"
-.TD
-.
-.
-.\" J ==================================================================
-.
-.TR
-.TD
-.FONT CB ".J"
-.TD
-.FONT R "(=" CB ".JUSTIFY" R ")"
-.TD
-.
-.TR hl=d
-.TD
-.FONT CB ".JUSTIFY"
-.TD
-.FONT R "(=" CB ".J" R ")"
-.TD
-.FONT CB ".NOJUSTIFY"
-.br
-.FONT R "(" CB ".NJ" R ")"
-.
-.
-.\" K ==================================================================
-.\" L ==================================================================
-.
-.TR
-.TD
-.FONT CB ".LC"
-.TD
-.FONT R "(=" CB ".LOWER CASE" R ")"
-.TD
-.
-.TR
-.TD
-.FONT CB ".LE"
-.TD
-.FONT R "(=" CB ".LIST ELEMENT" R ")"
-.TD
-.
-.TR
-.TD
-.FONT CB ".LEFT MARGIN" I " n"
-.TD
-.FONT R "(=" CB ".LM" R ")"
-.TD
-.FONT CB ".RIGHT MARGIN" I " n"
-.br
-.FONT R "(" CB ".RM" R ")"
-.
-.TR
-.TD
-.FONT CB ".LIST" I " n"
-.TD
-.FONT R "(=" CB ".LS" R ")"
-.TD
-.FONT CB ".END LIST"
-.br
-.FONT R "(" CB ".ELS" R ")"
-.
-.ETB
-.
-.
-.bp
-.\" --------------------------------------------------------------------
-.\" hdtbl Table: List of Commands (Alphabetical) page 3/5
-.\" --------------------------------------------------------------------
-.
-.fi
-.hy
-.
-.TBL cols=3
-.TR hl=d ".TH colspan=2 Command or Abbreviation" ".TH Related Commands"
-.
-.
-.nf
-.nh
-.
-.\" L2 =================================================================
-.
-.TR
-.TD
-.FONT CB ".LIST ELEMENT;" I "text"
-.TD
-.FONT R "(=" CB ".LE" R ")"
-.TD
-.FONT CB ".END LIST"
-.br
-.FONT R "(" CB ".ELS" R ")"
-.
-.TR
-.TD
-.FONT CB ".LIT"
-.TD
-.FONT R "(=" CB ".LITERAL" R ")"
-.TD
-.
-.TR
-.TD
-.FONT CB ".LITERAL"
-.TD
-.FONT R "(=" CB .LIT R ")"
-.TD
-.FONT CB ".END LITERAL"
-.FONT R ( CB .ELI R )
-.
-.TR
-.TD
-.FONT CB ".LM"
-.TD
-.FONT R "(=" CB ".LEFT MARGIN" R ")"
-.TD
-.
-.TR
-.TD
-.FONT CB ".LOWER CASE"
-.TD
-.FONT R "(=" CB ".LC" R ")"
-.TD
-.FONT CB ".UPPER CASE"
-.br
-.FONT R "(" CB ".UC" R ")"
-.
-.TR hl=d
-.TD
-.FONT CB ".LS"
-.TD
-.FONT R "(=" CB ".LIST" R ")"
-.TD
-.
-.
-.\" M ==================================================================
-.\" N ==================================================================
-.
-.TR
-.TD
-.FONT CB ".NAP"
-.TD
-.FONT R "(=" CB ".NOAUTOPARAGRAPH" R ")"
-.TD
-.
-.TR
-.TD
-.FONT CB ".NF"
-.TD
-.FONT R "(=" CB ".NOFILL" R ")"
-.TD
-.
-.TR
-.TD
-.FONT CB ".NFC"
-.TD
-.FONT R "(=" CB ".NO FLAGS CAPITALIZE" R ")"
-.TD
-.
-.TR
-.TD
-.FONT CB ".NFH"
-.TD
-.FONT R "(=" CB ".NO FLAGS HYPHENATE" R ")"
-.TD
-.
-.TR
-.TD
-.FONT CB ".NFL"
-.TD
-.FONT R "(=" CB ".NO FLAGS CAPITALIZE"
-.br
-and
-.br
-.FONT CB ".NO FLAGS HYPHENATE" R ")"
-.TD
-.
-.TR
-.TD
-.FONT CB ".NHD"
-.TD
-.FONT R "(=" CB ".NO HEADER" R ")"
-.TD
-.
-.TR
-.TD
-.FONT CB ".NHY"
-.TD
-.FONT R "(=" CB ".NO HYPHENATION" R ")"
-.TD
-.
-.TR
-.TD
-.FONT CB ".NJ"
-.TD
-.FONT R "(=" CB ".NO JUSTIFY" R ")"
-.TD
-.
-.TR
-.TD
-.FONT CB ".NM"
-.TD
-.FONT R "(=" CB ".NUMBER" R ")"
-.TD
-.
-.TR
-.TD
-.FONT CB ".NNM"
-.TD
-.FONT R "(=" CB ".NO NUMBER" R ")"
-.TD
-.
-.TR
-.TD
-.FONT CB ".NOAUTOPARAGRAPH"
-.TD
-.FONT R "(=" CB ".NAP" R ")"
-.TD
-.FONT CB ".AUTOPARAGRAPH"
-.br
-.FONT R "(" CB ".AP" R ")"
-.br
-.FONT CB ".PARAGRAPH" I " h" CB "," I "v" CB "," I "t"
-.br
-.FONT R "(" CB ".P" R ")"
-.
-.TR
-.TD
-.FONT CB ".NOFILL"
-.TD
-.FONT R "(=" CB ".NF" R ")"
-.TD
-.FONT CB ".FILL"
-.br
-.FONT R "(" CB ".F" R ")"
-.
-.TR
-.TD
-.FONT CB ".NO FLAGS CAPITALIZE"
-.TD
-.FONT R "(=" CB ".NFL" R ")"
-.TD
-.FONT CB ".FLAGS CAPITALIZE"
-.br
-.FONT R ( CB ".FL CAPITALIZE" R )
-.
-.TR
-.TD
-.FONT CB ".NO FLAGS HYPHENATE"
-.TD
-.FONT R "(=" CB ".NFH" R ")"
-.TD
-.FONT CB ".FLAGS HYPHENATE"
-.
-.TR
-.TD
-.FONT CB ".NOHEADER"
-.TD
-.FONT R "(=" CB ".NHD" R ")"
-.TD
-.FONT CB ".HEADER " I "arg"
-.br
-.FONT R "(" CB ".HD" R ")"
-.
-.ETB
-.
-.
-.bp
-.\" --------------------------------------------------------------------
-.\" hdtbl Table: List of Commands (Alphabetical) page 4/5
-.\" --------------------------------------------------------------------
-.
-.fi
-.hy
-.
-.TBL cols=3
-.TR hl=d ".TH colspan=2 Command or Abbreviation" ".TH Related Commands"
-.
-.
-.nf
-.nh
-.
-.\" N2 =================================================================
-.
-.TR
-.TD
-.FONT CB ".NO HYPHENATION"
-.TD
-.FONT R "(=" CB ".NHY" R ")"
-.TD
-.FONT CB ".HYPHENATION"
-.br
-.FONT R "(" CB ".HY" R ")"
-.
-.TR
-.TD
-.FONT CB ".NOJUSTIFY"
-.TD
-.FONT R "(=" CB ".NJ" R ")"
-.TD
-.FONT CB ".JUSTIFY"
-.br
-.FONT R "(" CB ".J" R ")"
-.
-.TR
-.TD
-.FONT CB ".NONUMBER"
-.TD
-.FONT R "(=" CB ".NNM" R ")"
-.TD
-.FONT CB ".NUMBER " I "n"
-.br
-.FONT R "(" CB ".NM" R ")"
-.
-.TR
-.TD
-.FONT CB ".NOPERIOD"
-.TD
-.FONT R "(=" CB ".NPR" R ")"
-.TD
-.FONT CB ".PERIOD"
-.br
-.FONT R "(" CB ".PR" R ")"
-.
-.TR
-.TD
-.FONT CB ".NOTE" I " text"
-.TD
-.FONT R "(=" CB ".NT" R ")"
-.TD
-.FONT CB ".END NOTE"
-.br
-.FONT R "(" CB ".EN" R ")"
-.
-.TR
-.TD
-.FONT CB ".NPR"
-.TD
-.FONT R "(=" CB ".NO PERIOD" R ")"
-.TD
-.
-.TR
-.TD
-.FONT CB ".NT"
-.TD
-.FONT R "(=" CB ".NOTE" R ")"
-.TD
-.
-.TR
-.TD
-.FONT CB ".NUMBER APPENDIX" I " a"
-.TD
-.TD
-.FONT CB ".APPENDIX" I " text"
-.
-.TR hl=d
-.TD
-.FONT CB ".NUMBER CHAPTER " I "n"
-.TD
-.TD
-.FONT CB ".CHAPTER text"
-.
-.
-.\" P ==================================================================
-.
-.TR
-.TD
-.FONT CB ".P"
-.TD
-.FONT R "(=" CB ".PARAGRAPH" R ")"
-.TD
-.
-.TR
-.TD
-.FONT CB ".PAGE"
-.TD
-.FONT R "(=" CB ".PG" R ")"
-.TD
-.
-.TR
-.TD
-.FONT CB ".PAGE SIZE"
-.TD
-.FONT R "(=" CB ".PAPER SIZE" R ")"
-.TD
-.
-.TR
-.TD
-.FONT CB ".PAPER SIZE" I " v" CB "," I "h"
-.br
-.FONT R "(=" CB ".PS" R ", " CB ".PAGE SIZE" R ")"
-.TD
-.TD
-.
-.TR
-.TD
-.FONT CB ".PERIOD"
-.TD
-.FONT R "(=" CB ".PR" R ")"
-.TD
-.FONT CB ".NOPERIOD"
-.br
-.FONT R "(" CB ".NPR" R ")"
-.
-.TR
-.TD
-.FONT CB ".PG"
-.TD
-.FONT R "(=" CB ".PAGE" R ")"
-.TD
-.
-.TR
-.TD
-.FONT CB ".PITCH"
-.TD
-.FONT R "(=" CB ".PIT" R ")"
-.TD
-.
-.TR
-.TD
-.FONT CB ".PRINT INDEX"
-.TD
-.FONT R "(=" CB ".PX" R ")"
-.TD
-.FONT CB ".DO INDEX" I " text"
-.FONT R "(" CB ".DX" R ")"
-.
-.TR
-.TD
-.FONT CB ".PS"
-.TD
-.FONT R "(=" CB ".PAPER SIZE" R ")"
-.TD
-.
-.TR hl=d
-.TD
-.FONT CB ".PX"
-.TD
-.FONT R "(=" CB ".PRINT INDEX" R ")"
-.TD
-.
-.
-.\" R ==================================================================
-.
-.TR
-.TD
-.FONT CB ".RIGHT MARGIN " I "n"
-.TD
-.FONT R "(=" CB ".RM" R ")"
-.TD
-.
-.TR hl=d
-.TD
-.FONT CB ".RM"
-.TD
-.FONT R "(=" CB ".RIGHT MARGIN" R ")"
-.TD
-.
-.
-.\" S ==================================================================
-.
-.TR
-.TD
-.FONT CB ".S"
-.TD
-.FONT R "(=" CB ".SKIP" R ")"
-.TD
-.
-.ETB
-.
-.
-.bp
-.\" --------------------------------------------------------------------
-.\" hdtbl Table: List of Commands (Alphabetical) page 5/5
-.\" --------------------------------------------------------------------
-.
-.fi
-.hy
-.
-.TBL cols=3
-.TR hl=d ".TH colspan=2 Command or Abbreviation" ".TH Related Commands"
-.
-.
-.nf
-.nh
-.
-.\" S2 =================================================================
-.
-.TR
-.TD
-.FONT CB ".SD"
-.TD
-.FONT R "(=" CB ".STANDARD" R ")"
-.TD
-.
-.TR
-.TD
-.FONT CB ".SKIP" I " n"
-.TD
-.FONT R "(=" CB ".S" R ")"
-.TD
-.FONT CB ".BLANK" I " n"
-.br
-.FONT R "(" CB ".B" R ")"
-.
-.TR
-.TD
-.FONT CB ".SP"
-.TD
-.FONT R "(=" CB ".SPACING" R ")"
-.TD
-.
-.TR
-.TD
-.FONT CB ".SPACING" I " n"
-.TD
-.FONT R "(=" CB ".SP" R ")"
-.TD
-.
-.TR
-.TD
-.FONT CB ".ST"
-.TD
-.FONT R "(=" CB ".SUBTITLE" R ")"
-.TD
-.
-.TR
-.TD
-.FONT CB ".SUBPAGE"
-.TD
-.TD
-.FONT CB ".END SUBPAGE"
-.
-.TR hl=d
-.TD
-.FONT CB ".SUBTITLE" I " text"
-.TD
-.FONT R "(=" CB ".ST" R ")"
-.TD
-.
-.
-.\" T ==================================================================
-.
-.TR
-.TD
-.FONT CB ".T"
-.TD
-.FONT R "(=" CB ".TITLE" R ")"
-.TD
-.
-.TR
-.TD
-.FONT CB ".TAB STOPS" I " n,n, \*[Ellipsis] ,n"
-.TD
-.FONT R "(=" CB ".TS" R ")"
-.TD
-.
-.TR
-.TD
-.FONT CB ".TEST PAGE" I " n"
-.TD
-.FONT R "(=" CB ".TP" R ")"
-.TD
-.
-.TR
-.TD
-.FONT CB ".TITLE" I " text"
-.TD
-.FONT R "(=" CB ".T" R ")"
-.TD
-.
-.TR
-.TD
-.FONT CB ".TP"
-.TD
-.FONT R "(=" CB ".TEST PAGE" R ")"
-.TD
-.
-.TR hl=d
-.TD
-.FONT CB ".TS"
-.TD
-.FONT R "(=" CB ".TAB STOPS" R ")"
-.TD
-.
-.
-\" U ==================================================================
-.
-.TR
-.TD
-.FONT CB ".UC"
-.TD
-.FONT R "(=" CB ".UPPER CASE" R ")"
-.TD
-.
-.TR
-.TD
-.FONT CB ".UPPER CASE"
-.TD
-.FONT R "(=" CB ".UC" R ")"
-.TD
-.FONT CB ".LOWER CASE"
-.br
-.FONT R "(" CB ".LC" R ")"
-.
-.
-\" U ==================================================================
-.
-.TR
-.TD
-.FONT CB ".X"
-.TD
-.FONT R "(=" CB ".INDEX" R ")"
-.TD
-.
-.
-.ETB
-.
-.
-.fi
-.hy
-.
-.bp
-.
-.
-.eHDTBL
-.\" end of .de1 TableHDTBL
-.\" --------------------------------------------------------------------
-.
-.
-.\" --------------------------------------------------------------------
-.\" End of macro definitions.
-.\" --------------------------------------------------------------------
-.
-.
-.\" --------------------------------------------------------------------
-.SH DESCRIPTION
-..\" --------------------------------------------------------------------
-.
-.FONT CI RUNOFF
-is a language for creating documents.
-.
-This was the first document language at all.
-.
-It is the ancestor of
-.FONT CI roff R .
-.
-.
-.P
-See section
-.FONT CB "SEE ALSO"
-at the end of this document for internet addresses.
-.
-.
-.\" --------------------------------------------------------------------
-.SH HISTORY
-.\" --------------------------------------------------------------------
-.
-The first text processing language was
-.FONT CI DITTO
-at the
-.FONT CI CTSS
-computer at
-.FONT CI MIT R .
-.
-But now there isn't any documentation about the corresponding programs
-nor files written in the
-.FONT CI DITTO
-language.
-.
-.
-.P
-So
-.FONT CI RUNOFF
-can regarded as the oldest text processing language, because there is
-enough documentation and files written inb this language.
-.
-.
-.P
-.FONT CI RUNOFF
-was built by
-.FONT CI "Jerome H. Saltzer"
-in 1963 and 1964 at
-.FONT CR \%MIT
-using the operating system
-.FONT CR CTSS
-on computers
-.FONT CR "IBM 7090"
-and 
-.FONT CR 7094
-at the
-.FONT CI MIT
-in Boston.
-.
-.
-.P
-At the
-.FONT CI Unix
-operating system, the
-.FONT CI RUNOFF
-language was the base for the generation of the text generator language
-.IR \%roff .
-.
-Today
-.I \%roff
-is maintained by
-.IR \%GNU\~troff ,
-the program 
-.BR \%groff (@MAN1EXT@)
-and its language
-.BR \%groff (@MAN7EXT@).
-.
-So
-.FONT CI RUNOFF
-is the ancestor for
-.IR \%groff .
-.
-.
-.\" --------------------------------------------------------------------
-.SS Old RUNOFF Documentation
-.\" --------------------------------------------------------------------
-.
-Look at section
-.FONT CR "SEE ALSO"
-for the internet connections to these documents.
-.
-.
-.P
-All started at the operating system called
-.I \%CTSS
-in the early 1960s at the
-.IR \%MIT .
-.
-.
-.P
-There was a first documentation in 1964 by
-.FONT CI Saltzer
-who created the
-.FONT CI RUNOFF
-language.
-.
-He published a documentation titled
-.FONT CI "Jerome H. Saltzer \(em TYPSET and RUNOFF, Memorandum editor and \
-type\-out commands" R .
-.
-.
-.P
-In december 1966,
-.FONT CI Saltzer
-published an updated documentation
-.FONT CI "Jerome H. Saltzer \(em Manuscript Typing and Editing" R .
-.
-This article can be regarded as the documentation of the original
-.FONT CI RUNOFF R .
-.
-.
-.P
-Moreover
-.FONT CI Saltzer
-published another document in 1965.
-.
-It's titled
-.FONT CI "Jerome H. Saltzer \(em Experimental Additions to the RUNOFF Command"
-.
-We integrate the
-.I "control words"
-in this documentation in a section about
-.I \%Experimental
-.IR \%Additions .
-.
-.
-.P
-In later years, many people worked with the operating system
-.FONT CI Multics R .
-.
-There
-.FONT CI RUNOFF
-was further developed.
-.
-.
-.P
-There is a good documentation of 1973 titled
-.FONT CI "Larry Barnes \(em RUNOFF: \
-A Program for the Preparation of Documents" R .
-.
-The
-.FONT CI RUNOFF
-was here further developed.
-.
-We use this document as well.
-.
-.
-.P
-Another good document comes from 1974 at the
-.FONT CR "DEC RSTS" R .
-.
-It is titled
-.FONT CI "RUNOFF User's Guide" R .
-.
-It contains the best description of the text lines.
-.
-We are glad to use that.
-.
-.
-.P
-The latest
-.FONT CI RUNOFF
-documentation is file
-.FONT CB RUNOFF.DOC
-from 
-.FONT CR PDP\-11
-at 1981, see
-.FONT CR "SEE ALSO" R .
-.
-The content of this document is also included in this document,
-although it has some errors.
-.
-.
-.P
-There is still more documentation by the
-.FONT CR "DEC PDP\-10 archive" R .
-.
-So far this information is not yet included in this document, but it
-will be done later on.
-.
-.
-.\" --------------------------------------------------------------------
-.SS Early Environment 1963\-66 (CTSS)
-.\" --------------------------------------------------------------------
-.
-.FONT CI Saltzer
-originally worked on
-.IR \%MIT 's
-.I \%CTSS time-sharing operating
-.IR \%system .
-.
-There he had an editor
-.FONT CB TYPSET
-that he also documented in the documentation cited above.
-.
-This editor was an ancestor for
-.BR \%ed (@MAN1EXT@).
-.
-.
-.P
-To use his
-.FONT CI RUNOFF
-language, he programmed a tool that he called
-.FONT CB RUNOFF R .
-.
-.
-.P
-There is still an emulator and the old source files for
-.FONT CB RUNOFF
-and
-.FONT CB TYPSET
-at
-.nh
-.UR http://\:www.cozx.com/\:~dpitts/\:ibm7090.html 
-.FONT CR "IBM 7090 CTSS"
-.UE .
-.hy
-.
-.
-.\" --------------------------------------------------------------------
-.SS The original RUNOFF program 1963-66
-.\" --------------------------------------------------------------------
-.
-The original
-.FONT CB RUNOFF
-program is also documented in the documentation of 1966 above.
-.
-.
-.P
-.FONT CI Saltzer
-uses upper case
-.FONT CB RUNOFF
-to denote his program.
-.
-So we will also use 
-.FONT CB RUNOFF
-to refer to the original program of 1963-66.
-.
-.
-.P
-This program has mainly the task to adjust a printer of that time and
-then print a
-.FONT CI RUNOFF
-document with this configuration.
-.
-Today this does not make much sense, but some parts are still
-available in the options of
-.BR \%groff (@MAN1EXT@),
-but under different names.
-.
-So we will not build this ancient program, but we will document its
-old command line here.
-.
-A lower case program
-.FONT CB runoff
-will be something different.
-.
-.
-.P
-.FONT CB RUNOFF
-is a command used to type out files of the
-.FONT CI RUNOFF
-language in manuscript format.
-.
-.I Control words
-(command names) scattered in the text may be used to provide detailed
-control over the format.
-.
-Input files may be prepared by the context editor
-.FONT CB TYPSET
-which does not exist today.
-.
-.
-.\" --------------------------------------------------------------------
-.SS Usage of RUNOFF Program
-\" --------------------------------------------------------------------
-.
-.SY RUNOFF
-.I \%filespec
-.RI [ "parameter \*[Ellipsis]" ]
-.YS
-.
-.
-.TP
-.I filespec
-is the primary name of a file to be typed out.
-.
-.TP
-.I parameter
-arguments are any number of the following parameters, in any order:
-.
-.
-.RS
-.
-.TP
-.FONT CB STOP
-Pause between pages.
-.
-.
-.TP
-.FONT CB NOWAIT
-Suppress the initial pause to load paper and the pause between pages
-(not necessary today).
-.
-.
-.TP
-.FONT CB PAGE I " n"
-Begin printing with the page numbered
-.IR n .
-.
-.
-.TP
-.FONT CB BALL I " n"
-Typewriter is using printing ball
-.IR n .
-If this parameter is omitted,
-.FONT CB RUNOFF
-assumes that the ball in use will properly print all
-.I CTSS characters
-in the file.
-.
-The number
-.I n
-is engraved on top of the printing ball.
-.
-.I CTSS characters
-not appearing on the ball being used will be printed as blanks, so
-that they may be drawn in.
-.
-This parameter does not make sense in our modern printers.
-.
-.RE
-.
-.
-.\" --------------------------------------------------------------------
-.SH BASIC RUNOFF LANGUAGE OF ALL TIMES
-.\" --------------------------------------------------------------------
-.
-Files written in the
-.FONT CI RUNOFF
-language are similar to modern
-.FONT CI roff
-files.
-.
-.
-.P
-They are both written in text mode.
-.
-So they can be manipulated with text editors like
-.BR emacs (1).
-.
-.
-.P
-In files written in the text languages
-.FONT CI RUNOFF
-or
-.FONT CI roff R ,
-there are command lines and text lines.
-.
-.
-.\" --------------------------------------------------------------------
-.SS Basic Command Lines
-.\" --------------------------------------------------------------------
-.
-All lines beginning with a period (dot)
-.FONT CB .
-are command lines in both languages
-.FONT CI RUNOFF
-and
-.FONT CI roff R .
-.
-The period is followed by the name of the command (1 or 2 words of
-arbitrary length, later one even more words), optionally followed by 1
-or more arguments.
-.
-.
-.P
-The inventor
-.FONT CI Saltzer
-called the command name
-.IR "control word" ,
-but we keep using
-.I command name
-as was done in later times.
-.
-.
-.P
-In
-.FONT CI roff R ,
-lines starting with a single quote
-.FONT CB '
-are also command lines, but that's not true for the
-.FONT CI RUNOFF
-language by default.
-.
-.
-.P
-But in
-.FONT CI RUNOFF R ,
-the period
-.FONT CB .
-at the beginning of a line can be changed into any character.
-.
-This can be done by the command
-.FONT CB ".FLAG CONTROL" R .
-.
-So the starting period is only one possible special character.
-.
-But in this man\-page, we use the period before a command name,
-because it is the default and helps recognizing commands directly.
-.
-.
-.P
-In
-.FONT CI RUNOFF R ,
-the command names were quite long, sometimes consisting even of
-several words.
-.
-This is the same in the
-.FONT CI mom
-language in
-.FONT CI groff R .
-.
-.
-.P
-Moreover, the
-.FONT CI RUNOFF
-commands can be appreviated by defined 2 letters words (or 3 later on).
-.
-Later on, the
-.FONT CI "classical roff"
-languages used only the 2-letter abbreviations as requests; but
-.FONT CI groff
-expanded these to arbitrary length.
-.
-.
-.P
-In
-.FONT CI RUNOFF R ,
-each
-.FONT CI "control word"
-(command name) can be written in upper or lower case.
-.
-That comes from the time where the computers had only upper case input.
-.
-This was not taken into
-.FONT CI roff R ,
-because there were not enough 2-letter requests.
-.
-.
-.P
-In
-.FONT CI RUNOFF R ,
-comments could be appended to a command line, see section
-.FONT CB Comments R .
-.
-.
-.P
-Lines beginning with a period but having unrecognizable format are
-treated as error.
-.
-.
-.P
-No lines beginning with a dot are printed unless the preceding line
-was a
-.I command line
-with control name
-.FONT CB .LITERAL R .
-.
-Then the the line is output or printed as is, special characters are
-output without their special meaning.
-.
-.
-.P
-Abbreviations for command names are normally based on the first two
-letters of a one word command or the first letter of the first two
-words of a multi\-word command.
-.
-Later on 3-letter abbreviations where used for command names of 3
-words.
-.
-.
-.P
-An example of a
-.I "control line"
-(command line) with a single
-.I "control word"
-with 2 arguments is a long name with upper case
-.IP
-.FONT CB .COMMAND I " arg1 arg2"
-.P
-or the same name in lower case
-.IP
-.FONT CB .command I " arg1 arg2"
-.P
-or an abbreviation with upper case
-.IP
-.FONT CB .CO I " arg1 arg2"
-.P
-or the same abbreviation with lower case
-.IP
-.FONT CB .co I " arg1 arg2"
-.
-.
-.P
-Another example of a
-.I "control line"
-(command line) with 2
-.I "control words"
-with 1 argument is a long name with upper case
-.IP
-.FONT CB ".WORD1 WORD2" I " arg"
-.P
-or the same name in lower case
-.IP
-.FONT CB ".word1 word2" I " arg"
-.P
-or an abbreviation with upper case
-.IP
-.FONT CB .WW I " arg"
-.P
-or the same abbreviation in lower case
-.IP
-.FONT CB .ww I " arg"
-.
-.
-.P
-These
-.I "control words"
-were renamed to
-.I requests
-and
-.I macros
-later on in
-.FONT CI roff R .
-.
-.
-In the 1973 document, the words
-.I macros
-and
-.I formats
-are used, but there isn't any documentation for these terms.
-.
-.
-.\" --------------------------------------------------------------------
-.SS Comments
-.\" --------------------------------------------------------------------
-.
-In
-.FONT CI roff R ,
-comments can be included by preceding the special character combination
-.FONT CB \[rs]\[rq] R .
-.
-.
-.P
-That was unknown in
-.FONT CI RUNOFF R .
-.
-There was only 1 method for including comments.
-.
-Command lines could be appended by comments.
-.
-.
-.P
-In the original
-.FONT CI RUNOFF
-language, a comment could be appended after the command arguments
-without using separators.
-.
-For example,
-.RS
-.FONT CB ".cmd1 cmd2 arg1 arg2 This is a comment"
-.RE
-.
-.
-.P
-In the newer
-.FONT CI RUNOFF
-languages (documented in 1974), they preceded the comments in command
-lines by the exclamation point (bang)
-.FONT CB ! R .
-.
-For example,
-.RS
-.FONT CB ".cmd1 cmd2 arg1 arg2 !This is a comment"
-.RE
-.
-.
-.\" --------------------------------------------------------------------
-.SS Basic Text Lines
-.\" --------------------------------------------------------------------
-.
-All lines that are not command lines are text lines in both languages.
-.
-.
-.P
-There are 2 modes of text lines in
-.FONT CI RUNOFF R .
-.
-The newer mode had upper and lower case in the source file.
-.
-This was similar to
-.FONT CI roff R .
-.
-.
-.P
-In the
-.FONT CI CTSS
-computer (early 1960s), there were only upper case input hardware.
-.
-So the
-.FONT CI RUNOFF
-files had only upper case ASCII characters in the original
-.FONT CI RUNOFF
-language.
-.
-.
-.P
-As the printers could print in upper and lower case, there were
-special characters as case-shifters.
-.
-That was also used in late
-.FONT CI RUNOFF
-files.
-.
-This process is very different from
-.FONT CI roff R .
-.
-.
-.P
-In the following sections, only the upper case text lines are documented.
-.
-.
-.P
-In
-.FONT CI RUNOFF
-and
-.FONT CI roff R ,
-there are special character combinations that can change the handling
-of the text.
-.
-But these special characters are totally different in both languages.
-.
-.
-.P
-One or more
-.I blank lines
-are not printed, but mean a
-.IR "line break" .
-.
-This can also be reached by the
-.FONT CB .BREAK
-.IR "control word" .
-.
-.
-.P
-In
-.IR groff ,
-blank lines are printed as lines of their own.
-.
-This is not a paragraph break, because a line is bigger than a
-paragraph break.
-.
-.
-.P
-A text line that starts with one or more space characters means
-.IR "begin a new paragraph" .
-.
-.
-.P
-In
-.IR groff ,
-this will start a new line and inserts the space characters at the
-beginning of the line.
-.
-.
-.\" --------------------------------------------------------------------
-.SS Appending several Lines in RUNOFF
-.\" --------------------------------------------------------------------
-.
-In the 1974 paper, it is documented that a command line can be
-appended by several text or command lines into a single line, each
-being separated by a
-.FONT CI semi-colon
-.FONT CB ; R .
-.
-.
-.P
-If the appended line is a command line, then it starts with a period.
-.
-That's regarded as enough for separation.
-.
-In this case, the separating semi\-colon can be omitted.
-.
-.
-.\" --------------------------------------------------------------------
-.SS Default Conditions (modes) in RUNOFF
-.\" --------------------------------------------------------------------
-.
-The starting case-mode (for output or printing) is lower case.
-.
-Each text line starts with that mode.
-.
-.
-.P
-Usually the text is
-.I filled
-and
-.I justified
-as it is processed.
-.
-That is, the program
-.I fills
-a line by adding successive words from the source text until one more
-word would cause the right margin to be exceeded.
-.
-The line is then
-.I justified
-by making the word spacings larger until the last word in the line
-exactly meets the right margin.
-.
-.
-.P
-The user may occasionally wish to reproduce the source text exactly,
-which is done by disabling
-.I filling
-and
-.I justification
-or by use of the
-.FONT CR .LITERAL
-command.
-.
-The program may be set to
-.I fill
-but not
-.IR justify ,
-in which case the output will be normal except that lines will not be
-justified to the right margin.
-.
-The program may also be set to
-.I justify
-but not
-.IR fill ,
-although this would probably produce peculiar results and is not
-recommended.
-.
-.
-.P
-When the
-.I fill mode
-is on, spaces and carriage returns occurring in the source text are
-treated only as word separators.
-.
-Multiple separators are ignored.
-.
-.
-.P
-Some of the commands cause a BREAK in the output.
-.
-A
-.I break
-means that the current line is output without justification, and the
-next word goes at the beginning of the next line.
-.
-This occurs at the end of paragraphs.
-.
-.
-.P
-The program will advance to new pages as necessary, placing the title
-(if given) and the page number at the top of each page.
-.
-The user may call explicitly for a
-.I page advance
-where desired, and may inhibit the occurrence of a
-.I page advance
-within specified material.
-.
-.
-.P
-By the documentation of 1974 and 1981, some special characters in text
-lines are initially disabled:
-.FONT CB < R " (" CB CAPITALIZE R ),
-.FONT CB > R " (" CB INDEX R ),
-.FONT CB = R " (" CB HYPHENATE R ),
-and
-.FONT CB % R " (" CB OVERSTRIKE R ).
-.
-.
-.P
-The other special characters seem to be enabled by default.
-.
-These should be:
-.FONT CB . R " (" CB CONTROL  R ),
-.FONT CB ! R " (" CB ENDFOOTNOTE R ),
-.FONT CB ^ R " (" CB UPPERCASE R ),
-.FONT CB \[rs] R " (" CB LOWERCASE R ),
-.FONT CB & R " (" CB UNDERLINE R ),
-.FONT CB # R " (" CB SPACE R ),
-and
-.FONT CB _ R " (" CB QUOTE R ).
-.
-.
-.P
-This can be changed by the commands
-.RS
-.FONT CB .FLAGS I " <mode>"
-.RE
-(enabling) and
-.RS
-.FONT CB ".NO FLAGS" I " <mode>"
-.RE
-(disabling).
-.
-Also, each special character can be set to another character by the
-.RS
-.FONT CB .FLAGS I " <mode> <some_character>"
-.RE
-command.
-.
-.
-.P
-The following informs about the
-.I <mode>
-arguments:
-.
-.
-.TP
-.FONT CB CONTROL
-default:
-.FONT CI period
-on first column (start command line):
-.FONT CB .
-.
-.TP
-.FONT CB ENDFOOTNOTE
-default:
-.FONT CI "exclamation character"
-on first column (end of footnote):
-.FONT CB !
-.
-.TP
-.FONT CB UPPERCASE
-upper case (single character) and case lock (2 characters), default:
-.FONT CB ^
-.
-.TP
-.FONT CB LOWERCASE
-lower case (single character) and case lock (2 characters), default:
-.FONT CB \[rs]
-.
-.TP
-.FONT CB UNDERLINE
-underlining word witout spaces, default:
-.FONT CB &
-.
-.TP
-.FONT CB SPACE
-quoted space (no filling and justifying), default:
-.FONT CB #
-.
-.TP
-.FONT CB QUOTE
-quoting character (output special character without specialization),
-default:
-.FONT CB _
-.
-.TP
-.FONT CB CAPITALIZE
-upper case for next character, default:
-.FONT CB <
-.
-.TP
-.FONT CB INDEX
-set following word into index, default:
-.FONT CB >
-.
-.TP
-.FONT CB OVERSTRIKE
-superimpose the surrounding characters, default:
-.FONT CB %
-.
-.TP
-.FONT CB HYPHENATE
-default:
-.FONT CB =
-.
-.TP
-.FONT CB ALL
-all but the 1st column characters
-.FONT CB .
-and
-.FONT CB !
-.
-.TP
-.FONT CB null
-same as
-.FONT CB ALL
-.
-.
-.P
-The following special characters are only documented in 1981, but it
-is not clear if they are initially enabled.
-.
-Also no
-.I <mode>
-for
-.FONT CB .FLAGS
-are documented:
-.FONT CB { R ,
-.FONT CB } R ,
-.FONT CB | R ,
-and
-.FONT CB Ctrl-N R .
-.
-.
-.P
-.FONT CI RUNOFF R 's
-ability to change most special characters is unique.
-.
-.FONT CI roff
-cannot do that.
-.
-.
-.\" --------------------------------------------------------------------
-.SH UPPER CASE TEXT LINES
-.\" --------------------------------------------------------------------
-.
-The original
-.FONT CI RUNOFF
-text lines are different from the
-.FONT CI roff
-language.
-.
-.
-.P
-As the early
-.FONT CI CTSS
-computers could only produce upper case characters as input, the text
-lines look very strange today.
-.
-This wasn't documented in the documentation of the 1960s.
-.
-But there are good documentations of 1974 and 1981 which contain also
-the old style.
-.
-.
-.\" --------------------------------------------------------------------
-.SS Case Changing of Text Lines
-.\" --------------------------------------------------------------------
-.
-In this section, the specification of case for files prepared on an
-upper case terminal is documented.
-.
-There are special characters that in printing act as case-shifters for
-ASCII characters into lower (ASCII code 97 to 122 decimal) or upper
-case (ASCII code 65 to 90 decimal).
-.
-.
-.P
-The lower case mode seems to be the default mode.
-.
-Also, according to existing old
-.FONT CI RUNOFF
-files, each text line starts with this default mode.
-.
-.
-.TP
-.FONT CI "single circumflex " CB ^
-The following ASCII character is shifted to
-.FONT CI "upper case" R .
-.
-The following from the document of 1981 seems to be wrong:
-.
-(It is also used to lock the
-.I case mode
-in
-.IR "upper case" ,
-and the
-.I underline mode
-to
-.UL "underline all text" ).
-
-.
-.
-.TP
-.FONT CI "single back\-slash " CB \[rs]
-The following ASCII character is shifted into lower case.
-.
-The following from the document of 1981 seems to be wrong:
-.
-(It is also used to lock the
-.I case mode
-in
-.IR "lower case" ,
-and disable underlining.)
-.
-.
-.TP
-.FONT CI "double circumflex " CB ^^
-The case mode is shifted into upper case.
-.
-.
-.TP
-.FONT CI "double back\-slash " CB \[rs]\[rs]
-The case mode is shifted into lower case.
-.
-.
-.P
-A common example with starting mode in lower case for these 4 special
-characters is:
-.
-.P
-.RS
-^HERE IS A ^SAMPLE ^SENTENCE IN ^^UPPER CASE\\ AND LOWER CASE.
-.RE
-.
-.P
-is printed as:
-.
-.RS
-Here is a Sample Sentence in UPPER CASE and lower case.
-.RE
-.
-.
-.\" --------------------------------------------------------------------
-.SS Further special Characters in Text Lines
-.\" --------------------------------------------------------------------
-.
-.TP
-.FONT CI "ampersand " CB &
-This is used for underscoring the next following character.
-.
-For example:
-.
-.RS
-.P
-.RS
-&s&o&f&t&w&a&r&e
-.RE
-.
-.P
-becomes:
-.RS
-.UL software
-.RE
-.
-.P
-in the output or printing.
-.RE
-.
-.
-.TP
-.FONT CI "circumflex and ampersand " CB ^&
-This is used for underscoring all following characters except for
-blanks.
-.
-One could say that by this character combination the underline mode is
-put on.
-.
-.
-.TP
-.FONT CI "back\-slash and ampersand " CB \[rs]&
-This is used for stopping the underscoring.
-.
-One could say that by this character combination the underline mode is
-put off.
-.
-.
-.RS
-.P
-For example:
-.RS
-^&PLATO\[rs]& was a very ^&wise \[rs]&man.
-.RE
-becomes
-.RS
-.UL PLATO
-was a very
-.UL wise
-man.
-.RE
-.
-.
-.P
-In
-.FONT CI groff R ,
-spaces are not underlined as well.
-.
-.RE
-.
-.
-.TP
-.FONT CI "number sign " CB #
-.FONT CI RUNOFF 
-interprets this character as a
-.FONT CI "quoted space" R .
-.
-It outputs exactly 1 space character, it is not justified or filled.
-.
-It cannot end a line.
-.
-In the text it is not treated as a
-.IR "word separator" .
-.
-.
-.TP
-.FONT CI "less\-than " CB <
-This character preceding a word capitalizes the entire word up to the
-first space character.
-.
-This is the same as preceding the word with
-.FONT CB ^^
-and ending it with
-.FONT CB \[rs]\[rs] R .
-.
-For example, if the current case mode is lower case, the following
-text line
-.RS
-.RS
-.FONT CB "<DIGITAL OF ^MAYNARD, <MA"
-.RE
-becomes
-.RS
-.FONT CB "DIGITAL of Maynard, MA"
-.RE
-in the output (printing).
-.
-This special character is initially disabled.
-.
-It can be activated by the command
-.FONT CB .FLAGS R .
-.
-.RE
-.
-.
-.TP
-.FONT CI "greater\-than " CB >
-This character enters the immediately following word (up to the first
-space character) into the index, including all case shifters in the
-word.
-.
-This special character is initially disabled.
-.
-It can be enabled by the command
-.FONT CB .FLAGS R .
-.
-.
-.TP
-.FONT CI "percent " CB %
-This is for
-.FONT CI superimposition
-of the surrounding characters, one character over the other.
-.
-For example, the combination
-.FONT CB /%=
-overstrikes the 2 characters
-.FONT CI slash
-and
-.FONT CI equal
-into the character
-.FONT CB \[!=]
-(unequal).
-.
-In underlining, superimposition cannot be done.
-.
-This special character is initially disabled.
-.
-So a percent character is output as is.
-.
-This character can be enabled by the command
-.FONT CB .FLAGS R .
-.
-.
-.\" --------------------------------------------------------------------
-.SS Special Characters in Text Lines of 1981
-.\" --------------------------------------------------------------------
-.
-.TP
-.FONT CB = CI " equals\-sign " I  "\[em] hypenation disable"
-If
-.FONT CB ".FLAGS HYPHENATE"
-has been engaged, the
-.I equals
-character
-.FONT CB =
-used to disable
-.I hyphenation
-for the word it precedes.
-.
-.
-.TP
-.FONT CB { CI " left\-brace " I "\[em] Reverse half\-linefeed"
-If the output device type is no
-.FONT CB N R ,
-then the
-.I left
-and
-.I right braces
-are used for
-.I superscripting
-and
-.IR subscripting .
-.
-The
-.I left\-brace
-.FONT R ( CB { CR " 173 octal" R )
-produces a
-.IR "reverse half\-linefeed" .
-When combined with the
-.I right brace
-.FONT R ( CB } CR " 175 octal" R )
-scripting is created; e.g.
-.FONT CB {super}
-becomes
-.EQ
-"" sup superscript
-.EN
-and
-.FONT CB }sub{
-becomes
-.EQ
-"" sub subscript
-.EN
-.
-.
-.TP
-.FONT CB } CR " right\-brace " I "forward half\-linefeed"
-As described above, the
-.I right brace
-.FONT R ( CB } CR " 175 octal" R )
-when coupled with the
-.I left brace
-will produce scripting.
-.
-This will only occur when a scripting output device is selected.
-.
-.
-.TP
-.FONT CB | CR " vertical\-bar " I "Engage/disengage alternate character set"
-The
-.I vertical bar
-.FONT R ( CB | R , CR " 174 octal" R )
-acts as an on/off switch.
-.
-It will alternately transmit a
-.I shift\-out
-and a
-.I shift\-in
-character to change the selected character set; e.g.
-.FONT CB |ABC|
-becomes
-.FONT CI Ctrl\-N CB ABC CI Ctrl\-O R .
-.
-.
-.\" --------------------------------------------------------------------
-.SS Escape Sequences in Text Lines
-.\" --------------------------------------------------------------------
-.
-The
-.FONT CI "escape character"
-in
-.FONT CI RUNOFF
-(also called
-.FONT CI "quote character" R )
-is the
-.FONT CI "sub character " CB _ R .
-.
-Using this character as a prefix before a special character, outputs
-the special character as it is without its speciality, no formatting
-is done by it.
-.
-.
-.TP
-.FONT CB _^
-outputs the special character
-.FONT CB ^
-.
-.
-.TP
-.FONT CB _\[rs]
-outputs the special character
-.FONT CB \[rs]
-.
-.
-.TP
-.FONT CB _&
-outputs the special character
-.FONT CB &
-.
-.
-.TP
-.FONT CB _#
-outputs the special character
-.FONT CB #
-.
-.
-.TP
-.FONT CB _<
-outputs the special character
-.FONT CB <
-.
-.
-.TP
-.FONT CB _>
-outputs the special character
-.FONT CB >
-.
-.
-.TP
-.FONT CB _%
-outputs the special character
-.FONT CB %
-.
-.
-.TP
-.FONT CB __
-outputs the special character
-.FONT CB _
-.
-.
-.\" --------------------------------------------------------------------
-.SH COMMAND NAMES (CONTROL WORDS) IN THE ORIGINAL RUNOFF LANGUAGE OF 1966
-.\" --------------------------------------------------------------------
-.
-The documentation for
-.I "control words"
-in this paragraph are taken from the
-.FONT CI RUNOFF
-documentation of 1966.
-.
-Often this documentation refers to the
-.FONT CB RUNOFF
-program that doesn't exist any more.
-.
-When the
-.FONT CI RUNOFF
-language will be implemented for
-.BR \%groff (@MAN1EXT@)
-these documentations must be adjusted.
-.
-.
-.TP
-.FONT CB .ADJUST
-.TQ
-.FONT CB .AD
-Enable
-.I fill
-mode.
-.
-The next line is the first one affected.
-.
-This is the default mode.
-.
-.
-.TP
-.FONT CB .APPEND I " file"
-.TQ
-.FONT CB .AP I " file"
-Take as the next input line the first line of
-.IR \%file .
-.
-Note that the whole of 
-.I \%file
-is appended, and that the appending is an irreversible process \[em] that
-is, once
-.FONT CB RUNOFF
-encounters the
-.FONT CB .APPEND
-.I "control line"
-it will switch to the file
-.I \%file
-and continue from the first line of
-.IR \%file .
-.
-All lines following the
-.FONT CB .APPEND
-.I "control line"
-will not be processed by
-.FONT CB RUNOFF R .
-.
-The file
-.I \%file
-may, of course, itself call for appending of still another file, and
-so on.
-.
-.
-.TP
-.FONT CB ".BEGIN PAGE"
-.TQ
-.FONT CB .BP
-Print out this page, start next line on a new page.
-.
-.
-.TP
-.FONT CB .BREAK
-.TQ
-.FONT CB .BR
-The lines before and after the
-.FONT CB .BREAK
-.I "control word"
-will not be run together by the
-.FONT CI fill
-mode of operation.
-.
-.
-.TP
-.FONT CB .CENTER
-.TQ
-.FONT CB .CD
-The following line is to be centered between the left and right
-margins.
-.
-.
-.TP
-.FONT CB ".DOUBLE SPACE"
-.TQ
-.FONT CB .DS
-Copy is to be double spaced.
-.
-This mode  takes  effect after the next line.
-.
-.
-.TP
-.FONT CB .FILL
-.TQ
-.FONT CB .FI
-Enable
-.IR "fill mode" .
-.
-That means: Lengthen short lines by moving words from the following
-line; trim long lines by moving words to the following line.
-.
-This is the default mode.
-.
-.FONT CB .NOFILL
-disables the
-.I fill
-mode.
-.
-.
-.TP
-.FONT CB .HEADER I " word1 word2 \*[Ellipsis]"
-.TQ
-.FONT CB .HE I " word1 word2 \*[Ellipsis]"
-All of the line after the first blank is used as a header line, and
-appears at the top of each page, along with the page number, if
-specified.
-.
-.
-.TP
-.FONT CB ".HEADING MODE" I " arg"
-.TQ
-.FONT CB .HM I " arg"
-This
-.I control sequence
-alters the mode of the running head to that specified by the parameter
-.IR \%arg .
-.
-Any of the following parameters are allowed for
-.IR \%arg:
-.
-.
-.\"  --------------------------------------------------------------------
-.RS
-.
-.
-.TP
-.FONT CB CENTER
-The header will be centered on the page.
-.
-.
-.TP
-.FONT CB MARGIN
-The header will be adjusted against the right margin of the page.
-.
-.
-.TP
-.FONT CB FACING
-On even\-numbered pages, the header will be adjusted against the left
-margin, on odd numbered pages against the right.
-.
-.
-.TP
-.FONT CB OPPOSED
-The header will be adjusted against the opposite margin from the page
-number.
-.
-In the absence of a
-.FONT CB ".HEADING MODE"
-.IR "control sequence" ,
-the default option is
-.FONT CB OPPOSED R .
-.
-.
-.RE
-.\"  --------------------------------------------------------------------
-.
-.
-.TP
-.FONT CB .INDENT I " n"
-.TQ
-.FONT CB .IN I " n"
-The argument
-.I \%n
-is a number.
-.
-Set the number of spaces to be inserted at the beginning of each line
-to
-.IR \%n .
-.
-Indent is preset to 0.
-.
-.
-.TP
-.FONT CB ".LINE LENGTH" I " n"
-.TQ
-.FONT CB .LL I " n"
-The argument
-.I \%n
-is a positive number.
-.
-Set the line length to
-.IR \%n .
-.
-The line length is preset to 60.
-.
-.
-.TP
-.FONT CB .LITERAL
-.TQ
-.FONT CB .LI
-The following line is not a
-.IR "control word" ,
-despite the fact that it begins with a period.
-.
-.
-.TP
-.FONT CB .NOFILL
-.TQ
-.FONT CB .NF
-Disable
-.IR "fill mode" .
-.
-That means: Print all lines exactly as they appear without right
-adjustment or filling out.
-.
-In
-.I NOFILL
-mode each input line produces one output line; further blank lines are
-output in this mode.
-.
-Use the
-.FONT CB .FILL
-.I control word
-to restart
-.IR filling .
-.
-.
-.TP
-.FONT CB .NOJUST
-.TQ
-.FONT CB .NJ
-Disable
-.IR "fill mode" .
-.
-.
-.TP
-.FONT CB ".ODD PAGE"
-.TQ
-.FONT CB .OP
-This
-.I "control word"
-causes the current page to be printed out, and the next page to be
-numbered with the next higher odd page number.
-.
-.
-.TP
-.FONT CB .PAGE R " [" I n R ]
-.TQ
-.FONT CB .PA R " [" I n R ]
-Print page numbers.
-.
-(The first page is not given a page number.
-.
-It has instead a two\-inch top margin.
-.
-See also
-.FONT CB "Manuscript Conventions" R ,
-below.)
-.
-If argument
-.I \%n
-is present, insert a page break and number the next page
-.IR \%n .
-Note that
-.FONT CB RUNOFF
-does not output or print completely empty pages.
-.
-.
-.TP
-.FONT CB ".PAGING MODE" I " arg1 arg2 \*[Ellipsis]"
-.TQ
-.FONT CB .PM I " arg1 arg2 \*[Ellipsis]"
-This
-.I control sequence
-alters the mode of page numbering to that specified by the arguments.
-.
-The arguments may be in any order, and must be selected from the
-following list:
-.
-.
-.\"  --------------------------------------------------------------------
-.RS
-.
-.
-.TP
-.FONT CB MARGIN
-Page numbers will be adjusted against the right margin.
-.
-.
-.TP
-.FONT CB FACING
-Odd page numbers are adjusted against the right margin, even page
-numbers are adjusted against the left margin.
-.
-.
-.TP
-.FONT CB CENTER
-Page numbers are centered between the right and left margin.
-.
-.
-.TP
-.FONT CB TOP
-Page numbers are placed on the fourth line from the top of the page.
-.
-.
-.TP
-.FONT CB BOTTOM
-Page numbers are placed on the fourth line from the bottom of the
-page.
-.
-.
-.TP
-.FONT CB OFF
-Page numbers are discontinued.
-.
-.
-.TP
-.FONT CB PREFIX I " \(dqstring\(dq"
-The string of characters between quotation marks is prefixed to the
-page number.
-.
-The quotation marks may be next to each other, in which case no prefix
-is used.
-.
-.
-.TP
-.FONT CB ROMANU
-Page numbers will be printed in upper case Roman numerals.
-.
-.
-.TP
-.FONT CB ROMANL
-Page numbers will be printed in lower case Roman numerals.
-.
-.
-.TP
-.FONT CB ARABIC
-Page numbers will be printed in Arabic.  (This is the normal mode.)
-.
-.
-.TP
-.FONT CB SET I " n"
-Set the next page number to be the positive number
-.IR \%n .
-.
-.
-.TP
-.FONT CB SKIP I " n"
-Skip
-.I \%n
-page numbers.
-.
-.
-.P
-If in a single use of
-.FONT CB ".PAGING MODE"
-several arguments specify competing functions, the last one specified
-takes precedence.
-.
-When the
-.FONT CB ".PAGING MODE"
-sequence appears in text at point A, all text up to A (and probably
-some text after A) will appear on a page controlled by the previous
-paging mode.
-.
-The new
-.I paging mode
-will take effect on the next page.
-.
-Then there is no danger of getting page numbers both at the top and
-bottom of the same page.
-.
-.
-.P
-Use of the
-.FONT CB .TOP
-parameter may conflict with the
-.I \%heading
-.IR \%mode .
-.
-If a heading and a page number should be printed in the same column,
-the page number will take precedence.
-.
-In the absence of a
-.FONT CB ".PAGING MODE"
-.I control
-.IR sequence ,
-the default options are:
-.FONT CB "TOP MARGIN PREFIX \(dqPAGE\(dq" R .
-.
-.
-.RE
-.\"  --------------------------------------------------------------------
-.
-.
-.TP
-.FONT CB ".PAPER LENGTH" I " n"
-.TQ
-.FONT CB .PL I " n"
-This
-.I control word
-is used for running off a documentation file on non\-standard paper.
-.
-The number
-.I \%n
-is a line count, figured at 6 lines per inch.
-.
-If this
-.I control word
-is not given,
-.I n
-is assumed to be 66, for 11\-inch paper.
-.
-.
-.TP
-.FONT CB ".SINGLE SPACE"
-.TQ
-.FONT CB .SS
-Copy is to be single spaced.
-.
-This mode takes effect after the next line.
-.
-(The normal mode is single space.)
-.
-.
-.TP
-.FONT CB .SPACE R " [" I n R ]
-.TQ
-.FONT CB .SP  R " [" I n R ]
-Insert
-.I \%n
-vertical spaces (carriage returns) in the copy.
-.
-If
-.I \%n
-carries spacing to the bottom of a page, spacing is stopped.
-.
-If
-.I \%n
-is absent or 0, one space is inserted.
-.
-.
-.TP
-.FONT CB .UNDENT I " n"
-.TQ
-.FONT CB .UN I " n"
-In an indented region, this
-.I control word
-causes a break, and the next line only will be indented n spaces fewer
-than usual.
-.
-This
-.I "control word"
-is useful for typing indented numbered paragraphs.
-.
-.
-.\" --------------------------------------------------------------------
-.SH RUNOFF ADDITIONS 1973
-.\" --------------------------------------------------------------------
-.
-Here are described only the additional
-.I control words
-that are documented in the 1973 documentation.
-.
-.\" --------------------------------------------------------------------
-.SS Formats
-.\" --------------------------------------------------------------------
-.
-.
-.TP
-.FONT CB .FORMAT I " name"
-This command causes subsequent text to be output under the control of
-tne specified format (see below at
-.FONT CB ".DEFINE FORMAT" R ).
-.
-Each following logical line will be fit into the format until a
-.FONT CB .FILL
-or
-.FONT CB .NOFILL
-command 1s encountered.
-.
-.
-.TP
-.FONT CB ".DEFINE FORMAT" I " <name> <pos> <field_ definition> \
-\*[Ellipsis]"
-.TQ
-.FONT CB ".END FORMAT"
-These commands define a format for use in producing tables, etc.
-.
-.
-.RS
-.
-.
-.TP
-.I <name>
-identifies the format.
-.
-It can be activated by the
-.FONT CB .FORMAT
-.IR command .
-.
-.
-.TP
-.I <pos>
-is the position and may be one of
-.FONT CB .LEFT R ,
-.FONT CB .RIGHT R ,
-or
-.FONT CB .CENTER R ,
-and determines the overall positlon of the format with respect to the
-margins.
-.
-.
-.TP
-.I <field_definition>
-There can be several arguments of this type.
-.
-Each has the form:
-.
-.
-.RS
-.
-.FONT CI <type> CB ( CI "<letter> \*[Ellipsis] <letter>" CB )
-.
-.P
-where the
-.FONT CI <type>
-is one of
-.
-.TP
-.FONT CB L
-for left,
-.
-.TP
-.FONT CB R
-for riqht,
-.
-.TP
-.FONT CB C
-for center,
-.
-.TP
-.FONT CB F
-for
-.FONT CI fill R ,
-or
-.FONT CB J
-for
-.FONT CI justify R .
-.
-.
-.P
-The first three types define fixed fields; the text to be formatted
-must fit within the allocated space.
-.
-The latter types define variable fields; the text will be handled as
-in normal fill mode processing.
-.
-.
-.P
-A picture showing the manner in which text should be output follows
-the
-.FONT CB ".DEFINE FORMAT"
-command; following the picture should be an
-.FONT CB ".END FORMAT"
-command.
-.
-The following lines give an example:
-.
-.
-.RS
-.  ft CB
-.  nf
-.  nh
-.    nop ".DEFINE FORMAT SUMMARY L(A) F(C) C(B)"
-.    nop "AAAA	CCCCCCCCCCCCCCCCCCCCCCCCC	BBBBBBB"
-.    nop "	CCCCCCCCCCCCCCCCCCCCCCCCC		"
-.    nop ".END FORMAT"
-.  hy
-.  fi
-.  ft
-.RE
-.
-.
-.P
-The first field of text is left justified; the second is centered; the
-third is subjected to
-.I fill mode
-processing without justification.
-.
-After the first line of output is generated using this format, all
-subsequent lines are produced using the last picture 1ine.
-.
-(Strictly speaking the third line is unnecessary.)
-.
-.
-.P
-Text for formatted processing consists of a logical line (or
-paragraph).
-.
-Each field except the last must be separated by
-.IR tab .
-.
-The
-.I tab character
-is displayed here as backslash character
-.FONT R ( CB \[rs] R ).
-.
-.
-.P
-The first field of text is
-.FONT CB A R ,
-the second
-.FONT CB B R ,
-etc.
-.
-Typical input for our example might be:
-.
-.
-.RS
-.nf
-.nh
-|A\\YES\\/THIS IS SOME TEXT
-TO BE FILLED.
-.hy
-.fi
-.RE
-.
-.
-.P
-The characters 1n the picture lines were 1nterpreted as follows.
-.
-Contiguous sequences of letters determine the fie1d positions;
-non\-alphabetic characters are output literally.
-.
-(Note:
-.FONT CB Q.QQ
-wi11 not work, put the period
-.RB \[dq] . \[dq]
-in the text.
-.
-A sequence of characters written between double quotes is considered
-literal text.
-.
-The
-.I double quotes
-are not output, and there is no way to use
-.I double quote
-as a
-.IR literal .
-.
-.
-.\" --------------------------------------------------------------------
-.SS Hyphenation Processing
-.\" --------------------------------------------------------------------
-.
-.TP
-.FONT CB .HYPHENATE
-Enable
-.IR "hyphenation mode" .
-.
-This is the default when starting up.
-.
-The
-.FONT CB RUNOFF
-program used a small
-.I glossary
-for splitting.
-.
-In
-.I hyphenation mode
-.FONT CB RUNOFF
-would try to find a word 1n the glossary which is the same (except for
-the endings
-.FONT CB \-S R ,
-.FONT CB \-ES R ,
-.FONT CB \-ED R ,
-and
-.FONT CB \-E R )
-as the word at the end of the line of text.
-.
-When running in
-.BR groff (1)
-there are
-.I glossaries
-being much more complete than in
-.BR RUNOFF .
-.
-.
-.TP
-.FONT CB .NOHYPHEN
-Disable
-.IR "hyphenation mode" .
-.
-.
-.TP
-.FONT CB .GLOSSARY I " word"
-This command inserts words into the
-.I glossary
-for use in
-.IR hyphenation .
-.
-Each word should have the form
-.FONT CB hy\[hy]phen\[hy]ate
-and be separated by spaces.
-.
-.
-.TP
-.FONT CB ".HYPHENATION BREAK" I " n"
-This command set the parameter which determines the allowable number
-of spaces to te inserted in a line before
-.FONT CB RUNOFF
-tried to hyphenate the last word.
-.
-Each space counts ten points.
-.
-If more than
-.I n
-points per word would have to be inserted, then
-.I hyphenation
-will be attempted.
-.
-The initial setting of this parameter is 5 (one\-half space per word).
-.
-.
-.\" --------------------------------------------------------------------
-.SS Margin Controls
-.\" --------------------------------------------------------------------
-.
-There are two types of margins involved in
-.FONT CI RUNOFF R .
-.
-.
-.TP
-(1)
-The physical margins.
-.
-These are determined by the nature of the printing device.
-.
-The margins outline the area where it is physically possible to print
-characters.
-.
-.
-.TP
-(2)
-.
-The logical margins.
-.
-These can be set bv the user as he wishes.
-.
-(Limits are imposed by the physical margins.)
-.
-They are initialized for standard 8.5\[dq] by 11\[dq] printing.
-.
-.
-.P
-Commands concerning vertical and horizontal margins are:
-.
-.
-.TP
-.FONT CB ".PAGE LAYOUT TM, EM, TOL"
-This sets the vertical logical margins and vertical tolerence.
-.
-Parameters are top margin, bottom margin and tolerance.
-.
-The tolerance is used to determine where to break between pages on
-page overflows.
-.
-If
-there is a line break within
-.I TCL lines
-of the bottom,
-.FONT CB RUNOFF
-will break the page there; otherwise it will fill the page completely.
-.
-.
-.TP
-.FONT CB ".LINE LAYOUT LM, RM, NO, CS"
-This sets the logical left and right margin, the number of columns,
-and the number of spaces to insert between columns.
-.
-These margins are used for the page headings.
-.
-To adjust the relative
-text position, use the subsequent commands.
-.
-.
-.TP
-.FONT CB ".REDUCE MARGIN LM, RM"
-.TQ
-.FONT CB ".EXPAND MARGIN LM, RM"
-.TQ
-.FONT CB ".END REDUCTION"
-These commands enable the user to indent a certain portion of his text
-using the first command, or
-.FONT CB .UNDENT
-his text using the second command.
-.
-In either case the original margins are restored by the third command.
-.
-The use of several
-.FONT CB ".REDUCE MARGIN"
-commends before the corresponding
-.FONT CB ".END REDUCTION"
-commands succesively indents the text more, and more.
-.
-Thus these commands are 1ike brackets (i.e. recursive).
-.
-.FONT CB LM
-is added to the left logical margin and
-.FONT CB RM
-is subtracted from the right logical margin in the first command.
-.
-Just
-the opposite is done on the second command.
-.
-Negative numbers are permitted.
-.
-These commands do not effect the position of page headings.
-.
-.
-.TP
-.FONT CB ".LAYOUT PLM, PRM, PTM, PBM, LL, LO"
-This command defines the physical margins in the followinq complex
-manner.
-.
-(It should only be used for non\-standard devices, normally this
-command should not be necessary.)
-.
-The parameters are the physical left margin (in spaces), the physical
-right margin, the physical top 1ine, the physical bottom line, the
-line lenqth, and line origin.
-.
-The first four parameters define the physical 1imits of the printing
-device.
-.
-The final two parameters define the length of the logical line and its
-origin with respect to the left edge of the paper.
-.
-Printing starts at column
-.FONT CB "LO + LM" R ,
-and ends at
-.FONT CB "LO + RM" R ,
-where
-.FONT CB LM
-and
-.FONT CB RM
-are the logical margins established by
-.FONT CB ".LINE LAYOUT" R .
-.
-When using the
-.FONT CI "facing feature"
-(see
-.FONT CB ".PAGING MODE" R ),
-the logical left margin is
-.FONT CB "LL \[em] RM"
-on even pages, and the right margin is
-.
-.FONT CB "LL \[em] LM" R .
-.
-The parameters for the layout command must satisfy:
-.
-.RS
-.RS
-.nh
-.nf
-.ft CB
-.nop "min(LO + LL \[em] PLM, PRM \[em] LO) > max(PLM \[em] LO, \
-LO + LL \[em] PRM)\f[],\f[CB]"
-.nop LL > 25\f[], and \f[CB]PBM \[em] PTM > 6\f[]
-.fi
-.hy
-.RE
-.
-.
-.P
-This command sets
-.FONT CB LM
-to 15,
-.FONT CB RM
-to
-.FONT CB "LL \[em] 10" R ,
-.FONT CB TM
-to
-.FONT CB PTM R ,
-and
-.cb BM
-to
-.FONT CB "PBM \[em] 6" R .
-.
-(These margin settings produce the standard 1.5 inch left, and 1 inch
-right, too, and bottom margins.)
-.
-.RE
-.
-.
-.P
-Initially
-.FONT CB RUNOFF
-sets the margins for
-.I teletype
-output to:
-.
-.
-.RS
-.RS
-.nh
-.nf
-.ft CB
-.nop .LAYOUT 6, 89, 6, 66, 8S, 0
-.nop .LINE LAYOUT 15, 75
-.nop .FILL
-.ft
-.fi
-.hy
-.RE
-.RE
-.
-.
-.P
-The printer layout is:
-.
-.RS
-.RS
-.nh
-.nf
-.ft CB
-.nop ".layout 5, 137, 6, 66, 85, 15"
-.nop ".page layout 6, 60, 4"
-.ft
-.fi
-.hy
-.RE
-.RE
-.
-.P
-The logical margins must satisfy:
-.
-.RS
-.RS
-.nh
-.nf
-.ft CB
-.nop min(LL, PRM \[em] LO, LO \[em] LL \[em] PLM) >= RM >
-.nop "     LM >= max(0, PLM \[em] LO, LO + LL \[em] PRM)" \f[],\f[CB]
-.nop "PBM >= BM > TM >= PTM" "\f[], and\f[CB]"
-.nop BM \[em] TM > TOL\f[].
-.fi
-.hy
-.RE
-.RE
-.
-.
-.\" --------------------------------------------------------------------
-.SS Paragraph Formatting
-.\" --------------------------------------------------------------------
-.
-.TP
-.FONT CB ".PARAGRAPH SPACING" I " n"
-.
-This specifies how many lines are to be inserted between paragraphs.
-.
-Initial setting = 1.
-.
-.
-.TP
-.FONT CB ".PARAGRAPH INDENTATION" I " n"
-This specifies how many additional spaces to insert at the beginning
-of a paragraph.
-.
-Initial setting = 5.
-.
-.
-.TP
-.FONT CB ".PARAGRAPH UNDENTATION" I " n"
-This command is the same as
-.FONT CB ".PARAGRAPH INDENTATION" I " \-n" R .
-.
-That is,
-.I n
-fewer spaces are inserted at the beginning of the paragraph.
-.
-.
-.\" --------------------------------------------------------------------
-.SS Special Line Justification and Control
-.\" --------------------------------------------------------------------
-.
-These commands pertain to the next logical line.
-.
-The end of the line should be designated with a break.
-.
-.
-.TP
-.FONT CB .CENTER
-.
-Center the next line.
-.
-.
-.TP
-.FONT CB .INDENT I " n"
-.
-Indent the next line
-.I n
-spaces.
-.
-If
-.I n
-is not provided, 5 is assumed.
-.
-.
-.TP
-.FONT CB .UNDENT I " n"
-.
-Start the next line
-.I n
-spaces to the left of the normal margin.
-.
-This command is the same as
-.FONT CB .INDENT I " \-n" R .
-.
-.
-.TP
-.FONT CB .MARGIN
-Justify the next 1ine against the right hand margin.
-.
-.
-.\" --------------------------------------------------------------------
-.SS Heading and Paging
-.\" --------------------------------------------------------------------
-.
-.TP
-.FONT CB .HEADER I " XXXXXXX"
-.FONT CB RUNOFF
-accepts a heading to go on the first line of
-each paqe.
-.
-The heading strinq is assured to start at the first non\-blank
-character after thd control word and end at carriage return.
-.
-.
-.TP
-.FONT CB ".HEADING MODE" I " <param>"
-.I <param>
-determines the position of the heading on the 11ne.
-.
-.I <param>
-may be any of the following.
-.
-.
-.RS
-.
-.TP
-.FONT CB CENTER
-The header will be centered on the 1ine.
-.
-.
-.TP
-.FONT CB MARGIN
-The header will be adjusted against the riqht margin.
-.
-.
-.TP
-.FONT CB PAGING
-On even numbered pages the header is adjusted against the right
-margin.
-.
-On odd pages it is adjusted against the left mergin.
-.
-.
-.TP
-.FONT CB OPPOSED
-The header will be adjusted against the opposite margin from the
-page numter.
-.
-This is the initial mode.
-.
-.RE
-.
-.
-.TP
-.FONT CB ".PAGING MODE" I " <param>"
-.
-This command determines the placing of the page number.
-.
-All parameters are optional.
-.I <param>
-may be anyone or more of the following oommands.
-.
-In case of conflict the latest command wins.
-.
-.RS
-.
-.TP
-.FONT CB CENTER
-The page numbers are centered between the logical margins.
-.
-.TP
-.FONT CB MARGIN
-The page number is adjusted against the right margin.
-.
-.TP
-.FONT CB FACING
-On even numbered pages the number will be adjusted against the right
-margin.
-.
-On odd numbered pages tne number will be adjusted against the
-left margin.
-.
-.TP
-.FONT CB TOP
-Page numbers are placed on the first line.
-.
-.TP
-.FONT CB BOTTOM
-Page numbers are placed on the last line.
-.
-.TP
-.FONT CB OFF
-Printing page numbers is discontinued.
-.
-.TP
-.FONT CB .PREFIX I " <string>"
-.TQ
-.FONT CB .SECTION I " <string>"
-.TQ
-.FONT CB .SUFFIX I " <string>"
-The strings of characters between quotation marks are used to form the
-page string, which has the form:
-.
-.RS
-.I <prefix><section><page number><suffix>
-.
-.P
-Any or all of these strings mav be null.
-.
-The section string is considered to be part of the page number for
-purposes of indexing.
-.
-.RE
-.P
-Initial mode is:
-.
-.RS
-.RS
-.ft CB
-.nop ".PAGING MODE TOP MARGIN PREFIX \[dq]Page\[dq]"
-.nop ".PAGING MODE SECTION \[dq]\[dq] SUFFIX \[dq]\[dq]"
-.RE
-.RE
-.
-.
-.P
-If neither page number nor heading is used, the text will start on the
-first logical line.
-.
-Otherwise it will start on the fourth logical line.
-.
-If the page number is at the bottom, text will end on the fourth line
-from the bottom.
-.
-If the paging and headinq mode conflict, the page string overwrites
-the heading.
-.
-.RE
-.
-.
-.TP
-.FONT CB ".ODD PAGE"
-This
-.FONT CI "control word"
-causes the ourrent page to be printed out and the next page to be
-started with the next higher odd number.
-.
-.
-.TP
-.FONT CB .PAGE I " n"
-If
-.I n
-is present, insert a page break and start numbering the next pege
-with
-.IR n .
-Otherwise, turn the
-.I paging mode
-on and do not insert a page break.
-.
-.
-.TP
-.FONT CB .EJECT I " n"
-Insert a page break if either there are fewer than
-.I n
-lines left on the page or
-.I n
-is not present.
-.
-.
-.\" --------------------------------------------------------------------
-.SS Lines and Spacing
-.\" --------------------------------------------------------------------
-.
-.TP
-.FONT CB ".SINGLE SPACE"
-Sing1e space all 1ines within paragraphs.
-.
-This is the initial state.
-.
-.
-.TP
-.FONT CB ".DOUBLE SPACE"
-Double space all lines within paragraphs.
-.
-.
-.TP
-.FONT CB .SPACE I " n"
-Output
-.I n
-1ine spaces.
-.
-If
-.I n
-is not provided, 1 is assumed.
-.
-In case of page overflow all remaining blank 1ines to be output are
-deleted.
-.
-.
-.TP
-.FONT CB ".FIGURE SPACING" I " n"
-This command is equivalent to
-.FONT CB .EJECT I " n"
-followed by
-.FONT CB .SPACE
-.IR n .
-.
-These commands provide the only means of creatinq blank 11nes.
-.
-.
-.TP
-.FONT CB .BREAK
-The lines before and after this command will not be run together in
-.IR "fill mode" .
-.
-A simpler way to get a line break is to insert one or more blank lines
-in the text.
-.
-.
-.TP
-.FONT CB ".BEGIN GROUP"
-.TQ
-.FONT CB ".END GROUP"
-The output lines enclosed between these two commands are forced to lie
-on a page.
-.
-Thus this command acts in a manner similar to
-.FONT CB .EJECT I " n" R ,
-where
-.I n
-has the 'right' value.
-.
-.
-.\" --------------------------------------------------------------------
-.SS Miscellanous
-.\" --------------------------------------------------------------------
-.
-.TP
-.FONT CB .UNDERLINE
-The following 1ine is underlined.
-.
-.
-.TP
-.FONT CB .LITERAL
-The next line is taken as part of text whether or not
-it begins with dot.
-.
-.
-.TP
-.FONT CB .ESCAPE I <char>
-.TQ
-.FONT CB .SHIFT I <char>
-.TQ
-.FONT CB ".TAB CHARACTER" I <char>
-The given character becomes the
-.IR escape ,
-.IR shift ,
-or
-.I tab
-character.
-.
-The parameter for the
-.FONT CB .SHIFT
-and
-.FONT CB ".TAB CHARACTER"
-commands may be null, if no
-.I shift
-or
-.I tab
-character is desired.
-.
-.
-.TP
-.FONT CB ".DEFINE COMMAND" I " <name>"
-.TQ
-.FONT CB ".END COMMAND"
-.TQ
-.FONT CB .CALL I " <name>"
-These commands give the user the opportunity to combine text and
-control lines to form his own commands.
-.
-All text and command lines between the first and second commands is
-stored away under
-.IR name .
-.
-When the third command is executed, the stored string is read and the
-commands within the string are executed.
-.
-Recursion is not permitted.
-.
-.
-.TP
-.FONT CB .INDEX I " <phrase>, <phrase>"
-.
-.FONT CB RUNOfF
-saves the first phrase in the main index table and the second phrase
-(if any) in a sub\-index table associated with the first phrase.
-.
-.RS
-.
-The index is formatted and output after the last page of text.
-.
-Two built\-in but redefinable formats,
-.FONT CI RINDEX
-and
-.FONT CI SINDEX R ,
-are used to format the index as shown in the following example.
-.
-.RS
-.nh
-.nf
-.FONT CB "Algorithms, 40, 78," R "             \[rs]\[dq] uses " I RINDEX
-.FONT CB "  analysis of, 27, " R "             \[rs]\[dq] uses " I SINDEX
-.fi
-.hy
-.RE
-.
-.
-The following lines give the initial definitions for the indexing
-formats.
-.
-.
-.RS
-.nh
-.nf
-.ft CB
-.nop ".define format RINDEX f(A)"
-.nop "AAAAAAAAAAAAAAAAAAAAAAAAAAA"
-.nop "    AAAAAAAAAAIAAAAAAAAAAAA"
-.nop ".end format"
-.nop ".define format SINDEX f(A)"
-.nop "  AAAAAAAAAAAAAAAAAAAAAAAAA"
-.nop "    AAAAAAAAAAIAAAAAAAAAAAA"
-.nop ".end format"
-.ft
-.fi
-.hy
-.RE
-.
-.
-In order to get an index output in two columns,
-.RS
-.P
-.FONT CB ".LINE LAYOUT 15, 75, 2, 4"
-.P
-should be the last line of the input.
-.RE
-.
-.RE
-.
-.
-.\" --------------------------------------------------------------------
-.SH RUNOFF DOCUMENTATION 1974
-.\" --------------------------------------------------------------------
-.
-This document is the best documentation about text lines.
-.
-Parts of that is used in the document of 1981.
-.
-The documentation of text lines is the best at all.
-.
-This is reguarded above.
-.
-.
-.P
-The documentation of commands will be including later on.
-.
-.
-.\" --------------------------------------------------------------------
-.SH RUNOFF COMMAND ADDITIONS 1981
-.\" --------------------------------------------------------------------
-.
-The following
-.I commands
-will be recognized if they are at the beginning of a line started with
-a period.
-.
-Any line in the source file beginning with a period is assumed to be
-one of these
-.IR commands .
-.
-If it is not, an
-.I error diagnostic
-will be typed and the line will be ignored.
-.
-Some
-.I commands
-take one or more decimal numeric arguments.
-.
-These are separated from the
-.I command
-by a
-.FONT CR space R .
-.
-More than one
-.I command
-may be entered on a single line by separating the
-.I commands
-with a
-.FONT CI semicolon
-.FONT R ` CB ; R '
-or a
-.FONT CI period
-.FONT R ` CB . R '.
-.
-.
-.P
-.I Multi\-word commands
-may appear in any form.
-.
-Thus,
-.FONT CB ".NO HEADER"
-and
-.FONT CB .NOHEADER
-are both legal.
-.
-.
-.P
-Many
-.I commands
-may be abbreviated.
-.
-Standard
-.I abbreviations
-are given below each
-.IR command .
-.
-.
-.\" --------------------------------------------------------------------
-.SS Text Formatting Commands
-.\" --------------------------------------------------------------------
-.
-.TP
-.FONT CB .BREAK
-.TQ
-.FONT CB .BR
-causes a
-.IR break ,
-i.e. the current line will be output with no
-.IR justification ,
-and the next word of the source text will be placed at the beginning
-of the next line.
-.
-.
-.TP
-.FONT CB .SKIP CI " n"
-.TQ
-.FONT CB .SK CI " n"
-.TQ
-.FONT CB .S CI " n"
-causes a BREAK after which
-.CI n
-is multiplied by the number of
-.I spaces
-between lines.
-.
-The result is the number of lines
-.IR skipped .
-.
-Output is advanced to the top of the next page if there is no room on
-the current page.
-.
-If the current page is empty,
-.FONT CB .SKIP
-does nothing.
-.
-.
-.TP
-.FONT CB .BLANK I " n"
-.TQ
-.FONT CB .B I " n"
-causes the current line to be output with no
-.IR justification ,
-skips
-.FONT CI n
-line spaces, and then starts output of the current source text.
-.
-.FONT CB .BLANK
-is like
-.FONT CB .SKIP R ,
-except that the
-.I space
-to be left is independent of line spacing.
-.
-If the page is empty,
-.FONT CB .BLANK
-does nothing.
-.
-.
-.TP
-.FONT CB .FIGURE I " n"
-.TQ
-.FONT CB .FG I " n"
-leaves
-.I n
-lines blank to make room for a figure or diagram.
-.
-If fewer than
-.I n
-lines remain on the current page, text continues to
-.I fill
-this page, then the page is advanced and
-.I n
-blank lines are left at the top of the next page.
-.
-.
-.TP
-.FONT CB .INDENT I " n"
-.TQ
-.FONT CB .I I " n"
-causes a
-.CI break
-and sets the next line to begin
-.I n
-spaces to the right of the left margin.
-.
-The
-.I n
-can be negative to allow beginning a line to the left of the left
-margin.
-.
-However, a line cannot begin to the left of column 0.
-.
-If
-.I n
-is not supplied, the current paragraph indent is used.
-.
-.
-.TP
-.FONT CB .PARAGRAPH I " n, v, t"
-.FONT CB .P I " n, v, t"
-causes a
-.I break
-and formats the output paragraphs.
-.
-The
-.I n
-is optional and, if present, sets the number of spaces the paragraph
-is to be indented.
-.
-The default value for
-.I n
-is
-.FONT CB 5
-.RI ( n
-can also have a negative value).
-.
-.I v
-is the vertical spacing between paragraphs.
-.
-.I v
-can range from
-.FONT CB 0
-to
-.FONT CB 5 R .
-.
-.FONT R ( CB 1
-is
-.IR "single spacing" ,
-.FONT CB 2
-is
-.IR "double spacing" ,
-etc.)
-.
-.I t
-causes an automatic
-.FONT CI ".TEST PAGE"
-(see the
-.FONT CB ".TEST PAGE"
-.IR command ).
-.
-.
-.TP
-.FONT CB .CENTER I " n" CB ; I text
-.TQ
-.FONT CB .CENTRE I " n" CB ; I text
-.TQ
-.FONT CB .C I " n" CB ; I text
-causes a
-.I break
-and centers the following text in the source file.
-.
-The centering is over column
-.FONT CB ( I n CB " + " I "left margin" CB )/2 R .
-If
-.I n
-is not given, it is assumed to be the
-.
-.IR "right margin" .
-.
-.
-.RS
-.P
-.ce
-NOTE
-.
-.P
-.FONT CB .CENTER R ,
-.FONT CB ".RIGHT MARGIN" R ,
-.FONT CB ".LEFT MARGIN" R ,
-.FONT CB ".PAGE SIZE" R ,
-and
-.FONT CB .STANDARD
-take both relative and absolute values.
-.
-Relative values are expressed as
-.FONT CB + I n
-or
-.FONT CB \- I n R ,
-while absolute values of
-.I n
-are unsigned.
-.RE
-.
-.
-.TP
-.FONT CB .FOOTNOTE I " n"
-.TQ
-.FONT CB .FN I " n"
-saves
-.I n
-lines at the bottom of the current page for a
-.IR footnote .
-.
-The
-.I n
-is multiplied by the number of spaces set with the
-.FONT CB .SPACING
-command.
-.
-If insufficient room remains on the current page, space is allocated
-at the bottom of the following page.
-.
-The text of the
-.I footnote
-should begin on the line following the
-.FONT CB .FOOTNOTE
-command.
-.
-.IR Indentation ,
-.IR "case lock" ,
-.IR justify ,
-.IR margins ,
-.IR spacing ,
-and
-.I fill
-are preserved around footnotes.
-.
-However,
-.I commands
-that affect page formatting are illegal in a
-.IR footnote .
-.
-.I Tab stops
-are illegal because they are not preserved.
-.
-A footnote within a footnote is also illegal.
-.
-.
-.P
-The actual space taken by a footnote can be more or less than
-specified by
-.IR n .
-If necessary
-.FONT CR adjust
-.I n
-after examining a draft printout.
-.
-.
-.P
-The
-.I footnote
-is terminated with a line beginning with an exclamation point (the
-remainder of which is ignored).
-.
-.
-.TP
-.FONT CB .NOTE I " text"
-.TQ
-.FONT CB .NT I " text"
-starts an
-.IR "indented note" .
-.
-This command
-.I blanks
-.FONT CB 2 R ,
-reduces both
-.IR margins ,
-.I centers
-the text (if no text is given, it centers the word
-.FONT CB NOTE R ),
-and then
-.I blanks
-.FONT CB 1 R .
-.
-At this point you enter the text of the
-.IR note .
-.
-If the left margin is at
-.FONT CB 0 R ,
-the
-.I margin reduction
-is
-.FONT CB 15 R ,
-otherwise it is
-.FONT CB 5 R .
-.
-.
-.TP
-.FONT CB ".END NOTE"
-.TQ
-.FONT CB .EN
-terminates the
-.FONT CB .NOTE
-command,
-.I blanks
-.CONT CB 2 R ,
-and reverts the margins and spacing modes to their settings before the
-last
-.FONT CB .NOTE
-command.
-.
-.
-.TP
-.FONT CB .LIST I " n"
-.FONT CB .LS I " n"
-starts an indented list with
-.I n
-spacing, moves the left margin
-.FONT CB 9
-spaces to the right for the first
-.FONT CB .LIST
-command, and
-.FONT CB 4
-more spaces for each subsequent nested
-.FONT CB .LIST R .
-.
-The normal
-.I fill
-and
-.I justify modes
-remain in effect.
-.
-Therefore, you must disengage them just after the
-.FONT CB .LS
-command if you want a ragged right.
-.
-.
-.TP
-.FONT CB ".LIST ELEMENT;" I " text"
-.TQ
-.FONT CB .LE; I " text"
-starts an item in the list, used in conjunction with the
-.FONT CB .LIST
-comand.
-.
-The elements are numbered sequentially and the number is given a
-negative indent so that the list lines up.
-.
-The number is followed by a
-.I period
-and two
-.I spaces
-so that the indent will be by 
-.FONT CB \-4 R .
-.
-The
-.I list elements
-are separated by the standard paragraph spacing and
-.FONT CI "TEST PAGE" R .
-.
-If you want to type the text on the same line as the command, you must
-separate the text from the command with any number of intervening
-.I spaces
-or
-.IR tabs ,
-or (optionally) one
-.IR semicolon .
-.
-.
-.TP
-.FONT CB ".END LIST"
-.TQ
-.FONT CB .ELS
-terminates the
-.FONT CB .LIST
-command and returns to settings before the last
-.FONT CB .LIST
-command.
-.
-.
-.TP
-.FONT CB .COMMENT I " text"
-.TQ
-.FONT CB .; I " text"
-causes the line to be ignored.
-.
-The text is not printed in the output file, but rather is used as a
-.I comment
-line in the source text.
-.
-.
-.\" --------------------------------------------------------------------
-.SS Page Formatting Commands
-.\" --------------------------------------------------------------------
-.
-.TP
-.FONT CB .PAGE
-.FONT CB .PG
-causes a
-.I break
-and an
-.I advance
-to a new page.
-.
-If the current page is empty, this
-.I command
-does not
-.I advance
-the page.
-.
-Just like an
-.IR "automatic page advance" ,
-this
-.I command
-prints the
-.I title
-(if given) and
-.I page numbers
-on every page.
-.
-.
-.TP
-.FONT CB ".TEST PAGE" I " n"
-.TQ
-.FONT CB .TP I " n"
-causes a
-.I break
-followed by a
-.IR "conditional page advance" .
-.
-It skips to the next page if fewer than
-.I n
-lines are left on the page.
-.
-This capability is to ensure that the following
-.I n
-lines are all output on the same page.
-.
-This
-.I command
-has the form
-.I t
-as an optional argument to the
-.FONT CB .PARAGRAPH
-command.
-.
-.
-.TP
-.FONT CB .NUMBER I " n"
-.TQ
-.FONT CB .NM I " n"
-starts page numbering.
-.
-This is the default so there is no reason to issue this command unless
-page numbering is disengaged.
-.
-If
-.I resumption
-of page numbering is desired at a certain page, specify
-.IR n .
-.
-.
-.TP
-.FONT CB .NONUMBER
-.FONT CB .NNM
-disengages page numbering.
-.
-However, pages continue to be counted, so that the normal page number
-can appear if page numbering is re\-entered with the
-.FONT CB .NUMBER
-command.
-.
-.
-.TP
-.FONT CB .CHAPTER I " text"
-.TQ
-.FONT CB .CH I " text"
-starts a new chapter using the text as the title of the chapter.
-.
-This
-.I command
-acts as if the following
-.I command string
-were entered:
-.
-.
-.P
-.EX
-.nop ".BREAK;.PAGE;.BLANK 12;.CENTER;CHAPTER n"
-.EE
-.P
-The
-.I n
-is incremented by
-.FONT CB 1
-automatically.
-.
-After the CHAPTER
-.I n
-is typed on the page,
-.
-.
-.P
-.EX
-.nop .BLANK 2;.CENTER;text;.BLANK 3
-.EE
-.P
-occurs.
-.
-This
-.I command
-then resets the
-.IR case ,
-.IR margins ,
-.IR spacing ,
-and
-.IR "justify/fill modes" .
-.
-It also clears any
-.I subtitles
-and sets the
-.I chapter name
-as the
-.IR title .
-.
-.
-.TP
-.FONT CB ".NUMBER CHAPTER " I " n"
-supplies a number
-.I n
-to be used in a subsequent
-.FONT CB .CHAPTER
-command.
-.
-.FONT CB ".NUMBER CHAPTER"
-would be used when a
-.I chapter
-of a document occupies a source file of its own.
-.
-In such a case,
-.FONT CB ".NUMBER CHAPTER"
-would be the first command of the source file.
-.
-.
-.TP
-.FONT  CB ".HEADER LEVEL" I " n text"
-.TQ
-.FONT CB .HL I " n text"
-starts a section at the level specified and takes the following text
-as the header.
-.
-.I n
-can range from
-.FONT CB 1
-to
-.FONT CB 5 R .
-.
-The sections are incremented by
-.FONT CB 1
-automatically, and the number is output in the form
-.FONT I i CB . I j CB . I k CB . I l CB . I m R .
-If this is a chapter oriented document, the
-.I i
-is the chapter number.
-.
-Otherwise, it is the number of the
-.FONT CB ".HL 1"
-level.
-.
-This command acts as a
-.
-.P
-.EX
-.FONT CB ".BREAK;.TEST PAGE 9;.BLANK 3"
-.EE
-.
-.P
-followed by the
-.IR "section number" ,
-two
-.IR spaces ,
-and the
-.IR "section name" .
-.
-.FONT CI "HEADER LEVELS " CB 1
-and
-.FONT CB 2
-end with a
-.IR break .
-.FONT CI "HEADER LEVELS"
-.FONT CB 3 R ", " CB 4 R ,
-and
-.FONT CB 5
-end with a space\-dash\-space combination (#\-#).
-.
-.
-.TP
-.FONT CB .TITLE I " text"
-.TQ
-.FONT CB .T I " text"
-takes the remaining text as the title and outputs it on every page at
-line
-.FONT CB 0 R .
-.
-The default is no title.
-.
-If a
-.I title
-is desired, this
-.I command
-must be entered in the source file.
-.
-.
-.TP
-.FONT CB ".FIRST TITLE" I " text"
-.TQ
-.FONT CB ".FT" I " text"
-Same as
-.FONT CB .TITLE R ,
-but used to specify the title to be printed on the first page of the
-document.
-.
-This command must precede all text in the source file.
-.
-Use of the
-.FONT CB ".FIRST TITLE"
-command is the only way to print a title line on the first page of the
-document.
-.
-.
-.TP
-.FONT CB .SUBTITLE I " text"
-.TQ
-.FONT CB .SUBTTL I " text"
-.TQ
-.FONT CB .ST I " text"
-takes the remaining text as the
-.I subtitle
-and outputs it on every page.
-.
-It appears directly under the title.
-.
-The
-.I subtitle
-is not
-.IR indented ,
-but
-.I indentation
-can be achieved by typing leading spaces.
-.
-.
-.TP
-.FONT CB .INDEX I " text"
-.TQ
-.FONT CB .X I " text"
-takes the remaining text on the line as a keyword and adds it, along
-with the current
-.IR "page number" ,
-to the internal index buffer.
-.
-The command does not cause a
-.IR break .
-.
-It should appear immediately before the item to be
-.IR indexed .
-.
-A keyword may be
-.I indexed
-more than once.
-.
-.
-.TP
-.FONT CB ".DO INDEX" I " text"
-.TQ
-.FONT CB ".DX" I " text"
-forces a new page, centers the text, if given, otherwise it centers
-the word
-.FONT CI "INDEX" R .
-.
-This command prints the entire contents of the index buffer.
-.
-Entries are printed in alphabetic order and are set against the left
-margin.
-.
-Regular line spacing is used, except that a blank line is left between
-entries of different first letters.
-.
-The page number of each entry is placed on the same line as the entry
-and in the middle of the page.
-.
-Additional page numbers for multiple entries follow, separated by
-commas.
-.
-The index buffer is left empty.
-.
-.
-.TP
-.FONT CB ".PRINT INDEX"
-.TQ
-.FONT CB ".PX"
-forces a new page after which it prints the entire contents of the
-index buffer.
-.
-Entries are printed in alphabetical order and are set against the left
-margin.
-.
-Regular line spacing is used, except that a blank line is left between
-entries of different first letters.
-.
-The number of the first page on which each entry appeared is put on
-the same line as the entry, beginning at the middle of the line
-(midway betweeen the left and right margins).
-.
-Additional page numbers for multiple entries follow, separated by
-commas.
-.
-The index buffer is left empty.
-.
-.
-.P
-.FONT CB ".PRINT INDEX"
-and
-.FONT CB ".DO INDEX"
-perform the same task.
-.
-The only difference is that
-.FONT CB ".PRINT INDEX"
-does not interrupt the normal chapter and page sequencing.
-.
-.
-.TP
-.FONT CB .SUBPAGE
-executes a
-.FONT CB .PAGE
-with page numbering suspended.
-.
-The page number is unchanged, but letters are appended to the page
-number.
-.
-This permits insertion of additional pages within an existing document
-without changing the existing page numbering.
-.
-.
-.TP
-.FONT CB ".END SUBPAGE"
-disengages the
-.FONT CB .SUBPAGE
-command by executing a
-.FONT CB .PAGE
-command with page numbering resumed.
-.
-.
-.TP
-.FONT CB .APPENDIX I " text"
-.TP
-.FONT CB .AX I " text"
-starts a new appendix using the text as the title of the appendix.
-.
-This command acts as if the following command string were entered:
-.
-.RS
-.P
-.EX
-.nop ".BREAK;.PAGE;.BLANK 12;.CENTER;APPENDIX a"
-.EE
-.RE
-.P
-The a is a letter that is incremented alphabetically automatically.
-.
-After the
-.FONT CB "APPENDIX A"
-is typed on the page,
-.
-.RS
-.P
-.EX
-.nop .BLANK 2;.CENTER;text;.BLANK 3
-.EE
-.RE
-.
-.P
-occurs.
-.
-This command then resets the
-.IR case ,
-.IR margins ,
-.IR spacing ,
-and
-.IR justify/fill
-modes.
-.
-It also clears any subtitles and sets the appendix name as the title.
-.
-.
-.TP
-.FONT CB ".NUMBER APPENDIX" I " a"
-supplies a letter
-.I a
-to be used as the letter for a subsequent
-.FONT CB .APPENDIX
-command.
-.
-.
-.TP
-.FONT CB .HEADER I " arg"
-.TQ
-.FONT CB .HD I " arg"
-causes the page header
-.RI ( title ,
-.IR subtitle ,
-and
-.IR "page number" )
-to be printed.
-.
-.I arg should be
-.FONT CB UPPER
-to specify
-.I upper case characters
-for the title text,
-.FONT CB LOWER
-to specify
-.IR "lower case" ,
-or
-.FONT CB MIXED R .
-.
-The initial setting is
-.FONT CB ".HEADER UPPER" R .
-.
-.
-.TP
-.FONT CB .NOHEADER
-.TP
-.FONT CB .NHD
-causes the page header
-.RI ( title ,
-.IR subtitle ,
-and
-.IR "page number" )
-to be omitted.
-.
-The header lines are completely omitted, so that text begins at the
-top of the page with no
-.IR "top margin" .
-.
-.
-.\" --------------------------------------------------------------------
-.SS Mode Setting Commands
-.\" --------------------------------------------------------------------
-.
-.TP
-.FONT CB .JUSTIFY
-.TQ
-.FONT CB .J
-causes a break and sets subsequent output lines to be justified
-(initial setting).
-.
-The
-.I command
-increases the spaces between words until the last word exactly meets
-the right margin.
-.
-.
-.TP
-.FONT CB .NOJUSTIFY
-.TQ
-.FONT CB .NJ
-causes a
-.I break
-and prevents
-.I justification
-of subsequent output lines to make a ragged right margin.
-.
-.
-.TP
-.FONT CB .FILL
-.TQ
-.FONT CB .F
-causes a break and specifies that subsequent output lines be filled
-(inital setting).
-.
-Sets the justification mode to be that specified by the last
-appearance of
-.FONT CB  .JUSTIFY
-or
-.FONT CB .NOJUSTIFY R .
-.
-.FONT CB .FILL
-adds successive words from the source text until the adding of one
-more word will exceed the right margin.
-.
-It stops before putting the last word in.
-.
-(If
-.I hyphenation
-has not been disabled,
-.FONT CB RNO
-will attempt to
-.I break
-words which cause line overflow into syllables.)
-.
-.
-.TP
-.FONT CB .NOFILL
-.TP
-.FONT CB .NF
-disengages the
-.I fill
-and
-.IR "justify modes" .
-.
-This
-.I command
-is used to permit typing a table.
-.
-.
-.RS
-.
-.
-.P
-.ce
-NOTE
-.
-.P
-1. The
-.I nofill\-nojustify mode
-need be used only where there are several lines of material to be
-copied exactly.
-.
-A single line example will not require using these commands if there
-are breaks before and after.
-.
-.
-.P
-2. Normally
-.FONT CB .FILL
-and
-.FONT CB .NOFILL
-are used to turn both
-.I filling
-and
-.I justification
-on and off.
-.
-It is usually desirable to do both.
-.
-A subsequent appearance of a
-.I justification command
-will override the
-.I fill command
-however.
-.
-.
-.P
-3. Because of the action of
-.FONT CB .FILL R ,
-a single occurrance of
-.FONT CB .NOJUSTIFY
-will cause the remainder of the file to be
-.IR unjustified ,
-with
-.I filling
-as specified.
-.
-In order to
-.I justify
-but
-.I not fill
-(not recommended), a
-.FONT CB .JUSTIFY
-command must follow every
-.FONT CB .NOFILL
-command.
-.
-.
-.RE
-.
-.
-.TP
-.FONT CB ".UPPER CASE"
-.TQ
-.FONT CB .UC
-sets the output mode to
-.IR "upper case" .
-.
-This comand acts the same as typing two
-.CI circumflexes
-.FONT CB ^^ R .
-.
-This is the default mode.
-.
-There is no need to type this command unless the mode was previously
-altered to
-.IR "lower case" .
-.
-.
-.TP
-.FONT CB ".LOWER CASE"
-.TQ
-.FONT CB .LC
-sets the typeout mode to
-.IR "lower case" .
-This command acts the same as typing two
-.I back\-slashes
-.FONT CB \[rs]\[rs] R .
-.
-.
-.TP
-.FONT CB ".FLAGS CAPITALIZE"
-.TQ
-.FONT CB ".FL CAPITALIZE"
-enables the
-.CI less\-than
-.FONT CB <
-character to
-.I capitalize
-the entire word it precedes.
-.
-It then returns the file to the current case mode.
-.
-This
-.I special character
-is usually
-.FONT CR off
-and must be typed at the very beginning of the source text to enable
-this character.
-.
-Typing a space or another
-.FONT CI "less\-than " CB <
-returns the file to the current
-.IR "case lock" .
-.
-.
-.TP
-.FONT CB ".NO FLAGS CAPITALIZE"
-.TQ
-.FONT CB .NFC
-disengages the
-.FONT CB "FLAG CAPITALIZE"
-command (inital setting).
-.
-.
-.TP
-.FONT CB .HYPHENATION
-.TQ
-.FONT CB .HY
-engages
-.I hyphenization
-(initial setting).
-.
-.
-.TP
-.FONT CB ".NO HYPHENATION"
-.TQ
-.FONT CB .NHY
-disengages
-IR hyphenization .
-.
-.
-.TP
-.FONT CB ".FLAGS HYPHENATE"
-.TQ
-.FONT CB ".FL HYPHENATE"
-enables the
-.I equals character
-.FONT CB =
-to disengage
-.I hyphenization
-for the word it precedes.
-.
-This
-.I special character
-is initially
-.FONT CR off
-and must be typed at the beginning of the source file to enable this
-character.
-.
-The
-.FONT CI "FLAGS HYPHENATE"
-.I character
-is used to disengage
-.I hyphenization
-for words improperly
-.I hyphenated
-by the
-.IR "hyphenization algorithm" .
-.
-.
-.TP
-.FONT CB ".NO FLAGS HYPHENATE"
-.TQ
-.FONT CB .NFH
-disengages the
-.FONT CB ".FLAGS HYPHENATE"
-command (initial setting).
-.
-.
-.TP
-.FONT CB .NFL
-disengages the
-.FONT CB ".FLAGS CAPITALIZE"
-and the
-.FONT CB ".FLAGS HYPHENATE"
-commands (initial setting).
-.
-.
-.TP
-.FONT CB .PERIOD
-.TQ
-.FONT CB .PR
-enables printing of two
-.I spaces
-after every
-.I period
-.FONT CB .
-that is followed by at least one
-.I separator character
-(initial setting).
-.
-.
-.TP
-.FONT CB .NOPERIOD
-.TQ
-.FONT CB .NPR
-disengages conversion of
-.I period/separator
-to
-.IR "period/two spaces" .
-.
-.
-.TP
-.FONT CB .LITERAL
-.TQ
-,FONT CB .LIT
-disengages
-.I fill/justify
-to permit printing of text exactly as entered in source file.
-.
-.
-.TP
-.FONT CB ".END LITERAL"
-.TQ
-.FONT CB .ELI
-used after
-.FONT CB .LITERAL
-command to re\-engage
-.IR fill/justify .
-.
-.
-.\" --------------------------------------------------------------------
-.SS Parameter Setting Commands
-.\" --------------------------------------------------------------------
-.
-.TP
-.FONT CB ".LEFT MARGIN" I " n"
-.TQ
-.FONT CB .LM I " n"
-sets the left margin to
-.IR n .
-.
-The
-.I n
-must be less than the right margin but not less than
-.FONT CB 0 R .
-The initial setting is
-.FONT CB 0 R .
-If
-.I n
-is not supplied,
-.FONT CB 0
-is used.
-.
-.
-.TP
-.FONT CB ".RIGHT MARGIN" I " n"
-.TQ
-.FONT CB .RM I " n"
-sets the right margin
-.IR n .
-The
-.I n
-must be greater than the left margin.
-.
-The initial setting is
-.FONT CB 60 R .
-.
-If
-.I n
-is not supplied, the current page width (set with the
-.FONT CB ".PAGE SIZE"
-command) is used.
-.
-.
-.TP
-.FONT CB ".PAPER SIZE" I " n" CB , I m
-.TP
-.FONT CB ".PAGE SIZE" I " n" CB , I m
-.TP
-.FONT CB ".PS" I " n" CB , I m
-sets the size of the page
-.I n
-lines by
-.I m
-columns and sets the right margin to
-.IR m .
-The default setting is
-.FONT CB 58,60 R .
-.
-.
-.TP
-.FONT CB .PITCH I " n" CB , I m
-.TQ
-.FONT CB .PIT I " n" CB , I m
-sets the horizontal and vertical pitch on a supporting output device.
-.
-The horizontal pitch is
-.I n
-and is specified as characters per inch.
-.
-The value must divide evenly into
-.FONT CB 60
-for
-.FONT CI "Anderson\-Jacobson devices"
-and into
-.FONT CB 120
-for
-.FONT CI "Diablo devices" R .
-.
-The default is
-.FONT CB 12 R .
-.
-.
-.P
-The vertical pitch is
-.I m
-and is specified as lines per inch.
-.
-.I m
-must divide evenly into
-.FONT CB 48 R .
-.
-The default is the hardware setting.
-.
-.I n
-and
-.I m
-may be set independently.
-.
-.
-.TP
-.FONT CB .SPACING I " n"
-.TQ
-.FONT CB .SP I " n"
-sets the number of spaces between lines.
-.
-The
-.I n
-can range from
-.FONT CB 1
-to
-.FONT CB 5 R .
-.
-The default setting is
-.FONT CB 1 R .
-.
-.FONT CB ".SPACING 1"
-is like
-.I single spacing
-on a typewriter and
-.FONT CB ".SPACING 2"
-is like
-.IR "double spacing" .
-.FONT CB ".SPACING 2"
-puts one
-.I blank line
-between lines of text.
-.
-.
-.TP
-.FONT CB .STANDARD I " n"
-.TQ
-.FONT CB .SD I " n"
-returns all parameters, except the pitch settings, to their initial
-settings and sets
-.I n
-as the page width.
-.
-If
-.FONT CB ".STANDARD 60"
-is specified, margins are reset
-.FONT CB ".LM 0" R ,
-.FONT CB ".RM 60" R ,
-.FONT CB ".PAGE SIZE 58,60" R ,
-.FONT CB ".SPACING 1" R ,
-.FONT CB "PARAGRAPH INDENT 5" R ,
-and
-.I fill
-and
-.I justify
-are enabled.
-.
-.FONT CB ".STANDARD 70"
-sets right margin to
-.FONT CB 70
-and
-.I page size
-to
-.FONT CB 58,70 R .
-.
-.
-.TP
-.FONT CB ".TAB STOPS" I " n" CB , I n CB , I \*[Ellipsis]
-.TQ
-.FONT CB ".TS" I " n" CB , I n CB , I \*[Ellipsis]
-sets tabs.
-.
-The
-.I  n
-must be greater than
-.FONT CB 0
-and listed in ascending order.
-.
-If tabs already exist, the issuing of another
-.FONT CB ".TAB STOPS"
-command clears all previous
-.I tabs
-before setting new ones.
-.
-The
-.I default tabs
-are set at eight\-column intervals to match the
-.FONT CR Digital
-hardware standard.
-.
-These
-.I tabs
-are at columns
-.FONT CB 8 R ,
-.FONT CB 16 R ,
-.FONT CB 24 R ,
-.FONT CB 32 R ,
-.FONT CB 40 R ,
-.FONT CB 48 R ,
-.FONT CB 56 R ,
-.FONT CB 64 R ,
-.FONT CB 72 R ,
-and
-.FONT CB 80 R .
-.
-The tabs are converted to the appropriate number of non\-expandable
-spaces.
-.
-If there are no regular spaces to the left of the
-.IR tabs ,
-they will print out at the appropriate position, even if
-.I fill
-is on.
-.
-If
-.I literal
-is on, the
-.I tabs
-are not converted to
-.IR spaces ,
-but are output as
-.IR tabs .
-.
-.
-.TP
-.FONT CB .AUTOPARAGRAPH
-.TQ
-.FONT CB .AP
-causes any
-.I blank line
-or any line starting with a
-.I space
-or
-.I tab
-to be considered as the start of a new paragraph.
-.
-This command allows normally typed text to be
-.I justified
-without special commands.
-.
-It does not cause a paragraph if
-.I blank lines
-are followed by a command.
-.
-.
-.TP
-.FONT CB .NOAUTOPARAGRAPH
-.TQ
-.FONT CB .NAP
-disengages the
-.FONT CI AUTOPARAGRAPH
-mode.
-.
-.
-.\" --------------------------------------------------------------------
-.SS List of Commands (Alphabetical)
-.\" --------------------------------------------------------------------
-.
-.if t \{
-.ig endTBL
-.\}
-.
-.\" --------------------------------------------------------------------
-.\" Table using tbl for running in tty
-.\" --------------------------------------------------------------------
-.
-.nf
-.nh
-.
-.TS
-center,allbox,tab(@);
-cIw(1.5i) sw(1.5i) cIw(1.5i).
-Command or Abbreviation@Related Commands
-=
-.
-.T&
-l l l.
-\f[CB].AP\f[R]@(=\f[CB].AUTOPARAGRAPH\f[R])@
-\f[CB].APPENDIX\f[I] text \f[R]@(=\f[CB].AX\f[R])@\f[CB].NUMBER APPENDIX\f[I] a
-\f[CB].AX\f[R]@(=\f[CB].APPENDIX\f[R])@
-\f[CB].AUTOPARAGRAPH \f[R]@(=\f[CB].AP\f[R])@T{
-\f[CB].NOAUTOPARAGRAPH
-.br
-\f[R](\f[CB].NAP\f[R])
-T}
-_
-\f[CB].B\f[R]@(=\f[CB].BLANK\f[R])@
-\f[CB].BLANK \f[I]n \f[R]@(=\f[CB].B\f[R])@T{
-7\f[CB].SKIP \f[I]n
-.br
-\f[R](\f[CB].S\f[R])
-T}
-\f[CB].BR\f[R]@(=\f[CB].BREAK\f[R])@
-\f[CB].BREAK@\f[R](=\f[CB].BR\f[R])
-_
-\f[CB].C\f[R]@(=\f[CB].CENTRE\f[R])@
-\f[CB].CENTER\f[R]@(=\f[CB].CENTRE\f[R])@
-\f[CB].CENTRE \f[I]n\f[CB];\f[I]text \f[R]@(=\f[CB].C\f[R])@
-\f[CB].CH\f[R]@(=\f[CB].CHAPTER\f[R])@
-\f[CB].CHAPTER \f[I]text \f[R]@(=\f[CB].CH\f[R])@\f[CB].NUMBER CHAPTER \f[I]n
-\f[CB].COMMENT \f[I]text\f[R]@@
-_
-\f[CB].DO INDEX \f[I]text \f[R]@(=\f[CB].DX\f[R])@T{
-.
-\f[CB].PRINT INDEX
-.br
-\f[R](\f[CB].PX\f[R])
-T}
-.
-\f[CB].DX\f[R]@(=\f[CB].DO INDEX\f[R])@
-_
-\f[CB].ELS\f[R]@(=\f[CB].END LIST\f[R])@
-\f[CB].EN\f[R]@(=\f[CB].END NOTE\f[R])@
-.
-\f[CB].END LIST\f[R]@(=\f[CB].ELS\f[R])@T{
-\f[CB].LIST \f[I]n
-.br
-\f[R](\f[CB].LS\f[R])
-T}
-.
-\f[CB].END LITERAL \f[R]@(=\f[CB].ELI\f[R])@T{
-\f[CB].LITERAL
-.br
-\f[R](\f[CB].LIT\f[R])
-T}
-.
-\f[CB].END NOTE\f[R]@(=\f[CB].EN\f[R])@T{
-\f[CB].NOTE \f[I]text
-.br
-\f[R](\f[CB].NT\f[R])
-T}
-.
-\f[CB].END SUBPAGE\f[R]@@\f[CB].SUBPAGE
-_
-\f[CB].F\f[R]@(=\f[CB].FILL\f[R])@
-\f[CB].FG\f[R]@(=\f[CB].FIGURE\f[R])@
-\f[CB].FIGURE n \f[R]@(=\f[CB].FG\f[R])@
-.
-\f[CB].FILL \f[R]@(=\f[CB].F\f[R])@T{
-\f[CB].NOFILL
-.br
-\f[R](\f[CB].NF\f[R])
-T}
-.
-\f[CB].FIRST TITLE \f[I]text\f[R]@(=\f[CB].FT\f[R])@\f[CB].TITLE \f[I]text
-.
-\f[CB].FLAGS CAPITALIZE\f[R]@(=\f[CB].FL CAPITALIZE\f[R])@T{
-\f[CB].NO FLAGS CAPITALIZE
-.br
-\f[R](\f[CB].NFL\f[R])
-T}
-.
-\f[CB].FLAGS HYPHENATE \f[R]@(=\f[CB].FL HYPHENATE\f[R])@T{
-\f[CB].NO FLAGS HYPHENATE
-.br
-\f[R](\f[CB].NFH\f[R])
-T}
-.
-\f[CB].FN\f[R]@(=\f[CB].FOOTNOTE\f[R])@
-\f[CB].FOOTNOTE \f[I]n\f[R]@(=\f[CB].FN\f[R])@
-\f[CB].FT\f[R]@(=\f[CB].FIRST TITLE\f[R])@
-_
-\f[CB].HD\f[R]@(=\f[CB].HEADER\f[R])@
-.
-T{
-\f[CB].HEADER \f[I]arg\f[R]
-.br
-\f[R]  [\f[I]arg\f[R]=\f[CB]UPPER\f[R], \f[CB]LOWER\f[R], or \f[CB]MIXED]\f[R]
-T}@(=\f[CB].HD\f[R])@T{
-\f[CB].NOHEADER
-.br
-\f[R](\f[CB].NHD\f[R])
-T}
-.
-\f[CB].HEADER LEVEL \f[I]n text\f[R]@(=\f[CB].HL\f[R])@
-\f[CB].HL\f[R]@(=\f[CB].HEADER LEVEL\f[R])@
-\f[CB].HY\f[R]@(=\f[CB].HYPHENATION\f[R])@
-.
-\f[CB].HYPHENATION \f[R]@(=\f[CB].HY\f[R])@T{
-\f[CB].NO HYPHENATION
-.br
-\f[R](\f[CB].NHY\f[R])
-T}
-.
-_
-\f[CB].I\f[R]@(=\f[CB].INDENT\f[R])@
-\f[CB].INDENT \f[I]n\f[R]@(=\f[CB].I\f[R])@
-\f[CB].INDEX \f[I]text \f[R]@(=\f[CB].X\f[R])@
-_
-\f[CB].J\f[R]@(=\f[CB].JUSTIFY\f[R])@
-.
-\f[CB].JUSTIFY \f[R](\f[CB].J\f[R])@@T{
-\f[CB].NOJUSTIFY
-.br
-\f[R](\f[CB].NJ\f[R])
-T}
-.
-_
-\f[CB].LC\f[R]@(=\f[CB].LOWER CASE\f[R])@
-\f[CB].LE\f[R]@(=\f[CB].LIST ELEMENT\f[R])@
-.
-\f[CB].LEFT MARGIN \f[I]n\f[R]@(=\f[CB].LM\f[R])@T{
-\f[CB].RIGHT MARGIN \f[I]n
-.br
-\f[R](\f[CB].RM\f[R])
-T}
-.
-\f[CB].LIST \f[I]n\f[R]@(=\f[CB].LS\f[R])@T{
-\f[CB].END LIST
-.br
-\f[R](\f[CB].ELS\f[R])
-T}
-.
-\f[CB].LIST ELEMENT;\f[I]text\f[R]@(=\f[CB].LE\f[R])@T{
-\f[CB].END LIST
-.br
-\f[R](\f[CB].ELS\f[R])
-T}
-.
-\f[CB].LIT\f[R]@(=\f[CB].LITERAL\f[R])@
-.
-\f[CB].LITERAL\f[R]@(=\f[CB].LIT\f[R])@T{
-\f[CB].END LITERAL
-.br
-\f[R](\f[CB].ELI\f[R])
-T}
-.
-\f[CB].LM\f[R]@(=\f[CB].LEFT MARGIN\f[R])@
-.
-\f[CB].LOWER CASE\f[R]@(=\f[CB].LC\f[R])@T{
-\f[CB].UPPER CASE
-.br
-\f[R](\f[CB].UC\f[R])
-T}
-.
-\f[CB].LS\f[R]@(=\f[CB].LIST\f[R])@
-_
-\f[CB].NAP\f[R]@(=\f[CB].NOAUTOPARAGRAPH\f[R])@
-\f[CB].NF\f[R]@(=\f[CB].NOFILL\f[R])@
-\f[CB].NFC\f[R]@(=\f[CB].NO FLAGS CAPITALIZE\f[R])@
-\f[CB].NFH\f[R]@(=\f[CB].NO FLAGS HYPHENATE\f[R])@
-.
-\f[CB].NFL\f[R]@T{
-(=\f[CB].NO FLAGS CAPITALIZE
-.br
-.ce
-\f[R] and
-.br
-\f[CB].NO FLAGS HYPHENATE\f[R])
-T}@
-.
-\f[CB].NHD\f[R]@(=\f[CB].NO HEADER\f[R])@
-\f[CB].NHY\f[R]@(=\f[CB].NO HYPHENATION\f[R])@
-\f[CB].NJ\f[R]@(=\f[CB].NO JUSTIFY\f[R])@
-\f[CB].NM\f[R]@(=\f[CB].NUMBER\f[R])@
-\f[CB].NNM\f[R]@(=\f[CB].NO NUMBER\f[R])@
-.
-\f[CB].NOAUTOPARAGRAPH\f[R]@(=\f[CB].NAP\f[R])@T{
-\f[CB].AUTOPARAGRAPH \f[R](\f[CB].AP\f[R])
-.br
-\f[CB]\ .PARAGRAPH \f[I]n,v,t \f[R](\f[CB].P\f[R])
-T}
-.
-\f[CB].NOFILL\f[R]@=(\f[CB].NF\f[R])@T{
-\f[CB].FILL
-.br
-\f[R](\f[CB].F\f[R])
-T}
-.
-\f[CB].NO FLAGS CAPITALIZE\f[R]@(=\f[CB].NFL\f[R])@T{
-\f[CB].FLAGS CAPITALIZE
-.br
-\f[R](\f[CB].FL CAPITALIZE\f[R])
-T}
-.
-\f[CB].NO FLAGS HYPHENATE\f[R]@(=\f[CB].NFH\f[R])@T{
-\f[CB].FLAGS HYPHENATE
-.br
-\f[R](\f[CB].FL HYPHENATE\f[R])
-T}
-.
-\f[CB].NOHEADER\f[R]@(=\f[CB].NHD\f[R])@T{
-\f[CB].HEADER \f[I]arg
-.br
-\f[R](\f[CB].HD\f[R])
-T}
-.
-\f[CB].NO HYPHENATION \f[R]@(=\f[CB].NHY\f[R])@T{
-\f[CB].HYPHENATION
-.br
-\f[R](\f[CB].HY\f[R])
-T}
-.
-\f[CB].NOJUSTIFY \f[R]@(=\f[CB].NJ\f[R])@T{
-\f[CB].JUSTIFY
-.br
-\f[R](\f[CB].J\f[R])
-T}
-.
-\f[CB].NONUMBER \f[R]@(=\f[CB].NNM\f[R])@T{
-\f[CB].NUMBER \f[I]n
-.br
-\f[R](\f[CB].NM\f[R])
-T}
-.
-\f[CB].NOPERIOD \f[R]@(=\f[CB].NPR\f[R])@T{
-\f[CB].PERIOD
-.br
-\f[R](\f[CB].PR\f[R])
-T}
-.
-\f[CB].NOTE text \f[R]@(=\f[CB].NT\f[R])@T{
-\f[CB].END NOTE
-.br
-\f[R](\f[CB].EN\f[R])
-T}
-.
-\f[CB].NPR\f[R]@(=\f[CB].NO PERIOD\f[R])@
-\f[CB].NT\f[R]@(=\f[CB].NOTE\f[R])@
-\f[CB].NUMBER APPENDIX \f[I]a\f[R]@@\f[CB].APPENDIX text
-\f[CB].NUMBER CHAPTER \f[I]n\f[R]@@\f[CB].CHAPTER text
-_
-\f[CB].P\f[R]@(=\f[CB].PARAGRAPH\f[R])@
-\f[CB].PAGE\f[R]@(=\f[CB].PG\f[R])@
-\f[CB].PAGE SIZE\f[R]@(=\f[CB].PAPER SIZE\f[R])@
-.
-\f[CB].PAPER SIZE \f[I]v\f[CB],\f[I]h\f[R]@T{
-(=\f[CB].PS\f[R]
-.br
-\f[CB].PAGE SIZE\f[R])
-T}@
-.
-\f[CB].PARAGRAPH \f[I]h\f[CB],\f[I]v\f[CB],\f[I]t \f[R]@(=\f[CB].P\f[R])@
-\f[CB].SKIP \f[I]n\f[R]@(=\f[CB].S\f[R])@\f[CB].BLANK \f[I]n \f[R](\f[CB].B\f[R])
-\f[CB].SP\f[R]@(=\f[CB].SPACING\f[R])@
-\f[CB].SPACING \f[I]n \f[R]@(=\f[CB].SP\f[R])@
-.
-\f[CB].PERIOD\f[R]@(=\f[CB].PR\f[R])@T{
-\f[CB].NOPERIOD
-.br
-\f[R](\f[CB].NPR\f[R])
-T}
-.
-\f[CB].PG\f[R]@(=\f[CB].PAGE\f[R])@
-\f[CB].PITCH\f[R]@(=\f[CB].PIT\f[R])@
-
-.\f[CB].PRINT INDEX \f[R]@(=\f[CB].PX\f[R])@T{
-\f[CB].DO INDEX text
-.br
-\f[R](\f[CB].DX\f[R])
-T}
-.
-\f[CB].PS\f[R]@(=\f[CB].PAPER SIZE\f[R])@
-\f[CB].PX\f[R]@(=\f[CB].PRINT INDEX\f[R])@
-_
-\f[CB].RIGHT MARGIN \f[I]n \f[R]@(=\f[CB].RM\f[R])@
-\f[CB].RM\f[R]@(=\f[CB].RIGHT MARGIN\f[R])@
-_
-\f[CB].S\f[R]@(=\f[CB].SKIP\f[R])@
-\f[CB].SD\f[R]@(=\f[CB].STANDARD\f[R])@
-\f[CB].ST\f[R]@(=\f[CB].SUBTITLE\f[R])@
-\f[CB].SUBPAGE\f[R]@@\f[CB].END SUBPAGE
-\f[CB].SUBTITLE \f[I]text \f[R]@(=\f[CB].ST\f[R])@
-_
-\f[CB].T\f[R]@(=\f[CB].TITLE\f[R])@
-\f[CB].TAB STOPS \f[I]n,n, \*[Ellipsis] ,n \f[R]@(=\f[CB].TS\f[R])@
-\f[CB].TEST PAGE \f[I]n \f[R]@(=\f[CB].TP\f[R])@
-\f[CB].TITLE text\f[R]@(=\f[CB].T\f[R])@
-\f[CB].TP\f[R]@(=\f[CB].TEST PAGE\f[R])@
-\f[CB].TS\f[R]@(=\f[CB].TAB STOPS\f[R])@
-_
-\f[CB].UC\f[R]@(=\f[CB].UPPER CASE\f[R])@
-.
-\f[CB].UPPER CASE\f[R]@(=\f[CB].UC\f[R])@T{
-\f[CB].LOWER CASE
-.br
-\f[R](\f[CB].LC\f[R])
-T}
-.
-_
-\f[CB].X\f[R]@(=\f[CB].INDEX\f[R])@
-.
-.TE
-.
-.hy
-.fi
-.
-.
-.\" End of tbl ----------------------------------------------------------------
-.
-.
-.if t \{
-.  endTBL
-.\}
-.
-.
-.\" use groff_hdtbl
-.if t \{
-.  mso hdtbl.tmac
-.  TableHDTBL
-.\}
-.
-.
-.\" --------------------------------------------------------------------
-.SH EXPERIMENTAL ADDITIONS 1965
-.\" --------------------------------------------------------------------
-.
-.
-These
-.I "control words"
-are documented in
-.FONT CI Saltzer R 's
-documentation of 1965.
-.
-It is unsure whether they were really implemented.
-.
-.
-.P
-In this documentation, all
-.I control words
-are written in
-.IR "lower case" .
-.
-The writing in
-.I upper case
-is not mentioned, the same is true for
-.IR abbreviations .
-.
-So this documentation uses only
-.IR "lower case" . 
-.
-.
-.TP
-.FONT CB .FIGURE
-This
-.I control word
-turns control over to a 
-.I figure
-.IR processor ,
-which creates in
-.I core memory
-a representation of a
-.I flow diagram
-under the control of a few special
-.IR "control words" .
-When the
-.I control word
-.FONT CB ".END FIGURE"
-is encountered, the completed picture is printed immediately on the
-page being generated if there is room on that page; otherwise the
-.I figure
-will appear at the top of the next page.
-.
-.
-.RS
-.
-.
-.P
-Text following the
-.FONT CB ".END FIGURE"
-.I control word
-will be smoothly attached to text before the
-.FONT CB .FIGURE R .
-.
-No break is generated.
-.
-(Restriction: If a
-.I figure
-is being held for placement at the top of the next page, another
-.I figure
-may not be encountered before the first one is printed.)
-.
-.
-.P
-The only
-.I control words
-which are recognized when in the
-.I \%figure processor
-are the following three:
-.FONT CB .FRAME R ,
-.FONT CB .BOX R ,
-and
-.FONT CB ".END FIGURE" R .
-.
-.
-.RE
-.
-.
-.TP
-.FONT CB .FRAME I " m n"
-This
-.I control word
-intitalizes the
-.I figure  processor
-by giving the height and width of the figure to be produced.
-.
-.I m
-is
-the height, in lines; and
-.I n
-is the width, in characters.
-.
-(Note that a 1050 types 6 lines per inch, and 10 characters per inch.)
-.
-.
-.RS
-.
-.
-.P
-Any attempt to place items in the picture which extend beyond the
-boundaries will cause an error comment to be generated.
-.
-.I \%m
-and
-.I \%n
-must both be less than 100 and their product must be smaller than
-5400.
-.
-We may now think of the
-.I figure
-to be produced as an array of
-.I m
-times
-.I n
-elements.
-.
-.
-.RE
-.
-.
-.TP
-.FONT CB .BOX I " i j"
-The text on the lines following this
-.I control word
-will be placed in the
-.I figure
-such that the first character on the first line following the
-.FONT CB .BOX
-will appear in row
-.IR i ,
-character position
--IR j .
-.
-The end of the text is indicated by a
-.FONT CB .BOX
-.I control word
-for another piece of text or the
-.FONT CB ".END FIGURE"
-.I control
-.IR word .
-.
-Temporarily, the text should not include underlined or overtyped
-characters.
-.
-.
-.TP
-.FONT CB ".END FIGURE"
-This
-.I control word
-causes control to return to the regular
-.I control processor
-of the
-.FONT CB .RUNOFF
-command, for the decision to print the picture.
-.
-Note that another
-.FONT CB .FIGURE
-.I control word
-may not appear until after this
-.I figure
-has been printed.
-.
-.
-.RS
-.P
-One further
-.I control word
-has been added which is intended to facilitate bringing out revised
-editions of a memorandum.
-.
-.
-.RE
-.
-.
-.TP
-.FONT CB .FLAG
-The next line to be printed after this
-.I control word
-is encountered will have an asterisk placed two spaces to the right of
-the right margin, as illustrated.
-.
-.
-.TP
-.FONT CB .DEFINE I " symbol"
-.
-This
-.I control word
-defines  the  value  of  the  symbol
-.I symbol
-to be the number of the page currently being printed.
-.
-The symbol may be used later with the
-.FONT CB .USE
-.I control word
-to cause printing of the page number in text.
-.
-The characters in the symbol must be mappable into the six\-bit
-character set, and all symbols must be six of fewer characters.
-.
-.
-.TP
-.FONT CB .USE I " symbol"
-The value of the symbol
-.I symbol
-is inserted into the text with a single blank preceding and no blank
-following.
-.
-If the symbol has not been previously defined, its value is
-.FONT CB 0 R .
-Text may continue following a blank typed after the symbol.
-.
-.
-.RS
-.
-.
-.P
-Here is an example of the use of these
-.I control
-.IR words .
-.
-.
-.RS
-.
-.
-.P
-In one area of text:
-.
-.
-.RS
-.
-.
-.P
-We now discuss the operation of the typewriter
-.FONT CB ".DEFINE REF1"
-coordinator module, which \*[Ellipsis]
-.
-.
-.RE
-.
-.
-.P
-In a later area of text:
-.
-.
-.RS
-.
-.
-.P
-As we saw in the discussion of the typewriter coordinator on page
-.FONT CB ".USE REF1" R ,
-the rest of \*[Ellipsis]
-.
-.
-.RE
-.
-.
-.P
-if the first area of text were on page 14, the later line would read:
-.
-.
-.RS
-.
-.
-.P
-As we saw in the discussion of the typewriter coordinator on page 14,
-the rest of \*[Ellipsis]
-.
-.
-.RE
-.RE
-.RE
--
-.
-.\" --------------------------------------------------------------------
-.SS Further Study of Experimental Additions
-.\" --------------------------------------------------------------------
-.
-A number of suggestions have been made for extending the
-.I control word
-language of
-.FONT CI RUNOFF R ,
-and its capabilities.
-.
-These are listed here, primarily to elicit comment and discussion,
-both on the language which describes these operations and the less
-important problem of their implementation.
--
-.
-.TP
-1.
-.
-Word division.
-.
-This is a whole are of study in itself.
-.
-.
-.TP
-2.
-.
-Automatic  footnote  insertion.
-.
-This was handled somewhat awkwardly in the
-.FONT CB .DITTO
-.IR command ,
-although the basic approach was probably reasonable.
-.
-.
-.TP
-3.
-.
-Automatic page references, perhaps via some symbolic reference scheme.
-.
-This would enable the page number in "as was described on page 32" to
-be inserted by the program.
-.
-The analogy with an assembly program should be hotly pursued for
-ideas.
-.
-.
-.TP
-4.
-.
-Special provision for printing facing pages.
-.
-This would require alternate running heads, placing page numbers
-alternately at right and left, and matching line counts on facing
-pages.
-.
-.
-.TP
-5.
-.
-Improved page\-division rules, to prevent the last line of a paragraph
-appearing alone at the top of a page, for example.
-.
-At present, copy must be run off to check by hand that awkward page
-divisions have not been made.
-.
-.
-.TP
-6.
-.
-Automatic generation of page numbers for a table of contents.
-.
-Again, the analogy of an assembly program symbol table appears
-fruitful.
-.
-.
-.TP
-7.
-.
-Automatic generations of an index.
-.
-The problem here is obtaining too many references to a given word,
-many irrelevant.
-.
-.
-.TP
-8.
-.
-Arrangement of tabulated data.
-.
-This problem may have already been partly approached with the
-above\-described figure generator, or the facilities already available
-in
-.IR RUNOFF ,
-but automatic setup of column widths and positions would be desirable.
-.
-One could include in this category the ability to call on other
-programs to computer numbers to place in tables, although this is
-going pretty far afield.
-.
-.
-.TP
-9.
-.
-Placing figures in a
-.I "cut"
-or
-.IR inset .
-.
-The control language is the most difficult problem here.
-.
-.
-.TP
-10.
-.
-Equation typing and  numbering.
-.
-Again, the control language appears formidable.
-.
-.
-.\" --------------------------------------------------------------------
-.SH "SEE ALSO"
-.\" --------------------------------------------------------------------
-.
-.PP
-.\" BR RUNOFF (@MAN1EXT@),
-.BR groff (@MAN1EXT@),
-.BR groff (@MAN7EXT@),
-.BR roff (@MAN7EXT@),
-.BR groff_filenames (@MAN7EXT@)
-.
-.
-.TP
-.FONT R "1964 " CR "Jerome H. Saltzer" R :
-.nh
-.FONT CI "Jerome H. Saltzer \[em] TYPSET and RUNOFF, Memorandum editor and \
-type\-out commands"
-.hy
-available at
-.UR \%http://\:mit.edu/\:Saltzer/\:www/\:publications/\:CC\-244.html
-.UE
-.
-.
-.TP
-.FONT R "1965 " CR "Jerome H. Saltzer" R :
-.nh
-.FONT CI "Jerome H. Saltzer \(em Experimental Additions to the RUNOFF Command"
-available at
-.UR http://\:web.mit.edu/\:afs/\:athena.mit.edu/\:user/\:other/\
-\:a/\:Saltzer/\:www/\:publications/\:PSN\-40.html
-.UE
-.hy
-.
-.
-.TP
-.FONT R "1966 " CR "Jerome H. Saltzer" R :
-.nh
-.FONT CI "Jerome H. Saltzer \[em] Manuscript Typing and Editing"
-.hy
-which is available in the internet at
-.UR http://\:mit.edu/\:Saltzer/\:www/\:publications/\:AH.9.01.html
-.I MIT html
-.UE
-or
-.UR \%http://\:web.mit.edu/\:Saltzer/\:www/\:publications/\:ctss\/\:AH.9.01.html
-.I CTSS html
-.UE
-or
-.UR \%http://\:web.mit.edu/\:Saltzer/\:www/\:publications/\:ctss/\:AH.9.01.pdf
-.I CTSS pdf
-.UE .
-.
-.
-.TP
-.FONT R "1973 " CR "Larry Barnes" R :
-.FONT CI "Larry Barnes \[em] RUNOFF: A Program for the Preparation of Documents"
-available as
-.UR http://\:www.textfiles.com/\:bitsavers/\:pdf/\:sds/\:9xx/\:940/\
-\:ucbProjectGenie/\:mcjones/\:R\-37_RUNOFF.pdf
-.I pdf
-.UE .
-.
-.
-.TP
-.
-.P
-There is still more documentation by the
-.FONT CR "DEC PDP\-10 archive" R .
-.
-So far this information is not yet included, but it will be done later
-on.
-.
-.
-.P
-The latest
-.FONT CI RUNOFF
-documentation is file
-.FONT CB RUNOFF.DOC
-from 
-.FONT CR PDP\-11
-at 1981, see
-.FONT CR "SEE ALSO" R .
-.
-The content of this document is also included in this document.
-.
-.
-.P
-Look at section
-.FONT CR "SEE ALSO"
-for the internet connections to the documents.
-.
-.
-.\" --------------------------------------------------------------------
-.SS Early Environment 1963\-66
-.\" --------------------------------------------------------------------
-.
-.FONT CI Saltzer
-originally worked on
-.IR \%MIT 's
-.I \%CTSS time-sharing operating
-.IR \%system .
-.
-There he had an editor
-.FONT CB TYPSET
-that he also documented in the documentation cited above.
-.
-This editor was an ancestor for
-.BR \%ed (@MAN1EXT@).
-.
-.
-.P
-To use his
-.FONT CI RUNOFF
-language, he programmed a tool that he called
-.FONT CB RUNOFF R .
-.
-.
-.P
-There is still an emulator and the old source files for
-.FONT CB RUNOFF
-and
-.FONT CB TYPSET
-at
-.nh
-.UR http://\:www.cozx.com/\:~dpitts/\:ibm7090.html 
-.FONT CR "IBM 7090 CTSS"
-.UE .
-.hy
-.
-.
-.\" --------------------------------------------------------------------
-.SS The original RUNOFF program 1963-66
-.\" --------------------------------------------------------------------
-.
-The original
-.FONT CB RUNOFF
-program is also documented in the documentation of 1966 above.
-.
-.
-.P
-.FONT CI Saltzer
-uses upper case
-.FONT CB RUNOFF
-to denote his program.
-.
-So we will also use 
-.FONT CB RUNOFF
-to refer to the original program of 1963-66.
-.
-.
-.P
-This program has mainly the task to adjust a printer of that time and
-then print a
-.FONT CI RUNOFF
-document with this configuration.
-.
-Today this does not make much sense, but some parts are still
-available in the options of
-.BR \%groff (@MAN1EXT@),
-but under different names.
-.
-So we will not build this ancient program, but we will document its
-old command line here.
-.
-A lower case program
-.FONT CB runoff
-will be something different.
-.
-.
-.P
-.FONT CB RUNOFF
-is a command used to type out files of the
-.FONT CI RUNOFF
-language in manuscript format.
-.
-.I Control words
-scattered in the text may be used to provide detailed control over the
-format.
-.
-Input files may be prepared by the context editor
-.FONT CB TYPSET
-which does not exist today.
-.
-.
-.\" --------------------------------------------------------------------
-.SS Usage of RUNOFF Program
-\" --------------------------------------------------------------------
-.
-.SY RUNOFF
-.I \%filespec
-.RI [ "parameter \*[Ellipsis]" ]
-.YS
-.
-.
-.TP
-.I filespec
-is the primary name of a file to be typed out.
-.
-.TP
-.I parameter
-arguments are any number of the following parameters, in any order:
-.
-.
-.RS
-.
-.TP
-.FONT CB STOP
-Pause between pages.
-.
-.
-.TP
-.FONT CB NOWAIT
-Suppress the initial pause to load paper and the pause between pages
-(not necessary today).
-.
-.
-.TP
-.FONT CB PAGE I " n"
-Begin printing with the page numbered
-.IR n .
-.
-.
-.TP
-.FONT CB BALL I " n"
-Typewriter is using printing ball
-.IR n .
-If this parameter is omitted,
-.FONT CB RUNOFF
-assumes that the ball in use will properly print all
-.I CTSS characters
-in the file.
-.
-The number
-.I n
-is engraved on top of the printing ball.
-.
-.I CTSS characters
-not appearing on the ball being used will be printed as blanks, so
-that they may be drawn in.
-.
-This parameter does not make sense in our modern printers.
-.
-.RE
-.
-.
-.\" --------------------------------------------------------------------
-.SH THE ORIGINAL RUNOFF LANGUAGE OF 1966
-.\" --------------------------------------------------------------------
-.
-A
-.FONT CI RUNOFF
-file consists of
-.I command lines
-and
-.IR "text lines" .
-.
-The
-.I command lines
-start with a period (dot)
-.RB \(dq . \(dq,
-all other lines are
-IR "text lines" . 
-.
-.
-.P
-.I Command lines
-are also called
-.I command lines
-by
-.FONT CI Saltzer R .
-.
-.
-.\" --------------------------------------------------------------------
-.SS Text Lines and Conditions
-.\" --------------------------------------------------------------------
-.
-.FONT CI RUNOFF
-.I text lines
-are different from the
-.FONT CI groff
-language.
-.
-.
-.P
-As the early
-.FONT CI CTSS
-computers could only produce upper case characters, the text lines
-look very strange today.
-.
-This wasn't documented in the documentation of the 1960s.
-.
-But there is a good documentation of 1981 which contains also the old
-style.
-.
-Have a look at chapter
-.FONT CI "RUNOFF ADDITIONS 1981"
-section
-.FONT CI "Case Information"
-in this document.
-.
-.
-.P
-One or more
-.I blank lines
-are not printed, but mean a
-.IR "line break" .
-.
-This can also be reached by the
-.FONT CB .BREAK
-.IR "control word" .
-.
-.
-.P
-In
-.IR groff ,
-blank lines are printed as lines of their own.
-.
-This is not a paragraph break, because a line is bigger than a
-paragraph break.
-.
-.
-.P
-A text line that starts with one or more space characters means
-.IR "begin a new paragraph" .
-.
-.
-.P
-In
-.IR groff ,
-this will start a new line and inserts the space characters at the
-beginning of the line.
-.
-.
-.\" --------------------------------------------------------------------
-.SS Command Lines
-.\" --------------------------------------------------------------------
-.
-A command line begins with a period (dot)
-.RB \(dq . \(dq.
-.
-Following the dot
-.FONT CB RUNOFF
-expects a
-.IR "command name" .
-.
-This is called
-.I control word 
-by
-.FONT CI Saltzer
-.BI
-.
-.
-.P
-These
-.I command names
-or
-.I control words
-were defined by
-.FONT CI Saltzer
-as 1 or 2 words of arbitrary length.
-.
-or an
-.I abbreviation
-of defined 2 characters.
-.
-The later
-.FONT CI roff
-language uses only 2\-character requests; but
-.FONT CI groff
-expanded these to arbitrary length.
-.
-Each
-.I control word
-(1 or two words) can be written in upper or lower case as you like.
-.
-.
-.P
-Some
-.FONT CI "control words"
-are followed by a
-.I space
-and the
-.I parameters
-for that
-.IR command ,
-followed optionally by a comment (Comments are not documented
-further).
-.
-.
-.P
-Lines beginning with a dot but having an unrecognizable format are
-treated as errors.
-.
-.
-.P
-No lines beginning with a dot are printed unless the preceding line
-was a
-.I control line
-.FONT CB .LITERAL R .
-.
-All commands are described below.
-.
-Abbreviations for command names are normally based on the first two
-letters of a one word command or the first letter of the first two
-words of a multi\-word command.
-.
-Commands which should close a logical line break do.
-.
-Information on abbreviations and whether commands cause line breaks
-will be found in the summary at the end of the manual.
-.
-In a command line
-.FONT CB RUNOFF
-will consider multiple blanks as a single blank (space), if a blank
-character 1s legal.
-.
-.
-A
-.FONT CI RUNOFF
-document contains text separated by so\-called
-.IR "control words" .
-.
-As these are full lines, a better name would be
-.I "control lines"
-as is used in the documentation for
-.BR \%groff (@MAN7EXT@),
-.
-.
-.P
-These are lines starting with a period
-.RB ( . )
-and directly followed by a command with or without arguments.
-.
-The command names are arbitrarily long, they can even consist of
-several words, possibly followed by arguments.
-.
-.
-.P
-The
-.I "control words"
-can be written in lower or upper case, just as wanted.
-.
-Moreover, each command name can be shortened to an abbreviation of 2
-characters.
-.
-When the command name has only 1 word, the first 2 characters are taken.
-.
-.I Command names
-with 2 words abbreviate to the first character of each word.
-.
-These abbreviations led later to the 2 character
-.I \%requests
-of
-.IR \%roff .
-.
-.
-.P
-An example of a
-.I "control line"
-with a single
-.I "control word"
-with 2 arguments is a long name with lower case
-.IP
-.FONT CB .command I " arg1 arg2"
-.P
-or a long name with upper case
-.IP
-.FONT CB .COMMAND I " arg1 arg2"
-.P
-or an abbreviation with lower case
-.IP
-.FONT CB .co I " arg1 arg2"
-.P
-or an abbreviation with upper case
-.IP
-.FONT CB .CO I " arg1 arg2"
-.
-.
-.P
-Another example of a
-.I "control line"
-with 2
-.I "control words"
-with 1 argument is a long name with lower case
-.IP
-.FONT CB ".word1 word2" I " arg"
-.P
-or a long name with upper case
-.IP
-.FONT CB ".WORD1 WORD2" I " arg"
-.P
-or an abbreviation with lower case
-.IP
-.FONT CB .ww I " arg"
-.P
-or an abbreviation with upper case
-.IP
-.FONT CB .WW I " arg"
-.
-.
-.P
-These
-.I "control words"
-were renamed to
-.I requests
-later on in
-.FONT CI roff R .
-.
-.
-In the 1973 document, the words
-.I macros
-and
-.I formats
-are used without any documentation.
-.
-.
-.\" --------------------------------------------------------------------
-.SS Control Words (Command Names, Requests)
-.\" --------------------------------------------------------------------
-.
-The documentation for
-.I "control words"
-in this paragraph are taken from the
-.FONT CI RUNOFF
-documentation of 1966.
-.
-Often this documentation refers to the
-.FONT CB RUNOFF
-program that doesn't exist any more.
-.
-When the
-.FONT CI RUNOFF
-language will be implemented for
-.BR \%groff (@MAN1EXT@)
-these documentations must be adjusted.
-.
-.
-.TP
-.FONT CB .ADJUST
-.TQ
-.FONT CB .AD
-Enable
-.I fill
-mode.
-.
-The next line is the first one affected.
-.
-This is the default mode.
-.
-.
-.TP
-.FONT CB .APPEND I " file"
-.TQ
-.FONT CB .AP I " file"
-Take as the next input line the first line of
-.IR \%file .
-.
-Note that the whole of 
-.I \%file
-is appended, and that the appending is an irreversible process \[em] that
-is, once
-.FONT CB RUNOFF
-encounters the
-.FONT CB .APPEND
-.I "control line"
-it will switch to the file
-.I \%file
-and continue from the first line of
-.IR \%file .
-.
-All lines following the
-.FONT CB .APPEND
-.I "control line"
-will not be processed by
-.FONT CB RUNOFF R .
-.
-The file
-.I \%file
-may, of course, itself call for appending of still another file, and
-so on.
-.
-.
-.TP
-.FONT CB ".BEGIN PAGE"
-.TQ
-.FONT CB .BP
-Print out this page, start next line on a new page.
-.
-.
-.TP
-.FONT CB .BREAK
-.TQ
-.FONT CB .BR
-The lines before and after the
-.FONT CB .BREAK
-.I "control word"
-will not be run together by the
-.FONT CI fill
-mode of operation.
-.
-.
-.TP
-.FONT CB .CENTER
-.TQ
-.FONT CB .CD
-The following line is to be centered between the left and right
-margins.
-.
-.
-.TP
-.FONT CB ".DOUBLE SPACE"
-.TQ
-.FONT CB .DS
-Copy is to be double spaced.
-.
-This mode  takes  effect after the next line.
-.
-.
-.TP
-.FONT CB .FILL
-.TQ
-.FONT CB .FI
-Enable
-.IR "fill mode" .
-.
-That means: Lengthen short lines by moving words from the following
-line; trim long lines by moving words to the following line.
-.
-This is the default mode.
-.
-.FONT CB .NOFILL
-disables the
-.I fill
-mode.
-.
-.
-.TP
-.FONT CB .HEADER I " word1 word2 \*[Ellipsis]"
-.TQ
-.FONT CB .HE I " word1 word2 \*[Ellipsis]"
-All of the line after the first blank is used as a header line, and
-appears at the top of each page, along with the page number, if
-specified.
-.
-.
-.TP
-.FONT CB ".HEADING MODE" I " arg"
-.TQ
-.FONT CB .HM I " arg"
-This
-.I control sequence
-alters the mode of the running head to that specified by the parameter
-.IR \%arg .
-.
-Any of the following parameters are allowed for
-.IR \%arg:
-.
-.
-.\"  --------------------------------------------------------------------
-.RS
-.
-.
-.TP
-.FONT CB CENTER
-The header will be centered on the page.
-.
-.
-.TP
-.FONT CB MARGIN
-The header will be adjusted against the right margin of the page.
-.
-.
-.TP
-.FONT CB FACING
-On even\-numbered pages, the header will be adjusted against the left
-margin, on odd numbered pages against the right.
-.
-.
-.TP
-.FONT CB OPPOSED
-The header will be adjusted against the opposite margin from the page
-number.
-.
-In the absence of a
-.FONT CB ".HEADING MODE"
-.IR "control sequence" ,
-the default option is
-.FONT CB .OPPOSED R .
-.
-.
-.RE
-.\"  --------------------------------------------------------------------
-.
-.
-.TP
-.FONT CB .INDENT I " n"
-.TQ
-.FONT CB .IN I " n"
-The argument
-.I \%n
-is a number.
-.
-Set the number of spaces to be inserted at the beginning of each line
-to
-.IR \%n .
-.
-Indent is preset to 0.
-.
-.
-.TP
-.FONT CB ".LINE LENGTH" I " n"
-.TQ
-.FONT CB .LL I " n"
-The argument
-.I \%n
-is a positive number.
-.
-Set the line length to
-.IR \%n .
-.
-The line length is preset to 60.
-.
-.
-.TP
-.FONT CB .LITERAL
-.TQ
-.FONT CB .LI
-The following line is not a
-.IR "control word" ,
-despite the fact that it begins with a period.
-.
-.
-.TP
-.FONT CB .NOFILL
-.TQ
-.FONT CB .NF
-Disable
-.IR "fill mode" .
-.
-That means: Print all lines exactly as they appear without right
-adjustment or filling out.
-.
-In
-.I NOFILL
-mode each input line produces one output line; further blank lines are
-output in this mode.
-.
-Use the
-.FONT CB .FILL
-.I control word
-to restart
-.IR filling .
-.
-.
-.TP
-.FONT CB .NOJUST
-.TQ
-.FONT CB .NJ
-Disable
-.IR "fill mode" .
-.
-.
-.TP
-.FONT CB ".ODD PAGE"
-.TQ
-.FONT CB .OP
-This
-.I "control word"
-causes the current page to be printed out, and the next page to be
-numbered with the next higher odd page number.
-.
-.
-.TP
-.FONT CB .PAGE R " [" I n R ]
-.TQ
-.FONT CB .PA R " [" I n R ]
-Print page numbers.
-.
-(The first page is not given a page number.
-.
-It has instead a two\-inch top margin.
-.
-See also
-.FONT CB "Manuscript Conventions" R ,
-below.)
-.
-If argument
-.I \%n
-is present, insert a page break and number the next page
-.IR \%n .
-Note that
-.FONT CB RUNOFF
-does not print completely empty pages.
-.
-.
-.TP
-.FONT CB ".PAGING MODE" I " arg1 arg2 \*[Ellipsis]"
-.TQ
-.FONT CB .PM I " arg1 arg2 \*[Ellipsis]"
-This
-.I control sequence
-alters the mode of page numbering to that specified by the arguments.
-.
-The arguments may be in any order, and must be selected from the
-following list:
-.
-.
-.\"  --------------------------------------------------------------------
-.RS
-.
-.
-.TP
-.FONT CB MARGIN
-Page numbers will be adjusted against the right margin.
-.
-.
-.TP
-.FONT CB FACING
-Odd page numbers are adjusted against the right margin, even page
-numbers are adjusted against the left margin.
-.
-.
-.TP
-.FONT CB CENTER
-Page numbers are centered between the right and left margin.
-.
-.
-.TP
-.FONT CB TOP
-Page numbers are placed on the fourth line from the top of the page.
-.
-.
-.TP
-.FONT CB BOTTOM
-Page numbers are placed on the fourth line from the bottom of the
-page.
-.
-.
-.TP
-.FONT CB OFF
-Page numbers are discontinued.
-.
-.
-.TP
-.FONT CB PREFIX I " \(dqstring\(dq"
-The string of characters between quotation marks is prefixed to the
-page number.
-.
-The quotation marks may be next to each other, in which case no prefix
-is used.
-.
-.
-.TP
-.FONT CB ROMANU
-Page numbers will be printed in upper case Roman numerals.
-.
-.
-.TP
-.FONT CB ROMANL
-Page numbers will be printed in lower case Roman numerals.
-.
-.
-.TP
-.FONT CB ARABIC
-Page numbers will be printed in Arabic.  (This is the normal mode.)
-.
-.
-.TP
-.FONT CB SET I " n"
-Set the next page number to be the positive number
-.IR \%n .
-.
-.
-.TP
-.FONT CB SKIP I " n"
-Skip
-.I \%n
-page numbers.
-.
-.
-.P
-If in a single use of
-.FONT CB ".PAGING MODE"
-several arguments specify competing functions, the last one specified
-takes precedence.
-.
-When the
-.FONT CB ".PAGING MODE"
-sequence appears in text at point A, all text up to A (and probably
-some text after A) will appear on a page controlled by the previous
-paging mode.
-.
-The new
-.I paging mode
-will take effect on the next page.
-.
-Then there is no danger of getting page numbers both at the top and
-bottom of the same page.
-.
-.
-.P
-Use of the
-.FONT CB TOP
-parameter may conflict with the
-.I \%heading
-.IR \%mode .
-.
-If a heading and a page number should be printed in the same column,
-the page number will take precedence.
-.
-In the absence of a
-.FONT CB ".PAGING MODE"
-.I control
-.IR sequence ,
-the default options are:
-.FONT CB "TOP MARGIN PREFIX \(dqPAGE\(dq" R .
-.
-.
-.RE
-.\"  --------------------------------------------------------------------
-.
-.
-.TP
-.FONT CB ".PAPER LENGTH" I " n"
-.TQ
-.FONT CB .PL I " n"
-This
-.I control word
-is used for running off a documentation file on non\-standard paper.
-.
-The number
-.I \%n
-is a line count, figured at 6 lines per inch.
-.
-If this
-.I control word
-is not given,
-.I n
-is assumed to be 66, for 11\-inch paper.
-.
-.
-.TP
-.FONT CB ".SINGLE SPACE"
-.TQ
-.FONT CB .SS
-Copy is to be single spaced.
-.
-This mode takes effect after the next line.
-.
-(The normal mode is single space.)
-.
-.
-.TP
-.FONT CB .SPACE R " [" I n R ]
-.TQ
-.FONT CB .SP  R " [" I n R ]
-Insert
-.I \%n
-vertical spaces (carriage returns) in the copy.
-.
-If
-.I \%n
-carries spacing to the bottom of a page, spacing is stopped.
-.
-If
-.I \%n
-is absent or 0, one space is inserted.
-.
-.
-.TP
-.FONT CB .UNDENT I " n"
-.TQ
-.FONT CB .UN I " n"
-In an indented region, this
-.I control word
-causes a break, and the next line only will be indented n spaces fewer
-than usual.
-.
-This
-.I "control word"
-is useful for typing indented numbered paragraphs.
-.
-.
-.\" --------------------------------------------------------------------
-.SH RUNOFF ADDITIONS 1973
-.\" --------------------------------------------------------------------
-.
-Here are described only the additional
-.I control words
-that are documented in the 1973 documentation.
-.
-.\" --------------------------------------------------------------------
-.SS Formats
-.\" --------------------------------------------------------------------
-.
-.
-.TP
-.FONT CB .FORMAT I " name"
-This command causes subsequent text to be output under the control of
-tne specified format (see below at
-.FONT CB ".DEFINE FORMAT" R ).
-.
-Each following logical line will be fit into the format until a
-.FONT CB .FILL
-or
-.FONT CB .NOFILL
-command 1s encountered.
-.
-.
-.TP
-.FONT CB ".DEFINE FORMAT" I " <name> <pos> <field_ definition> \
-\*[Ellipsis]"
-.TQ
-.FONT CB ".END FORMAT"
-These commands define a format for use in producing tables, etc.
-.
-.
-.RS
-.
-.
-.TP
-.I <name>
-identifies the format.
-.
-It can be activated by the
-.FONT CB .FORMAT
-.IR command .
-.
-.
-.TP
-.I <pos>
-is the position and may be one of
-.FONT CB LEFT R ,
-.FONT CB RIGHT R ,
-or
-.FONT CB CENTER R ,
-and determines the overall positlon of the format with respect to the
-margins.
-.
-.
-.TP
-.I <field_definition>
-There can be several arguments of this type.
-.
-Each has the form:
-.
-.
-.RS
-.
-.FONT CI <type> CB ( CI "<letter> \*[Ellipsis] <letter>" CB )
-.
-.P
-where the
-.FONT CI <type>
-is one of
-.
-.TP
-.FONT CB L
-for left,
-.
-.TP
-.FONT CB R
-for riqht,
-.
-.TP
-.FONT CB C
-for center,
-.
-.TP
-.FONT CB F
-fer fill, or
-.FONT CB J
-for justify.
-.
-.
-.P
-The first three types define fixed fields; the text to be formatted
-must fit within the allocated space.
-.
-The latter types define variable fields; the text will be handled as
-in normal fill mode processing.
-.
-.
-.P
-A picture showing the manner in which text should be output follows
-the
-.FONT CB ".DEFINE FORMAT"
-command; following the picture should be an
-.FONT CB ".END FORMAT"
-command.
-.
-The following lines give an example:
-.
-.
-.RS
-.  ft CB
-.  nf
-.  nh
-.    nop ".DEFINE FORMAT SUMMARY L(A) F(C) C(B)"
-.    nop "AAAA	CCCCCCCCCCCCCCCCCCCCCCCCC	BBBBBBB"
-.    nop "	CCCCCCCCCCCCCCCCCCCCCCCCC		"
-.    nop ".END FORMAT"
-.  hy
-.  fi
-.  ft
-.RE
-.
-.
-.P
-The first field of text is left justified; the second is centered; the
-third is subjected to
-.I fill mode
-processing without justification.
-.
-After the first line of output is generated using this format, all
-subsequent lines are produced using the last picture 1ine.
-.
-(Strictly speaking the third line is unnecessary.)
-.
-.
-.P
-Text for formatted processing consists of a logical line (or
-paragraph).
-.
-Each field except the last must be separated by
-.IR tab .
-.
-The
-.I tab character
-is displayed here as backslash character
-.FONT R ( CB \[rs] R ).
-.
-.
-.P
-The first field of text is
-.FONT CB A R ,
-the second
-.FONT CB B R ,
-etc.
-.
-Typical input for our example might be:
-.
-.
-.RS
-.nf
-.nh
-|A\\YES\\/THIS IS SOME TEXT
-TO BE FILLED.
-.hy
-.fi
-.RE
-.
-.
-.P
-The characters 1n the picture lines were 1nterpreted as follows.
-.
-Contiguous sequences of letters determine the fie1d positions;
-non\-alphabetic characters are output literally.
-.
-(Note:
-.FONT CB Q.QQ
-wi11 not work, put the period
-.RB \[dq] . \[dq]
-in the text.
-.
-A sequence of characters written between double quotes is considered
-literal text.
-.
-The
-.I double quotes
-are not output, and there is no way to use
-.I double quote
-as a
-.IR literal .
-.
-.
-.\" --------------------------------------------------------------------
-.SS Hyphenation Processing
-.\" --------------------------------------------------------------------
-.
-.TP
-.FONT CB .HYPHENATE
-Enable
-.IR "hyphenation mode" .
-.
-This is the default when starting up.
-.
-The
-.FONT CB RUNOFF
-program used a small
-.I glossary
-for splitting.
-.
-In
-.I hyphenation mode
-.FONT CB RUNOFF
-would try to find a word 1n the glossary which is the same (except for
-the endings
-.FONT CB \-S R ,
-.FONT CB \-ES R ,
-.FONT CB \-ED R ,
-and
-.FONT CB \-E R )
-as the word at the end of the line of text.
-.
-When running in
-.BR groff (1)
-there are
-.I glossaries
-being much more complete than in
-.BR RUNOFF .
-.
-.
-.TP
-.FONT CB .NOHYPHEN
-Disable
-.IR "hyphenation mode" .
-.
-.
-.TP
-.FONT CB .GLOSSARY I " word"
-This command inserts words into the
-.I glossary
-for use in
-.IR hyphenation .
-.
-Each word should have the form
-.FONT CB hy\[hy]phen\[hy]ate
-and be separated by spaces.
-.
-.
-.TP
-.FONT CB ".HYPHENATION BREAK" I " n"
-This command set the parameter which determines the allowable number
-of spaces to te inserted in a line before
-.FONT CB RUNOFF
-tried to hyphenate the last word.
-.
-Each space counts ten points.
-.
-If more than
-.I n
-points per word would have to be inserted, then
-.I hyphenation
-will be attempted.
-.
-The initial setting of this parameter is 5 (one\-half space per word).
-.
-.
-.\" --------------------------------------------------------------------
-.SS Margin Controls
-.\" --------------------------------------------------------------------
-.
-There are two types of margins involved in
-.FONT CI RUNOFF R .
-.
-.
-.TP
-(1)
-The physical margins.
-.
-These are determined by the nature of the printing device.
-.
-The margins outline the area where it is physically possible to print
-characters.
-.
-.
-.TP
-(2)
-.
-The logical margins.
-.
-These can be set bv the user as he wishes.
-.
-(Limits are imposed by the physical margins.)
-.
-They are initialized for standard 8.5\[dq] by 11\[dq] printing.
-.
-.
-.P
-Commands concerning vertical and horizontal margins are:
-.
-.
-.TP
-.FONT CB ".PAGE LAYOUT TM, EM, TOL"
-This sets the vertical logical margins and vertical tolerence.
-.
-Parameters are top margin, bottom margin and tolerance.
-.
-The tolerance is used to determine where to break between pages on
-page overflows.
-.
-If
-there is a line break within
-.I TCL lines
-of the bottom,
-.FONT CB RUNOFF
-will break the page there; otherwise it will fill the page completely.
-.
-.
-.TP
-.FONT CB ".LINE LAYOUT LM, RM, NO, CS"
-This sets the logical left and right margin, the number of columns,
-and the number of spaces to insert between columns.
-.
-These margins are used for the page headings.
-.
-To adjust the relative
-text position, use the subsequent commands.
-.
-.
-.TP
-.FONT CB ".REDUCE MARGIN LM, RM"
-.TQ
-.FONT CB ".EXPAND MARGIN LM, RM"
-.TQ
-.FONT CB ".END REDUCTION"
-These commands enable the user to indent a certain portion of his text
-using the first command, or
-.FONT CB .UNDENT
-his text using the second command.
-.
-In either case the original margins are restored by the third command.
-.
-The use of several
-.FONT CB ".REDUCE MARGIN"
-commends before the corresponding
-.FONT CB ".END REDUCTION"
-commands succesively indents the text more, and more.
-.
-Thus these commands are 1ike brackets (i.e. recursive).
-.
-.FONT CB LM
-is added to the left logical margin and
-.FONT CB RM
-is subtracted from the right logical margin in the first command.
-.
-Just
-the opposite is done on the second command.
-.
-Negative numbers are permitted.
-.
-These commands do not effect the position of page headings.
-.
-.
-.TP
-.FONT CB ".LAYOUT PLM, PRM, PTM, PBM, LL, LO"
-This command defines the physical margins in the followinq complex
-manner.
-.
-(It should only be used for non\-standard devices, normally this
-command should not be necessary.)
-.
-The parameters are the physical left margin (in spaces), the physical
-right margin, the physical top 1ine, the physical bottom line, the
-line lenqth, and line origin.
-.
-The first four parameters define the physical 1imits of the printing
-device.
-.
-The final two parameters define the length of the logical line and its
-origin with respect to the left edge of the paper.
-.
-Printing starts at column
-.FONT CB "LO + LM" R ,
-and ends at
-.FONT CB "LO + RM" R ,
-where
-.FONT CB LM
-and
-.FONT CB RM
-are the logical margins established by
-.FONT CB ".LINE LAYOUT" R .
-.
-When using the
-.FONT CI "facing feature"
-(see
-.FONT CB ".PAGING MODE" R ),
-the logical left margin is
-.FONT CB "LL \[em] RM"
-on even pages, and the right margin is
-.
-.FONT CB "LL \[em] LM" R .
-.
-The parameters for the layout command must satisfy:
-.
-.RS
-.RS
-.nh
-.nf
-.ft CB
-.nop "min(LO + LL \[em] PLM, PRM \[em] LO) > max(PLM \[em] LO, \
-LO + LL \[em] PRM)\f[],\f[CB]"
-.nop LL > 25\f[], and \f[CB]PBM \[em] PTM > 6\f[]
-.fi
-.hy
-.RE
-.
-.
-.P
-This command sets
-.FONT CB LM
-to 15,
-.FONT CB RM
-to
-.FONT CB "LL \[em] 10" R ,
-.FONT CB TM
-to
-.FONT CB PTM R ,
-and
-.cb BM
-to
-.FONT CB "PBM \[em] 6" R .
-.
-(These margin settings produce the standard 1.5 inch left, and 1 inch
-right, too, and bottom margins.)
-.
-.RE
-.
-.
-.P
-Initially
-.FONT CB RUNOFF
-sets the margins for
-.I teletype
-output to:
-.
-.
-.RS
-.RS
-.nh
-.nf
-.ft CB
-.nop .LAYOUT 6, 89, 6, 66, 8S, 0
-.nop .LINE LAYOUT 15, 75
-.nop .FILL
-.ft
-.fi
-.hy
-.RE
-.RE
-.
-.
-.P
-The printer layout is:
-.
-.RS
-.RS
-.nh
-.nf
-.ft CB
-.nop ".layout 5, 137, 6, 66, 85, 15"
-.nop ".page layout 6, 60, 4"
-.ft
-.fi
-.hy
-.RE
-.RE
-.
-.P
-The logical margins must satisfy:
-.
-.RS
-.RS
-.nh
-.nf
-.ft CB
-.nop min(LL, PRM \[em] LO, LO \[em] LL \[em] PLM) >= RM >
-.nop "     LM >= max(0, PLM \[em] LO, LO + LL \[em] PRM)" \f[],\f[CB]
-.nop "PBM >= BM > TM >= PTM" "\f[], and\f[CB]"
-.nop BM \[em] TM > TOL\f[].
-.fi
-.hy
-.RE
-.RE
-.
-.
-.\" --------------------------------------------------------------------
-.SS Paragraph Formatting
-.\" --------------------------------------------------------------------
-.
-.TP
-.FONT CB ".PARAGRAPH SPACING" I " n"
-.
-This specifies how many lines are to be inserted between paragraphs.
-.
-Initial setting = 1.
-.
-.
-.TP
-.FONT CB ".PARAGRAPH INDENTATION" I " n"
-This specifies how many additional spaces to insert at the beginning
-of a paragraph.
-.
-Initial setting = 5.
-.
-.
-.TP
-.FONT CB ".PARAGRAPH UNDENTATION" I " n"
-This command is the same as
-.FONT CB ".PARAGRAPH INDENTATION" I " \-n" R .
-.
-That is,
-.I n
-fewer spaces are inserted at the beginning of the paragraph.
-.
-.
-.\" --------------------------------------------------------------------
-.SS Special Line Justification and Control
-.\" --------------------------------------------------------------------
-.
-These commands pertain to the next logical line.
-.
-The end of the line should be designated with a break.
-.
-.
-.TP
-.FONT CB .CENTER
-.
-Center the next line.
-.
-.
-.TP
-.FONT CB .INDENT I " n"
-.
-Indent the next line
-.I n
-spaces.
-.
-If
-.I n
-is not provided, 5 is assumed.
-.
-.
-.TP
-.FONT CB .UNDENT I " n"
-.
-Start the next line
-.I n
-spaces to the left of the normal margin.
-.
-This command is the same as
-.FONT CB .INDENT I " \-n" R .
-.
-.
-.TP
-.FONT CB .MARGIN
-Justify the next 1ine against the right hand margin.
-.
-.
-.\" --------------------------------------------------------------------
-.SS Heading and Paging
-.\" --------------------------------------------------------------------
-.
-.TP
-.FONT CB .HEADER I " XXXXXXX"
-.FONT CB RUNOFF
-accepts a heading to go on the first line of
-each paqe.
-.
-The heading strinq is assured to start at the first non\-blank
-character after thd control word and end at carriage return.
-.
-.
-.TP
-.FONT CB ".HEADING MODE" I " <param>"
-.I <param>
-determines the position of the heading on the 11ne.
-.
-.I <param>
-may be any of the following.
-.
-.
-.RS
-.
-.TP
-.FONT CB CENTER
-The header will be centered on the 1ine.
-.
-.
-.TP
-.FONT CB MARGIN
-The header will be adjusted against the riqht margin.
-.
-.
-.TP
-.FONT CB PAGING
-On even numbered pages tne header is adjusted against the right
-margin.
-.
-On odd pages it is adjusted against the left mergin.
-.
-.
-.TP
-.FONT CB OPPOSED
-The header will be adjusted against the opposite margin from the
-page numter.
-.
-This is the initial mode.
-.
-.RE
-.
-.
-.TP
-.FONT CB ".PAGING MODE" I " <param>"
-.
-This command determines the placing of the page number.
-.
-All parameters are optional.
-.I <param>
-may be anyone or more of the following oommands.
-.
-In case of conflict the latest command wins.
-.
-.RS
-.
-.TP
-.FONT CB CENTER
-The page numbers are centered between the logical margins.
-.
-.TP
-.FONT CB MARGIN
-The page number is adjusted against the right margin.
-.
-.TP
-.FONT CB FACING
-On even numbered pages the number will be adjusted against the right
-margin.
-.
-On odd numbered pages tne number will be adjusted against the
-left margin.
-.
-.TP
-.FONT CB TOP
-Page numbers are placed on the first line.
-.
-.TP
-.FONT CB BOTTOM
-Page numbers are placed on the last line.
-.
-.TP
-.FONT CB OFF
-Printing page numbers is discontinued.
-.
-.TP
-.FONT CB PREFIX I " <string>"
-.TQ
-.FONT CB SECTION I " <string>"
-.TQ
-.FONT CB SUFFIX I " <string>"
-The strings of characters between quotation marks are used to form the
-page. string, which has the form:
-.
-.RS
-.I <prefix><section><page number><suffix>
-.
-.P
-Any or all of these strings mav be null.
-.
-The section string is considered to be part of the page number for
-purposes of indexing.
-.
-.RE
-.P
-Initial mode is:
-.
-.RS
-.RS
-.ft CB
-.nop ".PAGING MODE TOP MARGIN PREFIX \[dq]Page\[dq]"
-.nop ".PAGING MODE SECTION \[dq]\[dq] SUFFIX \[dq]\[dq]"
-.RE
-.RE
-.
-.
-.P
-If neither page number nor heading is used, the text will start on the
-first logical line.
-.
-Otherwise it will start on the fourth logical line.
-.
-If the page number is at the bottom, text will end on the fourth line
-from the bottom.
-.
-If the paging and headinq mode conflict, the page string overwrites
-the heading.
-.
-.RE
-.
-.
-.TP
-.FONT CB ".ODD PAGE"
-This
-.FONT CI "control word"
-causes the ourrent page to be printed out and the next page to be
-started with the next higher odd number.
-.
-.
-.TP
-.FONT CB .PAGE I " n"
-If
-.I n
-is present, insert a page break and start numbering the next pege
-with
-.IR n .
-Otherwise, turn the
-.I paging mode
-on and do not insert a page break.
-.
-.
-.TP
-.FONT CB .EJECT I " n"
-Insert a page break if either there are fewer than
-.I n
-lines left on the page or
-.I n
-is not present.
-.
-.
-.\" --------------------------------------------------------------------
-.SS Lines and Spacing
-.\" --------------------------------------------------------------------
-.
-.TP
-.FONT CB ".SINGLE SPACE"
-Sing1e space all 1ines within paragraphs.
-.
-This is the initial state.
-.
-.
-.TP
-.FONT CB ".DOUBLE SPACE"
-Double space all lines within paragraphs.
-.
-.
-.TP
-.FONT CB .SPACE I " n"
-Output
-.I n
-1ine spaces.
-.
-If
-.I n
-is not provided, 1 is assumed.
-.
-In case of page overflow all remaining blank 1ines to be output are
-deleted.
-.
-.
-.TP
-.FONT CB ".FIGURE SPACING" I " n"
-This command is equivalent to
-.FONT CB .EJECT I " n"
-followed by
-.FONT CB .SPACE
-.IR n .
-.
-These commands provide the only means of creatinq blank 11nes.
-.
-.
-.TP
-.FONT CB .BREAK
-The lines before and after this command will not be run together in
-.IR "fill mode" .
-.
-A simpler way to get a line break is to insert one or more blank lines
-in the text.
-.
-.
-.TP
-.FONT CB ".BEGIN GROUP"
-.TQ
-.FONT CB ".END GROUP"
-The output lines enclosed between these two commands are forced to lie
-on a page.
-.
-Thus this command acts in a manner similar to
-.FONT CB .EJECT I " n" R ,
-where
-.I n
-has the 'right' value.
-.
-.
-.\" --------------------------------------------------------------------
-.SS Miscellanous
-.\" --------------------------------------------------------------------
-.
-.TP
-.FONT CB .UNDERLINE
-The following 1ine is underlined.
-.
-.
-.TP
-.FONT CB .LITERAL
-The next line is taken as part of text whether or not
-it begins with dot.
-.
-.
-.TP
-.FONT CB .ESCAPE I <char>
-.TQ
-.FONT CB .SHIFT I <char>
-.TQ
-.FONT CB ".TAB CHARACTER" I <char>
-The given character becomes the
-.IR escape ,
-.IR shift ,
-or
-.I tab
-character.
-.
-The parameter for the
-.FONT CB .SHIFT
-and
-.FONT CB ".TAB CHARACTER"
-commands may be null, if no
-.I shift
-or
-.I tab
-character is desired.
-.
-.
-.TP
-.FONT CB ".DEFINE COMMAND" I " <name>"
-.TQ
-.FONT CB ".END COMMAND"
-.TQ
-.FONT CB .CALL I " <name>"
-These commands give the user the opportunity to combine text and
-control lines to form his own commands.
-.
-All text and command lines between the first and second commands is
-stored away under
-.IR name .
-.
-When the third command is executed, the stored string is read and the
-commands within the string are executed.
-.
-Recursion is not permitted.
-.
-.
-.TP
-.FONT CB .INDEX I " <phrase>, <phrase>"
-.
-.FONT CB RUNOfF
-saves the first phrase in the main index table and the second phrase
-(if any) in a sub\-index table associated with the first phrase.
-.
-.RS
-.
-The index is formatted and output after the last page of text.
-.
-Two built\-in but redefinable formats,
-.FONT CI RINDEX
-and
-.FONT CI SINDEX R ,
-are used to format the index as shown in the following example.
-.
-.RS
-.nh
-.nf
-.FONT CB "Algorithms, 40, 78," R "             \[rs]\[dq] uses " I RINDEX
-.FONT CB "  analysis of, 27, " R "             \[rs]\[dq] uses " I SINDEX
-.fi
-.hy
-.RE
-.
-.
-The following lines give the initial definitions for the indexing
-formats.
-.
-.
-.RS
-.nh
-.nf
-.ft CB
-.nop ".define format RINDEX f(A)"
-.nop "AAAAAAAAAAAAAAAAAAAAAAAAAAA"
-.nop "    AAAAAAAAAAIAAAAAAAAAAAA"
-.nop ".end format"
-.nop ".define format SINDEX f(A)"
-.nop "  AAAAAAAAAAAAAAAAAAAAAAAAA"
-.nop "    AAAAAAAAAAIAAAAAAAAAAAA"
-.nop ".end format"
-.ft
-.fi
-.hy
-.RE
-.
-.
-In order to get an index output in two columns,
-.RS
-.P
-.FONT CB ".LINE LAYOUT 15, 75, 2, 4"
-.P
-should be the last line of the input.
-.RE
-.
-.RE
-.
-.
-.\" --------------------------------------------------------------------
-.SH RUNOFF DOCUMENTATION 1974
-.\" --------------------------------------------------------------------
-.
-This document is the best documentation about text lines.
-.
-Parts of that is used in the document of 1981.
-.
-.
-.\" --------------------------------------------------------------------
-.SS Command Lines
-.\" --------------------------------------------------------------------
-.
-All lines beginning with a period (dot) are
-.FONT CI RUNOFF
-command lines.
-.
-All other lines are text lines.
-.
-.
-.P
-A command line consists of a period, following by a command, which can
-consist of one or more words, or a 2- or 3-letter abbreviation,
-followed by 0 or 1 or more arguments.
-.
-This can be followed by a comment, which is preceeded by an
-exclamation point (bang character)
-.FONT CB ! R .
-.
-In ancient 
-.FONT CI RUNOFF R ,
-The comment didn't need to be preceeded.
-.
-.
-.P
-In this document, several command or text lines can be appended into a
-multiple line if these parts are separated by a semi-colon
-.FONT CB ; R .
-.
-If 2 commands are appended, the semi-colon may be omitted, because the
-period is a sufficient separator.
-.
-.
-.\" --------------------------------------------------------------------
-.SS Text Lines
-.\" --------------------------------------------------------------------
-.
-.P
-There are 2 modes of text line structures:
-.
-.
-.TP
-.I ancient style
-This is the original style.
-.
-Due to very old hardware, there were only input methods for upper case
-characters.
-.
-But typewriters and printers were able to use both upper and lower case.
-.
-So the text lines are all in upper case with special characters that
-are case-shifters for the printing.
-.
-.
-.TP
-.I newer style
-By better hardware, it was possible to use input methods with both
-upper and lower case.
-.
-Here the text lines are like those in later
-.FONT CI roff
-and
-.FONT CI groff
-mode.
-.
-.
-.P
-This paragraph describes only the
-.I ancient style
-of text lines.
-.
-.
-.P
-This text is filled and justified such as with the later
-.FONT CI roff
-language.
-.
-Just as in
-.FONT CI roff R ,
-the filling, justification, and line break can be turned on or off by
-commands.
-.
-.
-.\" --------------------------------------------------------------------
-.SS Case Changing of Text Lines
-.\" --------------------------------------------------------------------
-.
-In this section, the specification of case for files prepared on an
-upper case terminal is documented.
-.
-There are special characters that in printing act as case-shifters for
-ASCII characters into lower (ASCII code 97 to 122 decimal) or upper
-case (ASCII code 65 to 90 decimal).
-.
-.
-.P
-The lower case mode seems to be the default mode.
-.
-Also, according to existing old
-.FONT CI RUNOFF
-files, each text line starts with this default mode.
-.
-.
-.TP
-.FONT CI "single circumflex " CB ^
-The following ASCII character is shifted into upper case.
-.
-.
-.TP
-.FONT CI "single back\-slash " CB \[rs]
-The following ASCII character is shifted into lower case.
-.
-.
-.TP
-.FONT CI "double circumflex " CB ^^
-The case mode is shifted into upper case.
-.
-.
-.TP
-.FONT CI "double back\-slash " CB \[rs]\[rs]
-The case mode is shifted into lower case.
-.
-.
-.P
-A common example with starting mode in lower case for these 4 special
-characters is:
-.
-.P
-.RS
-^HERE IS A ^SAMPLE ^SENTENCE IN ^^UPPER CASE\\ AND LOWER CASE.
-.RE
-.
-.P
-is printed as:
-.
-.RS
-Here is a Sample Sentence in UPPER CASE and lower case.
-.RE
-.
-.
-.\" --------------------------------------------------------------------
-.SS Further special Characters in Text Lines
-.\" --------------------------------------------------------------------
-.
-.TP
-.FONT CI "ampersand " CB &
-This is used for underscoring the next following character.
-.
-For example:
-.
-.RS
-.P
-.RS
-&s&o&f&t&w&a&r&e
-.RE
-.
-.P
-becomes:
-.RS
-.UL software
-.RE
-.
-.P
-in the output or printing.
-.RE
-.
-.
-.TP
-.FONT CI "circumflex and ampersand " CB ^&
-This is used for underscoring all following characters except for
-blanks.
-.
-.
-.\" --------------------------------------------------------------------
-.SH RUNOFF ADDITIONS 1981
-.\" --------------------------------------------------------------------
-.
-.\" --------------------------------------------------------------------
-.SS Source File Format
-.\" --------------------------------------------------------------------
-.
-The source file contains the textual material which will appear on the
-final copy, plus information to specify formatting.
-.
-Most importantly, upper and lower case information also may be
-supplied so that copy can be prepared on the terminal or other such
-device which can input only upper case letters.
-.
-All command information consists of regular
-.FONT CI ASCII
-printing characters so that a listing of the source file may be
-examined if the final copy is not exactly as desired.
-.
-.
-.P
-All material in the source file is taken to be source text except
-those lines beginning with a period.
-.
-A line beginning with a period is assumed to be a command, and must
-match one of those listed below.
-.
-The commands provide the formatting information, and control various
-optional modes of operation.
-.
-.
-.P
-Usually the text is
-.I filled
-and
-.I justified
-as it is processed.
-.
-That is, the program
-.I fills
-a line by adding successive words from the source text until one more
-word would cause the right margin to be exceeded.
-.
-The line is then
-.I justified
-by making the word spacings larger until the last word in the line
-exactly meets the right margin.
-.
-.
-.P
-The user may occasionally wish to reproduce the source text exactly,
-which is done by disabling
-.I filling
-and
-.I justification
-or by use of the
-.FONT CR .LITERAL
-command.
-.
-The program may be set to
-.I fill
-but not
-.IR justify ,
-in which case the output will be normal except that lines will not be
-justified to the right margin.
-.
-The program may also be set to
-.I justify
-but not
-.IR fill ,
-although this would probably produce peculiar results and is not
-recommended.
-.
-.
-.P
-When the
-.I fill mode
-is on, spaces and carriage returns occurring in the source text are
-treated only as word separators.
-.
-Multiple separators are ignored.
-.
-.
-.P
-Some of the commands cause a BREAK in the output.
-.
-A
-.I break
-means that the current line is output without justification, and the
-next word goes at the beginning of the next line.
-.
-This occurs at the end of paragraphs.
-.
-.
-.P
-The program will advance to new pages as necessary, placing the title
-(if given) and the page number at the top of each page.
-.
-The user may call explicitly for a
-.I page advance
-where desired, and may inhibit the occurrence of a
-.I page advance
-within specified material.
-.
-.
-.\" --------------------------------------------------------------------
-.SS Case Information of Text Lines
-.\" --------------------------------------------------------------------
-.
-The information in this section documents the style of the text lines
-that could only be upper case in the ancient
-.FONT CI CTSS
-computers of the early 1960s..
-.
-It seems as if this section documents the old
-.FONT CI RUNOFF
-style.
-.
-.
-.P
-Specification of
-.I case
-for files prepared on the terminal is done with two characters,
-circumflex 
-.FONT R ( CB ^ R , CI " 136 octal" R ),
-and
-.FONT CR back\-slash R " (" CB \[rs] R , CI " 134 octal" R ).
-The appearance of a circumflex causes the letter immediately following
-to be transmitted in upper case.
-.
-The appearance of a
-.FONT CR back\-slash
-causes the letter immediately following to be converted to lower case.
-.
-Any letter not preceded by one of these characters is transmitted in
-the current mode.
-.
-.
-.P
-The mode is initially
-.I "upper case"
-.FONT CB (wrong!) R .
-.
-(The initial mode seems to be
-.IR "lower case" .
-.
-That's the style used by the available
-.FONT CI RUNOFF
-files in the PDP-10 archive and by the example below.
-.
-And each newline seems to switch back to the initial mode, well:
-.IR "lower case" ). 
-.
-.
-.P
-The mode is changed by the occurrance of two successive
-.I case
-control characters.
-.
-Two
-.FONT CR circumflexes
-.FONT CB ^^
-cause the mode to be set to
-.IR "upper case" ,
-and two
-.FONT CR back\-slashes
-.FONT CB "\[rs]\[rs]"
-cause the mode to be set to
-.IR "lower case" .
-.
-.
-.P
-The use of the above corresponds to the use of the
-.FONT CR shift
-and
-.FONT CR shift\-lock
-keys on a typewriter.
-.
-Usually, typing appears in
-.IR "lower case" .
-To type one letter in
-.IR "upper case" ,
-the
-.FONT CR shift
-.I key
-is used.
-.
-The
-.FONT CR shift\-lock
-is set to type a series of
-.IR "upper case letters" ,
-after which it is released.
-.
-.
-.P
-The following shows the uses of the case control characters:
-.EX
-^HERE IS A ^SAMPLE ^SENTENCE IN ^^UPPER CASE\[rs]\[rs] AND LOWER CASE.  
-.EE
-becomes:
-.EX
-Here is a Sample Sentence in UPPER CASE and lower case.
-.EE
-.
-.
-.RS
-.P
-.ce
-NOTE
-.
-.P
-Case conversion takes place only on
-.FONT CI ASCII
-.I " codes"
-.FONT CR 101
-to
-.FONT CR "132 octal" R ,
-that is, the
-.I upper case
-letters.
-.
-Any actual
-.I lower case
-letters (codes
-.FONT CR 141
-to
-.FONT CR "172 octal" R )
-appearing in the source will be transmitted unchanged.
-.
-If the source is prepared on a device such as a
-.FONT CI DECwriter
-or model
-.FONT CI "37 Teletype"
-which produce letters of the proper
-.IR case ,
-the mode should be set to
-.I upper case
-at the beginning of the file and left unchanged for the remainder.
-.RE
-.
-.
-.P
-An additional character,
-.FONT CR less\-than
-.FONT R ( CR < R ,
-.FONT CR "074 octal" R ),
-capitalizes the entire word it precedes.
-.
-It then returns the file to the current
-.IR case .
-.
-This character is not engaged unless preceded by the
-.nh
-.FONT CB ".FLAGS CAPITALIZE"
-.hy
-.IR command .
-.
-Similarly, the
-.nh
-.FONT CB ".FLAGS HYPHENATE"
-.hy
-.I command
-engages the special character
-.FONT CR equals
-.FONT R ( CB = R , CR "075 octal" R ),
-which causes
-.I hyphenization
-to be suspended for the word it precedes.
-.
-.
-.\" --------------------------------------------------------------------
-.SS Special Characters
-.\" --------------------------------------------------------------------
-.
-.TP
-.FONT CB & CI " Ampersand    " CR Underscoring
-The character
-.FONT CI ampersand
-.FONT R ( CB & R ,
-.FONT CR "046 octal" R )
-is used to specify
-.UL underscoring .
-.
-The
-.FONT CI ampersand
-will cause the character following it to be
-.IR underscored ,
-e.g.
-.FONT CB &f&o&o
-becomes
-.UL \f[CB]foo\f[] .
-.
-.
-.P
-Underlining of a string of characters can also be specified in a
-manner similar to that of the
-.CI shift lock
-operations described above.
-;
-An appearance of
-.FONT CI ampersand
-preceded by
-.FONT CI circumflex
-.FONT CB ^&
-will cause underlining of all following characters except space.
-.
-An appearance of
-.CI ampersand
-preceded by
-.CI back\-slash
-.FONT CB \[rs]&
-will disable this mode.
-.
-.
-.TP
-.FONT CB # CR "  Number Sign  " I "Explicit space"
-It is occasionally necessary to include
-.I spaces
-in the text which should not be treated as
-.IR "word separators" .
-.
-For this purpose,
-.FONT CI RUNOFF
-treats the
-.I number\-sign
-character
-.FONT R ( CB # R ,
-.FONT CR "043 octal" R )
-as a
-.IR "quoted space" ;
-i.e.  it will print as exactly one
-.I space
-in the output, will never be expanded nor changed to a
-.IR "carriage return" .
-.
-.
-.TP
-.FONT CB _ CR "  Underline   " I "Quote next character"
-To allow the appearance of the
-.I special characters
-.FONT R ( CI ampersand
-used as a
-.IR "quote character" .
-.
-The character immediately following an
-.FONT CR underscore
-will be transmitted to the output with no formatting effect.
-.
-The
-.FONT CR underscore
-itself is thus another
-.IR "case requiring quoting" .
-.
-The following five cases occur:
-.FONT CB _& R ,
-.FONT CB _^ R ,
-.FONT CB _\[rs] R ,
-.FONT CB __ R ,
-.FONT CB _# R ,
-.FONT CB _{ R ,
-.FONT CB _} R ,
-and
-.FONT CB _| R .
-.
-.
-.TP
-.FONT CB ^ CI "   Circumflex   " I "Upper\-case shift or mode lock"
-As described above, the
-.FONT CI circumflex
-character
-.FONT CB ^
-is used to convert the letter following to
-.IR upper\-case .
-It is also used to lock the
-.I case mode
-in
-.IR "upper case" ,
-and the
-.I underline mode
-to
-.UL "underline all text" .
-.
-If it is to appear in the printed text, it must be preceded by the
-.I quote character
-.FONT CB _^ R .
-.
-.
-.TP
-.FONT CR \[rs] CI "  back\-slash  " I "lower\-case shift or mode unlock"
-As described above, the
-.FONT CI back\-slash
-character
-.FONT CB \[rs]
-is used to output the letter following in
-.IR lower\-case .
-.
-It is also used to lock the
-.I case mode
-in
-.IR lower\-case ,
-and to disable
-.IR underlining .
-.
-If it is to appear in the printed text, it must be preceded by the
-.I quote
-character
-.FONT CB _\[rs] R .
-.
-.
-.TP
-.FONT CB < CI "   less\-than   " I "Capitalize next word"
-If
-.FONT CB ".FLAGS CAPITALIZE"
-has been engaged, the
-.FONT CI less\-than
-character
-.FONT CB <
-is a special character used to capitalize the entire word it precedes.
-.
-If it is to appear in the printed text, it must be preceded by the
-.I quote
-character
-.FONT CB _< R .
-.
-.
-.TP
-.FONT CB = CR " equals\-sign " I  "hypenation disable"
-If
-.FONT CB ".FLAGS HYPHENATE"
-has been engaged, the
-.I equals
-character
-.FONT CB =
-used to disable
-.I hyphenation
-for the word it preceds.
-.
-If it is to appear in the printed text, it must be preceded by the
-.I quote
-character
-.FONT CB _= R .
-.
-.
-.TP
-.FONT CB { CR " left\-brace " I "Reverse half\-linefeed"
-If the output device type is no
-.FONT CB N R ,
-then the
-.I left
-and
-.I right braces
-are used for
-.I superscripting
-and
-.IR subscripting .
-.
-The
-.I left\-brace
-.FONT R ( CB { CR " 173 octal" R )
-produces a
-.IR "reverse half\-linefeed" .
-When combined with the
-.I right brace
-.FONT R ( CB } CR " 175 octal" R )
-scripting is created; e.g.
-.FONT CB {super}
-becomes
-.FONT CB {super} R ,
-and
-.FONT CB }sub{
-becomes
-.FONT CB }sub{ R .
-.
-.
-.TP
-.FONT CB } CR " right\-brace " I "forward half\-linefeed"
-As described above, the
-.I right brace
-.FONT R ( CB } CR " 175 octal" R )
-when coupled with the
-.I left brace
-will produce scripting.
-.
-This will only occur when a scripting output device is selected.
-.
-.
-.TP
-.FONT CB | CR " vertical\-bar " I "Engage/disengage alternate character set"
-The
-.I vertical bar
-.FONT R ( CB | R , CR " 174 octal" R )
-acts as an on/off switch.
-.
-It will alternatly transmit a
-.I shift\-out
-and a
-.I shift\-in
-character to change the selected character set; e.g.
-.FONT CB |ABC|
-becomes
-.FONT CI Ctrl\-N CB ABC CI Ctrl\-O R .
-.
-.
-.TP
-.FONT CI Ctrl\-N CR " Control-N " I "enchacement on/off;  red/black ribbon"
-If an
-.I Anderson-Jacobson output device
-is selected, a
-.FONT CI Control\-N
-.FONT R ( CI Ctrl\-N R ,
-.FONT CR "016 octal" R )
-will alternatly engage and disengage the print enchancement; e.g.
-.FONT CB NFOO CI Ctrl\-N
-becomes
-.FONT CB FOO R .
-.
-.
-.P
-If a
-.I Diablo output device
-is selected, a
-.FONT CI Control\-N
-will alternatly  select  the  red  and  black  ribbon color;  e.g.
-.FONT CB NFOO CI Ctrl\-N
-becomes
-.FONT CB FOO R .
-.
-.
-.\" --------------------------------------------------------------------
-.SS Special Characters Overview
-.\" --------------------------------------------------------------------
-.
-.P
-Below is a list of
-.FONT CI RUNOFF R 's
-special characters.
-.
-To appear in the text, each must be preceded by the
-.CI underscore
-character (itself a special character).
-.
-.
-.TP
-.FONT CB ^
-shift character for upper case
-.
-.TP
-.FONT CB \[rs]
-shift character for lower case
-.
-.TP
-.FONT  CB <
-flag character for upper case.
-.
-Only becomes a special character if
-.FONT CB ".FLAGS CAPITALIZE"
-is engaged.
-.
-.TP
-.FONT CB #
-quoted space character
-.
-.TP
-.FONT CB =
-flag character for disabling hyphenation.
-.
-Only becomes a
-.I special character
-if
-.FONT CB ".FLAGS HYPHENATE"
-is  engaged.
-.
-.TP
-.FONT CB &
-.FONT CR underscore
-.
-.TP
-.FONT CB _
-.I quote special character
-.
-.TP
-.FONT CB {
-.I reverse half\-linefeed
-for scripting
-.
-.TP
-.FONT CB }
-.I forward half\-linefeed
-for scripting
-.
-.TP
-.FONT CB |
-switch on/off the
-.I alternate character set
-.
-.TP
-.FONT CB ^n
-switch on/off the print enchancement or switch to the red/black ribbon
-color
-.
-.
-.\" --------------------------------------------------------------------
-.SS RUNOFF Commands
-.\" --------------------------------------------------------------------
-.
-The following
-.I commands
-will be recognized if they are at the beginning of a line started with
-a period.
-.
-Any line in the source file beginning with a period is assumed to be
-one of these
-.IR commands .
-.
-If it is not, an
-.I error diagnostic
-will be typed and the line will be ignored.
-.
-Some
-.I commands
-take one or more decimal numeric arguments.
-.
-These are separated from the
-.I command
-by a
-.FONT CR space R .
-.
-More than one
-.I command
-may be entered on a single line by separating the
-.I commands
-with a
-.FONT CI semicolon
-.FONT R ` CB ; R '
-or a
-.FONT CI period
-.FONT R ` CB . R '.
-.
-.
-.P
-.I Multi\-word commands
-may appear in any form.
-.
-Thus,
-.FONT CB ".NO HEADER"
-and
-.FONT CB .NOHEADER
-are both legal.
-.
-.
-.P
-Many
-.I commands
-may be abbreviated.
-.
-Standard
-.I abbreviations
-are given below each
-.IR command .
-.
-.
-.\" --------------------------------------------------------------------
-.SS Text Formatting Commands
-.\" --------------------------------------------------------------------
-.
-.TP
-.FONT CB .BREAK
-.TQ
-.FONT CB .BR
-causes a
-.IR break ,
-i.e. the current line will be output with no
-.IR justification ,
-and the next word of the source text will be placed at the beginning
-of the next line.
-.
-.
-.TP
-.FONT CB .SKIP CI " n"
-.TQ
-.FONT CB .SK CI " n"
-.TQ
-.FONT CB .S CI " n"
-causes a BREAK after which
-.CI n
-is multiplied by the number of
-.I spaces
-between lines.
-.
-The result is the number of lines
-.IR skipped .
-.
-Output is advanced to the top of the next page if there is no room on
-the current page.
-.
-If the current page is empty,
-.FONT CB .SKIP
-does nothing.
-.
-.
-.TP
-.FONT CB .BLANK I " n"
-.TQ
-.FONT CB .B I " n"
-causes the current line to be output with no
-.IR justification ,
-skips
-.FONT CI n
-line spaces, and then starts output of the current source text.
-.
-.FONT CB .BLANK
-is like
-.FONT CB .SKIP R ,
-except that the
-.I space
-to be left is independent of line spacing.
-.
-If the page is empty,
-.FONT CB .BLANK
-does nothing.
-.
-.
-.TP
-.FONT CB .FIGURE I " n"
-.TQ
-.FONT CB .FG I " n"
-leaves
-.I n
-lines blank to make room for a figure or diagram.
-.
-If fewer than
-.I n
-lines remain on the current page, text continues to
-.I fill
-this page, then the page is advanced and
-.I n
-blank lines are left at the top of the next page.
-.
-.
-.TP
-.FONT CB .INDENT I " n"
-.TQ
-.FONT CB .I I " n"
-causes a
-.CI break
-and sets the next line to begin
-.I n
-spaces to the right of the left margin.
-.
-The
-.I n
-can be negative to allow beginning a line to the left of the left
-margin.
-.
-However, a line cannot begin to the left of column 0.
-.
-If
-.I n
-is not supplied, the current paragraph indent is used.
-.
-.
-.TP
-.FONT CB .PARAGRAPH I " n, v, t"
-.FONT CB .P I " n, v, t"
-causes a
-.I break
-and formats the output paragraphs.
-.
-The
-.I n
-is optional and, if present, sets the number of spaces the paragraph
-is to be indented.
-.
-The default value for
-.I n
-is
-.FONT CB 5
-.RI ( n
-can also have a negative value).
-.
-.I v
-is the vertical spacing between paragraphs.
-.
-.I v
-can range from
-.FONT CB 0
-to
-.FONT CB 5 R .
-.
-.FONT R ( CB 1
-is
-.IR "single spacing" ,
-.FONT CB 2
-is
-.IR "double spacing" ,
-etc.)
-.
-.I t
-causes an automatic
-.FONT CI ".TEST PAGE"
-(see the
-.FONT CB ".TEST PAGE"
-.IR command ).
-.
-.
-.TP
-.FONT CB .CENTER I " n" CB ; I text
-.TQ
-.FONT CB .CENTRE I " n" CB ; I text
-.TQ
-.FONT CB .C I " n" CB ; I text
-causes a
-.I break
-and centers the following text in the source file.
-.
-The centering is over column
-.FONT CB ( I n CB " + " I "left margin" CB )/2 R .
-If
-.I n
-is not given, it is assumed to be the
-.
-.IR "right margin" .
-.
-.
-.RS
-.P
-.ce
-NOTE
-.
-.P
-.FONT CB CENTER R ,
-.FONT CB "RIGHT MARGIN" R ,
-.FONT CB "LEFT MARGIN" R ,
-.FONT CB "PAGE SIZE" R ,
-and
-.FONT CB STANDARD
-take both relative and absolute values.
-.
-Relative values are expressed as
-.FONT CB + I n
-or
-.FONT CB \- I n R ,
-while absolute values of
-.I n
-are unsigned.
-.RE
-.
-.
-.TP
-.FONT CB .FOOTNOTE I " n"
-.TQ
-.FONT CB .FN I " n"
-saves
-.I n
-lines at the bottom of the current page for a
-.IR footnote .
-.
-The
-.I n
-is multiplied by the number of spaces set with the
-.FONT CB .SPACING
-command.
-.
-If insufficient room remains on the current page, space is allocated
-at the bottom of the following page.
-.
-The text of the
-.I footnote
-should begin on the line following the
-.FONT CB .FOOTNOTE
-command.
-.
-.IR Indentation ,
-.IR "case lock" ,
-.IR justify ,
-.IR margins ,
-.IR spacing ,
-and
-.I fill
-are preserved around footnotes.
-.
-However,
-.I commands
-that affect page formatting are illegal in a
-.IR footnote .
-.
-.I Tab stops
-are illegal because they are not preserved.
-.
-A footnote within a footnote is also illegal.
-.
-.
-.P
-The actual space taken by a footnote can be more or less than
-specified by
-.IR n .
-If necessary
-.FONT CR adjust
-.I n
-after examining a draft printout.
-.
-.
-.P
-The
-.I footnote
-is terminated with a line beginning with an exclamation point (the
-remainder of which is ignored).
-.
-.
-.TP
-.FONT CB .NOTE I " text"
-.TQ
-.FONT CB .NT I " text"
-starts an
-.IR "indented note" .
-.
-This command
-.I blanks
-.FONT CB 2 R ,
-reduces both
-.IR margins ,
-.I centers
-the text (if no text is given, it centers the word
-.FONT CB NOTE R ),
-and then
-.I blanks
-.FONT CB 1 R .
-.
-At this point you enter the text of the
-.IR note .
-.
-If the left margin is at
-.FONT CB 0 R ,
-the
-.I margin reduction
-is
-.FONT CB 15 R ,
-otherwise it is
-.FONT CB 5 R .
-.
-.
-.TP
-.FONT CB ".END NOTE"
-.TQ
-.FONT CB .EN
-terminates the
-.FONT CB .NOTE
-command,
-.I blanks
-.CONT CB 2 R ,
-and reverts the margins and spacing modes to their settings before the
-last
-.FONT CB .NOTE
-command.
-.
-.
-.TP
-.FONT CB .LIST I " n"
-.FONT CB .LS I " n"
-starts an indented list with
-.I n
-spacing, moves the left margin
-.FONT CB 9
-spaces to the right for the first
-.FONT CB .LIST
-command, and
-.FONT CB 4
-more spaces for each subsequent nested
-.FONT CB .LIST R .
-.
-The normal
-.I fill
-and
-.I justify modes
-remain in effect.
-.
-Therefore, you must disengage them just after the
-.FONT CB .LS
-command if you want a ragged right.
-.
-.
-.TP
-.FONT CB ".LIST ELEMENT;" I " text"
-.TQ
-.FONT CB .LE; I " text"
-starts an item in the list, used in conjunction with the
-.FONT CB LIST
-comand.
-.
-The elements are numbered sequentially and the number is given a
-negative indent so that the list lines up.
-.
-The number is followed by a
-.I period
-and two
-.I spaces
-so that the indent will be by 
-.FONT CB \-4 R .
-.
-The
-.I list elements
-are separated by the standard paragraph spacing and
-.FONT CI "TEST PAGE" R .
-.
-If you want to type the text on the same line as the command, you must
-separate the text from the command with any number of intervening
-.I spaces
-or
-.IR tabs ,
-or (optionally) one
-.IR semicolon .
-.
-.
-.TP
-.FONT CB ".END LIST"
-.TQ
-.FONT CB .ELS
-terminates the
-.FONT CB .LIST
-command and returns to settings before the last
-.FONT CB .LIST
-command.
-.
-.
-.TP
-.FONT CB .COMMENT I " text"
-.TQ
-.FONT CB .; I " text"
-causes the line to be ignored.
-.
-The text is not printed in the output file, but rather is used as a
-.I comment
-line in the source text.
-.
-.
-.\" --------------------------------------------------------------------
-.SS Page Formatting Commands
-.\" --------------------------------------------------------------------
-.
-.TP
-.FONT CB .PAGE
-.FONT CB .PG
-causes a
-.I break
-and an
-.I advance
-to a new page.
-.
-If the current page is empty, this
-.I command
-does not
-.I advance
-the page.
-.
-Just like an
-.IR "automatic page advance" ,
-this
-.I command
-prints the
-.I title
-(if given) and
-.I page numbers
-on every page.
-.
-.
-.TP
-.FONT CB ".TEST PAGE" I " n"
-.TQ
-.FONT CB .TP I " n"
-causes a
-.I break
-followed by a
-.IR "conditional page advance" .
-.
-It skips to the next page if fewer than
-.I n
-lines are left on the page.
-.
-This capability is to ensure that the following
-.I n
-lines are all output on the same page.
-.
-This
-.I command
-has the form
-.I t
-as an optional argument to the
-.FONT CB .PARAGRAPH
-command.
-.
-.
-.TP
-.FONT CB .NUMBER I " n"
-.TQ
-.FONT CB .NM I " n"
-starts page numbering.
-.
-This is the default so there is no reason to issue this command unless
-page numbering is disengaged.
-.
-If
-.I resumption
-of page numbering is desired at a certain page, specify
-.IR n .
-.
-.
-.TP
-.FONT CB .NONUMBER
-.FONT CB .NNM
-disengages page numbering.
-.
-However, pages continue to be counted, so that the normal page number
-can appear if page numbering is re\-entered with the
-.FONT CB .NUMBER
-command.
-.
-.
-.TP
-.FONT CB .CHAPTER I " text"
-.TQ
-.FONT CB .CH I " text"
-starts a new chapter using the text as the title of the chapter.
-.
-This
-.I command
-acts as if the following
-.I command string
-were entered:
-.
-.
-.P
-.EX
-.nop ".BREAK;.PAGE;.BLANK 12;.CENTER;CHAPTER n"
-.EE
-.P
-The
-.I n
-is incremented by
-.FONT CB 1
-automatically.
-.
-After the CHAPTER
-.I n
-is typed on the page,
-.
-.
-.P
-.EX
-.nop .BLANK 2;.CENTER;text;.BLANK 3
-.EE
-.P
-occurs.
-.
-This
-.I command
-then resets the
-.IR case ,
-.IR margins ,
-.IR spacing ,
-and
-.IR "justify/fill modes" .
-.
-It also clears any
-.I subtitles
-and sets the
-.I chapter name
-as the
-.IR title .
-.
-.
-.TP
-.FONT CB ".NUMBER CHAPTER " I " n"
-supplies a number
-.I n
-to be used in a subsequent
-.FONT CB .CHAPTER
-command.
-.
-.FONT CB ".NUMBER CHAPTER"
-would be used when a
-.I chapter
-of a document occupies a source file of its own.
-.
-In such a case,
-.FONT CB ".NUMBER CHAPTER"
-would be the first command of the source file.
-.
-.
-.TP
-.FONT  CB ".HEADER LEVEL" I " n text"
-.TQ
-.FONT CB .HL I " n text"
-starts a section at the level specified and takes the following text
-as the header.
-.
-.I n
-can range from
-.FONT CB 1
-to
-.FONT CB 5 R .
-.
-The sections are incremented by
-.FONT CB 1
-automatically, and the number is output in the form
-.FONT I i CB . I j CB . I k CB . I l CB . I m R .
-If this is a chapter oriented document, the
-.I i
-is the chapter number.
-.
-Otherwise, it is the number of the
-.FONT CB ".HL 1"
-level.
-.
-This command acts as a
-.
-.P
-.EX
-.FONT CB ".BREAK;.TEST PAGE 9;.BLANK 3"
-.EE
-.
-.P
-followed by the
-.IR "section number" ,
-two
-.IR spaces ,
-and the
-.IR "section name" .
-.
-.FONT CI "HEADER LEVELS " CB 1
-and
-.FONT CB 2
-end with a
-.IR break .
-.FONT CI "HEADER LEVELS"
-.FONT CB 3 R ", " CB 4 R ,
-and
-.FONT CB 5
-end with a space\-dash\-space combination (#\-#).
-.
-.
-.TP
-.FONT CB .TITLE I " text"
-.TQ
-.FONT CB .T I " text"
-takes the remaining text as the title and outputs it on every page at
-line
-.FONT CB 0 R .
-.
-The default is no title.
-.
-If a
-.I title
-is desired, this
-.I command
-must be entered in the source file.
-.
-.
-.TP
-.FONT CB ".FIRST TITLE" I " text"
-.TQ
-.FONT CB ".FT" I " text"
-Same as
-.FONT CB .TITLE R ,
-but used to specify the title to be printed on the first page of the
-document.
-.
-This command must precede all text in the source file.
-.
-Use of the
-.FONT CB ".FIRST TITLE"
-command is the only way to print a title line on the first page of the
-document.
-.
-.
-.TP
-.FONT CB .SUBTITLE I " text"
-.TQ
-.FONT CB .SUBTTL I " text"
-.TQ
-.FONT CB .ST I " text"
-takes the remaining text as the
-.I subtitle
-and outputs it on every page.
-.
-It appears directly under the title.
-.
-The
-.I subtitle
-is not
-.IR indented ,
-but
-.I indentation
-can be achieved by typing leading spaces.
-.
-.
-.TP
-.FONT CB .INDEX I " text"
-.TQ
-.FONT CB .X I " text"
-takes the remaining text on the line as a keyword and adds it, along
-with the current
-.IR "page number" ,
-to the internal index buffer.
-.
-The command does not cause a
-.IR break .
-.
-It should appear immediately before the item to be
-.IR indexed .
-.
-A keyword may be
-.I indexed
-more than once.
-.
-.
-.TP
-.FONT CB ".DO INDEX" I " text"
-.TQ
-.FONT CB ".DX" I " text"
-forces a new page, centers the text, if given, otherwise it centers
-the word
-.FONT CI "INDEX" R .
-.
-This command prints the entire contents of the index buffer.
-.
-Entries are printed in alphabetic order and are set against the left
-margin.
-.
-Regular line spacing is used, except that a blank line is left between
-entries of different first letters.
-.
-The page number of each entry is placed on the same line as the entry
-and in the middle of the page.
-.
-Additional page numbers for multiple entries follow, separated by
-commas.
-.
-The index buffer is left empty.
-.
-.
-.TP
-.FONT CB ".PRINT INDEX"
-.TQ
-.FONT CB ".PX"
-forces a new page after which it prints the entire contents of the
-index buffer.
-.
-Entries are printed in alphabetical order and are set against the left
-margin.
-.
-Regular line spacing is used, except that a blank line is left between
-entries of different first letters.
-.
-The number of the first page on which each entry appeared is put on
-the same line as the entry, beginning at the middle of the line
-(midway betweeen the left and right margins).
-.
-Additional page numbers for multiple entries follow, separated by
-commas.
-.
-The index buffer is left empty.
-.
-.
-.P
-.FONT CB ".PRINT INDEX"
-and
-.FONT CB ".DO INDEX"
-perform the same task.
-.
-The only difference is that
-.FONT CB ".PRINT INDEX"
-does not interrupt the normal chapter and page sequencing.
-.
-.
-.TP
-.FONT CB .SUBPAGE
-executes a
-.FONT CB .PAGE
-with page numbering suspended.
-.
-The page number is unchanged, but letters are appended to the page
-number.
-.
-This permits insertion of additional pages within an existing document
-without changing the existing page numbering.
-.
-.
-.TP
-.FONT CB ".END SUBPAGE"
-disengages the
-.FONT CB .SUBPAGE
-command by executing a
-.FONT CB .PAGE
-command with page numbering resumed.
-.
-.
-.TP
-.FONT CB .APPENDIX I " text"
-.TP
-.FONT CB .AX I " text"
-starts a new appendix using the text as the title of the appendix.
-.
-This command acts as if the following command string were entered:
-.
-.RS
-.P
-.EX
-.nop ".BREAK;.PAGE;.BLANK 12;.CENTER;APPENDIX a"
-.EE
-.RE
-.P
-The a is a letter that is incremented alphabetically automatically.
-.
-After the
-.FONT CB "APPENDIX A"
-is typed on the page,
-.
-.RS
-.P
-.EX
-.nop .BLANK 2;.CENTER;text;.BLANK 3
-.EE
-.RE
-.
-.P
-occurs.
-.
-This command then resets the
-.IR case ,
-.IR margins ,
-.IR spacing ,
-and
-.IR justify/fill
-modes.
-.
-It also clears any subtitles and sets the appendix name as the title.
-.
-.
-.TP
-.FONT CB ".NUMBER APPENDIX" I " a"
-supplies a letter
-.I a
-to be used as the letter for a subsequent
-.FONT CB .APPENDIX
-command.
-.
-.
-.TP
-.FONT CB .HEADER I " arg"
-.TQ
-.FONT CB .HD I " arg"
-causes the page header
-.RI ( title ,
-.IR subtitle ,
-and
-.IR "page number" )
-to be printed.
-.
-.I arg should be
-.FONT CB UPPER
-to specify
-.I upper case characters
-for the title text,
-.FONT CB LOWER
-to specify
-.IR "lower case" ,
-or
-.FONT CB MIXED R .
-.
-The initial setting is
-.FONT CB ".HEADER UPPER" R .
-.
-.
-.TP
-.FONT CB .NOHEADER
-.TP
-.FONT CB .NHD
-causes the page header
-.RI ( title ,
-.IR subtitle ,
-and
-.IR "page number" )
-to be omitted.
-.
-The header lines are completely omitted, so that text begins at the
-top of the page with no
-.IR "top margin" .
-.
-.
-.\" --------------------------------------------------------------------
-.SS Mode Setting Commands
-.\" --------------------------------------------------------------------
-.
-.TP
-.FONT CB .JUSTIFY
-.TQ
-.FONT CB .J
-causes a break and sets subsequent output lines to be justified
-(initial setting).
-.
-The
-.I command
-increases the spaces between words until the last word exactly meets
-the right margin.
-.
-.
-.TP
-.FONT CB .NOJUSTIFY
-.TQ
-.FONT CB .NJ
-causes a
-.I break
-and prevents
-.I justification
-of subsequent output lines to make a ragged right margin.
-.
-.
-.TP
-.FONT CB .FILL
-.TQ
-.FONT CB .F
-causes a break and specifies that subsequent output lines be filled
-(inital setting).
-.
-Sets the justification mode to be that specified by the last
-appearance of
-.FONT CB  .JUSTIFY
-or
-.FONT CB NOJUSTIFY R .
-.
-.FONT CB .FILL
-adds successive words from the source text until the adding of one
-more word will exceed the right margin.
-.
-It stops before putting the last word in.
-.
-(If
-.I hyphenation
-has not been disabled,
-.FONT CB RNO
-will attempt to
-.I break
-words which cause line overflow into syllables.)
-.
-.
-.TP
-.FONT CB .NOFILL
-.TP
-.FONT CB .NF
-disengages the
-.I fill
-and
-.IR "justify modes" .
-.
-This
-.I command
-is used to permit typing a table.
-.
-.
-.RS
-.
-.
-.P
-.ce
-NOTE
-.
-.P
-1. The
-.I nofill\-nojustify mode
-need be used only where there are several lines of material to be
-copied exactly.
-.
-A single line example will not require using these commands if there
-are breaks before and after.
-.
-.
-.P
-2. Normally
-.FONT CB .FILL
-and
-.FONT CB NOFILL
-are used to turn both
-.I filling
-and
-.I justification
-on and off.
-.
-It is usually desirable to do both.
-.
-A subsequent appearance of a
-.I justification command
-will override the
-.I fill command
-however.
-.
-.
-.P
-3. Because of the action of
-.FONT CB .FILL R ,
-a single occurrance of
-.FONT CB NOJUSTIFY
-will cause the remainder of the file to be
-.IR unjustified ,
-with
-.I filling
-as specified.
-.
-In order to
-.I justify
-but
-.I not fill
-(not recommended), a
-.FONT CB .JUSTIFY
-command must follow every
-.FONT CB .NOFILL
-command.
-.
-.
-.RE
-.
-.
-.TP
-.FONT CB ".UPPER CASE"
-.TQ
-.FONT CB .UC
-sets the output mode to
-.IR "upper case" .
-.
-This comand acts the same as typing two
-.CI circumflexes
-.FONT CB ^^ R .
-.
-This is the default mode.
-.
-There is no need to type this command unless the mode was previously
-altered to
-.IR "lower case" .
-.
-.
-.TP
-.FONT CB ".LOWER CASE"
-.TQ
-.FONT CB .LC
-sets the typeout mode to
-.IR "lower case" .
-This command acts the same as typing two
-.I back\-slashes
-.FONT CB \[rs]\[rs] R .
-.
-.
-.TP
-.FONT CB ".FLAGS CAPITALIZE"
-.TQ
-.FONT CB ".FL CAPITALIZE"
-enables the
-.CI less\-than
-.FONT CB <
-character to
-.I capitalize
-the entire word it precedes.
-.
-It then returns the file to the current case mode.
-.
-This
-.I special character
-is usually
-.FONT CR off
-and must be typed at the very beginning of the source text to enable
-this character.
-.
-Typing a space or another
-.FONT CI "less\-than " CB <
-returns the file to the current
-.IR "case lock" .
-.
-.
-.TP
-.FONT CB ".NO FLAGS CAPITALIZE"
-.TQ
-.FONT CB .NFC
-disengages the
-.FONT CB "FLAG CAPITALIZE"
-command (inital setting).
-.
-.
-.TP
-.FONT CB .HYPHENATION
-.TQ
-.FONT CB .HY
-engages
-.I hyphenization
-(initial setting).
-.
-.
-.TP
-.FONT CB ".NO HYPHENATION"
-.TQ
-.FONT CB .NHY
-disengages
-IR hyphenization .
-.
-.
-.TP
-.FONT CB ".FLAGS HYPHENATE"
-.TQ
-.FONT CB ".FL HYPHENATE"
-enables the
-.I equals character
-.FONT CB =
-to disengage
-.I hyphenization
-for the word it precedes.
-.
-This
-.I special character
-is initially
-.FONT CR off
-and must be typed at the beginning of the source file to enable this
-character.
-.
-The
-.FONT CI "FLAGS HYPHENATE"
-.I character
-is used to disengage
-.I hyphenization
-for words improperly
-.I hyphenated
-by the
-.IR "hyphenization algorithm" .
-.
-.
-.TP
-.FONT CB ".NO FLAGS HYPHENATE"
-.TQ
-.FONT CB .NFH
-disengages the
-.FONT CB ".FLAGS HYPHENATE"
-command (initial setting).
-.
-.
-.TP
-.FONT CB .NFL
-disengages the
-.FONT CB ".FLAGS CAPITALIZE"
-and the
-.FONT CB ".FLAGS HYPHENATE"
-commands (initial setting).
-.
-.
-.TP
-.FONT CB .PERIOD
-.TQ
-.FONT CB .PR
-enables printing of two
-.I spaces
-after every
-.I period
-.FONT CB .
-that is followed by at least one
-.I separator character
-(initial setting).
-.
-.
-.TP
-.FONT CB .NOPERIOD
-.TQ
-.FONT CB .NPR
-disengages conversion of
-.I period/separator
-to
-.IR "period/two spaces" .
-.
-.
-.TP
-.FONT CB .LITERAL
-.TQ
-,FONT CB .LIT
-disengages
-.I fill/justify
-to permit printing of text exactly as entered in source file.
-.
-.
-.TP
-.FONT CB ".END LITERAL"
-.TQ
-.FONT CB .ELI
-used after
-.FONT CB .LITERAL
-command to re\-engage
-.IR fill/justify .
-.
-.
-.\" --------------------------------------------------------------------
-.SS Parameter Setting Commands
-.\" --------------------------------------------------------------------
-.
-.TP
-.FONT CB ".LEFT MARGIN" I " n"
-.TQ
-.FONT CB .LM I " n"
-sets the left margin to
-.IR n .
-.
-The
-.I n
-must be less than the right margin but not less than
-.FONT CB 0 R .
-The initial setting is
-.FONT CB 0 R .
-If
-.I n
-is not supplied,
-.FONT CB 0
-is used.
-.
-.
-.TP
-.FONT CB ".RIGHT MARGIN" I " n"
-.TQ
-.FONT CB .RM I " n"
-sets the right margin
-.IR n .
-The
-.I n
-must be greater than the left margin.
-.
-The initial setting is
-.FONT CB 60 R .
-.
-If
-.I n
-is not supplied, the current page width (set with the
-.FONT CB ".PAGE SIZE"
-command) is used.
-.
-.
-.TP
-.FONT CB ".PAPER SIZE" I " n" CB , I m
-.TP
-.FONT CB ".PAGE SIZE" I " n" CB , I m
-.TP
-.FONT CB ".PS" I " n" CB , I m
-sets the size of the page
-.I n
-lines by
-.I m
-columns and sets the right margin to
-.IR m .
-The default setting is
-.FONT CB 58,60 R .
-.
-.
-.TP
-.FONT CB .PITCH I " n" CB , I m
-.TQ
-.FONT CB .PIT I " n" CB , I m
-sets the horizontal and vertical pitch on a supporting output device.
-.
-The horizontal pitch is
-.I n
-and is specified as characters per inch.
-.
-The value must divide evenly into
-.FONT CB 60
-for
-.FONT CI "Anderson\-Jacobson devices"
-and into
-.FONT CB 120
-for
-.FONT CI "Diablo devices" R .
-.
-The default is
-.FONT CB 12 R .
-.
-.
-.P
-The vertical pitch is
-.I m
-and is specified as lines per inch.
-.
-.I m
-must divide evenly into
-.FONT CB 48 R .
-.
-The default is the hardware setting.
-.
-.I n
-and
-.I m
-may be set independently.
-.
-.
-.TP
-.FONT CB .SPACING I " n"
-.TQ
-.FONT CB .SP I " n"
-sets the number of spaces between lines.
-.
-The
-.I n
-can range from
-.FONT CB 1
-to
-.FONT CB 5 R .
-.
-The default setting is
-.FONT CB 1 R .
-.
-.FONT CB ".SPACING 1"
-is like
-.I single spacing
-on a typewriter and
-.FONT CB ".SPACING 2"
-is like
-.IR "double spacing" .
-.FONT CB ".SPACING 2"
-puts one
-.I blank line
-between lines of text.
-.
-.
-.TP
-.FONT CB .STANDARD I " n"
-.TQ
-.FONT CB .SD I " n"
-returns all parameters, except the pitch settings, to their initial
-settings and sets
-.I n
-as the page width.
-.
-If
-.FONT CB ".STANDARD 60"
-is specified, margins are reset
-.FONT CB ".LM 0" R ,
-.FONT CB ".RM 60" R ,
-.FONT CB ".PAGE SIZE 58,60" R ,
-.FONT CB ".SPACING 1" R ,
-.FONT CB "PARAGRAPH INDENT 5" R ,
-and
-.I fill
-and
-.I justify
-are enabled.
-.
-.FONT CB ".STANDARD 70"
-sets right margin to
-.FONT CB 70
-and
-.I page size
-to
-.FONT CB 58,70 R .
-.
-.
-.TP
-.FONT CB ".TAB STOPS" I " n" CB , I n CB , I \*[Ellipsis]
-.TQ
-.FONT CB ".TS" I " n" CB , I n CB , I \*[Ellipsis]
-sets tabs.
-.
-The
-.I  n
-must be greater than
-.FONT CB 0
-and listed in ascending order.
-.
-If tabs already exist, the issuing of another
-.FONT CB ".TAB STOPS"
-command clears all previous
-.I tabs
-before setting new ones.
-.
-The
-.I default tabs
-are set at eight\-column intervals to match the
-.FONT CR Digital
-hardware standard.
-.
-These
-.I tabs
-are at columns
-.FONT CB 8 R ,
-.FONT CB 16 R ,
-.FONT CB 24 R ,
-.FONT CB 32 R ,
-.FONT CB 40 R ,
-.FONT CB 48 R ,
-.FONT CB 56 R ,
-.FONT CB 64 R ,
-.FONT CB 72 R ,
-and
-.FONT CB 80 R .
-.
-The tabs are converted to the appropriate number of non\-expandable
-spaces.
-.
-If there are no regular spaces to the left of the
-.IR tabs ,
-they will print out at the appropriate position, even if
-.I fill
-is on.
-.
-If
-.I literal
-is on, the
-.I tabs
-are not converted to
-.IR spaces ,
-but are output as
-.IR tabs .
-.
-.
-.TP
-.FONT CB .AUTOPARAGRAPH
-.TQ
-.FONT CB .AP
-causes any
-.I blank line
-or any line starting with a
-.I space
-or
-.I tab
-to be considered as the start of a new paragraph.
-.
-This command allows normally typed text to be
-.I justified
-without special commands.
-.
-It does not cause a paragraph if
-.I blank lines
-are followed by a command.
-.
-.
-.TP
-.FONT CB .NOAUTOPARAGRAPH
-.TQ
-.FONT CB .NAP
-disengages the
-.FONT CI AUTOPARAGRAPH
-mode.
-.
-.
-.\" --------------------------------------------------------------------
-.SS List of Commands (Alphabetical)
-.\" --------------------------------------------------------------------
-.
-.if t \{
-.ig endTBL
-.\}
-.
-.\" --------------------------------------------------------------------
-.\" Table using tbl for running in tty
-.\" --------------------------------------------------------------------
-.
-.nf
-.nh
-.
-.TS
-center,allbox,tab(@);
-cIw(1.5i) sw(1.5i) cIw(1.5i).
-Command or Abbreviation@Related Commands
-=
-.
-.T&
-l l l.
-\f[CB].AP\f[R]@(=\f[CB].AUTOPARAGRAPH\f[R])@
-\f[CB].APPENDIX\f[I] text \f[R]@(=\f[CB].AX\f[R])@\f[CB].NUMBER APPENDIX\f[I] a
-\f[CB].AX\f[R]@(=\f[CB].APPENDIX\f[R])@
-\f[CB].AUTOPARAGRAPH \f[R]@(=\f[CB].AP\f[R])@T{
-\f[CB].NOAUTOPARAGRAPH
-.br
-\f[R](\f[CB].NAP\f[R])
-T}
-_
-\f[CB].B\f[R]@(=\f[CB].BLANK\f[R])@
-\f[CB].BLANK \f[I]n \f[R]@(=\f[CB].B\f[R])@T{
-\f[CB].SKIP \f[I]n
-.br
-\f[R](\f[CB].S\f[R])
-T}
-\f[CB].BR\f[R]@(=\f[CB].BREAK\f[R])@
-\f[CB].BREAK@\f[R](=\f[CB].BR\f[R])
-_
-\f[CB].C\f[R]@(=\f[CB].CENTRE\f[R])@
-\f[CB].CENTER\f[R]@(=\f[CB].CENTRE\f[R])@
-\f[CB].CENTRE \f[I]n\f[CB];\f[I]text \f[R]@(=\f[CB].C\f[R])@
-\f[CB].CH\f[R]@(=\f[CB].CHAPTER\f[R])@
-\f[CB].CHAPTER \f[I]text \f[R]@(=\f[CB].CH\f[R])@\f[CB].NUMBER CHAPTER \f[I]n
-\f[CB].COMMENT \f[I]text\f[R]@@
-_
-\f[CB].DO INDEX \f[I]text \f[R]@(=\f[CB].DX\f[R])@T{
-.
-\f[CB].PRINT INDEX
-.br
-\f[R](\f[CB].PX\f[R])
-T}
-.
-\f[CB].DX\f[R]@(=\f[CB].DO INDEX\f[R])@
-_
-\f[CB].ELS\f[R]@(=\f[CB].END LIST\f[R])@
-\f[CB].EN\f[R]@(=\f[CB].END NOTE\f[R])@
-.
-\f[CB].END LIST\f[R]@(=\f[CB].ELS\f[R])@T{
-\f[CB].LIST \f[I]n
-.br
-\f[R](\f[CB].LS\f[R])
-T}
-.
-\f[CB].END LITERAL \f[R]@(=\f[CB].ELI\f[R])@T{
-\f[CB].LITERAL
-.br
-\f[R](\f[CB].LIT\f[R])
-T}
-.
-\f[CB].END NOTE\f[R]@(=\f[CB].EN\f[R])@T{
-\f[CB].NOTE \f[I]text
-.br
-\f[R](\f[CB].NT\f[R])
-T}
-.
-\f[CB].END SUBPAGE\f[R]@@\f[CB].SUBPAGE
-_
-\f[CB].F\f[R]@(=\f[CB].FILL\f[R])@
-\f[CB].FG\f[R]@(=\f[CB].FIGURE\f[R])@
-\f[CB].FIGURE n \f[R]@(=\f[CB].FG\f[R])@
-.
-\f[CB].FILL \f[R]@(=\f[CB].F\f[R])@T{
-\f[CB].NOFILL
-.br
-\f[R](\f[CB].NF\f[R])
-T}
-.
-\f[CB].FIRST TITLE \f[I]text\f[R]@(=\f[CB].FT\f[R])@\f[CB].TITLE \f[I]text
-.
-\f[CB].FLAGS CAPITALIZE\f[R]@(=\f[CB].FL CAPITALIZE\f[R])@T{
-\f[CB].NO FLAGS CAPITALIZE
-.br
-\f[R](\f[CB].NFL\f[R])
-T}
-.
-\f[CB].FLAGS HYPHENATE \f[R]@(=\f[CB].FL HYPHENATE\f[R])@T{
-\f[CB].NO FLAGS HYPHENATE
-.br
-\f[R](\f[CB].NFH\f[R])
-T}
-.
-\f[CB].FN\f[R]@(=\f[CB].FOOTNOTE\f[R])@
-\f[CB].FOOTNOTE \f[I]n\f[R]@(=\f[CB].FN\f[R])@
-\f[CB].FT\f[R]@(=\f[CB].FIRST TITLE\f[R])@
-_
-\f[CB].HD\f[R]@(=\f[CB].HEADER\f[R])@
-.
-T{
-\f[CB].HEADER \f[I]arg\f[R]
-.br
-\f[R]  [\f[I]arg\f[R]=\f[CB]UPPER\f[R], \f[CB]LOWER\f[R], or \f[CB]MIXED]\f[R]
-T}@(=\f[CB].HD\f[R])@T{
-\f[CB].NOHEADER
-.br
-\f[R](\f[CB].NHD\f[R])
-T}
-.
-\f[CB].HEADER LEVEL \f[I]n text\f[R]@(=\f[CB].HL\f[R])@
-\f[CB].HL\f[R]@(=\f[CB].HEADER LEVEL\f[R])@
-\f[CB].HY\f[R]@(=\f[CB].HYPHENATION\f[R])@
-.
-\f[CB].HYPHENATION \f[R]@(=\f[CB].HY\f[R])@T{
-\f[CB].NO HYPHENATION
-.br
-\f[R](\f[CB].NHY\f[R])
-T}
-.
-_
-\f[CB].I\f[R]@(=\f[CB].INDENT\f[R])@
-\f[CB].INDENT \f[I]n\f[R]@(=\f[CB].I\f[R])@
-\f[CB].INDEX \f[I]text \f[R]@(=\f[CB].X\f[R])@
-_
-\f[CB].J\f[R]@(=\f[CB].JUSTIFY\f[R])@
-.
-\f[CB].JUSTIFY \f[R](\f[CB].J\f[R])@@T{
-\f[CB].NOJUSTIFY
-.br
-\f[R](\f[CB].NJ\f[R])
-T}
-.
-_
-\f[CB].LC\f[R]@(=\f[CB].LOWER CASE\f[R])@
-\f[CB].LE\f[R]@(=\f[CB].LIST ELEMENT\f[R])@
-.
-\f[CB].LEFT MARGIN \f[I]n\f[R]@(=\f[CB].LM\f[R])@T{
-\f[CB].RIGHT MARGIN \f[I]n
-.br
-\f[R](\f[CB].RM\f[R])
-T}
-.
-\f[CB].LIST \f[I]n\f[R]@(=\f[CB].LS\f[R])@T{
-\f[CB].END LIST
-.br
-\f[R](\f[CB].ELS\f[R])
-T}
-.
-\f[CB].LIST ELEMENT;\f[I]text\f[R]@(=\f[CB].LE\f[R])@T{
-\f[CB].END LIST
-.br
-\f[R](\f[CB].ELS\f[R])
-T}
-.
-\f[CB].LIT\f[R]@(=\f[CB].LITERAL\f[R])@
-.
-\f[CB].LITERAL\f[R]@(=\f[CB].LIT\f[R])@T{
-\f[CB].END LITERAL
-.br
-\f[R](\f[CB].ELI\f[R])
-T}
-.
-\f[CB].LM\f[R]@(=\f[CB].LEFT MARGIN\f[R])@
-.
-\f[CB].LOWER CASE\f[R]@(=\f[CB].LC\f[R])@T{
-\f[CB].UPPER CASE
-.br
-\f[R](\f[CB].UC\f[R])
-T}
-.
-\f[CB].LS\f[R]@(=\f[CB].LIST\f[R])@
-_
-\f[CB].NAP\f[R]@(=\f[CB].NOAUTOPARAGRAPH\f[R])@
-\f[CB].NF\f[R]@(=\f[CB].NOFILL\f[R])@
-\f[CB].NFC\f[R]@(=\f[CB].NO FLAGS CAPITALIZE\f[R])@
-\f[CB].NFH\f[R]@(=\f[CB].NO FLAGS HYPHENATE\f[R])@
-.
-\f[CB].NFL\f[R]@T{
-(=\f[CB].NO FLAGS CAPITALIZE
-.br
-.ce
-\f[R] and
-.br
-\f[CB].NO FLAGS HYPHENATE\f[R])
-T}@
-.
-\f[CB].NHD\f[R]@(=\f[CB].NO HEADER\f[R])@
-\f[CB].NHY\f[R]@(=\f[CB].NO HYPHENATION\f[R])@
-\f[CB].NJ\f[R]@(=\f[CB].NO JUSTIFY\f[R])@
-\f[CB].NM\f[R]@(=\f[CB].NUMBER\f[R])@
-\f[CB].NNM\f[R]@(=\f[CB].NO NUMBER\f[R])@
-.
-\f[CB].NOAUTOPARAGRAPH\f[R]@(=\f[CB].NAP\f[R])@T{
-\f[CB].AUTOPARAGRAPH \f[R](\f[CB].AP\f[R])
-.br
-\f[CB]\ .PARAGRAPH \f[I]n,v,t \f[R](\f[CB].P\f[R])
-T}
-.
-\f[CB].NOFILL\f[R]@=(\f[CB].NF\f[R])@T{
-\f[CB].FILL
-.br
-\f[R](\f[CB].F\f[R])
-T}
-.
-\f[CB].NO FLAGS CAPITALIZE\f[R]@(=\f[CB].NFL\f[R])@T{
-\f[CB].FLAGS CAPITALIZE
-.br
-\f[R](\f[CB].FL CAPITALIZE\f[R])
-T}
-.
-\f[CB].NO FLAGS HYPHENATE\f[R]@(=\f[CB].NFH\f[R])@T{
-\f[CB].FLAGS HYPHENATE
-.br
-\f[R](\f[CB].FL HYPHENATE\f[R])
-T}
-.
-\f[CB].NOHEADER\f[R]@(=\f[CB].NHD\f[R])@T{
-\f[CB].HEADER \f[I]arg
-.br
-\f[R](\f[CB].HD\f[R])
-T}
-.
-\f[CB].NO HYPHENATION \f[R]@(=\f[CB].NHY\f[R])@T{
-\f[CB].HYPHENATION
-.br
-\f[R](\f[CB].HY\f[R])
-T}
-.
-\f[CB].NOJUSTIFY \f[R]@(=\f[CB].NJ\f[R])@T{
-\f[CB].JUSTIFY
-.br
-\f[R](\f[CB].J\f[R])
-T}
-.
-\f[CB].NONUMBER \f[R]@(=\f[CB].NNM\f[R])@T{
-\f[CB].NUMBER \f[I]n
-.br
-\f[R](\f[CB].NM\f[R])
-T}
-.
-\f[CB].NOPERIOD \f[R]@(=\f[CB].NPR\f[R])@T{
-\f[CB].PERIOD
-.br
-\f[R](\f[CB].PR\f[R])
-T}
-.
-\f[CB].NOTE text \f[R]@(=\f[CB].NT\f[R])@T{
-\f[CB].END NOTE
-.br
-\f[R](\f[CB].EN\f[R])
-T}
-.
-\f[CB].NPR\f[R]@(=\f[CB].NO PERIOD\f[R])@
-\f[CB].NT\f[R]@(=\f[CB].NOTE\f[R])@
-\f[CB].NUMBER APPENDIX \f[I]a\f[R]@@\f[CB].APPENDIX text
-\f[CB].NUMBER CHAPTER \f[I]n\f[R]@@\f[CB].CHAPTER text
-_
-\f[CB].P\f[R]@(=\f[CB].PARAGRAPH\f[R])@
-\f[CB].PAGE\f[R]@(=\f[CB].PG\f[R])@
-\f[CB].PAGE SIZE\f[R]@(=\f[CB].PAPER SIZE\f[R])@
-.
-\f[CB].PAPER SIZE \f[I]v\f[CB],\f[I]h\f[R]@T{
-(=\f[CB].PS\f[R]
-.br
-\f[CB].PAGE SIZE\f[R])
-T}@
-.
-\f[CB].PARAGRAPH \f[I]h\f[CB],\f[I]v\f[CB],\f[I]t \f[R]@(=\f[CB].P\f[R])@
-\f[CB].SKIP \f[I]n\f[R]@(=\f[CB].S\f[R])@\f[CB].BLANK \f[I]n \f[R](\f[CB].B\f[R])
-\f[CB].SP\f[R]@(=\f[CB].SPACING\f[R])@
-\f[CB].SPACING \f[I]n \f[R]@(=\f[CB].SP\f[R])@
-.
-\f[CB].PERIOD\f[R]@(=\f[CB].PR\f[R])@T{
-\f[CB].NOPERIOD
-.br
-\f[R](\f[CB].NPR\f[R])
-T}
-.
-\f[CB].PG\f[R]@(=\f[CB].PAGE\f[R])@
-\f[CB].PITCH\f[R]@(=\f[CB].PIT\f[R])@
-
-.\f[CB].PRINT INDEX \f[R]@(=\f[CB].PX\f[R])@T{
-\f[CB].DO INDEX text
-.br
-\f[R](\f[CB].DX\f[R])
-T}
-.
-\f[CB].PS\f[R]@(=\f[CB].PAPER SIZE\f[R])@
-\f[CB].PX\f[R]@(=\f[CB].PRINT INDEX\f[R])@
-_
-\f[CB].RIGHT MARGIN \f[I]n \f[R]@(=\f[CB].RM\f[R])@
-\f[CB].RM\f[R]@(=\f[CB].RIGHT MARGIN\f[R])@
-_
-\f[CB].S\f[R]@(=\f[CB].SKIP\f[R])@
-\f[CB].SD\f[R]@(=\f[CB].STANDARD\f[R])@
-\f[CB].ST\f[R]@(=\f[CB].SUBTITLE\f[R])@
-\f[CB].SUBPAGE\f[R]@@\f[CB].END SUBPAGE
-\f[CB].SUBTITLE \f[I]text \f[R]@(=\f[CB].ST\f[R])@
-_
-\f[CB].T\f[R]@(=\f[CB].TITLE\f[R])@
-\f[CB].TAB STOPS \f[I]n,n, \*[Ellipsis] ,n \f[R]@(=\f[CB].TS\f[R])@
-\f[CB].TEST PAGE \f[I]n \f[R]@(=\f[CB].TP\f[R])@
-\f[CB].TITLE text\f[R]@(=\f[CB].T\f[R])@
-\f[CB].TP\f[R]@(=\f[CB].TEST PAGE\f[R])@
-\f[CB].TS\f[R]@(=\f[CB].TAB STOPS\f[R])@
-_
-\f[CB].UC\f[R]@(=\f[CB].UPPER CASE\f[R])@
-.
-\f[CB].UPPER CASE\f[R]@(=\f[CB].UC\f[R])@T{
-\f[CB].LOWER CASE
-.br
-\f[R](\f[CB].LC\f[R])
-T}
-.
-_
-\f[CB].X\f[R]@(=\f[CB].INDEX\f[R])@
-.
-.TE
-.
-.hy
-.fi
-.
-.
-.\" End of tbl ----------------------------------------------------------------
-.
-.
-.if t \{
-.  endTBL
-.\}
-.
-.
-.\" use groff_hdtbl
-.if t \{
-.  mso hdtbl.tmac
-.  TableHDTBL
-.\}
-.
-.
-.\" --------------------------------------------------------------------
-.SH EXPERIMENTAL ADDITIONS 1965
-.\" --------------------------------------------------------------------
-.
-.
-These
-.I "control words"
-are documented in
-.FONT CI Saltzer R 's
-documentation of 1965.
-.
-It is unsure whether they were really implemented.
-.
-.
-.P
-In this documentation, all
-.I control words
-are written in
-.IR "lower case" .
-.
-The writing in
-.I upper case
-is not mentioned, the same is true for
-.IR abbreviations .
-.
-So this documentation uses only
-.IR "lower case" . 
-.
-.
-.TP
-.FONT CB .FIGURE
-This
-.I control word
-turns control over to a 
-.I figure
-.IR processor ,
-which creates in
-.I core memory
-a representation of a
-.I flow diagram
-under the control of a few special
-.IR "control words" .
-When the
-.I control word
-.FONT CB ".END FIGURE"
-is encountered, the completed picture is printed immediately on the
-page being generated if there is room on that page; otherwise the
-.I figure
-will appear at the top of the next page.
-.
-.
-.RS
-.
-.
-.P
-Text following the
-.FONT CB ".END FIGURE"
-.I control word
-will be smoothly attached to text before the
-.FONT CB .FIGURE R .
-.
-No break is generated.
-.
-(Restriction: If a
-.I figure
-is being held for placement at the top of the next page, another
-.I figure
-may not be encountered before the first one is printed.)
-.
-.
-.P
-The only
-.I control words
-which are recognized when in the
-.I \%figure processor
-are the following three:
-.FONT CB .FRAME R ,
-.FONT CB .BOX R ,
-and
-.FONT CB ".END FIGURE" R .
-.
-.
-.RE
-.
-.
-.TP
-.FONT CB .FRAME I " m n"
-This
-.I control word
-intitalizes the
-.I figure  processor
-by giving the height and width of the figure to be produced.
-.
-.I m
-is
-the height, in lines; and
-.I n
-is the width, in characters.
-.
-(Note that a 1050 types 6 lines per inch, and 10 characters per inch.)
-.
-.
-.RS
-.
-.
-.P
-Any attempt to place items in the picture which extend beyond the
-boundaries will cause an error comment to be generated.
-.
-.I \%m
-and
-.I \%n
-must both be less than 100 and their product must be smaller than
-5400.
-.
-We may now think of the
-.I figure
-to be produced as an array of
-.I m
-times
-.I n
-elements.
-.
-.
-.RE
-.
-.
-.TP
-.FONT CB .BOX I " i j"
-The text on the lines following this
-.I control word
-will be placed in the
-.I figure
-such that the first character on the first line following the
-.FONT CB .BOX
-will appear in row
-.IR i ,
-character position
--IR j .
-.
-The end of the text is indicated by a
-.FONT CB .BOX
-.I control word
-for another piece of text or the
-.FONT CB ".END FIGURE"
-.I control
-.IR word .
-.
-Temporarily, the text should not include underlined or overtyped
-characters.
-.
-.
-.TP
-.FONT CB ".END FIGURE"
-This
-.I control word
-causes control to return to the regular
-.I control processor
-of the
-.FONT CB RUNOFF
-command, for the decision to print the picture.
-.
-Note that another
-.FONT CB .FIGURE
-.I control word
-may not appear until after this
-.I figure
-has been printed.
-.
-.
-.RS
-.P
-One further
-.I control word
-has been added which is intended to facilitate bringing out revised
-editions of a memorandum.
-.
-.
-.RE
-.
-.
-.TP
-.FONT CB .FLAG
-The next line to be printed after this
-.I control word
-is encountered will have an asterisk placed two spaces to the right of
-the right margin, as illustrated.
-.
-.
-.TP
-.FONT CB .DEFINE I " symbol"
-.
-This
-.I control word
-defines  the  value  of  the  symbol
-.I symbol
-to be the number of the page currently being printed.
-.
-The symbol may be used later with the
-.FONT CB .USE
-.I control word
-to cause printing of the page number in text.
-.
-The characters in the symbol must be mappable into the six\-bit
-character set, and all symbols must be six of fewer characters.
-.
-.
-.TP
-.FONT CB .USE I " symbol"
-The value of the symbol
-.I symbol
-is inserted into the text with a single blank preceding and no blank
-following.
-.
-If the symbol has not been previously defined, its value is
-.FONT CB 0 R .
-Text may continue following a blank typed after the symbol.
-.
-.
-.RS
-.
-.
-.P
-Here is an example of the use of these
-.I control
-.IR words .
-.
-.
-.RS
-.
-.
-.P
-In one area of text:
-.
-.
-.RS
-.
-.
-.P
-We now discuss the operation of the typewriter
-.FONT CB ".DEFINE REF1"
-coordinator module, which \*[Ellipsis]
-.
-.
-.RE
-.
-.
-.P
-In a later area of text:
-.
-.
-.RS
-.
-.
-.P
-As we saw in the discussion of the typewriter coordinator on page
-.FONT CB ".USE REF1" R ,
-the rest of \*[Ellipsis]
-.
-.
-.RE
-.
-.
-.P
-if the first area of text were on page 14, the later line would read:
-.
-.
-.RS
-.
-.
-.P
-As we saw in the discussion of the typewriter coordinator on page 14,
-the rest of \*[Ellipsis]
-.
-.
-.RE
-.RE
-.RE
--
-.
-.\" --------------------------------------------------------------------
-.SS Further Study of Experimental Additions
-.\" --------------------------------------------------------------------
-.
-A number of suggestions have been made for extending the
-.I control word
-language of
-.FONT CI RUNOFF R ,
-and its capabilities.
-.
-These are listed here, primarily to elicit comment and discussion,
-both on the language which describes these operations and the less
-important problem of their implementation.
--
-.
-.TP
-1.
-.
-Word division.
-.
-This is a whole are of study in itself.
-.
-.
-.TP
-2.
-.
-Automatic  footnote  insertion.
-.
-This was handled somewhat awkwardly in the
-.FONT CB DITTO
-.IR command ,
-although the basic approach was probably reasonable.
-.
-.
-.TP
-3.
-.
-Automatic page references, perhaps via some symbolic reference scheme.
-.
-This would enable the page number in "as was described on page 32" to
-be inserted by the program.
-.
-The analogy with an assembly program should be hotly pursued for
-ideas.
-.
-.
-.TP
-4.
-.
-Special provision for printing facing pages.
-.
-This would require alternate running heads, placing page numbers
-alternately at right and left, and matching line counts on facing
-pages.
-.
-.
-.TP
-5.
-.
-Improved page\-division rules, to prevent the last line of a paragraph
-appearing alone at the top of a page, for example.
-.
-At present, copy must be run off to check by hand that awkward page
-divisions have not been made.
-.
-.
-.TP
-6.
-.
-Automatic generation of page numbers for a table of contents.
-.
-Again, the analogy of an assembly program symbol table appears
-fruitful.
-.
-.
-.TP
-7.
-.
-Automatic generations of an index.
-.
-The problem here is obtaining too many references to a given word,
-many irrelevant.
-.
-.
-.TP
-8.
-.
-Arrangement of tabulated data.
-.
-This problem may have already been partly approached with the
-above\-described figure generator, or the facilities already available
-in
-.IR RUNOFF ,
-but automatic setup of column widths and positions would be desirable.
-.
-One could include in this category the ability to call on other
-programs to computer numbers to place in tables, although this is
-going pretty far afield.
-.
-.
-.TP
-9.
-.
-Placing figures in a
-.I "cut"
-or
-.IR inset .
-.
-The control language is the most difficult problem here.
-.
-.
-.TP
-10.
-.
-Equation typing and  numbering.
-.
-Again, the control language appears formidable.
-.
-.
-.\" --------------------------------------------------------------------
-.SH MANUSCRIPT CONVENTIONS
-.\" --------------------------------------------------------------------
-.
-Initially,
-.FONT CI RUNOFF
-is set to
-.I FILL
-mode, such as by using
-.FONT CB .FILL R .
-.
-The filling is identical to
-.FONT CI groff R 's
-filling mode:
-.
-Text lines will normally be adjuted by inserting extra spaces in
-mid\-line so that the end of the line is on the right margin.
-.
-.
-.\" --------------------------------------------------------------------
-.SH AVAILABLE RUNOFF FILES
-.\" --------------------------------------------------------------------
-.
-You can still find text files in the
-.FONT CI RUNOFF
-language.
-.
-.
-.P
-In the
-.nh
-.UR http://\:www.columbia.edu/\:kermit/\:pdp10.html
-Kermit website
-.UE
-you find 3 files in
-.FONT CI RUNOFF
-language maybe of the
-.FONT CR Multics
-era or later:
-.
-.Topic
-.UR ftp://\:kermit.columbia.edu/\:kermit/\:d/\:k10133.rno
-.FONT CR k10133.rno
-.UE
-.
-.Topic
-.UR ftp://\:kermit.columbia.edu/\:kermit/\:d/\:k10mit.rnh
-.FONT CR k10mit.rnh
-.UE
-.
-.Topic
-.UR ftp://\:kermit.columbia.edu/\:kermit/\:d/\:k10v3.rno
-.FONT CR k10v3.rno
-.UE
-.hy
-.
-.
-.P
-At
-.nh
-.UR http://\:web.mit.edu/\:Saltzer/\:www/\:publications/\:pubs.html
-.FONT CR Saltzer R 's
-publication website
-.UE
-you find files in
-.FONT CI RUNOFF
-of the
-.FONT CR Multics
-era.
-.hy
-.
-Search there for
-.nh
-.FONT CR runoff
-and you will find the following 5 files:
-.
-.Topic
-.UR http://\:web.mit.edu/\:Saltzer/\:www/\:publications/\:whyring/\:whyring.run
-.FONT CR whyring.run
-.UE
-.
-.Topic
-.UR http://\:web.mit.edu/\:Saltzer/\:www/\:publications/\:starring/\:starring.run
-.FONT CR starring.run
-.UE
-.
-.Topic
-.UR http://\:web.mit.edu/\:Saltzer/\:www/\:publications/\:tmring.run
-.FONT CR tmring.run
-.UE
-.
-.Topic
-.UR http://\:web.mit.edu/\:Saltzer/\:www/\:publications/\:florence.run
-.FONT CR "RFC1498 florence.run"
-.UE
-.
-.Topic
-.UR http://\:web.mit.edu/\:Saltzer/\:www/\:publications/\:sourcerouting/\:zurich.run
-.FONT CR zurich.run
-.UE
-.hy
-.
-.
-.P
-Most
-.nh
-.FONT CI RUNOFF
-files are found in the
-.UR http://\:pdp-10.trailing-edge.com/\:cgi-bin/
-.FONT CR "DEC PDP\-10 archive"
-.UE .
-.
-Many files are very old as they are written in
-.I upper case
-only:
-.
-.Topic
-.UR http://\:pdp-10.trailing-edge.com/\:cgi-bin/\:searchbyname?name=*.rno
-normal documents
-.FONT CB *.rno
-in
-.FONT CI RUNOFF
-.UE
-.
-.Topic
-.UR http://\:pdp-10.trailing-edge.com/\:cgi-bin/\:searchbyname?name=*.rnh
-.FONT CB *.rnh
-help files in
-.FONT CI RUNOFF
-.UE
-.
-.Topic
-.UR http://\:pdp-10.trailing-edge.com/\:cgi-bin/\:searchbyname?name=runoff.*
-.FONT CB runoff.*
-documents about
-.FONT CI RUNOFF
-.UE
-.hy
-.
-.
-.\" --------------------------------------------------------------------
-.SH "SEE ALSO"
-.\" --------------------------------------------------------------------
-.
-.
-.PP
-.\" BR RUNOFF (@MAN1EXT@),
-.BR groff (@MAN1EXT@),
-.BR groff (@MAN7EXT@),
-.BR roff (@MAN7EXT@),
-.BR groff_filenames (@MAN7EXT@)
-.
-.
-.TP
-.FONT R "1964 " CR "Jerome H. Saltzer" R :
-.nh
-.FONT CI "Jerome H. Saltzer \[em] TYPSET and RUNOFF, Memorandum editor and \
-type\-out commands"
-.hy
-available at
-.UR \%http://\:mit.edu/\:Saltzer/\:www/\:publications/\:CC\-244.html
-.UE
-.
-.
-.TP
-.FONT R "1965 " CR "Jerome H. Saltzer" R :
-.nh
-.FONT CI "Jerome H. Saltzer \(em Experimental Additions to the RUNOFF Command"
-available at
-.UR http://\:web.mit.edu/\:afs/\:athena.mit.edu/\:user/\:other/\
-\:a/\:Saltzer/\:www/\:publications/\:PSN\-40.html
-.UE
-.hy
-.
-.
-.TP
-.FONT R "1966 " CR "Jerome H. Saltzer" R :
-.nh
-.FONT CI "Jerome H. Saltzer \[em] Manuscript Typing and Editing"
-.hy
-which is available in the internet at
-.UR http://\:mit.edu/\:Saltzer/\:www/\:publications/\:AH.9.01.html
-.I MIT html
-.UE
-or
-.UR \%http://\:web.mit.edu/\:Saltzer/\:www/\:publications/\:ctss\/\:AH.9.01.html
-.I CTSS html
-.UE
-or
-.UR \%http://\:web.mit.edu/\:Saltzer/\:www/\:publications/\:ctss/\:AH.9.01.pdf
-.I CTSS pdf
-.UE .
-.
-.
-.TP
-.FONT R "1973 " CR "Larry Barnes" R :
-.FONT CI "Larry Barnes \[em] RUNOFF: A Program for the Preparation of Documents"
-available as
-.UR http://\:www.textfiles.com/\:bitsavers/\:pdf/\:sds/\:9xx/\:940/\
-\:ucbProjectGenie/\:mcjones/\:R\-37_RUNOFF.pdf
-.I pdf
-.UE .
-.
-.
-.TP
-.FONT R "1974 " CR "DEC RSTS" R :
-.FONT CI "RUNOFF User's Guide" R : CR " v8.0-v4-d-rsts_e_runoff_users_guide.pdf"
-at
-.UR http://elvira.stacken.kth.se/rstsdoc/rsts-doc-v80/v8.0-v4-d-rsts_e_runoff_users_guide.pdf
-.I DEC RSTS
-.UE .
-.
-.
-.TP
-.FONT R "1981 " CR PDP\-11 R :
-This is the latest documentation on
-.FONT CI RUNOFF
-available as
-.UR http://\:malarky.udel.edu/\:~dmills/\:data/\:du0/\:RUNOFF.DOC
-text file.
-.UE .
-.
-More exactly, this
-.FONT CB .DOC
-file is an output file produced by the
-.FONT CB RUNOFF
-program a long time ago.
-.
-This extension doesn't work on actual systems who expect a Microsoft
-office file.
-.
-You have to rename this file by appending the
-.FONT CB .txt
-extension.
-.
-Then the file can be viewed by
-.FONT CB more
-or
-.FONT CB less R .
-.
-.
-.P
-.nh
-.UR http://\:www.cozx.com/\:~dpitts/\:ibm7090.html 
-Emulator for
-.FONT CR "IBM 7090 CTSS"
-.UE .
-.hy
-.
-.
-.P
-The home page of
-.FONT CI "Jerome H. Saltzer"
-is
-.UR http://\:web.mit.edu/\:Saltzer/
-.UE .
-.
-.
-.SH "AUTHORS"
-.\" --------------------------------------------------------------------
-.
-.authors
-.
-.
-.\" --------------------------------------------------------------------
-.SH "COPYING"
-.\" --------------------------------------------------------------------
-.
-.copying
-.
-.
-.\" --------------------------------------------------------------------
-.\" Emacs settings
-.\" --------------------------------------------------------------------
-.
-.\" Local Variables:
-.\" mode: nroff
-.\" End:
-

Index: chem/ChangeLog
===================================================================
RCS file: chem/ChangeLog
diff -N chem/ChangeLog
--- chem/ChangeLog	29 Jan 2013 11:02:10 -0000	1.18
+++ /dev/null	1 Jan 1970 00:00:00 -0000
@@ -1,232 +0,0 @@
-2013-01-29  Werner LEMBERG  <wl@gnu.org>
-
-	* Makefile.sub (MOSTLYCLEANADD): Fix typo.
-
-2010-12-13  Werner LEMBERG  <wl@gnu.org>
-
-	Really fix handling of examples/122.
-
-	* examples/122/README: Renamed to...
-	* examples/122/README.txt: This.
-
-	* Makefile.sub (all, MOSTLYCLEANADD): Add `examples/122/README'.
-	(examples/122/README): New target.
-	(install_data): Fix typo.
-
-2010-06-02  Larry Jones  <lawrence.jones@siemens.com>
-
-	* Makefile.sub (install): Fix handling of examples/122.
-	It tried to process the CVS subdirectory as a file.
-
-2009-01-03  Werner LEMBERG  <wl@gnu.org>
-
-	* chem.pl: Prepare for groff version 1.20.
-
-2008-01-04  Werner LEMBERG  <wl@gnu.org>
-
-	* chem.man: Insert `\:' in URLs where appropriate.
-
-2007-02-06  Eric S. Raymond  <esr@snark.thyrsus.com>
-
-	* chem.man: Change .UR/.UE and .MT/.ME so the start macro no longer
-	takes a second argument that is pasted to the end of the generated
-	text.  Instead, the end macro takes an argument that does the same
-	thing.
-
-2007-02-02  Werner LEMBERG  <wl@gnu.org>
-
-	* chem.man: Further refinements and normalizations.
-
-2007-02-02  Eric S. Raymond  <esr@snark.thyrsus.com>
-
-	* chem.man: Converted to use .SY/.OP/.YS and for cross-viewer
-	portability.  Conversion checked using the protocol described in
-	tmac/TESTING-HINTS.
-
-2006-11-10  Bernd Warken <groff-bernd.warken-72@web.de>
-       ________________________________________________________________
-        * release of chem 0.3.1
-
-	* chem.man: Add information about example files.
-
-2006-11-10  Werner LEMBERG  <wl@gnu.org>
-
-        * chem.man1: Rename back to...
-        * chem.man: This.
-        Use @G@, @MACRODIR@, and @DATASUBDIR@.
-
-        * Makefile.sub (CLEANADD, all): Don't handle chem.man.
-        (chem.man): Remove rule.
-        (chem): s/tmacdir/MACRODIR/, s/picdir/PICDIR/.
-
-        * chem.pl: s/tmacdir/MACRODIR/, s/picdir/PICDIR/.
-
-2006-11-10  Bernd Warken <groff-bernd.warken-72@web.de>
-       ________________________________________________________________
-        * release of chem 0.3.0
-
-	* chem.man1: Rename `chem.man' to translate some `@...@'
-	constructs.  Some minor corrections.  Remove some unused macros.
-
-	* examples/README.txt, examples/122/README: Add information on
-	`roff2*' programs.
-
-	* chem.pic: Rename `macros.pic'.
-
-	* Makefile.sub, chem.pl: Replace `macros.pic' by `chem.pic'.
-
-2006-11-09  Werner LEMBERG  <wl@gnu.org>
-
-        * chem.man: Revised.
-
-2006-11-08  Bernd Warken <groff-bernd.warken-72@web.de>
-       ________________________________________________________________
-        * release of chem 0.2.0
-
-	* pic.tmac: Remove this file.  Use instead the installed pic.tmac
-	in $(tmacdir).
-
-	* Makefile.sub, chem.pl:
-	- Install macros.pic to $(tmacdir)/pic/chem.pic.
-	- Remove parts with `libdir'.
-
-2006-11-07  Werner LEMBERG  <wl@gnu.org>
-
-	* Makefile.sub: Add and fix $(srcdir) where necessary to make it
-	compile with srcdir != builddir.  Other minor fixes improvements.
-
-2006-11-07  Bernd Warken <groff-bernd.warken-72@web.de>
-       ________________________________________________________________
-        * release of chem 0.1.2
-
-	### `chem' works now with all example files (examples/*.chem and
-	examples/122/*.chem).
-	
-	* examples/122/README: Add some information on the example files.
-	
-	* examples/122/chAi_poly_vinyl_chloride.chem: Use .ps with
-	argument `-2' and recall `.ps +2' at the end of the file.  This
-	stops the size shift in the following files.
-
-	* examples/122/ch6b_dna.chem: Make the file runnable, it works
-	now.
-
-	* examples/reserpine.chem: Change access to `begin chem'.
-
-	* chem.man:
-	- Fix the BUGS section.
-	- Correct the name of the macro file to `macros.pic'.
-	- Extent section DESCRIPTION and LANGUAGE.
-	- Moieties and Strings: Rewritten section about moieties and
-	double quoted strings.
-
-	* chem.pl:
-	- parameter check: Add filespecs only when non-empty file.
-	- Set $Last_Type to $OTHER for the `pic' command.
-	- joinring(), label(), labsave(), reduce(): Remove these functions.
-	- `[', `]', `{', `}', `define': Make these and the defined
-	functions commands for `chem' without using the `pic' word.
-	- @Words: Fix it such that all double quoted strings are
-	completely in an element.
-	- `Last: ': Remove this prefix from all commands that are related
-	to `pic'.
-
-	### global variables
-	
-	* chem.pl:
-	- $Line: Add this variable to store the unchanged input line.
-	- %Params: Add the variables from setparams() to this hash.
-	- %Types: Add BOND, MOL, RING, OTHER from init() to this hash.
-	- %Put: Move %put to this.
-	- %Dbl: Move %dbl to this.
-	- %Labtype: Move %labtype to this.
-	- %Aromatic: Move $aromatic to this.
-	- %Dc: Move %dc to this.
-	- %Nput: Move $nput to this.
-	- %Define: New hash for storing the names of the `define'
-	constructs during `chem'.  Use the elements in `%Define' as `chem'
-	commands.
-
-2006-10-27  Bernd Warken <groff-bernd.warken-72@web.de>
-       ________________________________________________________________
-        * release of chem 0.1.1
-
-	* chem.pl:
-	- Add handling of `[' and `]' (extension of chem awk).
-	- Restrict line break after labels.
-
-	* ChangeLog: Correct the former entry.
-	
-2006-10-26  Bernd Warken <groff-bernd.warken-72@web.de>
-       ________________________________________________________________
-        * release of chem 0.1.0
-
-	### Extensions to the chem awk version.
-	
-	* chem.pl:
-	- parameters: -h, --help, -v, --version, -- are added as options.
-	The minus character - is added as filespec for standard input, it
-	may be used several times.
-	- remove the functions `inline', `shiftfields', and `set'.
-	- Fix the handling of the initialization commands .PS, .cstart,
-	`begin chem', and `end'.
-	- Add error massages.
-	- error(): Add file name.
-	- Add concatenation of lines with final backslash `\'.
-	- Add pic.tmac to guarantee that each pic display is centered.
-	- Warnings and strict are active.
-
-	### Source files of the chem Perl version
-
-	* chem.pl: Source file for the Perl version of chem.
-
-	* macros.pic: Pic macro file that is loaded by each run of chem.
-
-	* pic.tmac: Macro file for .PS and .PE; taken over from the groff
-	source file <groff-top-source>/tmac/pic.tmac.
-
-	* Makefile.sub: Make file for the groff system.
-
-	* ChangeLog: This file.
-	
-	* chem.man: Manual page for the Perl version of chem.
-
-	* README.txt: File for information on this chem version.
-
-	* examples/*.chem: Self-constructed example files for chem.
-
-	* examples/README.txt: Information on the example files.
-	
-	* examples/122/*.chem: Example files from the classical chem book
-	122.ps at <http://cm.bell-labs.com/cm/cs/cstr/122.ps.gz>.
-
-	* examples/122/README: Information on the example files in this
-	directory.
-
-2006-10-16  Bernd Warken <groff-bernd.warken-72@web.de>
-
-	* awk version of chem
-	chem is a roff preprocessor that generates chemical structure
-	diagrams suitable for the pic preprocessor.  The original version
-	of chem is an awk script written by Brian Kernighan.  This project
-	is a rewrite of chem in Perl.
-	
-2006-10-15  Bernd Warken <groff-bernd.warken-72@web.de>
-	________________________________________________________________
-	License
-
-	Copyright (C) 2006-2010, 2013
-	Free Software Foundation, Inc.
-	Written by Bernd Warken <groff-bernd.warken-72@web.de>.
-
-	Copying and distribution of this file, with or without
-	modification, are permitted provided the copyright notice and this
-	notice are preserved.
-
-	This file is part of `chem', which is part of the `groff' project.
-
-        ####### Emacs settings
-
-        Local Variables:
-        mode: change-log
-        End:

Index: chem/Makefile.sub
===================================================================
RCS file: chem/Makefile.sub
diff -N chem/Makefile.sub
--- chem/Makefile.sub	29 Jan 2013 11:02:10 -0000	1.16
+++ /dev/null	1 Jan 1970 00:00:00 -0000
@@ -1,112 +0,0 @@
-# Makefile.sub for `chem' (integration into the `groff' source tree)
-
-# File position: <groff-source>/contrib/chem/Makefile.sub
-
-# Copyright (C) 2006, 2009, 2010, 2013 Free Software Foundation, Inc.
-# Written by Bernd Warken <groff-bernd.warken-72@web.de>.
-
-# Last update: 29 Jan 2013
-
-# This file is part of `chem' 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/>.
-
-########################################################################
-
-MAN1=chem.n
-MOSTLYCLEANADD=\
-  chem \
-  chem.n \
-  README \
-  examples/README \
-  examples/122/README
-
-# not all make programs have $(RM) predefined.
-RM=rm -f
-
-all: README examples/README examples/122/README \
-     chem \
-     $(MAN1)
-
-README: $(srcdir)/README.txt
-	sed -e "s|@g@|$(g)|g" $? >$@
-
-examples/README: $(srcdir)/examples/README.txt
-	-test -d examples || $(mkinstalldirs) examples
-	sed -e "s|@g@|$(g)|g" $? >$@
-
-examples/122/README: $(srcdir)/examples/122/README.txt
-	-test -d examples || $(mkinstalldirs) examples
-	-test -d examples/122 || $(mkinstalldirs) examples/122
-	sed -e "s|@g@|$(g)|g" $? >$@
-
-chem: $(srcdir)/chem.pl $(SH_DEPS_SED_SCRIPT)
-	sed -f "$(SH_DEPS_SED_SCRIPT)" \
-	  -e "s|@g@|$(g)|g" \
-	  -e "s|@BINDIR@|$(DESTDIR)$(bindir)|g" \
-	  -e "s|@MACRODIR@|$(DESTDIR)$(tmacdir)|g" \
-	  -e "s|@PICDIR@|$(DESTDIR)$(datasubdir)/pic|g" \
-	  -e "s|@VERSION@|$(version)$(revision)|g" \
-	  -e "$(SH_SCRIPT_SED_CMD)" \
-	  $(srcdir)/chem.pl >$@
-	chmod +x $@
-
-install_data: chem \
-              README examples/README examples/122/README \
-              $(srcdir)/chem.pic \
-              $(srcdir)/examples/*.chem $(srcdir)/examples/122/*.chem
-	-test -d $(DESTDIR)$(bindir) || $(mkinstalldirs) $(DESTDIR)$(bindir)
-	$(RM) $(DESTDIR)$(bindir)/$(g)chem
-	$(INSTALL_SCRIPT) chem $(DESTDIR)$(bindir)/$(g)chem
-	-test -d $(DESTDIR)$(datasubdir)/pic \
-          || $(mkinstalldirs) $(DESTDIR)$(datasubdir)/pic
-	$(RM) $(DESTDIR)$(datasubdir)/pic/chem.pic
-	$(INSTALL_DATA) $(srcdir)/chem.pic \
-          $(DESTDIR)$(datasubdir)/pic/chem.pic
-	-test -d $(DESTDIR)$(exampledir)/chem \
-          || $(mkinstalldirs) $(DESTDIR)$(exampledir)/chem
-	-test -d $(DESTDIR)$(exampledir)/chem/122 \
-          || $(mkinstalldirs) $(DESTDIR)$(exampledir)/chem/122
-	-$(RM) $(DESTDIR)$(exampledir)/chem/*
-	$(INSTALL_DATA) examples/README \
-          $(DESTDIR)$(exampledir)/chem/README
-	for i in $(srcdir)/examples/*.chem; do \
-          n=`echo $$i | sed 's|$(srcdir)/examples/||g'`; \
-          $(INSTALL_DATA) $$i $(DESTDIR)$(exampledir)/chem/$$n; \
-        done
-	-$(RM) $(DESTDIR)$(exampledir)/chem/122/*
-	$(INSTALL_DATA) examples/122/README \
-          $(DESTDIR)$(exampledir)/chem/122/README
-	for i in $(srcdir)/examples/122/*.chem; do \
-          n=`echo $$i | sed 's|$(srcdir)/examples/122/||g'`; \
-          $(INSTALL_DATA) $$i $(DESTDIR)$(exampledir)/chem/122/$$n; \
-        done
-
-uninstall_sub:
-	$(RM) $(DESTDIR)$(bindir)/chem
-	$(RM) $(DESTDIR)$(datasubdir)/pic/chem.pic
-	-rmdir $(DESTDIR)$(datasubdir)/pic
-	$(RM) $(DESTDIR)$(exampledir)/chem/122/*
-	-rmdir $(DESTDIR)$(exampledir)/chem/122
-	$(RM) $(DESTDIR)$(exampledir)/chem/*
-	-rmdir $(DESTDIR)$(exampledir)/chem
-	-rmdir $(DESTDIR)$(exampledir)
-
-########################################################################
-# Emacs settings
-########################################################################
-#
-# Local Variables:
-# mode: makefile
-# End:

Index: chem/README.txt
===================================================================
RCS file: chem/README.txt
diff -N chem/README.txt
--- chem/README.txt	22 Jan 2013 00:29:39 -0000	1.5
+++ /dev/null	1 Jan 1970 00:00:00 -0000
@@ -1,52 +0,0 @@
-`chem' is a `roff' language to generate chemical structure diagrams.
-`@g@chem' is a `groff' preprocessor that produces output suitable for
-the `@g@pic' preprocessor.
-
-The original version of `chem' is an `awk' script written by Brian
-Kernighan <http://cm.bell-labs.com/cm/cs/who/bwk/index.html>.  The
-source files of the `awk' version of `chem' are available at
-<http://cm.bell-labs.com/netlib/typesetting/chem.gz>.
-
-This project is a rewrite of `chem' in Perl for the GNU `roff' project
-`groff'.  It was written under Perl v5.8.8, but at least Perl v5.6 is
-needed to run the Perl version of `chem'.
-
-In comparison to the original `awk' version of `chem', the Perl
-version does the following changements:
-- the options -h, --help, -v, --version to output usage and version
-information are added.
-- remove some functions `inline', `shiftfields', and `set' and some
-variables that are used only once.
-
-The subdirectory `examples/' contains example files for chem.  They
-are written in the `chem' language.  The file names end with .chem.
-
-
-####### License
-
-Last update: 5 Jan 2009
-
-Copyright (C) 2006, 2009 Free Software Foundation, Inc.
-Written by Bernd Warken <groff-bernd.warken-72@web.de>.
-
-This file is part of `chem', 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:

Index: chem/chem.man
===================================================================
RCS file: chem/chem.man
diff -N chem/chem.man
--- chem/chem.man	22 Jan 2013 00:29:39 -0000	1.13
+++ /dev/null	1 Jan 1970 00:00:00 -0000
@@ -1,1017 +0,0 @@
-.ig
-@g@chem.1 - man page for @g@chem (section 1).
-
-Source file position:  <groff_source_top>/contrib/chem/chem.man
-Installed position:    $prefix/share/man/man1/@g@chem.1
-
-Last update: 05 Jan 2009
-..
-.
-.
-.de au
-This file was written by Bernd Warken <groff-bernd.warken-72@web.de>.
-It is based on the documentation of
-.UR http://\:cm.bell-labs.com/\:cm/\:cs/\:who/\:bwk/\:index.html
-Brian Kernighan
-.UE 's
-original
-.I awk
-version of
-.IR chem .
-..
-.
-.
-.de co
-Copyright (C) 2006, 2007, 2008, 2009 Free Software Foundation, Inc.
-.
-.
-.P
-This file is part of
-.IR chem ,
-which is part of
-.IR groff ,
-a free software project.
-.
-You can redistribute it and/or modify it under the terms of the
-.nh
-.B "GNU General Public License"
-.hy
-as published by the
-.nh
-.BR "Free Software Foundation" ,
-.hy
-either version\~2, or (at your option) any later version.
-.
-.
-.P
-You should have received a copy of the \f(CRGNU General Public
-License\fP along with
-.IR groff ,
-see the files \%\f(CBCOPYING\fP and \%\f(CBLICENSE\fP in the top
-directory of the
-.I groff
-source package.
-.
-Or read the
-.I man page
-.BR gpl (1).
-You can also write to the
-.nh
-.B "Free Software Foundation, 51 Franklin St - Fifth Floor, Boston,"
-.BR "MA 02110-1301, USA" .
-.hy
-..
-.
-.
-.\" --------------------------------------------------------------------
-.\" Local macro definitions
-.
-.ds El \&.\|.\|.\&
-.
-.\" .File_name  (<path_name>)
-.\"
-.\" Display a file or directory name in CB font.
-.\"
-.de FN
-.  CB \\$@
-..
-.
-.\" .CB  (<path_name>)
-.\"
-.\" Display a line in CB font, for example after .TP
-.\"
-.de CB
-.nh
-\\&\\f(CB\\$1\\fP\\$2
-.hy
-..
-.
-.\" End of macro definitions
-.
-.
-.TH @G@CHEM @MAN1EXT@ "@MDATE@" "Groff Version @VERSION@"
-.SH NAME
-@g@chem \- groff preprocessor for producing chemical structure diagrams
-.
-.
-.SH "SYNOPSIS"
-.\" --------------------------------------------------------------------
-.\" SH "SYNOPSIS"
-.\" --------------------------------------------------------------------
-.
-.SY @g@chem
-.RI [ "\%option" \*(El]
-.OP \-\-
-.RI [ "\%filespec" \*(El]
-.
-.SY @g@chem
-.B \-h
-|
-.B \-\-help
-.
-.SY @g@chem
-.B \-v
-|
-.B \-\-version
-.YS
-.
-.
-.\" --------------------------------------------------------------------
-.SH OPTION USAGE
-.\" --------------------------------------------------------------------
-.
-.P
-There are no other options than
-.BR \-h ,
-.BR \-\-help ,
-.BR \-v ,
-and
-.BR \%\-\-version ;
-these options provoke the printing of a version or usage information,
-respectively, and all
-.I filespec
-arguments are ignored.
-.
-A
-.I filespec
-argument is either a file name of an existing file or a minus
-character
-.BR \- ,
-meaning standard input.
-.
-If no argument is specified then standard input is taken
-automatically.
-.
-.
-.\" --------------------------------------------------------------------
-.SH DESCRIPTION
-.\" --------------------------------------------------------------------
-.
-.I chem
-produces chemical structure diagrams.
-.
-Today's version is best suited for organic chemistry (bonds, rings).
-.
-The
-.B @g@chem
-program is a
-.B groff
-preprocessor like
-.BR @g@eqn ,
-.BR @g@pic ,
-.BR @g@tbl ,
-etc.
-.
-It generates
-.I pic
-output such that all
-.I chem
-parts are translated into diagrams of the
-.I pic
-language.
-.
-.
-.P
-The program
-.B @g@chem
-originates from the Perl source file
-.FN chem.pl .
-It tells
-.B @g@pic
-to include a copy of the macro file
-.FN chem.pic .
-.
-Moreover the
-.I groff
-source file
-.FN pic.tmac
-is loaded.
-.
-.
-.P
-In a style reminiscent of
-.I eqn
-and
-.IR pic ,
-the
-.I chem
-diagrams are written in a special language.
-.
-.
-.P
-A set of
-.I chem
-lines looks like this
-.
-.
-.IP
-.nf
-.ft B
-\&.cstart
-\fIchem data\fP
-\&.cend
-.ft
-.fi
-.
-.
-.P
-Lines containing the keywords
-.B .cstart
-and
-.B .cend
-start and end the input for
-.BR @g@chem ,
-respectively.
-.
-In
-.I pic
-context, i.e., after the call of
-.BR .PS ,
-.I chem
-input can optionally be started by the line
-.B \%begin\~chem
-and ended by the line with the single word
-.B end
-instead.
-.
-.
-.P
-Anything outside these initialization lines is copied through
-without modification;
-all data between the initialization lines is converted into
-.I pic
-commands to draw the diagram.
-.
-.
-.P
-As an example,
-.
-.IP
-.nf
-.ft B
-\&.cstart
-CH3
-bond
-CH3
-\&.cend
-.ft
-.fi
-.
-.
-.P
-prints two
-.B CH3
-groups with a bond between them.
-.
-.
-.P
-To actually view this, you must run
-.B @g@chem
-followed by
-.BR groffer :
-.
-.IP
-.B "@g@chem [file\*(El] | groffer"
-.
-.P
-If you want to create just
-.B groff
-output, you must run
-.B @g@chem
-followed by
-.B groff
-with the option
-.B \-p
-for the activation of
-.BR @g@pic :
-.IP
-.B "@g@chem [file\*(El] | groff -p \*(El"
-.
-.
-.\" --------------------------------------------------------------------
-.SH THE LANGUAGE
-.\" --------------------------------------------------------------------
-.
-The
-.I chem
-input language is rather small.  It provides rings of several styles
-and a way to glue them together as desired, bonds of several styles,
-moieties (e.g.,
-.BR C ,
-.BR NH3 ,
-\*(El), and strings.
-.
-.
-.\" --------------------------------------------------------------------
-.SS Setting Variables
-.\" --------------------------------------------------------------------
-.
-There are some variables that can be set by commands.
-.
-Such commands have two possible forms, either
-.
-.RS
-.P
-.I "variable value"
-.RE
-.
-.P
-or
-.
-.RS
-.P
-.IB "variable " = " value"
-.RE
-.
-.P
-This sets the given
-.I variable
-to the argument
-.IR value .
-If more arguments are given only the last argument is taken, all other
-arguments are ignored.
-.
-.
-.P
-There are only a few variables to be set by these commands:
-.
-.TP
-.BI textht " arg"
-Set the height of the text to
-.IR arg ;
-default is 0.16.
-.
-.TP
-.BI cwid " arg"
-Set the character width to
-.IR arg ;
-default is 0.12.
-.
-.TP
-.BI db " arg"
-Set the bond length to
-.IR arg ;
-default is 0.2.
-.
-.TP
-.BI size " arg"
-Scale the diagram to make it look plausible at point size
-.IR arg ;
-default is 10 point.
-.
-.
-.\" --------------------------------------------------------------------
-.SS Bonds
-.\" --------------------------------------------------------------------
-.
-This
-.
-.RS
-.SY bond
-.RI [ direction ]
-.RI [ length\ n ]
-.RB [ from\ \c
-.IR Name | picstuff ]
-.YS
-.RE
-.
-.P
-draws a single bond in direction from nearest corner of
-.IR Name .
-.B bond
-can also be
-.BR "double bond" ,
-.BR "front bond" ,
-.BR "back bond" ,
-etc.
-.
-(We will get back to
-.I Name
-soon.)
-.
-.
-.P
-.I direction
-is the angle in degrees (0\~up, positive clockwise)
-or a direction word like
-.BR up ,
-.BR down ,
-.B sw
-(=\~southwest), etc.
-.
-If no direction is specified, the bond goes in the current direction
-(usually that of the last bond).
-.
-.
-.P
-Normally the bond begins at the last object placed;  this
-can be changed by naming a
-.B from
-place.
-.
-For instance, to make a simple alkyl chain:
-.
-.RS
-.TS
-tab (@);
-lb l.
-CH3
-bond@(this one goes right from the CH3)
-C@(at the right end of the bond)
-double bond up@(from the C)
-O@(at the end of the double bond)
-bond right from C
-CH3
-.TE
-.RE
-.
-.
-.P
-A length in inches may be specified to override the default length.
-.
-Other
-.I pic
-commands can be tacked on to the end of a bond command, to created
-dotted or dashed bonds or to specify a
-.B to
-place.
-.
-.
-.\" --------------------------------------------------------------------
-.SS Rings
-.\" --------------------------------------------------------------------
-.
-There are lots of rings, but only 5 and 6-sided rings get
-much support.
-.
-.B ring
-by itself is a 6-sided ring;
-.B benzene
-is the benzene ring with a circle inside.
-.B aromatic
-puts a circle into any kind of ring.
-.
-.RS
-.SY ring
-.RB [ \%pointing\  ( up | right | left | down )]
-.RB [ \%aromatic ]
-.RB [ put\ Mol\ at\ \fIn\fP ]
-.RB [ \%double\ \c
-.IR i , j\ \c
-.IR k , l\ \c
-\*(El]
-.RI [ picstuff ]
-.YS
-.RE
-.
-.
-.P
-The vertices of a ring are numbered 1, 2, \*(El from the
-vertex that points in the natural compass direction.
-.
-So for a hexagonal ring with the point at the top, the top vertex
-is\~1, while if the ring has a point at the east side, that is
-vertex\~1.
-.
-This is expressed as
-.
-.IP
-.ft B
-.nf
-R1: ring pointing up
-R2: ring pointing right
-.fi
-.ft
-.
-.
-.P
-The ring vertices are named
-.BR .V1 ,
-\*(El,
-.BI .V n\fR,\fP
-with
-.B .V1
-in the pointing direction.
-.
-So the corners of
-.B R1
-are
-.B R1.V1
-(the
-.IR top ),
-.BR R1.V2 ,
-.BR R1.V3 ,
-.B R1.V4
-(the
-.IR bottom ),
-etc., whereas for
-.BR R2 ,
-.B R2.V1
-is the rightmost vertex and
-.B R2.V4
-the leftmost.
-.
-These vertex names are used for connecting bonds or other rings.  For
-example,
-.
-.IP
-.ft B
-.nf
-R1: benzene pointing right
-R2: benzene pointing right with .V6 at R1.V2
-.fi
-.ft
-.P
-creates two benzene rings connected along a side.
-.
-.
-.P
-Interior double bonds are specified as
-.BI \%double\  n1 , n2\ n3 , n4\ \fR\*(El;\fP
-each number pair adds an interior bond.
-.
-So the alternate form of a benzene ring is
-.
-.IP
-.B "ring double 1,2 3,4 5,6"
-.
-.
-.P
-Heterocycles (rings with something other than carbon at a vertex) are
-written as
-.BI put\  X\  at\  V\fR,\fP
-as in
-.
-.IP
-.B "R: ring put N at 1 put O at 2"
-.
-.
-.P
-In this heterocycle,
-.B R.N
-and
-.B R.O
-become synonyms for
-.B R.V1
-and
-.BR R.V2 .
-.
-.
-.P
-There are two 5-sided rings.
-.
-.B ring5
-is pentagonal with a side that matches the 6-sided ring; it has four
-natural directions.
-.
-A
-.B \%flatring
-is a 5-sided ring created by chopping one corner of a 6-sided ring so
-that it exactly matches the 6-sided rings.
-.
-.
-.P
-The description of a ring has to fit on a single line.
-.
-.
-.\" --------------------------------------------------------------------
-.SS Moieties and Strings
-.\" --------------------------------------------------------------------
-.
-A moiety is a string of characters beginning with a capital letter,
-such as N(C2H5)2.
-.
-Numbers are converted to subscripts (unless they appear to be
-fractional values, as in N2.5H).
-.
-The name of a moiety is determined from the moiety after special
-characters have been stripped out: e.g., N(C2H5)2) has the name NC2H52.
-.
-.
-.P
-Moieties can be specified in two kinds.
-.
-Normally a moiety is placed right after the last thing mentioned,
-separated by a semicolon surrounded by spaces, e.g.,
-.
-.IP
-.B "B1: bond ; OH"
-.
-.P
-Here the moiety is
-.BR OH ;
-it is set after a bond.
-.
-.
-.P
-As the second kind a moiety can be positioned as the first word in a
-.IR pic -like
-command, e.g.,
-.
-.IP
-.B "CH3 at C + (0.5,0.5)"
-.
-.P
-Here the moiety is
-.BR CH3 .
-It is placed at a position relative to
-.BR C ,
-a moiety used earlier in the chemical structure.
-.
-.
-.P
-So moiety names can be specified as
-.I chem
-positions everywhere in the
-.I chem
-code.
-.
-Beneath their printing moieties are names for places.
-.
-.
-.P
-The moiety
-.B BP
-is special.
-.
-It is not printed but just serves as a mark to be referred to in later
-.I chem
-commands.
-.
-For example,
-.
-.IP
-.B "bond ; BP"
-.
-.P
-sets a mark at the end of the bond.
-.
-This can be used then for specifying a place.
-.
-The name
-.B BP
-is derived from
-.I branch point
-(i.e., line crossing).
-.
-.
-.P
-A string within double quotes
-.B \(dq
-is interpreted as a part of a
-.I chem
-command.
-.
-It represents a string that should be printed (without the quotes).
-.
-Text within quotes \(dq\*(El\(dq is treated more or less
-like a moiety except that no changes are made to the quoted part.
-.
-.
-.\" --------------------------------------------------------------------
-.SS Names
-.\" --------------------------------------------------------------------
-.
-In the alkyl chain above, notice that the carbon atom
-.B C
-was used both to draw something and as the name for a place.
-.
-A moiety always defines a name for a place;  you can use
-your own names for places instead, and indeed, for rings
-you will have to.
-.
-A name is just
-.
-.IP
-.IB Name :
-\*(El
-.
-.
-.P
-.I Name
-is often the name of a moiety like
-.BR CH3 ,
-but it need not to be.
-.
-Any name that begins with a capital letter and which contains
-only letters and numbers is valid:
-.
-.RS
-.TP
-.B First:
-.B bond
-.TQ
-\&
-.B "bond 30 from First"
-.RE
-.
-.
-.\" --------------------------------------------------------------------
-.SS Miscellaneous
-.\" --------------------------------------------------------------------
-.
-The specific construction
-.RS
-.TP
-.BR bond\  \*(El " ; moiety"
-.RE
-.P
-is equivalent to
-.IP
-.ft B
-.nf
-bond
-moiety
-.fi
-.ft
-.
-.
-.P
-Otherwise, each item has to be on a separate line (and only one line).
-Note that there must be whitespace after the semicolon which separates
-the commands.
-.
-.
-.P
-A period character
-.B .\&
-or a single quote
-.B '
-in the first column of a line signals a
-.I troff
-command, which is copied through as-is.
-.
-.
-.P
-A line whose first non-blank character is a hash character
-.RB ( # )
-is treated as a comment and thus ignored.
-.
-However, hash characters within a word are kept.
-.
-.
-.P
-A line whose first word is
-.B pic
-is copied through as-is after the word
-.B pic
-has been removed.
-.
-.
-.P
-The command
-.IP
-.B size
-.I n
-.P
-scales the diagram to make it look plausible at point size\~\c
-.I n
-(default is 10\~point).
-.
-.
-.P
-Anything else is assumed to be
-.I pic
-code, which is copied through with a label.
-.
-.
-.P
-Since
-.B @g@chem
-is a
-.B @g@pic
-preprocessor, it is possible to include
-.I pic
-statements in the middle of a diagram to draw things not provided for
-by
-.I chem
-itself.
-.
-Such
-.I pic
-statements should be included in
-.I chem
-code by adding
-.B pic
-as the first word of this line for clarity.
-.
-.
-.P
-The following
-.I pic
-commands are accepted as
-.I chem
-commands, so no
-.B pic
-command word is needed:
-.
-.IP
-.B define
-Start the definition of
-.I pic
-macro within
-.IR chem .
-.
-.RS
-.TP
-.B [
-Start a block composite.
-.
-.TP
-.B ]
-End a block composite.
-.
-.TP
-.B {
-Start a macro definition block.
-.
-.TP
-.B }
-End a macro definition block.
-.RE
-.
-.P
-The macro names from
-.B define
-statements are stored and their call is accepted as a
-.I chem
-command as well.
-.
-.
-.\" --------------------------------------------------------------------
-.SS WISH LIST
-.\" --------------------------------------------------------------------
-.
-.P
-This TODO list was collected by Brian Kernighan.
-.
-.
-.P
-Error checking is minimal; errors are usually detected and reported in
-an oblique fashion by
-.IR pic .
-.
-.
-.P
-There is no library or file inclusion mechanism, and there is no
-shorthand for repetitive structures.
-.
-.
-.P
-The extension mechanism is to create
-.I pic
-macros, but these are tricky to get right and don't have all the
-properties of built-in objects.
-.
-.
-.P
-There is no in-line chemistry yet (e.g., analogous to the $\*(El$
-construct of eqn).
-.
-.
-.P
-There is no way to control entry point for bonds on groups.
-.
-Normally a bond connects to the carbon atom if entering from
-the top or bottom and otherwise to the nearest corner.
-.
-.
-.P
-Bonds from substituted atoms on heterocycles do not join at the proper
-place without adding a bit of
-.IR pic .
-.
-.
-.P
-There is no decent primitive for brackets.
-.
-.
-.P
-Text (quoted strings) doesn't work very well.
-.
-.
-.P
-A squiggle bond is needed.
-.
-.
-.\" --------------------------------------------------------------------
-.SH "FILES"
-.\" --------------------------------------------------------------------
-.
-.TP
-.FN @DATASUBDIR@/pic/chem.pic
-A collection of
-.I pic
-macros needed by
-.BR @g@chem .
-.
-.TP
-.FN @MACRODIR@/pic.tmac
-A macro file which redefines
-.B .PS
-and
-.BR .PE
-to center
-.I pic
-diagrams.
-.
-.TP
-.FN @DOCDIR@/examples/chem/*.chem
-Example files for
-.IR chem .
-.
-.TP
-.FN @DOCDIR@/examples/chem/122/*.chem
-Example files from the classical
-.I chem
-book
-.BR 122.ps .
-.
-.
-.\" --------------------------------------------------------------------
-.SH "BUGS"
-.\" --------------------------------------------------------------------
-.
-Report bugs to the
-.MT bug-groff@\:gnu.org
-bug-groff mailing list
-.ME .
-.
-Include a complete, self-contained example that will allow the bug to
-be reproduced, and say which version of
-.I groff
-and
-.I chem
-you are using.
-.
-You can get both version numbers by calling
-.BR "@g@chem --version" .
-.
-.
-.P
-You can also use the
-.MT groff@\:gnu.org
-groff mailing list
-.ME ,
-but you must first subscribe to this list.
-.
-You can do that by visiting the
-.UR http://\:lists.gnu.org/\:mailman/\:listinfo/\:groff
-groff mailing list web page
-.UE .
-.
-.
-.P
-See
-.BR \%groff (@MAN1EXT@)
-for information on availability.
-.
-.
-.\" --------------------------------------------------------------------
-.SH "SEE ALSO"
-.\" --------------------------------------------------------------------
-.
-.BR \%groff (@MAN1EXT@),
-.BR \%@g@pic (@MAN1EXT@),
-.BR \%groffer (@MAN1EXT@).
-.
-.
-.P
-You can still get the original
-.UR http://\:cm.bell-labs.com/\:netlib/\:typesetting/\:chem.gz
-chem awk source
-.UE .
-.
-Its
-.FN README
-file was used for this manual page.
-.
-.
-.P
-The other classical document on
-.I chem
-is
-.UR http://\:cm.bell-labs.com/\:cm/\:cs/\:cstr/\:122.ps.gz
-122.ps
-.UE .
-.
-.
-.\" --------------------------------------------------------------------
-.SH "AUTHOR"
-.\" --------------------------------------------------------------------
-.au
-.
-.
-.\" --------------------------------------------------------------------
-.SH "COPYING"
-.\" --------------------------------------------------------------------
-.co
-.
-.
-.\" --------------------------------------------------------------------
-.\" Emacs settings
-.\" --------------------------------------------------------------------
-.
-.\" Local Variables:
-.\" mode: nroff
-.\" End:

Index: chem/chem.pic
===================================================================
RCS file: chem/chem.pic
diff -N chem/chem.pic
--- chem/chem.pic	22 Jan 2013 00:29:39 -0000	1.5
+++ /dev/null	1 Jan 1970 00:00:00 -0000
@@ -1,94 +0,0 @@
-# macros for chem
-	
-# Source file position: <groff-source>/contrib/chem/chem.pic
-# Installed position: <prefix>/share/groff/<version>/pic
-
-# Copyright (C) 2006, 2008, 2009 Free Software Foundation, Inc.
-# Written by Brian Kernighan <http://cm.bell-labs.com/cm/cs/who/bwk>,
-# modified by Bernd Warken <groff-bernd.warken-72@web.de>.
-
-# This file is part of `chem', 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/>.
-
-########################################################################
-
-pi = 3.141592654
-deg = 57.29578
-# cr = 0.08		# radius of invis circle at ring vertices (see cr[vh])
-# crh = 0.16; crw = 0.12 # ht & wid of invis ellipse around atoms at ring vertices
-# dav = 0.015		# vertical shift up for atoms in atom macro
-
-# atom(text, wid, ht, carbon position, crh, crw, dav)
-define atom { [
-	T: $1 wid $2 ht $3-2*$7
-	C: ellipse invis ht $5 wid $6 at T.w + ($4,$7)
-	L: ellipse invis ht $5 wid $6 at T.w + (cwid/2,$7)
-	R: ellipse invis ht $5 wid $6 at T.e + (-cwid/2,$7)
-] }
-
-# bond(length, angle in degrees, whatever)
-define bond {
-	line $3 by ($1) * sin(($2)/deg), ($1) * cos(($2)/deg)
-}
-
-# fancy bonds:  r, theta, from/at
-define doublebond {
-	line $3 invis by ($1) * sin(($2)/deg), ($1) * cos(($2)/deg)
-	V1: last line.start; V2: last line.end; dx = V2.x-V1.x; dy = V2.y-V1.y
-	norm = sqrt(dx*dx + dy*dy)
-	ny = dx * .02 / norm
-	nx = -dy * .02 / norm
-	line from V1 + (nx,ny) to V2 + (nx,ny)
-	line from V1 - (nx,ny) to V2 - (nx,ny)
-	move to V2
-}
-define triplebond {
-	line $3 invis by ($1) * sin(($2)/deg), ($1) * cos(($2)/deg)
-	V1: last line.start; V2: last line.end; dx = V2.x-V1.x; dy = V2.y-V1.y
-	norm = sqrt(dx*dx + dy*dy)
-	ny = dx * .025 / norm
-	nx = -dy * .025 / norm
-	line from V1 + (nx,ny) to V2 + (nx,ny)
-	line from V1 - (nx,ny) to V2 - (nx,ny)
-	line from V1 to V2
-	move to V2
-}
-define backbond {
-	line $3 invis by ($1) * sin(($2)/deg), ($1) * cos(($2)/deg)
-	V1: last line.start; V2: last line.end; dx = V2.x-V1.x; dy = V2.y-V1.y
-	norm = sqrt(dx*dx + dy*dy)
-	n = norm / .025
-	ny = dx * .02 / norm
-	nx = -dy * .02 / norm
-	for i = 1 to n-1 do {
-		XZ: i/n <V1,V2>
-		line from XZ + (nx,ny) to XZ - (nx,ny)
-	}
-	move to V2
-}
-define frontbond {
-	line $3 invis by ($1) * sin(($2)/deg), ($1) * cos(($2)/deg)
-	V1: last line.start; V2: last line.end; dx = V2.x-V1.x; dy = V2.y-V1.y
-	ah = arrowht; aw = arrowwid; ahead = arrowhead
-	arrowht = sqrt(dx*dx + dy*dy)
-	arrowwid = 0.05
-	arrowhead = 7
-	line <- from V1 to V2
-	arrowht = ah; arrowwid = aw; arrowhead = ahead
-}
-### Emacs settings
-# Local Variables:
-# mode: Nroff
-# End:

Index: chem/chem.pl
===================================================================
RCS file: chem/chem.pl
diff -N chem/chem.pl
--- chem/chem.pl	22 Jan 2013 00:29:39 -0000	1.11
+++ /dev/null	1 Jan 1970 00:00:00 -0000
@@ -1,1274 +0,0 @@
-#! /usr/bin/env perl
-
-# chem - a groff preprocessor for producing chemical structure diagrams
-
-# Source file position: <groff-source>/contrib/chem/chem.pl
-# Installed position: <prefix>/bin/chem
-
-# Copyright (C) 2006, 2009 Free Software Foundation, Inc.
-# Written by Bernd Warken <groff-bernd.warken-72@web.de>.
-
-# This file is part of `chem', 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/>.
-
-########################################################################
-# settings
-########################################################################
-
-my $Program_Version = '0.3.1';
-my $Last_Update = '03 Jan 2009';
-
-# this setting of the groff version is only used before make is run,
-# otherwise @VERSION@ will set it.
-my $Groff_Version_Preset='1.20preset';
-
-# test on Perl version
-require v5.6;
-
-
-########################################################################
-# begin
-########################################################################
-
-use warnings;
-use strict;
-use Math::Trig;
-
-# for catfile()
-use File::Spec;
-
-# $Bin is the directory where this script is located
-use FindBin;
-
-my $Chem_Name;
-my $Groff_Version;
-my $File_chem_pic;
-my $File_pic_tmac;
-
-BEGIN {
-  {
-    my $before_make;		# script before run of `make'
-    {
-      my $at = '@';
-      $before_make = 1 if '@VERSION@' eq "${at}VERSION${at}";
-    }
-
-    my %at_at;
-
-    if ($before_make) {
-      my $chem_dir = $FindBin::Bin;
-      $at_at{'BINDIR'} = $chem_dir;
-      $at_at{'G'} = '';
-      $File_chem_pic = File::Spec->catfile($chem_dir, 'chem.pic');
-      $File_pic_tmac = File::Spec->catfile($chem_dir, '..', 'pic.tmac');
-      $Groff_Version = '';
-      $Chem_Name = 'chem';
-    } else {
-      $Groff_Version = '@VERSION@';
-      $at_at{'BINDIR'} = '@BINDIR@';
-      $at_at{'G'} = '@g@';
-      $at_at{'PICDIR'} = '@PICDIR@';
-      $at_at{'TMACDIR'} = '@MACRODIR@';
-      $File_chem_pic =
-	File::Spec->catfile($at_at{'PICDIR'}, 'chem.pic');
-      $File_pic_tmac = File::Spec->catfile($at_at{'TMACDIR'}, 'pic.tmac');
-      $Chem_Name = $at_at{'G'} . 'chem';
-    }
-  }
-}
-
-
-########################################################################
-# check the parameters
-########################################################################
-
-if (@ARGV) {
-  # process any FOO=bar switches
-  # eval '$'.$1.'$2;' while $ARGV[0] =~ /^([A-Za-z_0-9]+=)(.*)/ && shift;
-  my @filespec = ();
-  my $dbl_minus;
-  my $wrong;
-  foreach (@ARGV) {
-    next unless $_;
-    if (/=/) {
-      # ignore FOO=bar switches
-      push @filespec, $_ if -f;
-      next;
-    }
-    if ($dbl_minus) {
-      if (-f $_) {
-	push @filespec, $_ if -s $_;
-      } else {
-	warn "chem: argument $_ is not an existing file.\n";
-	$wrong = 1;
-      }
-      next;
-    }
-    if (/^--$/) {
-      $dbl_minus = 1;
-      next;
-    }
-    if (/^-$/) {
-      push @filespec, $_;
-      next;
-    }
-    if (/^-h$/ or '--help' =~ /^$_/) {
-      &usage();
-      exit 0;
-    }
-    if (/^-v$/ or '--version' =~ /^$_/) {
-      &version();
-      exit 0;
-    }
-    if (-f $_) {
-      push @filespec, $_ if -s $_;
-    } else {
-      $wrong = 1;
-      if (/^-/) {
-	warn "chem: wrong option ${_}.\n";
-      } else {
-	warn "chem: argument $_ is not an existing file.\n";
-      }
-    }
-  }
-  if (@filespec) {
-    @ARGV = @filespec;
-  } else {
-    exit 0 if $wrong;
-    @ARGV = ('-');
-  }
-} else {			# @ARGV is empty
-  @ARGV = ('-') unless @ARGV;
-}
-
-
-########################################################################
-# main process
-########################################################################
-
-my %Dc = ( 'up' => 0, 'right' => 90, 'down' => 180, 'left' => 270,
-	   'ne' => 45, 'se' => 135, 'sw' => 225, 'nw' => 315,
-	   0 => 'n', 90 => 'e', 180 => 's', 270 => 'w',
-	   30 => 'ne', 45 => 'ne', 60 => 'ne',
-	   120 => 'se', 135 => 'se', 150 => 'se',
-	   210 => 'sw', 225 => 'sw', 240 => 'sw',
-	   300 => 'nw', 315 => 'nw', 330 => 'nw',
-	 );
-
-my $Word_Count;
-my @Words;
-
-my $Line_No;
-my $Last_Name = '';
-
-# from init()
-my $First_Time = 1;
-my $Last_Type;
-my $Dir;			# direction
-my %Types = (
-	     'RING' => 'R',
-	     'MOL' => 'M',
-	     'BOND' => 'B',
-	     'OTHER' => 'O'	# manifests
-	    );
-
-# from setparams()
-my %Params;
-
-# from ring()
-my $Nput;
-my $Aromatic;
-my %Put;
-my %Dbl;
-
-my %Labtype;
-my %Define = ();
-
-my $File_Name = '';
-my $Line = '';
-
-&main();
-
-{
-  my $is_pic = '';
-  my $is_chem = '';
-  my $former_line = '';
-
-  ##########
-  # main()
-  #
-  sub main {
-    my $count_minus = 0;
-    my @stdin = ();
-    my $stdin = 0;
-
-    # for centralizing the pic code
-    open TMAC, "<$File_pic_tmac" and print <TMAC>;
-    close TMAC;
-
-    foreach (@ARGV) {
-      $count_minus++ if /^-$/;
-    }
-
-    foreach my $arg (@ARGV) {
-      &setparams(1.0);
-      next unless $arg;
-      $Line_No = 0;
-      $is_pic = '';
-      $is_chem = '';
-      if ($arg eq '-') {
-	$File_Name = 'standard input';
-	if ($stdin) {
-	  &main_line($_) foreach @stdin;
-	} else {
-	  $stdin = 1;
-	  if ($count_minus <= 1) {
-	    while (<STDIN>) {
-	      &main_line($_);
-	    }
-	  } else {
-	    @stdin = ();
-	    while (<STDIN>) {
-	      push @stdin, $_;
-	      &main_line($_);
-	    }
-	  }
-	}
-### main()
-      } else {			# $arg is not -
-	$File_Name = $arg;
-	open FILE, "<$arg";
-	&main_line($_) while <FILE>;
-	close FILE;
-      }				# if $arg
-      if ($is_pic) {
-	printf ".PE\n";
-      }
-    }
-  } # main()
-
-
-  ##########
-  # main_line()
-  #
-  sub main_line {
-    my $line = $_[0];
-#    $Last_Type = $Types{'OTHER'};
-#    $Last_Type = '';
-    my $stack;
-    $Line_No++;
-    chomp $line;
-
-    $line = $former_line . $line if $former_line;
-    if ($line =~ /^(.*)\\$/) {
-      $former_line = $1;
-      return 1;
-    } else {
-      $former_line = '';
-    }
-    $Line = $line;
-
-    {
-      @Words = ();
-      my $s = $line;
-      $s =~ s/^\s*//;
-      $s =~ s/\s+$//;
-      return 1 unless $s;
-      $s = " $s";
-      $s =~ s/\s+#.*$// if $is_pic;
-      return 1 unless $s;
-      $line = $s;
-      $line =~ s/^\s*|\s*$//g;
-      my $bool = 1;
-      while ($bool) {
-	$s =~ /^([^"]*)\s("[^"]*"?\S*)(.*)$/;
-	if (defined $1) {
-	  my $s1 = $1;
-	  my $s2 = $2;
-	  $s = $3;
-	  $s1 =~ s/^\s*|\s*$//g;
-	  push @Words, split(/\s+/, $s1) if $s1;
-	  push @Words, $s2;
-	}
-	if ($s !~ /\s"/) {
-	  $s =~ s/^\s*|\s*$//g;
-	  push @Words, split(/\s+/, $s) if $s;
-	  $bool = 0;
-	}
-      }
-
-#      @Words = split(/\s+/, $s);
-      return 1 unless @Words;
-#      foreach my $i (0..$#Words) {
-#	if ($Words[$i] =~ /^\s*#/) {
-#	  $#Words = $i - 1;
-#	  last;
-#	}
-#      }
-#      return 1 unless @Words;
-    }
-
-    if ($line =~ /^([\.']\s*PS\s*)|([\.']\s*PS\s.+)$/) {
-      # .PS
-      unless ($is_pic) {
-	$is_pic = 'running';
-	print "$line\n";
-      }
-      return 1;
-    }
-### main_line()
-    if ( $line =~ /^([\.']\s*PE\s*)|([\.']\s*PE\s.+)$/ ) {
-      # .PE
-      $is_chem = '';
-      if ($is_pic) {
-	$is_pic = '';
-	print "$line\n";
-      }
-      return 1;
-    }
-    if ($line =~ /^[\.']\s*cstart\s*$/) {
-      # line: `.cstart'
-      if ($is_chem) {
-	&error("additional `.cstart'; chem is already active.");
-	return 1;
-      }
-      unless ($is_pic) {
-	&print_ps();
-	$is_pic = 'by chem';
-      }
-      $is_chem = '.cstart';
-      &init();
-      return 1;
-    }
-### main_line()
-    if ($line =~ /^\s*begin\s+chem\s*$/) {
-      # line: `begin chem'
-      if ($is_pic) {
-	if ($is_chem) {
-	  &error("additional `begin chem'; chem is already active.");
-	  return 1;
-	}
-	$is_chem = 'begin chem';
-	&init();
-      } else {
-	print "$line\n";
-      }
-      return 1;
-    }
-    if ($line =~ /^[\.']\s*cend\s*/) {
-      # line `.cend'
-      if ($is_chem) {
-	&error("you end chem with `.cend', but started it with `begin chem'.")
-	  if $is_chem eq 'begin chem';
-	if ($is_pic eq 'by chem') {
-	  &print_pe();
-	  $is_pic = '';
-	}
-	$is_chem = '';
-      } else {
-	print "$line\n";
-      }
-      return 1;
-    }
-    if ($line =~ /^\s*end\s*$/) {
-      # line: `end'
-      if ($is_chem) {
-	&error("you end chem with `end', but started it with `.cstart'.")
-	  if $is_chem eq '.cstart';
-	if ($is_pic eq 'by chem') {
-	  &print_pe();
-	  $is_pic = '';
-	}
-	$is_chem = '';
-      } else {
-	print "$line\n";
-      }
-      return 1;
-    }
-
-### main_line()
-    if (! $is_chem) {
-      print "$line\n";
-      return 1;
-    }
-    if ($line =~ /^[.']/) {
-      # groff request line
-      print "$line\n";
-      return 1;
-    }
-
-    if ($Words[0] eq 'pic') {
-      # pic pass-thru
-      return 1 if $#Words == 0;
-      my $s = $line;
-      $s =~ /^\s*pic\s*(.*)$/;
-      $s = $1;
-      print "$s\n" if $s;
-      $Last_Type = $Types{'OTHER'};
-      $Define{ $Words[2] } = 1 if $#Words >= 2 && $Words[1] eq 'define';
-      return 1;
-    }
-
-    if ($Words[0] eq 'textht') {
-      if ($#Words == 0) {
-	&error("`textht' needs a single argument.");
-	return 0;
-      }
-      &error("only the last argument is taken for `textht', " .
-	     "all others are ignored.")
-	unless $#Words <= 1 or ($#Words == 2 && $Words[1] =~ /^=/);
-      $Params{'textht'} = $Words[$#Words];
-      return 1;
-    }
-### main_line()
-    if ($Words[0] eq 'cwid') {	# character width
-      if ($#Words == 0) {
-	&error("`cwid' needs a single argument.");
-	return 0;
-      }
-      &error("only the last argument is taken for `cwid', " .
-	     "all others are ignored.")
-	unless $#Words <= 1 or ($#Words == 2 && $Words[1] =~ /^=/);
-      $Params{'cwid'} = $Words[$#Words];
-      return 1;
-    }
-    if ($Words[0] eq 'db') {	# bond length
-      if ($#Words == 0) {
-	&error("`db' needs a single argument.");
-	return 0;
-      }
-      &error("only the last argument is taken for `db', " .
-	     "all others are ignored.")
-	unless $#Words <= 1 or ($#Words == 2 && $Words[1] =~ /^=/);
-      $Params{'db'} = $Words[$#Words];
-      return 1;
-    }
-    if ($Words[0] eq 'size') {	# size for all parts of the whole diagram
-      my $size;
-      if ($#Words == 0) {
-	&error("`size' needs a single argument.");
-	return 0;
-      }
-      &error("only the last argument is taken for `size', " .
-	     "all others are ignored.")
-	unless $#Words <= 1 or ($#Words == 2 && $Words[1] =~ /^=/);
-      if ($Words[$#Words] <= 4) {
-	$size = $Words[$#Words];
-      } else {
-	$size = $Words[$#Words] / 10;
-      }
-      &setparams($size);
-      return 1;
-    }
-
-### main_line()
-    print "\n#", $Line, "\n";  		      # debugging, etc.
-    $Last_Name = '';
-#    $Last_Type = $Types{'OTHER'};
-#    $Last_Type = '';
-
-    if ($Words[0] =~ /^[A-Z].*:$/) {
-      # label;  falls thru after shifting left
-      my $w = $Words[0];
-      $Last_Name = $w;
-      $Last_Name =~ s/:$//;
-      print "$w";
-      shift @Words;
-      if (@Words) {
-	print " ";
-	$line =~ s/^\s*$w\s*//;
-      } else {
-	print "\n";
-	return 1;
-      }
-    }
-
-    if ($Words[0] eq 'define') {
-      print "$line\n";
-      $Define{ $Words[1] } = 1 if $#Words >= 1;
-      $Last_Type = $Types{'OTHER'};
-      return 1;
-    }
-    if ($Words[0] =~ /^[\[\]{}]/) {
-      print "$line\n";
-      $Last_Type = $Types{'OTHER'};
-      return 1;
-    }
-
-    if ($Words[0] =~ /^"/) {
-      print 'Last: ', $line, "\n";
-      $Last_Type = $Types{'OTHER'};
-      return 1;
-    }
-
-    if ($Words[0] =~ /bond/) {
-      &bond($Words[0]);
-      return 1;
-    }
-
-    if ($#Words >= 1) {
-      if ($Words[0] =~ /^(double|triple|front|back)$/ &&
-	  $Words[1] eq 'bond') {
-	my $w = shift @Words;
-	$Words[0] = $w . $Words[0];
-	&bond($Words[0]);
-	return 1;
-      }
-      if ($Words[0] eq 'aromatic') {
-	my $temp = $Words[0];
-	$Words[0] = $Words[1] ? $Words[1] : '';
-	$Words[1] = $temp;
-      }
-    }
-
-    if ($Words[0] =~ /ring|benz/) {
-      &ring($Words[0]);
-      return 1;
-    }
-    if ($Words[0] eq 'methyl') {
-      # left here as an example
-      $Words[0] = 'CH3';
-    }
-### main_line()
-    if ($Words[0] =~ /^[A-Z]/) {
-      &molecule();
-      return 1;
-    }
-    if ($Words[0] eq 'left') {
-      my %left;			# not used
-      $left{++$stack} = &fields(1, $#Words);
-      printf (("Last: [\n"));
-      return 1;
-    }
-    if ($Words[0] eq 'right') {
-      &bracket();
-      $stack--;
-      return 1;
-    }
-    if ($Words[0] eq 'label') {	# prints the vertex numbers in a ring
-      if ( exists $Labtype{$Words[1]} and
-	   $Labtype{$Words[1]} =~ /^$Types{'RING'}/ ) {
-	my $v = substr($Labtype{$Words[1]}, 1, 1);
-	$Words[1] = '' unless $Words[1];
-	foreach my $i ( 1..$v ) {
-	  printf "\"\\s-3%d\\s0\" at 0.%d<%s.C,%s.V%d>\n", $i, $v + 2,
-	    $Words[1], $Words[1], $i;
-	}
-      } else {
-	&error("$Words[1] is not a ring.");
-      }
-      return 1;
-    }
-
-    if ( exists $Define{ $Words[0] } ) {
-      print $line, "\n";
-      $Last_Type = $Types{'OTHER'};
-      return 1;
-    }
-    return 1 unless $line;
-#    print STDERR "# $Line\n";
-#    &error('This is not a chem command.  To include a command for pic, ' .
-#	   "add `pic' as the first word to the command.");
-    print $line, "\n";
-    $Last_Type = $Types{'OTHER'};
-    1;
-  } # main_line()
-
-}
-
-########################################################################
-# functions
-########################################################################
-
-##########
-# atom(<string>)
-#
-sub atom {
-  # convert CH3 to atom(...)
-  my ($s) = @_;
-  my ($i, $n, $nsub, $cloc, $nsubc, @s);
-  if ($s eq "\"\"") {
-    return $s;
-  }
-  $n = length($s);
-  $nsub = $nsubc = 0;
-  $cloc = index($s, 'C');
-  if (! defined($cloc) || $cloc < 0) {
-    $cloc = 0;
-  }
-  @s = split('', $s);
-  $i = 0;
-  foreach (@s) {
-    unless (/[A-Z]/) {
-      $nsub++;
-      $nsubc++ if $i < $cloc;
-      $i++;
-    }
-  }
-  $s =~ s/([0-9]+\.[0-9]+)|([0-9]+)/\\s-3\\d$&\\u\\s+3/g;
-  if ($s =~ /([^0-9]\.)|(\.[^0-9])/) { # centered dot
-    $s =~ s/\./\\v#-.3m#.\\v#.3m#/g;
-  }
-  sprintf( "atom(\"%s\", %g, %g, %g, %g, %g, %g)",
-	   $s, ($n - $nsub / 2) * $Params{'cwid'}, $Params{'textht'},
-	   ($cloc - $nsubc / 2 + 0.5) * $Params{'cwid'}, $Params{'crh'},
-	   $Params{'crw'}, $Params{'dav'}
-	 );
-} # atom()
-
-
-##########
-# bond(<type>)
-#
-sub bond {
-  my ($type) = @_;
-  my ($i, $moiety, $from, $leng);
-  $moiety = '';
-  for ($i = 1; $i <= $#Words; $i++) {
-    if ($Words[$i] eq ';') {
-      &error("a colon `;' must be followed by a space and a single word.")
-       if $i != $#Words - 1;
-      $moiety = $Words[$i + 1] if $#Words > $i;
-      $#Words = $i - 1;
-      last;
-    }
-  }
-  $leng = $Params{'db'};	# bond length
-  $from = '';
-  for ($Word_Count = 1; $Word_Count <= $#Words; ) {
-    if ($Words[$Word_Count] =~
-	/(\+|-)?\d+|up|down|right|left|ne|se|nw|sw/) {
-      $Dir = &cvtdir($Dir);
-    } elsif ($Words[$Word_Count] =~ /^leng/) {
-      $leng = $Words[$Word_Count + 1] if $#Words > $Word_Count;
-      $Word_Count += 2;
-    } elsif ($Words[$Word_Count] eq 'to') {
-      $leng = 0;
-      $from = &fields($Word_Count, $#Words);
-      last;
-    } elsif ($Words[$Word_Count] eq 'from') {
-      $from = &dofrom();
-      last;
-    } elsif ($Words[$Word_Count] =~ /^#/) {
-      $Word_Count = $#Words + 1;
-      last;
-    } else {
-      $from = &fields($Word_Count, $#Words);
-      last;
-    }
-  }
-### bond()
-  if ($from =~ /( to )|^to/) {	# said "from ... to ...", so zap length
-    $leng = 0;
-  } elsif (! $from) {		# no from given at all
-    $from = 'from Last.' . &leave($Last_Type, $Dir) . ' ' .
-      &fields($Word_Count, $#Words);
-  }
-  printf "Last: %s(%g, %g, %s)\n", $type, $leng, $Dir, $from;
-  $Last_Type = $Types{'BOND'};
-  $Labtype{$Last_Name} = $Last_Type if $Last_Name;
-  if ($moiety) {
-    @Words = ($moiety);
-    &molecule();
-  }
-} # bond()
-
-
-##########
-# bracket()
-#
-sub bracket {
-  my $t;
-  printf (("]\n"));
-  if ($Words[1] && $Words[1] eq ')') {
-    $t = 'spline';
-  } else {
-    $t = 'line';
-  }
-  printf "%s from last [].sw+(%g,0) to last [].sw to last [].nw to last " .
-    "[].nw+(%g,0)\n", $t, $Params{'dbrack'}, $Params{'dbrack'};
-  printf "%s from last [].se-(%g,0) to last [].se to last [].ne to last " .
-    "[].ne-(%g,0)\n", $t, $Params{'dbrack'}, $Params{'dbrack'};
-  if ($Words[2] && $Words[2] eq 'sub') {
-    printf "\" %s\" ljust at last [].se\n", &fields(3, $#Words);
-  }
-} # bracket()
-
-
-##########
-# corner(<dir>)
-#
-# Return the corner name next to the given angle.
-#
-sub corner {
-  my ($d) = @_;
-  $Dc{ (45 * int(($d + 22.5) / 45)) % 360 };
-} # corner()
-
-
-##########
-# cvtdir(<dir>)
-#
-# Maps "[pointing] somewhere" to degrees.
-#
-sub cvtdir {
-  my ($d) = @_;
-  if ($Words[$Word_Count] eq 'pointing') {
-    $Word_Count++;
-  }
-  if ($Words[$Word_Count] =~ /^[+\\-]?\d+/) {
-    return ( $Words[$Word_Count++] % 360 );
-  } elsif ($Words[$Word_Count] =~ /left|right|up|down|ne|nw|se|sw/) {
-    return ( $Dc{$Words[$Word_Count++]} % 360 );
-  } else {
-    $Word_Count++;
-    return $d;
-  }
-} # cvtdir()
-
-
-##########
-# dblring(<v>)
-#
-sub dblring {
-  my ($v) = @_;
-  my ($d, $v1, $v2);
-  # should canonicalize to i,i+1 mod v
-  $d = $Words[$Word_Count];
-  for ($Word_Count++; $Word_Count <= $#Words &&
-       $Words[$Word_Count] =~ /^[1-9]/; $Word_Count++) {
-    $v1 = substr($Words[$Word_Count], 0, 1);
-    $v2 = substr($Words[$Word_Count], 2, 1);
-    if ($v2 == $v1 + 1 || $v1 == $v && $v2 == 1) { # e.g., 2,3 or 5,1
-      $Dbl{$v1} = $d;
-    } elsif ($v1 == $v2 + 1 || $v2 == $v && $v1 == 1) {	# e.g., 3,2 or 1,5
-      $Dbl{$v2} = $d;
-    } else {
-      &error(sprintf("weird %s bond in\n\t%s", $d, $_));
-    }
-  }
-} # dblring()
-
-
-##########
-# dofrom()
-#
-sub dofrom {
-  my $n;
-  $Word_Count++;			# skip "from"
-  $n = $Words[$Word_Count];
-  if (defined $Labtype{$n}) {	# "from Thing" => "from Thing.V.s"
-    return 'from ' . $n . '.' . &leave($Labtype{$n}, $Dir);
-  }
-  if ($n =~ /^\.[A-Z]/) {	# "from .V" => "from Last.V.s"
-    return 'from Last' . $n . '.' . &corner($Dir);
-  }
-  if ($n =~ /^[A-Z][^.]*\.[A-Z][^.]*$/) { # "from X.V" => "from X.V.s"
-    return 'from ' . $n . '.' . &corner($Dir);
-  }
-  &fields($Word_Count - 1, $#Words);
-} # dofrom()
-
-
-##########
-# error(<string>)
-#
-sub error {
-  my ($s) = @_;
-  printf STDERR "chem: error in %s on line %d: %s\n",
-    $File_Name, $Line_No, $s;
-} # error()
-
-
-##########
-# fields(<n1>, <n2>)
-#
-sub fields {
-  my ($n1, $n2) = @_;
-  if ($n1 > $n2) {
-    return '';
-  }
-  my $s = '';
-  foreach my $i ($n1..$n2) {
-    if ($Words[$i] =~ /^#/) {
-      last;
-    }
-    $s = $s . $Words[$i] . ' ';
-  }
-  $s;
-} # fields()
-
-
-##########
-# init()
-#
-sub init {
-  if ($First_Time) {
-    printf "copy \"%s\"\n", $File_chem_pic;
-    printf "\ttextht = %g; textwid = .1; cwid = %g\n",
-      $Params{'textht'}, $Params{'cwid'};
-    printf "\tlineht = %g; linewid = %g\n",
-      $Params{'lineht'}, $Params{'linewid'};
-    $First_Time = 0;
-  }
-  printf "Last: 0,0\n";
-  $Last_Type = $Types{'OTHER'};
-  $Dir = 90;
-} # init()
-
-
-##########
-# leave(<last>, <d>)
-#
-sub leave {
-  my ($last, $d) = @_;
-  my ($c, $c1);
-  # return vertex of $last in direction $d
-  if ( $last eq $Types{'BOND'} ) {
-    return 'end';
-  }
-  $d %= 360;
-  if ( $last =~ /^$Types{'RING'}/ ) {
-    return &ringleave($last, $d);
-  }
-  if ( $last eq $Types{'MOL'} ) {
-    if ($d == 0 || $d == 180) {
-      $c = 'C';
-    } elsif ($d > 0 && $d < 180) {
-      $c = 'R';
-    } else {
-      $c = 'L';
-    }
-    if (defined $Dc{$d}) {
-      $c1 = $Dc{$d};
-    } else {
-      $c1 = &corner($d);
-    }
-    return sprintf('%s.%s', $c, $c1);
-  }
-  if ( $last eq $Types{'OTHER'} ) {
-    return &corner($d);
-  }
-  'c';
-} # leave()
-
-
-##########
-# makering(<type>, <pt>, <v>)
-#
-sub makering {
-  my ($type, $pt, $v) = @_;
-  my ($i, $j, $a, $r, $rat, $fix, $c1, $c2);
-  if ($type =~ /flat/) {
-    $v = 6;
-    # vertices
-    ;
-  }
-  $r = $Params{'ringside'} / (2 * sin(pi / $v));
-  printf "\tC: 0,0\n";
-  for ($i = 0; $i <= $v + 1; $i++) {
-    $a = (($i - 1) / $v * 360 + $pt) / 57.29578; # 57. is $deg
-    printf "\tV%d: (%g,%g)\n", $i, $r * sin($a), $r * cos($a);
-  }
-  if ($type =~ /flat/) {
-    printf "\tV4: V5; V5: V6\n";
-    $v = 5;
-  }
-  # sides
-  if ($Nput > 0) {
-    # hetero ...
-    for ($i = 1; $i <= $v; $i++) {
-      $c1 = $c2 = 0;
-      if ($Put{$i} ne '') {
-	printf "\tV%d: ellipse invis ht %g wid %g at V%d\n",
-	  $i, $Params{'crh'}, $Params{'crw'}, $i;
-	printf "\t%s at V%d\n", $Put{$i}, $i;
-	$c1 = $Params{'cr'};
-      }
-      $j = $i + 1;
-      if ($j > $v) {
-	$j = 1;
-      }
-### makering()
-      if ($Put{$j} ne '') {
-	$c2 = $Params{'cr'};
-      }
-      printf "\tline from V%d to V%d chop %g chop %g\n", $i, $j, $c1, $c2;
-      if ($Dbl{$i} ne '') {
-	# should check i<j
-	if ($type =~ /flat/ && $i == 3) {
-	  $rat = 0.75;
-	  $fix = 5;
-	} else {
-	  $rat = 0.85;
-	  $fix = 1.5;
-	}
-	if ($Put{$i} eq '') {
-	  $c1 = 0;
-	} else {
-	  $c1 = $Params{'cr'} / $fix;
-	}
-	if ($Put{$j} eq '') {
-	  $c2 = 0;
-	} else {
-	  $c2 = $Params{'cr'} / $fix;
-	}
-	printf "\tline from %g<C,V%d> to %g<C,V%d> chop %g chop %g\n",
-	  $rat, $i, $rat, $j, $c1, $c2;
-	if ($Dbl{$i} eq 'triple') {
-	  printf "\tline from %g<C,V%d> to %g<C,V%d> chop %g chop %g\n",
-	    2 - $rat, $i, 2 - $rat, $j, $c1, $c2;
-	}
-      }
-    }
-### makering()
-  } else {
-    # regular
-    for ($i = 1; $i <= $v; $i++) {
-      $j = $i + 1;
-      if ($j > $v) {
-	$j = 1;
-      }
-      printf "\tline from V%d to V%d\n", $i, $j;
-      if ($Dbl{$i} ne '') {
-	# should check i<j
-	if ($type =~ /flat/ && $i == 3) {
-	  $rat = 0.75;
-	} else {
-	  $rat = 0.85;
-	}
-	printf "\tline from %g<C,V%d> to %g<C,V%d>\n",
-	  $rat, $i, $rat, $j;
-	if ($Dbl{$i} eq 'triple') {
-	  printf "\tline from %g<C,V%d> to %g<C,V%d>\n",
-	    2 - $rat, $i, 2 - $rat, $j;
-	}
-      }
-    }
-  }
-### makering()
-  # punt on triple temporarily
-  # circle
-  if ($type =~ /benz/ || $Aromatic > 0) {
-    if ($type =~ /flat/) {
-      $r *= .4;
-    } else {
-      $r *= .5;
-    }
-    printf "\tcircle rad %g at 0,0\n", $r;
-  }
-} # makering()
-
-
-##########
-# molecule()
-#
-sub molecule {
-  my ($n, $type);
-  if ($#Words >= 0) {
-    $n = $Words[0];
-    if ($n eq 'BP') {
-      $Words[0] = "\"\" ht 0 wid 0";
-      $type = $Types{'OTHER'};
-    } else {
-      $Words[0] = &atom($n);
-      $type = $Types{'MOL'};
-    }
-  }
-  $n =~ s/[^A-Za-z0-9]//g;	# for stuff like C(OH3): zap non-alnum
-  if ($#Words < 1) {
-    printf "Last: %s: %s with .%s at Last.%s\n",
-      $n, join(' ', @Words), &leave($type, $Dir + 180),
-	&leave($Last_Type, $Dir);
-### molecule()
-  } else {
-    if (! $Words[1]) {
-      printf "Last: %s: %s with .%s at Last.%s\n",
-	$n, join(' ', @Words), &leave($type, $Dir + 180),
-	  &leave($Last_Type, $Dir);
-    } elsif ($#Words >= 1 and $Words[1] eq 'below') {
-      $Words[2] = '' if ! $Words[2];
-      printf "Last: %s: %s with .n at %s.s\n", $n, $Words[0], $Words[2];
-    } elsif ($#Words >= 1 and $Words[1] eq 'above') {
-      $Words[2] = '' if ! $Words[2];
-      printf "Last: %s: %s with .s at %s.n\n", $n, $Words[0], $Words[2];
-    } elsif ($#Words >= 2 and $Words[1] eq 'left' && $Words[2] eq 'of') {
-      $Words[3] = '' if ! $Words[3];
-      printf "Last: %s: %s with .e at %s.w+(%g,0)\n",
-	$n, $Words[0], $Words[3], $Params{'dew'};
-    } elsif ($#Words >= 2 and $Words[1] eq 'right' && $Words[2] eq 'of') {
-      $Words[3] = '' if ! $Words[3];
-      printf "Last: %s: %s with .w at %s.e-(%g,0)\n",
-	$n, $Words[0], $Words[3], $Params{'dew'};
-    } else {
-      printf "Last: %s: %s\n", $n, join(' ', @Words);
-    }
-  }
-
-  $Last_Type = $type;
-  if ($Last_Name) {
-    #    $Last_Type = '';
-    $Labtype{$Last_Name} = $Last_Type;
-  }
- $Labtype{$n} = $Last_Type;
-} # molecule()
-
-
-##########
-# print_hash(<hash_or_ref>)
-#
-# print the elements of a hash or hash reference
-#
-sub print_hash {
-  my $hr;
-  my $n = scalar @_;
-  if ($n == 0) {
-    print STDERR "empty hash\n;";
-    return 1;
-  } elsif ($n == 1) {
-    if (ref($_[0]) eq 'HASH') {
-      $hr = $_[0];
-    } else {
-      warn 'print_hash(): the argument is not a hash or hash reference;';
-      return 0;
-    }
-  } else {
-    if ($n % 2) {
-      warn 'print_hash(): the arguments are not a hash;';
-      return 0;
-    } else {
-      my %h = @_;
-      $hr = \%h;
-    }
-  }
-
-### print_hash()
-  unless (%$hr) {
-    print STDERR "empty hash\n";
-    return 1;
-  }
-  print STDERR "hash (ignore the ^ characters):\n";
-  for my $k (sort keys %$hr) {
-    my $hk = $hr->{$k};
-    print STDERR "  $k => ";
-    if (defined $hk) {
-      print STDERR "^$hk^";
-    } else {
-      print STDERR "undef";
-    }
-    print STDERR "\n";
-  }
-
-  1;
-}				# print_hash()
-
-
-##########
-# print_pe()
-#
-sub print_pe {
-  print ".PE\n";
-} # print_pe()
-
-
-##########
-# print_ps()
-#
-sub print_ps {
-  print ".PS\n";
-} # print_ps()
-
-##########
-# putring(<v>)
-#
-sub putring {
-  # collect "put Mol at n"
-  my ($v) = @_;
-  my ($m, $mol, $n);
-  $Word_Count++;
-  $mol = $Words[$Word_Count++];
-  if ($Words[$Word_Count] eq 'at') {
-    $Word_Count++;
-  }
-  $n = $Words[$Word_Count];
-  if ($n !~ /^\d+$/) {
-    $n =~ s/(\d)+$/$1/;
-    $n = 0 if $n !~ /^\d+$/;
-    error('use single digit as argument for "put at"');
-  }
-  if ($n >= 1 && $n <= $v) {
-    $m = $mol;
-    $m =~ s/[^A-Za-z0-9]//g;
-    $Put{$n} = $m . ':' . &atom($mol);
-  } elsif ($n == 0) {
-    error('argument of "put at" must be a single digit');
-  } else {
-    error('argument of "put at" is too large');
-  }
-  $Word_Count++;
-} # putring()
-
-
-##########
-# ring(<type>)
-#
-sub ring {
-  my ($type) = @_;
-  my ($typeint, $pt, $verts, $i, $other, $fused, $withat);
-  $pt = 0;			# points up by default
-  if ($type =~ /([1-8])$/) {
-    $verts = $1;
-  } elsif ($type =~ /flat/) {
-    $verts = 5;
-  } else {
-    $verts = 6;
-  }
-  $fused = $other = '';
-  for ($i = 1; $i <= $verts; $i++) {
-    $Put{$i} = $Dbl{$i} = '';
-  }
-  $Nput = $Aromatic = $withat = 0;
-  for ($Word_Count = 1; $Word_Count <= $#Words; ) {
-    if ($Words[$Word_Count] eq 'pointing') {
-      $pt = &cvtdir(0);
-    } elsif ($Words[$Word_Count] eq 'double' ||
-	     $Words[$Word_Count] eq 'triple') {
-      &dblring($verts);
-    } elsif ($Words[$Word_Count] =~ /arom/) {
-      $Aromatic++;
-      $Word_Count++;		# handled later
-### ring()
-    } elsif ($Words[$Word_Count] eq 'put') {
-      &putring($verts);
-      $Nput++;
-    } elsif ($Words[$Word_Count] =~ /^#/) {
-      $Word_Count = $#Words + 1;
-      last;
-    } else {
-      if ($Words[$Word_Count] eq 'with' || $Words[$Word_Count] eq 'at') {
-	$withat = 1;
-      }
-      $other = $other . ' ' . $Words[$Word_Count];
-      $Word_Count++;
-    }
-  }
-  $typeint = $Types{'RING'} . $verts . $pt; # RING | verts | dir
-  if ($withat == 0) {
-    # join a ring to something
-    if ( $Last_Type =~ /^$Types{'RING'}/ ) {
-      # ring to ring
-      if (substr($typeint, 2) eq substr($Last_Type, 2)) {
-	# fails if not 6-sided
-	$fused = 'with .V6 at Last.V2';
-      }
-    }
-    # if all else fails
-    $fused = sprintf('with .%s at Last.%s',
-	  &leave($typeint, $Dir + 180), &leave($Last_Type, $Dir));
-  }
-  printf "Last: [\n";
-  &makering($type, $pt, $verts);
-  printf "] %s %s\n", $fused, $other;
-  $Last_Type = $typeint;
-  $Labtype{$Last_Name} = $Last_Type if $Last_Name;
-} # ring()
-
-
-##########
-# ringleave(<last>, <d>)
-#
-sub ringleave {
-  my ($last, $d) = @_;
-  my ($rd, $verts);
-  # return vertex of ring in direction d
-  $verts = substr($last, 1, 1);
-  $rd = substr($last, 2);
-  sprintf('V%d.%s', int( (($d - $rd) % 360) / (360 / $verts)) + 1,
-	  &corner($d));
-} # ringleave()
-
-
-##########
-# setparams(<scale>)
-#
-sub setparams {
-  my ($scale) = @_;
-  $Params{'lineht'} = $scale * 0.2;
-  $Params{'linewid'} = $scale * 0.2;
-  $Params{'textht'} = $scale * 0.16;
-  $Params{'db'} = $scale * 0.2;	# bond length
-  $Params{'cwid'} = $scale * 0.12;	# character width
-  $Params{'cr'} = $scale * 0.08; # rad of invis circles at ring vertices
-  $Params{'crh'} = $scale * 0.16; # ht of invis ellipse at ring vertices
-  $Params{'crw'} = $scale * 0.12; # wid	
-  $Params{'dav'} = $scale * 0.015; # vertical shift up for atoms in atom macro
-  $Params{'dew'} = $scale * 0.02; # east-west shift for left of/right of
-  $Params{'ringside'} = $scale * 0.3; # side of all rings
-  $Params{'dbrack'} = $scale * 0.1; # length of bottom of bracket
-} # setparams()
-
-
-##########
-# usage()
-#
-# Print usage information for --help.
-#
-sub usage {
-  print "\n";
-  &version();
-  print <<EOF;
-
-Usage: $Chem_Name [option]... [filespec]...
-
-$Chem_Name is a groff preprocessor for producing chemical structure
-diagrams.  The output suits to the pic preprocessor.
-
-"filespec" is one of
-  "filename"       name of a readable file
-  "-"              for standard input
-
-All available options are
-
--h --help         print this usage message.
--v --version      print version information.
-
-EOF
-} # usage()
-
-
-##########
-# version()
-#
-# Get version information from version.sh and print a text with this.
-#
-sub version {
-  $Groff_Version = $Groff_Version_Preset unless $Groff_Version;
-  my $year = $Last_Update;
-  $year =~ s/^.* //;
-  print <<EOF;
-$Chem_Name $Program_Version of $Last_Update (Perl version)
-is part of groff version $Groff_Version.
-Copyright (C) $year Free Software Foundation, Inc.
-GNU groff and chem come with ABSOLUTELY NO WARRANTY.
-You may redistribute copies of groff and its subprograms
-under the terms of the GNU General Public License.
-EOF
-} # version()
-
-1;
-### Emacs settings
-# Local Variables:
-# mode: CPerl
-# End:

Index: chem/examples/README.txt
===================================================================
RCS file: chem/examples/README.txt
diff -N chem/examples/README.txt
--- chem/examples/README.txt	22 Jan 2013 00:29:39 -0000	1.6
+++ /dev/null	1 Jan 1970 00:00:00 -0000
@@ -1,65 +0,0 @@
-This directory contains examples for the `chem' language.
-
-You can view the graphical display of the examples by calling
-
-    groffer <file>
-
-`groffer' calls `chem' automatically.
-
-If you want to transform example files to a different format use the
-`roff2*' programs:
-
-`roff2dvi' prints dvi format to standard output,
-`roff2html' generates html output,
-`roff2pdf' outputs pdf mode,
-`roff2ps' produces PostScript output,
-`roff2text' generates text output in the groff device `latin1',
-`roff2x' prints the output  in  the  groff  device  X  that  is
-         suitable  for programs  like `gxditview' or `xditview'.
-
-To get a suitable `groff' output run
-
-    @g@chem <file> | groff -p ...
-
-On the displays, you can see rings consisting of several lines and
-bonds (lines).  All points on rings and bonds that do not have a
-notation mean a C atom (carbon) filled with H atoms (hydrogen) such
-that the valence of 4 is satisfied.
-
-For example, suppose you have just a single line without any
-characters.  That means a bond.  It has two points, one at each end of
-the line.  So each of these points stands for a C atom, the bond
-itself connects these 2 C atoms.  To fulfill the valence of 4, each
-points has to carry additionally 3 H atoms.  So the single empty bond
-stands for CH3-CH3, though this combination doesn't make much sense
-chemically.
-
-
-####### License
-
-Last update: 5 Jan 2009
-
-Copyright (C) 2006, 2009 Free Software Foundation, Inc.
-Written by Bernd Warken <groff-bernd.warken-72@web.de>.
-
-This file is part of `chem', 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:

Index: chem/examples/atp.chem
===================================================================
RCS file: chem/examples/atp.chem
diff -N chem/examples/atp.chem
--- chem/examples/atp.chem	22 Jan 2013 00:29:39 -0000	1.4
+++ /dev/null	1 Jan 1970 00:00:00 -0000
@@ -1,63 +0,0 @@
-atp.chem:
-.cstart
-
-# Example file for `chem':
-#   ATP or C10_H16_N5_O13_P3 or
-#   [[[5-(6-aminopurin-9-yl)-3,4-dihydroxy-oxolan-2-yl]methoxy-hydroxy-
-#     phosphoryl]oxy-hydroxy-phosphoryl]oxyphosphonic acid
-
-# Found at http://www.chemindustry.com/apps/chemicals.
-
-# Source file position: <groff-source>/contrib/chem/example/atp.chem
-# Installed position: <prefix>/share/doc/groff/example/chem/atp.chem
-
-# Copyright (C) 2006, 2009 Free Software Foundation, Inc.
-# Written by Bernd Warken <groff-bernd.warken-72@web.de>.
-
-# Last update: 5 Jan 2009
-
-# This file is part of `chem', 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/>.
-
-R1:	ring5 pointing left double 1,2 3,4 put N at 2 put N at 5
-B:	benzene put N at 2 with .V6 at R1.V3 with .V5 at R1.V4
-	bond up ; NH2
-	backbond 170 length .7 from R1.V5
-R2:	ring5 pointing down with .V2 put O at 1
-	bond down at R2.V2 ; H
-	bond down length .1 at R2.V3 ; H
-	bond up length .1 at R2.V3 ; OH
-	bond down length .1 at R2.V4 ; H
-	bond up length .1 at R2.V4 ; OH
-	frontbond 70 at R2.V5
-	bond 110 ; O
-	bond right ; P
-	doublebond up ; O
-	bond down from P ; OH
-	bond right from P ; O
-	bond right ; P
-	doublebond up ; O
-	bond down from P ; OH
-	bond right from P ; O
-	bond right ; P
-	doublebond up ; O
-	bond down from P ; OH
-	bond right from P ; OH
-
-### Emacs settings
-# Local Variables:
-# mode: Nroff
-# End:
-.cend

Index: chem/examples/cholesterin.chem
===================================================================
RCS file: chem/examples/cholesterin.chem
diff -N chem/examples/cholesterin.chem
--- chem/examples/cholesterin.chem	22 Jan 2013 00:29:39 -0000	1.4
+++ /dev/null	1 Jan 1970 00:00:00 -0000
@@ -1,52 +0,0 @@
-cholesterin.chem:
-.cstart
-
-# Example file for `chem':
-#   Cholesterin or C27_H46O or
-#   10,13-dimethyl-17-(6-methylheptan-2-yl)-2,3,4,5,6,9,11,12,14,15,16,17-
-#     dodecahydro-1H-cyclopenta[a]phenanthren-3-ol
-
-# Source file position: <groff-source>/contrib/chem/example/cholesterin.p
-# Installed position: <prefix>/share/doc/groff/example/chem/cholesterin.p
-
-# Copyright (C) 2006, 2009 Free Software Foundation, Inc.
-# Written by Bernd Warken <groff-bernd.warken-72@web.de>.
-
-# Last update: 5 Jan 2009
-
-# This file is part of `chem', 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/>.
-
-R1:	ring6
-	bond -120 ; HO
-R2:	ring6 with .V5 at R1.V3 with .V6 at R1.V2 double 4,5
-	bond up at R2.V6
-R3:	ring6 with .V5 at R2.V1 with .V4 at R2.V2
-R4:	flatring5 pointing up with .V4 at R3.V3 with .V5 at R3.V2
-	bond up at R4.V5
-	bond up at R4.V1
-B1:	bond -60
-	bond 60 at B1.start
-	bond 120
-	bond 60
-	bond 120
-B2:	bond 60
-	bond down at B2.start
-
-### Emacs settings
-# Local Variables:
-# mode: Nroff
-# End:
-.cend

Index: chem/examples/ethamivan.chem
===================================================================
RCS file: chem/examples/ethamivan.chem
diff -N chem/examples/ethamivan.chem
--- chem/examples/ethamivan.chem	22 Jan 2013 00:29:39 -0000	1.4
+++ /dev/null	1 Jan 1970 00:00:00 -0000
@@ -1,48 +0,0 @@
-ethamivan.chem:
-.cstart
-
-# Example file for `chem':
-#   Ethamivan or Analepticon or C12_H17_N_O3 or
-#   N,N-diethyl-4-hydroxy-3-methoxy-benzamide
-
-# Source file position: <groff-source>/contrib/chem/example/ethamivan.chem
-# Installed position: <prefix>/share/doc/groff/example/chem/ethamivan.chem
-
-# Copyright (C) 2006, 2009 Free Software Foundation, Inc.
-# Written by Bernd Warken <groff-bernd.warken-72@web.de>.
-
-# Last update: 5 Jan 2009
-
-# This file is part of `chem', 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/>.
-
-R:	ring pointing left double 2,3 4,5 6,1
-	bond left from R.V1 ; O
-	bond left ; H
-	bond -150 from R.V6 ; O
-	bond left
-	bond 60 from R.V4
-B1:	double bond up ; O
-	bond 120 from B1.start ; N
-	bond 45
-	bond right
- 	bond 135 from N
-	bond right
-
-### Emacs settings
-# Local Variables:
-# mode: Nroff
-# End:
-.cend

Index: chem/examples/lsd.chem
===================================================================
RCS file: chem/examples/lsd.chem
diff -N chem/examples/lsd.chem
--- chem/examples/lsd.chem	22 Jan 2013 00:29:39 -0000	1.4
+++ /dev/null	1 Jan 1970 00:00:00 -0000
@@ -1,51 +0,0 @@
-lsd.chem:
-.cstart
-
-# Example file for `chem':
-#   LSD or Lysergic acid dethylamide or C20_H25_N3O or
-#   9,10-Didehydro-N,N-diethyl-6-methyl-ergoline-8-beta-carboxamide
-
-# Source file position: <groff-source>/contrib/chem/example/lsd.p
-# Installed position: <prefix>/share/doc/groff/example/chem/lsd.p
-
-# Copyright (C) 2006, 2009 Free Software Foundation, Inc.
-# Written by Bernd Warken <groff-bernd.warken-72@web.de>.
-
-# Last update: 5 Jan 2009
-
-# This file is part of `chem', 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/>.
-
-F:	flatring5 pointing left put N at 5 double 3,4
-	H below F.N
-B:	benzene pointing right with .V1 at F.V2
-R1:	ring pointing right with .V4 at B.V6
-	front bond right from R1.V6 ; H
-R2:	ring pointing right with .V2 at R1.V6 put N at 1 double 3,4
-	bond right from R2.N
-	back bond -60 from R2.V5 ; H
-	bond up from R2.V5
-B1:	double bond up ; O
-        bond right from B1.start ; N
-        bond 45
-	bond right
-        bond 135 from N
-	bond right
-
-### Emacs settings
-# Local Variables:
-# mode: Nroff
-# End:
-.cend

Index: chem/examples/morphine.chem
===================================================================
RCS file: chem/examples/morphine.chem
diff -N chem/examples/morphine.chem
--- chem/examples/morphine.chem	22 Jan 2013 00:29:39 -0000	1.4
+++ /dev/null	1 Jan 1970 00:00:00 -0000
@@ -1,55 +0,0 @@
-morphine.chem:
-.cstart
-
-# Example file for `chem':
-#    Morphine or C23_H31_N3O or
-#    N,N-diethyl-N'-(2-methoxyacridin-9-yl)-pentane-1,4-diamine
-
-# Found at http://www.chemindustry.com/apps/chemicals.
-
-# Source file position: <groff-source>/contrib/chem/example/morphine.chem
-# Installed position: <prefix>/share/doc/groff/example/chem/morphine.chem
-
-# Copyright (C) 2006, 2009 Free Software Foundation, Inc.
-# Written by Bernd Warken <groff-bernd.warken-72@web.de>.
-
-# Last update: 5 Jan 2009
-
-# This file is part of `chem', 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/>.
-
-R1:	benzene
-R2:	benzene with .V6 at R1.V2 with .V5 at R1.V3 put N at 4
-R3:	benzene with .V6 at R2.V2 with .V5 at R2.V3
-	bond 60 at R3.V2 ; O
-	bond 120
-	bond up at R2.V1 ; N
-	bond 60 ; H
-	bond -60 at N
-B1:	backbond -120
-	bond up at B1.start
-	bond -60
-	bond up
-	bond -60 ; N
-	bond up
-	bond -60
-	bond -120 at N
-	bond -60
-
-### Emacs settings
-# Local Variables:
-# mode: Nroff
-# End:
-.cend

Index: chem/examples/penicillin.chem
===================================================================
RCS file: chem/examples/penicillin.chem
diff -N chem/examples/penicillin.chem
--- chem/examples/penicillin.chem	22 Jan 2013 00:29:39 -0000	1.4
+++ /dev/null	1 Jan 1970 00:00:00 -0000
@@ -1,56 +0,0 @@
-penicillin.chem:
-.cstart
-
-# Example file for `chem':
-#    Penicillin or C16_H18_N2_O4_S or
-#    3,3-dimethyl-6-oxo-7-(2-phenylacetyl)amino-2-thia-5-
-#      azabicyclo[3.2.0]heptane-4-carboxylic acid
-
-# Found at http://www.chemindustry.com/apps/chemicals.
-
-# Source file position: <groff-source>/contrib/chem/example/morphine.chem
-# Installed position: <prefix>/share/doc/groff/example/chem/morphine.chem
-
-# Copyright (C) 2006, 2009 Free Software Foundation, Inc.
-# Written by Bernd Warken <groff-bernd.warken-72@web.de>.
-
-# Last update: 5 Jan 2009
-
-# This file is part of `chem', 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/>.
-
-R1:	flatring5 pointing up put S at 1 put N at 4
-	bond 45 at R1.V2
-	bond 135 at R1.V2
-	bond 120 at R1.V3
-D1:	doublebond 45 ; O
-	bond 135 at D1.start ; OH
-	bond left at R1.N
-	doublebond -135 ; O
-	bond left at R1.V5
-B1:	bond down length .3
-	bond -60 at B1.start ; N
-	bond up ; H
-	bond -120 at N
-D2:	doublebond down ; O
-	bond -60 at D2.start
-	bond -120
-	benzene
-
-### Emacs settings
-# Local Variables:
-# mode: Nroff
-# End:
-.cend

Index: chem/examples/reserpine.chem
===================================================================
RCS file: chem/examples/reserpine.chem
diff -N chem/examples/reserpine.chem
--- chem/examples/reserpine.chem	22 Jan 2013 00:29:39 -0000	1.5
+++ /dev/null	1 Jan 1970 00:00:00 -0000
@@ -1,65 +0,0 @@
-reserpine.chem:
-.PS
-begin chem
-
-# Example file for `chem':
-#   Reserpine or C33H40N2O9
-
-# Source file position: <groff-source>/contrib/chem/example/reserpine.chem
-# Installed position: <prefix>/share/doc/groff/example/chem/reserpine.chem
-
-# Copyright (C) 2006, 2009 Free Software Foundation, Inc.
-# Written by Bernd Warken <groff-bernd.warken-72@web.de>.
-
-# Last update: 5 Jan 2009
-
-# This file is part of `chem', 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/>.
-
-R1:	benzene pointing up
-	bond -120 from R1.V5 ; O
-	bond left
-R2:	flatring5 pointing down double 4,5 with .V2 at R1.V3 with .V3 at R1.V2 put N at 1
-	H below R2.V1
-R3:	ring put N at 3 with .V5 at R2.V5
-R4:	ring put N at 1 with .V1 at R3.V3
-	back bond -120 from R4.V4 ; H
-	back bond 60 from R4.V3 ; H
-R5:	ring with .V1 at R4.V3
-	bond -120
-D1:	double bond down ; O
-	bond left from D1.start ; O
-	bond left
-	back bond 60 from R5.V3 ; H
-	back bond down from R5.V4 ; O
-	bond down from O
-	bond 120 from R5.V3 ; O
-	bond 50 from O
-D2:	double bond up ; O
-	bond right length .1 from D2.start
-B:	benzene pointing right
-	bond 45 from B.V6 ; O
-	bond right
-	bond right from B.V1 ; O
-	bond right
-	bond 135 from B.V2 ; O
-	bond right
-
-### Emacs settings
-# Local Variables:
-# mode: Nroff
-# End:
-end
-.PE

Index: chem/examples/122/README.txt
===================================================================
RCS file: chem/examples/122/README.txt
diff -N chem/examples/122/README.txt
--- chem/examples/122/README.txt	22 Jan 2013 00:29:39 -0000	1.2
+++ /dev/null	1 Jan 1970 00:00:00 -0000
@@ -1,74 +0,0 @@
-This directory contains the examples for the `chem' language written
-in the book:
-
-    Computing Science Technical Report No. 122
-    CHEM - A Program for Typesetting Chemical Diagrams: User Manual
-    by Jon L. Bentley, Lynn W. Jelinski, Brian W. Kernighan
-
-The book is available in the internet at
-<http://cm.bell-labs.com/cm/cs/cstr/122.ps.gz>.
-
-Many of the examples had to be fixed.  Unfortunately, the `chem' akw
-version does not run on many of these programs.  But the Perl version
-of `chem' works on all examples.
-
-Most examples do not use the modern chemical display.  They have C
-atoms added, whereas the modern method omits all C atoms and their
-directly appended H atoms.
-
-The examples are named and sorted by the chapter where they are found
-in the book.  For example, the file `ch4c_colon.chem' means a `chem'
-example in chapter 4; according to `c', it is the third example in
-this chapter; the name `colon' is used to describe the context of the
-example.
-
-You can view the graphical display of the examples by calling
-
-    groffer <file>
-
-`groffer' calls `chem' automatically.
-
-If you want to transform example files to a different format use the
-`roff2*' programs:
-
-`roff2dvi' prints dvi format to standard output,
-`roff2html' generates html output,
-`roff2pdf' outputs pdf mode,
-`roff2ps' produces PostScript output,
-`roff2text' generates text output in the groff device `latin1',
-`roff2x' prints the output  in  the  groff  device  X  that  is
-         suitable  for programs  like `gxditview' or `xditview'.
-
-To get a suitable `groff' output run
-
-    @g@chem <file> | groff -p ...
-
-
-####### License
-
-Last update: 5 Jan 2009
-
-Copyright (C) 2006, 2009 Free Software Foundation, Inc.
-Written by Bernd Warken <groff-bernd.warken-72@web.de>.
-
-This file is part of `chem', 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:

Index: chem/examples/122/ch2a_ethyl.chem
===================================================================
RCS file: chem/examples/122/ch2a_ethyl.chem
diff -N chem/examples/122/ch2a_ethyl.chem
--- chem/examples/122/ch2a_ethyl.chem	5 Jan 2009 20:10:33 -0000	1.4
+++ /dev/null	1 Jan 1970 00:00:00 -0000
@@ -1,43 +0,0 @@
-ch2a_ethyl.chem:
-.br
-.cstart
-
-# Example file for `chem':
-
-# This originates from Computing Science Technical Report No. 122
-#   CHEM - A Program for Typesetting Chemical Diagrams: User Manual
-#   by Jon L. Bentley, Lynn W. Jelinski, Brian W. Kernighan
-#   <http://cm.bell-labs.com/cm/cs/cstr/122.ps.gz>.
-
-# Copyright (C) 2006, 2009 Free Software Foundation, Inc.
-
-# Last update: 5 Jan 2009
-
-# This file is part of `chem', 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/>.
-
-########################################################################
-
-	CH3
-	bond
-	CH2
-	bond
-
-########################################################################
-### Emacs settings
-# Local Variables:
-# mode: Nroff
-# End:
-.cend

Index: chem/examples/122/ch2b_benzene.chem
===================================================================
RCS file: chem/examples/122/ch2b_benzene.chem
diff -N chem/examples/122/ch2b_benzene.chem
--- chem/examples/122/ch2b_benzene.chem	5 Jan 2009 20:10:33 -0000	1.4
+++ /dev/null	1 Jan 1970 00:00:00 -0000
@@ -1,40 +0,0 @@
-ch2b_benzene.chem:
-.br
-.cstart
-
-# Example file for `chem':
-
-# This originates from Computing Science Technical Report No. 122
-#   CHEM - A Program for Typesetting Chemical Diagrams: User Manual
-#   by Jon L. Bentley, Lynn W. Jelinski, Brian W. Kernighan
-#   <http://cm.bell-labs.com/cm/cs/cstr/122.ps.gz>.
-
-# Copyright (C) 2006, 2009 Free Software Foundation, Inc.
-
-# Last update: 5 Jan 2009
-
-# This file is part of `chem', 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/>.
-
-########################################################################
-
-	benzene
-
-########################################################################
-### Emacs settings
-# Local Variables:
-# mode: Nroff
-# End:
-.cend

Index: chem/examples/122/ch2c_benzene_right.chem
===================================================================
RCS file: chem/examples/122/ch2c_benzene_right.chem
diff -N chem/examples/122/ch2c_benzene_right.chem
--- chem/examples/122/ch2c_benzene_right.chem	5 Jan 2009 20:10:33 -0000	1.4
+++ /dev/null	1 Jan 1970 00:00:00 -0000
@@ -1,40 +0,0 @@
-ch2c_benzene_right.chem:
-.br
-.cstart
-
-# Example file for `chem':
-
-# This originates from Computing Science Technical Report No. 122
-#   CHEM - A Program for Typesetting Chemical Diagrams: User Manual
-#   by Jon L. Bentley, Lynn W. Jelinski, Brian W. Kernighan
-#   <http://cm.bell-labs.com/cm/cs/cstr/122.ps.gz>.
-
-# Copyright (C) 2006, 2009 Free Software Foundation, Inc.
-
-# Last update: 5 Jan 2009
-
-# This file is part of `chem', 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/>.
-
-########################################################################
-
-	benzene pointing right       # a rotated benzene ring
-
-########################################################################
-### Emacs settings
-# Local Variables:
-# mode: Nroff
-# End:
-.cend

Index: chem/examples/122/ch4a_stick.chem
===================================================================
RCS file: chem/examples/122/ch4a_stick.chem
diff -N chem/examples/122/ch4a_stick.chem
--- chem/examples/122/ch4a_stick.chem	5 Jan 2009 20:10:33 -0000	1.4
+++ /dev/null	1 Jan 1970 00:00:00 -0000
@@ -1,45 +0,0 @@
-ch4a_stick.chem:
-.br
-.cstart
-
-# Example file for `chem':
-
-# This originates from Computing Science Technical Report No. 122
-#   CHEM - A Program for Typesetting Chemical Diagrams: User Manual
-#   by Jon L. Bentley, Lynn W. Jelinski, Brian W. Kernighan
-#   <http://cm.bell-labs.com/cm/cs/cstr/122.ps.gz>.
-
-# Copyright (C) 2006, 2009 Free Software Foundation, Inc.
-
-# Last update: 5 Jan 2009
-
-# This file is part of `chem', 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/>.
-
-########################################################################
-
-	bond right
-	bond 60
-	bond 120
-	bond 60
-	bond 120
-	bond down
-
-########################################################################
-### Emacs settings
-# Local Variables:
-# mode: Nroff
-# End:
-.cend

Index: chem/examples/122/ch4b_methyl_acetate.chem
===================================================================
RCS file: chem/examples/122/ch4b_methyl_acetate.chem
diff -N chem/examples/122/ch4b_methyl_acetate.chem
--- chem/examples/122/ch4b_methyl_acetate.chem	5 Jan 2009 20:10:33 -0000	1.4
+++ /dev/null	1 Jan 1970 00:00:00 -0000
@@ -1,49 +0,0 @@
-ch4b_methyl_acetate.chem:
-.br
-.cstart
-
-# Example file for `chem':
-
-# This originates from Computing Science Technical Report No. 122
-#   CHEM - A Program for Typesetting Chemical Diagrams: User Manual
-#   by Jon L. Bentley, Lynn W. Jelinski, Brian W. Kernighan
-#   <http://cm.bell-labs.com/cm/cs/cstr/122.ps.gz>.
-
-# Copyright (C) 2006, 2009 Free Software Foundation, Inc.
-
-# Last update: 5 Jan 2009
-
-# This file is part of `chem', 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/>.
-
-########################################################################
-
-CH3      # the 3 is automatically turned into a subscript
-bond     # the implicit direction is right
-         # implicit connection is to right side of CH3
-C
-double bond 30     # by default, from the substituent C
-O
-bond 120 from C    # must be "from C"; otherwise would leave from O
-O
-bond right
-CH3
-
-########################################################################
-### Emacs settings
-# Local Variables:
-# mode: Nroff
-# End:
-.cend

Index: chem/examples/122/ch4c_colon.chem
===================================================================
RCS file: chem/examples/122/ch4c_colon.chem
diff -N chem/examples/122/ch4c_colon.chem
--- chem/examples/122/ch4c_colon.chem	5 Jan 2009 20:10:33 -0000	1.4
+++ /dev/null	1 Jan 1970 00:00:00 -0000
@@ -1,44 +0,0 @@
-ch4c_colon.chem:
-.br
-.cstart
-
-# Example file for `chem':
-
-# This originates from Computing Science Technical Report No. 122
-#   CHEM - A Program for Typesetting Chemical Diagrams: User Manual
-#   by Jon L. Bentley, Lynn W. Jelinski, Brian W. Kernighan
-#   <http://cm.bell-labs.com/cm/cs/cstr/122.ps.gz>.
-
-# Copyright (C) 2006, 2009 Free Software Foundation, Inc.
-
-# Last update: 5 Jan 2009
-
-# This file is part of `chem', 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/>.
-
-########################################################################
-
-	CH3
-	bond ; C
-	double bond 30 ; O
-	bond 120 from C ; O
-	bond right ; CH3
-
-########################################################################
-### Emacs settings
-# Local Variables:
-# mode: Nroff
-# End:
-.cend

Index: chem/examples/122/ch4d_HCl.H2O.chem
===================================================================
RCS file: chem/examples/122/ch4d_HCl.H2O.chem
diff -N chem/examples/122/ch4d_HCl.H2O.chem
--- chem/examples/122/ch4d_HCl.H2O.chem	5 Jan 2009 20:10:33 -0000	1.4
+++ /dev/null	1 Jan 1970 00:00:00 -0000
@@ -1,40 +0,0 @@
-ch4d_HCl.H2O.chem:
-.br
-.cstart
-
-# Example file for `chem':
-
-# This originates from Computing Science Technical Report No. 122
-#   CHEM - A Program for Typesetting Chemical Diagrams: User Manual
-#   by Jon L. Bentley, Lynn W. Jelinski, Brian W. Kernighan
-#   <http://cm.bell-labs.com/cm/cs/cstr/122.ps.gz>.
-
-# Copyright (C) 2006, 2009 Free Software Foundation, Inc.
-
-# Last update: 5 Jan 2009
-
-# This file is part of `chem', 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/>.
-
-########################################################################
-
-	HCl.H2O
-
-########################################################################
-### Emacs settings
-# Local Variables:
-# mode: Nroff
-# End:
-.cend

Index: chem/examples/122/ch4e_CaSO4.2H2O.chem
===================================================================
RCS file: chem/examples/122/ch4e_CaSO4.2H2O.chem
diff -N chem/examples/122/ch4e_CaSO4.2H2O.chem
--- chem/examples/122/ch4e_CaSO4.2H2O.chem	5 Jan 2009 20:10:33 -0000	1.4
+++ /dev/null	1 Jan 1970 00:00:00 -0000
@@ -1,40 +0,0 @@
-ch4e_CaSO4.2H2O.chem:
-.br
-.cstart
-
-# Example file for `chem':
-
-# This originates from Computing Science Technical Report No. 122
-#   CHEM - A Program for Typesetting Chemical Diagrams: User Manual
-#   by Jon L. Bentley, Lynn W. Jelinski, Brian W. Kernighan
-#   <http://cm.bell-labs.com/cm/cs/cstr/122.ps.gz>.
-
-# Copyright (C) 2006, 2009 Free Software Foundation, Inc.
-
-# Last update: 5 Jan 2009
-
-# This file is part of `chem', 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/>.
-
-########################################################################
-
-	CaSO4.2H2O
-
-########################################################################
-### Emacs settings
-# Local Variables:
-# mode: Nroff
-# End:
-.cend

Index: chem/examples/122/ch4f_C.chem
===================================================================
RCS file: chem/examples/122/ch4f_C.chem
diff -N chem/examples/122/ch4f_C.chem
--- chem/examples/122/ch4f_C.chem	5 Jan 2009 20:10:33 -0000	1.4
+++ /dev/null	1 Jan 1970 00:00:00 -0000
@@ -1,50 +0,0 @@
-ch4f_C.chem:
-.br
-.cstart
-
-# Example file for `chem':
-
-# This originates from Computing Science Technical Report No. 122
-#   CHEM - A Program for Typesetting Chemical Diagrams: User Manual
-#   by Jon L. Bentley, Lynn W. Jelinski, Brian W. Kernighan
-#   <http://cm.bell-labs.com/cm/cs/cstr/122.ps.gz>.
-
-# Copyright (C) 2006, 2009 Free Software Foundation, Inc.
-
-# Last update: 5 Jan 2009
-
-# This file is part of `chem', 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/>.
-
-########################################################################
-
-	bond ; C             # 1st definition of C
-	bond up from C
-	bond down from C
-	bond right from C ; C         # 2nd definition of C
-	bond up from C
-	bond down from C
-	bond right from C ; C         # 3rd definition of C
-	bond up from C
-	bond down from C
-	bond right from C
-
-
-########################################################################
-### Emacs settings
-# Local Variables:
-# mode: Nroff
-# End:
-.cend

Index: chem/examples/122/ch4g_BP.chem
===================================================================
RCS file: chem/examples/122/ch4g_BP.chem
diff -N chem/examples/122/ch4g_BP.chem
--- chem/examples/122/ch4g_BP.chem	5 Jan 2009 20:10:33 -0000	1.4
+++ /dev/null	1 Jan 1970 00:00:00 -0000
@@ -1,50 +0,0 @@
-ch4g_BP.chem:
-.br
-.cstart
-
-# Example file for `chem':
-
-# This originates from Computing Science Technical Report No. 122
-#   CHEM - A Program for Typesetting Chemical Diagrams: User Manual
-#   by Jon L. Bentley, Lynn W. Jelinski, Brian W. Kernighan
-#   <http://cm.bell-labs.com/cm/cs/cstr/122.ps.gz>.
-
-# Copyright (C) 2006, 2009 Free Software Foundation, Inc.
-
-# Last update: 5 Jan 2009
-
-# This file is part of `chem', 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/>.
-
-########################################################################
-
-# this is the isopropyl group
-    bond 120 ; BP       # BP is right end of this bond
-    bond -120 from BP
-    bond right from BP ; C
-    front bond up ; CH3
-    back bond down from C ; D
-    bond right from C ; BP
-# redefine BP to mean the center carbon of this t-butyl group
-    bond up from BP
-    bond right from BP
-    bond down from BP
-
-########################################################################
-### Emacs settings
-# Local Variables:
-# mode: Nroff
-# End:
-.cend

Index: chem/examples/122/ch4h_methacrylate.chem
===================================================================
RCS file: chem/examples/122/ch4h_methacrylate.chem
diff -N chem/examples/122/ch4h_methacrylate.chem
--- chem/examples/122/ch4h_methacrylate.chem	5 Jan 2009 20:10:34 -0000	1.4
+++ /dev/null	1 Jan 1970 00:00:00 -0000
@@ -1,67 +0,0 @@
-ch4h_methacrylate.chem:
-.br
-.cstart
-
-# Example file for `chem':
-
-# This originates from Computing Science Technical Report No. 122
-#   CHEM - A Program for Typesetting Chemical Diagrams: User Manual
-#   by Jon L. Bentley, Lynn W. Jelinski, Brian W. Kernighan
-#   <http://cm.bell-labs.com/cm/cs/cstr/122.ps.gz>.
-
-# Copyright (C) 2006, 2009 Free Software Foundation, Inc.
-
-# Last update: 5 Jan 2009
-
-# This file is part of `chem', 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/>.
-
-########################################################################
-
-    bond dotted
-    bond right ; BP
-    bond up from BP ; C
-    double bond -60 from C ; O
-    bond 60 length .1 from C ; OCH3
-    bond down from BP ; CH3
-# begin second segment of polymer
-    bond right length .5 from BP ; BP
-    bond up length .1 from BP ; H
-    bond down length .1 from BP ; H
-# begin third segment of polymer
-    bond right length .5 from BP ; BP
-    bond up from BP ; C
-    double bond -60 from C ; O
-    bond 60 length .1 from C ; OCH3
-    bond down from BP ; CH3
-# begin fourth segment of polymer
-    bond right length .5 from BP ; BP
-    bond up length .1 from BP ; H
-    bond down length .1 from BP ; H
-# begin fifth segment of polymer
-    bond right length .5 from BP ; BP
-    bond up from BP ; C
-    double bond -60 from C ; O
-    bond 60 length .1 from C ; OCH3
-    bond down from BP ; CH3
-    bond right from BP
-    bond dotted
-
-########################################################################
-### Emacs settings
-# Local Variables:
-# mode: Nroff
-# End:
-.cend

Index: chem/examples/122/ch4i_cyclo.chem
===================================================================
RCS file: chem/examples/122/ch4i_cyclo.chem
diff -N chem/examples/122/ch4i_cyclo.chem
--- chem/examples/122/ch4i_cyclo.chem	5 Jan 2009 20:10:34 -0000	1.4
+++ /dev/null	1 Jan 1970 00:00:00 -0000
@@ -1,47 +0,0 @@
-ch4i_cyclo.chem:
-.br
-.cstart
-
-# Example file for `chem':
-
-# This originates from Computing Science Technical Report No. 122
-#   CHEM - A Program for Typesetting Chemical Diagrams: User Manual
-#   by Jon L. Bentley, Lynn W. Jelinski, Brian W. Kernighan
-#   <http://cm.bell-labs.com/cm/cs/cstr/122.ps.gz>.
-
-# Copyright (C) 2006, 2009 Free Software Foundation, Inc.
-
-# Last update: 5 Jan 2009
-
-# This file is part of `chem', 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/>.
-
-########################################################################
-
-R3:	ring3
-R4:	ring4 at R3 + (.75,0)
-R5:	ring5 at R4 + (.75,0)
-R6:	ring6 at R5 + (.75,0)
-B:	benzene at R6 + (.75,0)
-R7:	ring7 at B + (.75,0)
-R8:	ring8 at R7 + (.75,0)
-
-
-########################################################################
-### Emacs settings
-# Local Variables:
-# mode: Nroff
-# End:
-.cend

Index: chem/examples/122/ch4j_ring4.chem
===================================================================
RCS file: chem/examples/122/ch4j_ring4.chem
diff -N chem/examples/122/ch4j_ring4.chem
--- chem/examples/122/ch4j_ring4.chem	5 Jan 2009 20:10:34 -0000	1.4
+++ /dev/null	1 Jan 1970 00:00:00 -0000
@@ -1,40 +0,0 @@
-ch4j_ring4.chem:
-.br
-.cstart
-
-# Example file for `chem':
-
-# This originates from Computing Science Technical Report No. 122
-#   CHEM - A Program for Typesetting Chemical Diagrams: User Manual
-#   by Jon L. Bentley, Lynn W. Jelinski, Brian W. Kernighan
-#   <http://cm.bell-labs.com/cm/cs/cstr/122.ps.gz>.
-
-# Copyright (C) 2006, 2009 Free Software Foundation, Inc.
-
-# Last update: 5 Jan 2009
-
-# This file is part of `chem', 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/>.
-
-########################################################################
-
-	ring4 pointing 45
-
-########################################################################
-### Emacs settings
-# Local Variables:
-# mode: Nroff
-# End:
-.cend

Index: chem/examples/122/ch4k_ring3.chem
===================================================================
RCS file: chem/examples/122/ch4k_ring3.chem
diff -N chem/examples/122/ch4k_ring3.chem
--- chem/examples/122/ch4k_ring3.chem	5 Jan 2009 20:10:34 -0000	1.4
+++ /dev/null	1 Jan 1970 00:00:00 -0000
@@ -1,42 +0,0 @@
-ch4k_ring3.chem:
-.br
-.cstart
-
-# Example file for `chem':
-
-# This originates from Computing Science Technical Report No. 122
-#   CHEM - A Program for Typesetting Chemical Diagrams: User Manual
-#   by Jon L. Bentley, Lynn W. Jelinski, Brian W. Kernighan
-#   <http://cm.bell-labs.com/cm/cs/cstr/122.ps.gz>.
-
-# Copyright (C) 2006, 2009 Free Software Foundation, Inc.
-
-# Last update: 5 Jan 2009
-
-# This file is part of `chem', 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/>.
-
-########################################################################
-
-R: ring3
-   back bond 120 from R.V2 ; C2H5
-   front bond -120 from R.V3 ; HO
-
-########################################################################
-### Emacs settings
-# Local Variables:
-# mode: Nroff
-# End:
-.cend

Index: chem/examples/122/ch4l_vertex.chem
===================================================================
RCS file: chem/examples/122/ch4l_vertex.chem
diff -N chem/examples/122/ch4l_vertex.chem
--- chem/examples/122/ch4l_vertex.chem	5 Jan 2009 20:10:34 -0000	1.4
+++ /dev/null	1 Jan 1970 00:00:00 -0000
@@ -1,47 +0,0 @@
-ch4l_vertex.chem:
-.br
-.cstart
-
-# Example file for `chem':
-
-# This originates from Computing Science Technical Report No. 122
-#   CHEM - A Program for Typesetting Chemical Diagrams: User Manual
-#   by Jon L. Bentley, Lynn W. Jelinski, Brian W. Kernighan
-#   <http://cm.bell-labs.com/cm/cs/cstr/122.ps.gz>.
-
-# Copyright (C) 2006, 2009 Free Software Foundation, Inc.
-
-# Last update: 5 Jan 2009
-
-# This file is part of `chem', 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/>.
-
-########################################################################
-
-R: benzene pointing right
-   bond left from R.V4 ; HO
-   bond -150 from R.V3 ; CH3O
-   bond right from R.V1 ; C
-   double bond up from C ; O
-   bond right from C ; N
-   bond 45 ; C2H5
-   bond 135 from N ; C2H5
-
-########################################################################
-### Emacs settings
-# Local Variables:
-# mode: Nroff
-# End:
-.cend

Index: chem/examples/122/ch4m_double.chem
===================================================================
RCS file: chem/examples/122/ch4m_double.chem
diff -N chem/examples/122/ch4m_double.chem
--- chem/examples/122/ch4m_double.chem	5 Jan 2009 20:10:34 -0000	1.4
+++ /dev/null	1 Jan 1970 00:00:00 -0000
@@ -1,40 +0,0 @@
-ch4m_double.chem:
-.br
-.cstart
-
-# Example file for `chem':
-
-# This originates from Computing Science Technical Report No. 122
-#   CHEM - A Program for Typesetting Chemical Diagrams: User Manual
-#   by Jon L. Bentley, Lynn W. Jelinski, Brian W. Kernighan
-#   <http://cm.bell-labs.com/cm/cs/cstr/122.ps.gz>.
-
-# Copyright (C) 2006, 2009 Free Software Foundation, Inc.
-
-# Last update: 5 Jan 2009
-
-# This file is part of `chem', 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/>.
-
-########################################################################
-
-	ring double 1,2 3,4 5,6
-
-########################################################################
-### Emacs settings
-# Local Variables:
-# mode: Nroff
-# End:
-.cend

Index: chem/examples/122/ch4n_triple.chem
===================================================================
RCS file: chem/examples/122/ch4n_triple.chem
diff -N chem/examples/122/ch4n_triple.chem
--- chem/examples/122/ch4n_triple.chem	5 Jan 2009 20:10:34 -0000	1.4
+++ /dev/null	1 Jan 1970 00:00:00 -0000
@@ -1,40 +0,0 @@
-ch4n_triple.chem:
-.br
-.cstart
-
-# Example file for `chem':
-
-# This originates from Computing Science Technical Report No. 122
-#   CHEM - A Program for Typesetting Chemical Diagrams: User Manual
-#   by Jon L. Bentley, Lynn W. Jelinski, Brian W. Kernighan
-#   <http://cm.bell-labs.com/cm/cs/cstr/122.ps.gz>.
-
-# Copyright (C) 2006, 2009 Free Software Foundation, Inc.
-
-# Last update: 5 Jan 2009
-
-# This file is part of `chem', 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/>.
-
-########################################################################
-
-	ring8 triple 3,4
-
-########################################################################
-### Emacs settings
-# Local Variables:
-# mode: Nroff
-# End:
-.cend

Index: chem/examples/122/ch4o_aromatic.chem
===================================================================
RCS file: chem/examples/122/ch4o_aromatic.chem
diff -N chem/examples/122/ch4o_aromatic.chem
--- chem/examples/122/ch4o_aromatic.chem	5 Jan 2009 20:10:34 -0000	1.4
+++ /dev/null	1 Jan 1970 00:00:00 -0000
@@ -1,41 +0,0 @@
-ch4o_aromatic.chem:
-.br
-.cstart
-
-# Example file for `chem':
-
-# This originates from Computing Science Technical Report No. 122
-#   CHEM - A Program for Typesetting Chemical Diagrams: User Manual
-#   by Jon L. Bentley, Lynn W. Jelinski, Brian W. Kernighan
-#   <http://cm.bell-labs.com/cm/cs/cstr/122.ps.gz>.
-
-# Copyright (C) 2006, 2009 Free Software Foundation, Inc.
-
-# Last update: 5 Jan 2009
-
-# This file is part of `chem', 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/>.
-
-########################################################################
-
-R: aromatic ring7
-   "+" at R
-
-########################################################################
-### Emacs settings
-# Local Variables:
-# mode: Nroff
-# End:
-.cend

Index: chem/examples/122/ch4p_cholestanol.chem
===================================================================
RCS file: chem/examples/122/ch4p_cholestanol.chem
diff -N chem/examples/122/ch4p_cholestanol.chem
--- chem/examples/122/ch4p_cholestanol.chem	5 Jan 2009 20:10:34 -0000	1.4
+++ /dev/null	1 Jan 1970 00:00:00 -0000
@@ -1,62 +0,0 @@
-ch4p_cholestanol.chem:
-.br
-.cstart
-
-# Example file for `chem':
-
-# This originates from Computing Science Technical Report No. 122
-#   CHEM - A Program for Typesetting Chemical Diagrams: User Manual
-#   by Jon L. Bentley, Lynn W. Jelinski, Brian W. Kernighan
-#   <http://cm.bell-labs.com/cm/cs/cstr/122.ps.gz>.
-
-# Copyright (C) 2006, 2009 Free Software Foundation, Inc.
-
-# Last update: 5 Jan 2009
-
-# This file is part of `chem', 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/>.
-
-########################################################################
-
-R1: ring6
-    "R1" at R1     # this puts a label at R1
-    front bond -120 from R1.V5 ; HO
-         # the following line says "fuse the next six-
-         # membered ring with its 6th vertex joining
-         # the second vertex of R1"
-R2: ring6 with .V6 at R1.V2
-    front bond up from R2.V6 ; CH3
-    back bond down from R2.V4 ; H
-    back bond down from R2.V1 ; H
-    front bond up from R2.V2 ; H
-R3: ring6 with .V4 at R2.V2
-R4: flatring with .V5 at R3.V2
-    front bond up from R4.V5 ; CH3
-    back bond down from R4.V4 ; H # this is the alkyl chain
-    bond up from R4.V1 ; BP
-    bond -60 from BP
-    bond 60 from BP
-    bond 120
-    bond 60
-    bond 120 ; BP
-    bond down from BP
-    bond 60 from BP
-
-########################################################################
-### Emacs settings
-# Local Variables:
-# mode: Nroff
-# End:
-.cend

Index: chem/examples/122/ch4q_rings.chem
===================================================================
RCS file: chem/examples/122/ch4q_rings.chem
diff -N chem/examples/122/ch4q_rings.chem
--- chem/examples/122/ch4q_rings.chem	5 Jan 2009 20:10:34 -0000	1.4
+++ /dev/null	1 Jan 1970 00:00:00 -0000
@@ -1,48 +0,0 @@
-ch4q_rings.chem:
-.br
-.cstart
-
-# Example file for `chem':
-
-# This originates from Computing Science Technical Report No. 122
-#   CHEM - A Program for Typesetting Chemical Diagrams: User Manual
-#   by Jon L. Bentley, Lynn W. Jelinski, Brian W. Kernighan
-#   <http://cm.bell-labs.com/cm/cs/cstr/122.ps.gz>.
-
-# Copyright (C) 2006, 2009 Free Software Foundation, Inc.
-
-# Last update: 5 Jan 2009
-
-# This file is part of `chem', 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/>.
-
-########################################################################
-
-R3: ring3
-R4: ring4 pointing 45 with .V1 at R3.V2
-R5: ring5 pointing down with .V4 at R4.V2
-R6: ring6 pointing 54 with .V6 at R5.V5
-    # the following lines specify the labels inside the rings
-    "3" at R3
-    "4" at R4
-    "5" at R5
-    "6" at R6
-
-########################################################################
-### Emacs settings
-# Local Variables:
-# mode: Nroff
-# End:
-.cend

Index: chem/examples/122/ch4r_spiro.chem
===================================================================
RCS file: chem/examples/122/ch4r_spiro.chem
diff -N chem/examples/122/ch4r_spiro.chem
--- chem/examples/122/ch4r_spiro.chem	5 Jan 2009 20:10:34 -0000	1.4
+++ /dev/null	1 Jan 1970 00:00:00 -0000
@@ -1,44 +0,0 @@
-ch4r_spiro.chem:
-.br
-.cstart
-
-# Example file for `chem':
-
-# This originates from Computing Science Technical Report No. 122
-#   CHEM - A Program for Typesetting Chemical Diagrams: User Manual
-#   by Jon L. Bentley, Lynn W. Jelinski, Brian W. Kernighan
-#   <http://cm.bell-labs.com/cm/cs/cstr/122.ps.gz>.
-
-# Copyright (C) 2006, 2009 Free Software Foundation, Inc.
-
-# Last update: 5 Jan 2009
-
-# This file is part of `chem', 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/>.
-
-########################################################################
-
-R1: ring6
-R2: ring6 with .V1 at R1.V4
-R3: ring5 with .V5 at R2.V3
-    back bond 60 from R3.V2 ; OH
-    front bond 150 from R3.V3 ; OH
-
-########################################################################
-### Emacs settings
-# Local Variables:
-# mode: Nroff
-# End:
-.cend

Index: chem/examples/122/ch4s_heteroatoms.chem
===================================================================
RCS file: chem/examples/122/ch4s_heteroatoms.chem
diff -N chem/examples/122/ch4s_heteroatoms.chem
--- chem/examples/122/ch4s_heteroatoms.chem	5 Jan 2009 20:10:35 -0000	1.4
+++ /dev/null	1 Jan 1970 00:00:00 -0000
@@ -1,40 +0,0 @@
-ch4s_heteroatoms.chem:
-.br
-.cstart
-
-# Example file for `chem':
-
-# This originates from Computing Science Technical Report No. 122
-#   CHEM - A Program for Typesetting Chemical Diagrams: User Manual
-#   by Jon L. Bentley, Lynn W. Jelinski, Brian W. Kernighan
-#   <http://cm.bell-labs.com/cm/cs/cstr/122.ps.gz>.
-
-# Copyright (C) 2006, 2009 Free Software Foundation, Inc.
-
-# Last update: 5 Jan 2009
-
-# This file is part of `chem', 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/>.
-
-########################################################################
-
-	ring put N at 2 put S at 4 double 2,3 4,5 6,1
-
-########################################################################
-### Emacs settings
-# Local Variables:
-# mode: Nroff
-# End:
-.cend

Index: chem/examples/122/ch4t_polycyclic.chem
===================================================================
RCS file: chem/examples/122/ch4t_polycyclic.chem
diff -N chem/examples/122/ch4t_polycyclic.chem
--- chem/examples/122/ch4t_polycyclic.chem	5 Jan 2009 20:10:35 -0000	1.4
+++ /dev/null	1 Jan 1970 00:00:00 -0000
@@ -1,51 +0,0 @@
-ch4t_polycyclic.chem:
-.br
-.cstart
-
-# Example file for `chem':
-
-# This originates from Computing Science Technical Report No. 122
-#   CHEM - A Program for Typesetting Chemical Diagrams: User Manual
-#   by Jon L. Bentley, Lynn W. Jelinski, Brian W. Kernighan
-#   <http://cm.bell-labs.com/cm/cs/cstr/122.ps.gz>.
-
-# Copyright (C) 2006, 2009 Free Software Foundation, Inc.
-
-# Last update: 5 Jan 2009
-
-# This file is part of `chem', 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/>.
-
-########################################################################
-
-R1: benzene pointing right
-    bond 30 from R1.V6 ; Br
-R2: benzene pointing right with .V5 at R1.V1
-R3: benzene pointing right with .V1 at R2.V3
-    bond 150 from R3.V2 ; CO2H
-R4: benzene pointing right with .V1 at R1.V3
-# next line names bond B1 so we can refer to its end
-B1: bond left from R4.V4
-    ring6 put N at 4 double 2,3 4,5 6,1 with .V3 at B1.end
-B2: bond right from R2.V1
-R5: benzene with .V5 at B2.end
-    ring6 put N at 4 double 1,2 3,4 with .V5 at R5.V3
-
-########################################################################
-### Emacs settings
-# Local Variables:
-# mode: Nroff
-# End:
-.cend

Index: chem/examples/122/ch4u_nicotine.chem
===================================================================
RCS file: chem/examples/122/ch4u_nicotine.chem
diff -N chem/examples/122/ch4u_nicotine.chem
--- chem/examples/122/ch4u_nicotine.chem	5 Jan 2009 20:10:35 -0000	1.4
+++ /dev/null	1 Jan 1970 00:00:00 -0000
@@ -1,44 +0,0 @@
-ch4u_nicotine.chem:
-.br
-.cstart
-
-# Example file for `chem':
-
-# This originates from Computing Science Technical Report No. 122
-#   CHEM - A Program for Typesetting Chemical Diagrams: User Manual
-#   by Jon L. Bentley, Lynn W. Jelinski, Brian W. Kernighan
-#   <http://cm.bell-labs.com/cm/cs/cstr/122.ps.gz>.
-
-# Copyright (C) 2006, 2009 Free Software Foundation, Inc.
-
-# Last update: 5 Jan 2009
-
-# This file is part of `chem', 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/>.
-
-########################################################################
-
-	benzene put N at 4
-	bond right
-	ring5 pointing down put N at 1
-	bond down from .N ; CH3        # or .V1
-
-
-########################################################################
-### Emacs settings
-# Local Variables:
-# mode: Nroff
-# End:
-.cend

Index: chem/examples/122/ch4v_histidine.chem
===================================================================
RCS file: chem/examples/122/ch4v_histidine.chem
diff -N chem/examples/122/ch4v_histidine.chem
--- chem/examples/122/ch4v_histidine.chem	5 Jan 2009 20:10:35 -0000	1.4
+++ /dev/null	1 Jan 1970 00:00:00 -0000
@@ -1,46 +0,0 @@
-ch4v_histidine.chem:
-.br
-.cstart
-
-# Example file for `chem':
-
-# This originates from Computing Science Technical Report No. 122
-#   CHEM - A Program for Typesetting Chemical Diagrams: User Manual
-#   by Jon L. Bentley, Lynn W. Jelinski, Brian W. Kernighan
-#   <http://cm.bell-labs.com/cm/cs/cstr/122.ps.gz>.
-
-# Copyright (C) 2006, 2009 Free Software Foundation, Inc.
-
-# Last update: 5 Jan 2009
-
-# This file is part of `chem', 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/>.
-
-########################################################################
-
-R1: flatring pointing down put N at 2 put N at 5 double 1,2 3,4
-    H right of R1.V5
-    bond right from R1.V4 ; CH2
-    bond right ; C
-    bond up from C ; H
-    bond down from C ; NH2
-    bond right from C ; CO2H
-
-########################################################################
-### Emacs settings
-# Local Variables:
-# mode: Nroff
-# End:
-.cend

Index: chem/examples/122/ch4w_lsd.chem
===================================================================
RCS file: chem/examples/122/ch4w_lsd.chem
diff -N chem/examples/122/ch4w_lsd.chem
--- chem/examples/122/ch4w_lsd.chem	5 Jan 2009 20:10:35 -0000	1.4
+++ /dev/null	1 Jan 1970 00:00:00 -0000
@@ -1,52 +0,0 @@
-ch4w_lsd.chem:
-.br
-.cstart
-
-# Example file for `chem':
-
-# This originates from Computing Science Technical Report No. 122
-#   CHEM - A Program for Typesetting Chemical Diagrams: User Manual
-#   by Jon L. Bentley, Lynn W. Jelinski, Brian W. Kernighan
-#   <http://cm.bell-labs.com/cm/cs/cstr/122.ps.gz>.
-
-# Copyright (C) 2006, 2009 Free Software Foundation, Inc.
-
-# Last update: 5 Jan 2009
-
-# This file is part of `chem', 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/>.
-
-########################################################################
-
-B: benzene pointing right
-F: flatring pointing left put N at 5 double 3,4 with .V1 at B.V2
-   H below F.N
-R: ring pointing right with .V4 at B.V6
-   front bond right from R.V6 ; H
-W: ring pointing right with .V2 at R.V6 put N at 1 double 3,4
-   bond right from W.N ; CH3
-   back bond -60 from W.V5 ; H
-   bond up from W.V5 ; C
-   double bond up from C ; O
-   bond right from C ; N
-   bond 45 from N ; C2H5
-   bond 135 from N ; C2H5
-
-########################################################################
-### Emacs settings
-# Local Variables:
-# mode: Nroff
-# End:
-.cend

Index: chem/examples/122/ch4x_anisole.chem
===================================================================
RCS file: chem/examples/122/ch4x_anisole.chem
diff -N chem/examples/122/ch4x_anisole.chem
--- chem/examples/122/ch4x_anisole.chem	5 Jan 2009 20:10:35 -0000	1.4
+++ /dev/null	1 Jan 1970 00:00:00 -0000
@@ -1,44 +0,0 @@
-ch4x_anisole.chem:
-.br
-.cstart
-
-# Example file for `chem':
-
-# This originates from Computing Science Technical Report No. 122
-#   CHEM - A Program for Typesetting Chemical Diagrams: User Manual
-#   by Jon L. Bentley, Lynn W. Jelinski, Brian W. Kernighan
-#   <http://cm.bell-labs.com/cm/cs/cstr/122.ps.gz>.
-
-# Copyright (C) 2006, 2009 Free Software Foundation, Inc.
-
-# Last update: 5 Jan 2009
-
-# This file is part of `chem', 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/>.
-
-########################################################################
-
-R1: benzene
-    bond down from R1.V4 ; OCH3
-R2: benzene at R1 + (1.5,0)
-    bond down from R2.V4 ; O
-    CH3 right of O
-
-########################################################################
-### Emacs settings
-# Local Variables:
-# mode: Nroff
-# End:
-.cend

Index: chem/examples/122/ch4y_reserpine.chem
===================================================================
RCS file: chem/examples/122/ch4y_reserpine.chem
diff -N chem/examples/122/ch4y_reserpine.chem
--- chem/examples/122/ch4y_reserpine.chem	1 Feb 2013 08:12:26 -0000	1.5
+++ /dev/null	1 Jan 1970 00:00:00 -0000
@@ -1,64 +0,0 @@
-ch4y_reserpine.chem:
-.br
-.cstart
-
-# Example file for `chem':
-
-# This originates from Computing Science Technical Report No. 122
-#   CHEM - A Program for Typesetting Chemical Diagrams: User Manual
-#   by Jon L. Bentley, Lynn W. Jelinski, Brian W. Kernighan
-#   <http://cm.bell-labs.com/cm/cs/cstr/122.ps.gz>.
-# Some corrections were added.
-
-# Copyright (C) 2006, 2009 Free Software Foundation, Inc.
-
-# Last update: 5 Jan 2009
-
-# This file is part of `chem', 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/>.
-
-########################################################################
-
-    CH3O
-    bond 60
-R1: benzene
-R2: aromatic flatring5 pointing down put N at 1 with .V3 at R1.V2
-    H below R2.V1
-R3: ring put N at 3 with .V5 at R2.V5
-R4: ring put N at 1 with .V1 at R3.V3
-    back bond -120 from R4.V4 ; H
-    back bond 60 from R4.V3 ; H
-R5: ring with .V1 at R4.V3
-    bond -120 ; C
-    double bond down from C ; O
-    CH3O left of C
-    back bond 60 from R5.V3 ; H
-    back bond down from R5.V4 ; O
-    CH3 right of O
-    bond 120 from R5.V3 ; O
-    bond right length .1 from O ; C
-    double bond down ; O
-    bond right length .1 from C
-B:  benzene pointing right
-    bond 30 from B.V6 ; OCH3
-    bond right from B.V1 ; OCH3
-    bond 150 from B.V2 ; OCH3
-
-########################################################################
-### Emacs settings
-# Local Variables:
-# mode: Nroff
-# End:
-.cend

Index: chem/examples/122/ch4z1_eqn_glutamic.chem
===================================================================
RCS file: chem/examples/122/ch4z1_eqn_glutamic.chem
diff -N chem/examples/122/ch4z1_eqn_glutamic.chem
--- chem/examples/122/ch4z1_eqn_glutamic.chem	5 Jan 2009 20:10:35 -0000	1.4
+++ /dev/null	1 Jan 1970 00:00:00 -0000
@@ -1,80 +0,0 @@
-ch4z1_eqn_glutamic.chem:
-.br
-.EQ
-delim $$
-.EN
-.cstart
-
-# Example file for `chem':
-
-# This originates from Computing Science Technical Report No. 122
-#   CHEM - A Program for Typesetting Chemical Diagrams: User Manual
-#   by Jon L. Bentley, Lynn W. Jelinski, Brian W. Kernighan
-#   <http://cm.bell-labs.com/cm/cs/cstr/122.ps.gz>.
-# Some corrections were added.
-
-# Copyright (C) 2006, 2009 Free Software Foundation, Inc.
-
-# Last update: 5 Jan 2009
-
-# This file is part of `chem', 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/>.
-
-########################################################################
-
-# a left bracket
-    bond right length .1 ; BP
-    bond up length .3
-    bond right length .1
-    bond down length .3 from BP
-    bond right length .1
-# this is the mainchain amide structure
-    bond right length .1 from BP ; NH
-    bond right ; CH
-# label the CH with an alpha, intended for eqn.
-# this line says "put the north edge of the alpha at the
-# south edge of the CH"
-    "$alpha$" with .n at CH.s
-    bond right from CH ; C
-    double bond up from C ; O
-    bond right length .1 from C ; BP
-# a right bracket
-    bond up length .3
-    bond left length .1
-    bond right length .1 from BP
-    bond down length .3 from BP ; BP
-    bond left length .1
-# label the degree of polymerization
-    "$n$" with .w at BP.se
-# this is the sidechain
-    bond up from CH ; CH2
-    "$beta$" with .e at CH2.w
-    bond up from CH2 ; CH2
-    "$gamma$" with .e at CH2.w
-    bond up from CH2 ; C
-# this is the benzyl ester part
-    double bond -60 from C ; O
-    bond 60 from C ; O
-    bond right ; CH2C6H5
-
-########################################################################
-### Emacs settings
-# Local Variables:
-# mode: Nroff
-# End:
-.cend
-.EQ
-delim off
-.EN

Index: chem/examples/122/ch4z2_text.chem
===================================================================
RCS file: chem/examples/122/ch4z2_text.chem
diff -N chem/examples/122/ch4z2_text.chem
--- chem/examples/122/ch4z2_text.chem	5 Jan 2009 20:10:35 -0000	1.4
+++ /dev/null	1 Jan 1970 00:00:00 -0000
@@ -1,55 +0,0 @@
-ch4z2_text.chem:
-.br
-.cstart
-
-# Example file for `chem':
-
-# This originates from Computing Science Technical Report No. 122
-#   CHEM - A Program for Typesetting Chemical Diagrams: User Manual
-#   by Jon L. Bentley, Lynn W. Jelinski, Brian W. Kernighan
-#   <http://cm.bell-labs.com/cm/cs/cstr/122.ps.gz>.
-
-# Copyright (C) 2006, 2009 Free Software Foundation, Inc.
-
-# Last update: 5 Jan 2009
-
-# This file is part of `chem', 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/>.
-
-########################################################################
-
-    bond 120 dotted
-    bond 120 length .3 ; BP
-    back bond -120 length .25 from BP ; H
-    front bond 120 length .25 from BP ; CH3
-    bond 60 length .5 from BP ; BP
-    bond -60 length .25 from BP ; H
-# note the pic move command to position the text
-    move left .35 ; "(ANTI)"
-    front bond 60 length .25 from BP ; H
-# another positioning of text
-    move right .35 ; "(SYN)"
-    bond 120 length .4 from BP ; BP
-    back bond -120 length .25 from BP ; H
-    front bond 120 length .25 from BP ; CH3
-    bond 60 length .5 from BP
-    bond 60 dotted
-
-########################################################################
-### Emacs settings
-# Local Variables:
-# mode: Nroff
-# End:
-.cend

Index: chem/examples/122/ch5a_size.chem
===================================================================
RCS file: chem/examples/122/ch5a_size.chem
diff -N chem/examples/122/ch5a_size.chem
--- chem/examples/122/ch5a_size.chem	5 Jan 2009 20:10:35 -0000	1.4
+++ /dev/null	1 Jan 1970 00:00:00 -0000
@@ -1,47 +0,0 @@
-ch5a_size.chem:
-.br
-.cstart
-
-# Example file for `chem':
-
-# This originates from Computing Science Technical Report No. 122
-#   CHEM - A Program for Typesetting Chemical Diagrams: User Manual
-#   by Jon L. Bentley, Lynn W. Jelinski, Brian W. Kernighan
-#   <http://cm.bell-labs.com/cm/cs/cstr/122.ps.gz>.
-
-# Copyright (C) 2006, 2009 Free Software Foundation, Inc.
-
-# Last update: 5 Jan 2009
-
-# This file is part of `chem', 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/>.
-
-########################################################################
-
-.ps 14
-size 16
-R: ring6 put O at 1 put C at 2 put O at 3 put C at 4 put O at 5 put C at 6
-   double bond 60 from R.V2 ; NH
-   double bond down from R.V4 ; NH
-   double bond -60 from R.V6 ; HN
-size 10 # if you are doing more than one
-.ps 10
-
-########################################################################
-### Emacs settings
-# Local Variables:
-# mode: Nroff
-# End:
-.cend

Index: chem/examples/122/ch6a_pic.chem
===================================================================
RCS file: chem/examples/122/ch6a_pic.chem
diff -N chem/examples/122/ch6a_pic.chem
--- chem/examples/122/ch6a_pic.chem	5 Jan 2009 20:10:35 -0000	1.5
+++ /dev/null	1 Jan 1970 00:00:00 -0000
@@ -1,45 +0,0 @@
-ch6a_pic.chem:
-.br
-.cstart
-
-# Example file for `chem':
-
-# This originates from Computing Science Technical Report No. 122
-#   CHEM - A Program for Typesetting Chemical Diagrams: User Manual
-#   by Jon L. Bentley, Lynn W. Jelinski, Brian W. Kernighan
-#   <http://cm.bell-labs.com/cm/cs/cstr/122.ps.gz>.
-
-# Copyright (C) 2006, 2009 Free Software Foundation, Inc.
-
-# Last update: 5 Jan 2009
-
-# This file is part of `chem', 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/>.
-
-########################################################################
-
-R:	ring double 2,3
-	line from R.V6 to R.C
-	line from R.C to R.V4
-	X1: 1/2 <R.V5,R.C>
-	X2: 1/2 <R.C,R.V2>
-	bond from X1 to X2
-
-########################################################################
-### Emacs settings
-# Local Variables:
-# mode: Nroff
-# End:
-.cend

Index: chem/examples/122/ch6b_dna.chem
===================================================================
RCS file: chem/examples/122/ch6b_dna.chem
diff -N chem/examples/122/ch6b_dna.chem
--- chem/examples/122/ch6b_dna.chem	5 Jan 2009 20:10:35 -0000	1.5
+++ /dev/null	1 Jan 1970 00:00:00 -0000
@@ -1,61 +0,0 @@
-ch6b_dna.chem:
-.br
-.cstart
-
-# Example file for `chem':
-
-# This originates from Computing Science Technical Report No. 122
-#   CHEM - A Program for Typesetting Chemical Diagrams: User Manual
-#   by Jon L. Bentley, Lynn W. Jelinski, Brian W. Kernighan
-#   <http://cm.bell-labs.com/cm/cs/cstr/122.ps.gz>.
-
-# Copyright (C) 2006, 2009 Free Software Foundation, Inc.
-
-# Last update: 5 Jan 2009
-
-# This file is part of `chem', 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/>.
-
-########################################################################
-
-P: [
-R1:  flatring pointing up put N at 1 put N at 4 double 5,1
-     bond -135 from R1.V4 ; BP
-     "deoxyribose" rjust with .e at BP.w
-R2:  ring6 put N at 2 put N at 4 double 1,2 3,4 5,6 with .V6 at R1.V2
-     pic Conn: R2.V2.ne #because naming is too restricted in pic
-     bond up from R2.V1 ; N
-     bond -60 from N ; H
-     bond 60 from N ; H
-]
-     # thymine
-Q: [
-R3:  ring6 put N at 3 put N at 5 double 1,2
-     bond up from R3.V1 ; CH3
-     bond 120 from R3.V3 ; BP
-     "deoxyribose" ljust with .w at BP.e
-     double bond down from R3.V4 ; O
-     double bond -60 from R3.V6 ; O
-     bond -120 from R3.V5 ; H
-] with .O at P.H + (.3,.3)
-     bond from Q.O.sw to P.H.ne dotted
-     bond from Q.H.sw to P.Conn dotted
-
-########################################################################
-### Emacs settings
-# Local Variables:
-# mode: Nroff
-# End:
-.cend

Index: chem/examples/122/chAa_polymer.chem
===================================================================
RCS file: chem/examples/122/chAa_polymer.chem
diff -N chem/examples/122/chAa_polymer.chem
--- chem/examples/122/chAa_polymer.chem	5 Jan 2009 20:10:36 -0000	1.4
+++ /dev/null	1 Jan 1970 00:00:00 -0000
@@ -1,74 +0,0 @@
-chAa_polymer.chem:
-.br
-.cstart
-
-# Example file for `chem':
-
-# This originates from Computing Science Technical Report No. 122
-#   CHEM - A Program for Typesetting Chemical Diagrams: User Manual
-#   by Jon L. Bentley, Lynn W. Jelinski, Brian W. Kernighan
-#   <http://cm.bell-labs.com/cm/cs/cstr/122.ps.gz>.
-
-# Copyright (C) 2006, 2009 Free Software Foundation, Inc.
-
-# Last update: 5 Jan 2009
-
-# This file is part of `chem', 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/>.
-
-########################################################################
-
-# epoxy based on the m-phenyldiamine cured bisphenol-A
-     size 8
-     bond dotted
-     bond ; N
-     bond ; CH2
-     bond down from N
-R1:  benzene
-     bond 120 length .1 from R1.V3 ; N
-     bond right length .1 from N
-     bond down length .1 from N
-# back to the CH2
-     bond right from CH2 ; CH
-     bond down from CH ; OH
-     bond right from CH ; CH2
-     bond right ; O
-     bond right
-     benzene pointing right
-     bond right ; C
-     bond up from C ; CH3
-     bond down from C ; CH3
-     bond right from C
-     benzene pointing right
-     bond right ; O
-     bond right from O ; CH2
-     bond right ; CH
-     bond down from CH ; OH
-     bond right from CH ; CH2
-     bond right ; N
-     bond right from N
-     bond dotted
-     bond down from N
-R2:  benzene
-     bond 120 length .1 from R2.V3 ; N
-     bond right length .1 from N
-     bond down length .1 from N
-
-########################################################################
-### Emacs settings
-# Local Variables:
-# mode: Nroff
-# End:
-.cend

Index: chem/examples/122/chAb_vinyl_chloro.chem
===================================================================
RCS file: chem/examples/122/chAb_vinyl_chloro.chem
diff -N chem/examples/122/chAb_vinyl_chloro.chem
--- chem/examples/122/chAb_vinyl_chloro.chem	5 Jan 2009 20:10:36 -0000	1.4
+++ /dev/null	1 Jan 1970 00:00:00 -0000
@@ -1,64 +0,0 @@
-chAb_vinyl_chloro.chem:
-.br
-.cstart
-
-# Example file for `chem':
-
-# This originates from Computing Science Technical Report No. 122
-#   CHEM - A Program for Typesetting Chemical Diagrams: User Manual
-#   by Jon L. Bentley, Lynn W. Jelinski, Brian W. Kernighan
-#   <http://cm.bell-labs.com/cm/cs/cstr/122.ps.gz>.
-
-# Copyright (C) 2006, 2009 Free Software Foundation, Inc.
-
-# Last update: 5 Jan 2009
-
-# This file is part of `chem', 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/>.
-
-########################################################################
-
-    Cl
-    bond 120 length .25 ; BP
-    bond 60 length .25 from BP ; Cl
-B1: double bond down length .3 from BP
-    bond 120 length .35 ; BP
-# now comes the ring
-R1: ring6 double 1,2 3,4 5,6 with .V6 at BP
-    bond up length .1 from R1.V1 ; H
-    bond 60 length .1 from R1.V2 ; H
-    bond 120 from R1.V3 ; O
-    bond 60 from O ; C
-    double bond up from C ; O
-    bond 120 from C
-# continue decorating the ring
-    bond down length .1 from R1.V4 ; H
-    bond -120 length .1 from R1.V5 ; H
-# now go back and do the left hand ring
-    bond -120 length .35 from B1.end ; BP
-R2: ring6 double 1,2 3,4 5,6 with .V2 at BP
-    bond up length .1 from R2.V1 ; H
-    bond -60 length .1 from R2.V6 ; H
-    bond -120 from R2.V5 ; O
-    bond -60 from O
-    bond down length .1 from R2.V4 ; H
-    bond 120 length .1 from R2.V3 ; H
-
-########################################################################
-### Emacs settings
-# Local Variables:
-# mode: Nroff
-# End:
-.cend

Index: chem/examples/122/chAc_morphine.chem
===================================================================
RCS file: chem/examples/122/chAc_morphine.chem
diff -N chem/examples/122/chAc_morphine.chem
--- chem/examples/122/chAc_morphine.chem	5 Jan 2009 20:10:36 -0000	1.4
+++ /dev/null	1 Jan 1970 00:00:00 -0000
@@ -1,54 +0,0 @@
-chAc_morphine.chem:
-.br
-.cstart
-
-# Example file for `chem':
-
-# This originates from Computing Science Technical Report No. 122
-#   CHEM - A Program for Typesetting Chemical Diagrams: User Manual
-#   by Jon L. Bentley, Lynn W. Jelinski, Brian W. Kernighan
-#   <http://cm.bell-labs.com/cm/cs/cstr/122.ps.gz>.
-
-# Copyright (C) 2006, 2009 Free Software Foundation, Inc.
-
-# Last update: 5 Jan 2009
-
-# This file is part of `chem', 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/>.
-
-########################################################################
-
-R1:  ring6 double 1,2
-     bond -60 from R1.V6 ; HO
-R2:  ring6 with .V1 at R1.V3
-     bond 60 from R2.V2 ; N
-     bond right from N ; CH3
-R3:  benzene with .V1 at R2.V5
-     bond -120 from R3.V5 ; HO
-# this is the furan ring
-     bond -135 length .33 from R1.V5 ; O
-     bond -45 length .33 from R3.V6
-# this is the odd ring
-     bond up length .1 from N ; BP
-B1:  bond up length .33 from R1.V4
-     bond to BP
-
-
-########################################################################
-### Emacs settings
-# Local Variables:
-# mode: Nroff
-# End:
-.cend

Index: chem/examples/122/chAd_chlorophyll.chem
===================================================================
RCS file: chem/examples/122/chAd_chlorophyll.chem
diff -N chem/examples/122/chAd_chlorophyll.chem
--- chem/examples/122/chAd_chlorophyll.chem	5 Jan 2009 20:10:36 -0000	1.4
+++ /dev/null	1 Jan 1970 00:00:00 -0000
@@ -1,71 +0,0 @@
-chAd_chlorophyll.chem:
-.br
-.cstart
-
-# Example file for `chem':
-
-# This originates from Computing Science Technical Report No. 122
-#   CHEM - A Program for Typesetting Chemical Diagrams: User Manual
-#   by Jon L. Bentley, Lynn W. Jelinski, Brian W. Kernighan
-#   <http://cm.bell-labs.com/cm/cs/cstr/122.ps.gz>.
-
-# Copyright (C) 2006, 2009 Free Software Foundation, Inc.
-
-# Last update: 5 Jan 2009
-
-# This file is part of `chem', 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/>.
-
-########################################################################
-
-    Mg
-    bond 45 ; N
-R1: ring5 pointing up put N at 4 double 1,2 4,5 with .V4 at N
-         bond up from R1.V1 ; CH3
-         bond right from R1.V2 ; CH2CH3
-    bond 135 from Mg ; N
-R2: ring5 pointing down put N at 3 double 1,2 4,5 with .V3 at N
-         bond right from R2.V5 ; CH3
-    bond 225 from Mg ; N
-R3: ring5 pointing down put N at 4 double 3,4 with .V4 at N
-    bond -45 from Mg ; N
-R4: ring5 pointing up put N at 3 double 1,5 with .V3 at N
-         bond left from R4.V5 ; H3C
-         bond up from R4.V1 ; CH
-         double bond right length .1 from CH ; CH2
-    double bond 150 length .3 from R1.V3
-    bond to R2.V4
-R5: ring5 pointing 72 with .V5 at R2.V2
-         double bond 135 from R5.V2 ; O
-         bond down from R5.V3 ; C
-         double bond left length .1 from C ; O
-         bond down from C ; O
-         CH3 left of O
-    double bond -25 from R5.V4
-    bond down from R3.V1 ; CH2
-    CH2 left of CH2
-    bond left ; C
-    double bond -45 ; O
-    bond -135 from C ; C20H39O
-    bond left from R3.V2 ; H3C
-    double bond -150 length .3 from R4.V4
-    bond to R3.V3
-
-########################################################################
-### Emacs settings
-# Local Variables:
-# mode: Nroff
-# End:
-.cend

Index: chem/examples/122/chAe_chair.chem
===================================================================
RCS file: chem/examples/122/chAe_chair.chem
diff -N chem/examples/122/chAe_chair.chem
--- chem/examples/122/chAe_chair.chem	5 Jan 2009 20:10:36 -0000	1.4
+++ /dev/null	1 Jan 1970 00:00:00 -0000
@@ -1,51 +0,0 @@
-chAe_chair.chem:
-.br
-.cstart
-
-# Example file for `chem':
-
-# This originates from Computing Science Technical Report No. 122
-#   CHEM - A Program for Typesetting Chemical Diagrams: User Manual
-#   by Jon L. Bentley, Lynn W. Jelinski, Brian W. Kernighan
-#   <http://cm.bell-labs.com/cm/cs/cstr/122.ps.gz>.
-
-# Copyright (C) 2006, 2009 Free Software Foundation, Inc.
-
-# Last update: 5 Jan 2009
-
-# This file is part of `chem', 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/>.
-
-########################################################################
-
-pic define chair { [
-    V1: bond 120 length .25
-    V2: bond right length .35
-    V3: bond 150 length .35
-    V4: bond -60 length .25
-    V5: bond left length .35
-    V6: bond to V1.start
-pic ] }
-R1: chair
-R2: chair with .V1 at R1.V4.start
-bond 60 from R2.V4.start ; CH3
-bond down from R2.V4.start ; OH
-
-########################################################################
-### Emacs settings
-# Local Variables:
-# mode: Nroff
-# End:
-.cend

Index: chem/examples/122/chAf_arrow.chem
===================================================================
RCS file: chem/examples/122/chAf_arrow.chem
diff -N chem/examples/122/chAf_arrow.chem
--- chem/examples/122/chAf_arrow.chem	5 Jan 2009 20:10:36 -0000	1.4
+++ /dev/null	1 Jan 1970 00:00:00 -0000
@@ -1,70 +0,0 @@
-chAf_arrow.chem:
-.br
-.EQ
-delim $$
-.EN
-.cstart
-
-# Example file for `chem':
-
-# This originates from Computing Science Technical Report No. 122
-#   CHEM - A Program for Typesetting Chemical Diagrams: User Manual
-#   by Jon L. Bentley, Lynn W. Jelinski, Brian W. Kernighan
-#   <http://cm.bell-labs.com/cm/cs/cstr/122.ps.gz>.
-
-# Copyright (C) 2006, 2009 Free Software Foundation, Inc.
-
-# Last update: 5 Jan 2009
-
-# This file is part of `chem', 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/>.
-
-########################################################################
-
-    bond length .1 ; BP
-    bond up length .5
-    bond right
-    bond down length .5 from BP
-    bond right
-    bond right from BP ; C
-    double bond up ; O
-    bond right from C
-    benzene pointing right
-    bond right ; C
-    double bond up from C ; O
-    bond right from C ; O
-    bond right ; CH2
-# this is the statement to make the arrow
-    line <- from CH2.s down
-    move down .1 ; "0.085"
-    CH2CH2CH2 right of CH2
-    bond right ; O
-    bond right length .1 ; BP
-    bond up length .5 from BP
-    bond left
-    bond right length .1 from BP
-    bond down length .5 from BP ; BP
-    bond left
-    "$n$" with .w at BP.se
-
-########################################################################
-### Emacs settings
-# Local Variables:
-# mode: Nroff
-# End:
-.cend
-.EQ
-delim off
-.EN

Index: chem/examples/122/chAg_circle.chem
===================================================================
RCS file: chem/examples/122/chAg_circle.chem
diff -N chem/examples/122/chAg_circle.chem
--- chem/examples/122/chAg_circle.chem	5 Jan 2009 20:10:36 -0000	1.5
+++ /dev/null	1 Jan 1970 00:00:00 -0000
@@ -1,56 +0,0 @@
-chAg_circle.chem:
-.br
-.cstart
-
-# Example file for `chem':
-
-# This originates from Computing Science Technical Report No. 122
-#   CHEM - A Program for Typesetting Chemical Diagrams: User Manual
-#   by Jon L. Bentley, Lynn W. Jelinski, Brian W. Kernighan
-#   <http://cm.bell-labs.com/cm/cs/cstr/122.ps.gz>.
-
-# Copyright (C) 2006, 2009 Free Software Foundation, Inc.
-
-# Last update: 5 Jan 2009
-
-# This file is part of `chem', 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/>.
-
-########################################################################
-
-bond 120 ; C
-bond 60 ; C
-bond up ; Cl
-double bond 120 from C ; C
-bond 60 ; C
-bond 120 ; C
-bond 60 ; C
-bond up ; Cl
-double bond 120 from C ; C
-circle at C rad .08
-bond 60 from C ; C
-bond 120 ; C
-bond 60 ; C
-double bond 120 ; C
-bond down ; Cl
-bond 60 from C ; C
-bond 120
-
-########################################################################
-### Emacs settings
-# Local Variables:
-# mode: Nroff
-# End:
-.cend

Index: chem/examples/122/chAh_brackets.chem
===================================================================
RCS file: chem/examples/122/chAh_brackets.chem
diff -N chem/examples/122/chAh_brackets.chem
--- chem/examples/122/chAh_brackets.chem	5 Jan 2009 20:10:36 -0000	1.4
+++ /dev/null	1 Jan 1970 00:00:00 -0000
@@ -1,62 +0,0 @@
-chAh_brackets.chem:
-.br
-.EQ
-delim $$
-.EN
-.cstart
-
-# Example file for `chem':
-
-# This originates from Computing Science Technical Report No. 122
-#   CHEM - A Program for Typesetting Chemical Diagrams: User Manual
-#   by Jon L. Bentley, Lynn W. Jelinski, Brian W. Kernighan
-#   <http://cm.bell-labs.com/cm/cs/cstr/122.ps.gz>.
-
-# Copyright (C) 2006, 2009 Free Software Foundation, Inc.
-
-# Last update: 5 Jan 2009
-
-# This file is part of `chem', 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/>.
-
-########################################################################
-
-[
-    bond right ; CH2
-    bond 120 ; (CH2)
-    "$nothing sub n$"
-    bond 60 ; .CH2
-]
-# now put the arrow in
-    move right .3
-    arrow .5
-    move right .3
-# begin second structure
-[
-    bond right ; CH.
-    bond 120 ; (CH2)
-    "$nothing sub n$"
-    bond 60 ; CH3
-]
-
-########################################################################
-### Emacs settings
-# Local Variables:
-# mode: Nroff
-# End:
-.cend
-.EQ
-delim $$
-.EN

Index: chem/examples/122/chAi_poly_vinyl_chloride.chem
===================================================================
RCS file: chem/examples/122/chAi_poly_vinyl_chloride.chem
diff -N chem/examples/122/chAi_poly_vinyl_chloride.chem
--- chem/examples/122/chAi_poly_vinyl_chloride.chem	5 Jan 2009 20:10:36 -0000	1.5
+++ /dev/null	1 Jan 1970 00:00:00 -0000
@@ -1,143 +0,0 @@
-chAi_poly_vinyl_chloride.chem:
-.br
-.ps -2
-.cstart
-
-# Example file for `chem':
-
-# This originates from Computing Science Technical Report No. 122
-#   CHEM - A Program for Typesetting Chemical Diagrams: User Manual
-#   by Jon L. Bentley, Lynn W. Jelinski, Brian W. Kernighan
-#   <http://cm.bell-labs.com/cm/cs/cstr/122.ps.gz>.
-
-# Copyright (C) 2006, 2009 Free Software Foundation, Inc.
-
-# Last update: 5 Jan 2009
-
-# This file is part of `chem', 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/>.
-
-########################################################################
-
-db = .12
-cwid = .095
-A: [
-      bond dotted
-      bond right ; CH
-      bond down ; Cl
-      bond right from CH ; CH2
-      bond ; CH
-      bond down ; Cl
-      bond right from CH ; CH2
-      bond ; C.
-      bond down ; Cl
-      bond right from C ; CH2
-      bond ; CH2
-      bond down ; Cl
-]
-"     (6.13a)" ljust at A.e
-arrow down .5 from A.s
-[
-      CH2
-      double bond right ; CHCl
-] with .w at last arrow.c
-B: [
-      bond dotted
-      bond right ; CH
-      bond down ; Cl
-      bond right from CH ; CH2
-      bond ; CH
-      bond down ; Cl
-      bond right from CH ; CH2
-      bond ; C
-      bond up ; Cl
-      bond down from C ; CH2
-      bond ; CH2Cl
-      bond right from C ; CH2
-      bond ; CH
-      bond down ; Cl
-      bond right from CH
-      bond dotted
-] with .n at end of last arrow
-"     (6.13b)" ljust at B.e
-C: [
-      bond dotted
-      bond right ; CH
-      bond down ; Cl
-      bond right from CH ; CH2
-      bond ; C.
-      bond down ; Cl
-      bond right from C ; CH2
-      bond ; CH
-      bond down ; Cl
-      bond right from CH ; CH2
-      bond ; CH2
-      bond down ; Cl
-] with .n at B.s - (0,.5)
-"     (6.14a)" ljust at C.e
-arrow down .3 from C.s
-[
-      CH2
-      double bond right
-      CHCl
-] with .w at last arrow.s
-arrow down .3 from last arrow.s
-
-D: [
-      bond dotted
-      bond right ; CH
-      bond down ; Cl
-      bond right from CH ; CH2
-      bond ; C
-      bond up ; Cl
-      bond down from C ; CH2
-      bond ; CHCl
-      bond ; CH2
-      bond ; CH2Cl
-      bond right from C ; CH2
-      bond ; CH
-      bond down ; Cl
-      bond right from CH ; CH2
-      bond ; CH
-      bond down ; Cl
-      bond right from CH
-      bond dotted
-] with .n at last arrow.s
-"     (6.14b)" ljust at D.e
-E: [
-      bond dotted
-      bond ; CH
-      bond down ; Cl
-      bond right from CH ; CH2
-      bond ; CH
-      bond down ; Cl
-      bond right from CH ; CH2
-      bond ; CH
-      bond down ; Cl
-      bond right from CH ; CH2
-      bond ; CH
-      bond down ; Cl
-] with .e at B.w - (.5,0)
-
-arrow from E.ne to A.sw
-arrow from E.se to C.nw
-
-########################################################################
-### Emacs settings
-# Local Variables:
-# mode: Nroff
-# End:
-.cend
-.ps +2

Index: chem/examples/122/chBa_jump.chem
===================================================================
RCS file: chem/examples/122/chBa_jump.chem
diff -N chem/examples/122/chBa_jump.chem
--- chem/examples/122/chBa_jump.chem	5 Jan 2009 20:10:37 -0000	1.4
+++ /dev/null	1 Jan 1970 00:00:00 -0000
@@ -1,43 +0,0 @@
-chBa_jump.chem:
-.br
-.cstart
-
-# Example file for `chem':
-
-# This originates from Computing Science Technical Report No. 122
-#   CHEM - A Program for Typesetting Chemical Diagrams: User Manual
-#   by Jon L. Bentley, Lynn W. Jelinski, Brian W. Kernighan
-#   <http://cm.bell-labs.com/cm/cs/cstr/122.ps.gz>.
-
-# Copyright (C) 2006, 2009 Free Software Foundation, Inc.
-
-# Last update: 5 Jan 2009
-
-# This file is part of `chem', 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/>.
-
-########################################################################
-
-SiO2          # name = SiO2
-move right 1
-CH3CH2NH2.HCl # name = CH3CH2NH2HCl
-
-
-########################################################################
-### Emacs settings
-# Local Variables:
-# mode: Nroff
-# End:
-.cend

Index: chem/examples/122/chBb_bonds.chem
===================================================================
RCS file: chem/examples/122/chBb_bonds.chem
diff -N chem/examples/122/chBb_bonds.chem
--- chem/examples/122/chBb_bonds.chem	5 Jan 2009 20:10:37 -0000	1.4
+++ /dev/null	1 Jan 1970 00:00:00 -0000
@@ -1,44 +0,0 @@
-chBb_bonds.chem:
-.br
-.cstart
-
-# Example file for `chem':
-
-# This originates from Computing Science Technical Report No. 122
-#   CHEM - A Program for Typesetting Chemical Diagrams: User Manual
-#   by Jon L. Bentley, Lynn W. Jelinski, Brian W. Kernighan
-#   <http://cm.bell-labs.com/cm/cs/cstr/122.ps.gz>.
-
-# Copyright (C) 2006, 2009 Free Software Foundation, Inc.
-
-# Last update: 5 Jan 2009
-
-# This file is part of `chem', 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/>.
-
-########################################################################
-
-C
-frontbond -170 from C ; H
-backbond 10 from C ; CO2H
-bond left length .15 from C ; H2N
-bond right from C ; CH3
-
-########################################################################
-### Emacs settings
-# Local Variables:
-# mode: Nroff
-# End:
-.cend

Index: chem/examples/122/chBc_rings.chem
===================================================================
RCS file: chem/examples/122/chBc_rings.chem
diff -N chem/examples/122/chBc_rings.chem
--- chem/examples/122/chBc_rings.chem	5 Jan 2009 20:10:37 -0000	1.4
+++ /dev/null	1 Jan 1970 00:00:00 -0000
@@ -1,45 +0,0 @@
-chBc_rings.chem:
-.br
-.cstart
-
-# Example file for `chem':
-
-# This originates from Computing Science Technical Report No. 122
-#   CHEM - A Program for Typesetting Chemical Diagrams: User Manual
-#   by Jon L. Bentley, Lynn W. Jelinski, Brian W. Kernighan
-#   <http://cm.bell-labs.com/cm/cs/cstr/122.ps.gz>.
-
-# Copyright (C) 2006, 2009 Free Software Foundation, Inc.
-
-# Last update: 5 Jan 2009
-
-# This file is part of `chem', 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/>.
-
-########################################################################
-
-R1: benzene
-    bond -120 from R1.V5 ; CH3O
-R2: ring4 pointing 45 with .V4 at R1.V2
-R3: aromatic ring6 put N at 4 put S at 2 at R2 + (.75,0)
-R4: ring5 pointing left at R3 + (.75,0)
-    label R4
-
-########################################################################
-### Emacs settings
-# Local Variables:
-# mode: Nroff
-# End:
-.cend

Index: glilypond/ChangeLog
===================================================================
RCS file: glilypond/ChangeLog
diff -N glilypond/ChangeLog
--- glilypond/ChangeLog	13 May 2013 20:08:23 -0000	1.12
+++ /dev/null	1 Jan 1970 00:00:00 -0000
@@ -1,141 +0,0 @@
-2013-05-10  Bernd Warken  <groff-bernd.warken-72@web.de>
-
-	* glilypond.pl: Correct position information.  Add debug code.
-
-	* args.pl, oop_fh.pl, subs.pl: Correct position information.
-
-2013-04-25  Bernd Warken  <groff-bernd.warken-72@web.de>
-
-	* Makefile.sub: minor corrections.
-
-2013-04-24  Bernd Warken  <groff-bernd.warken-72@web.de>
-
-	Public `glilypond' version `v1.1'.
-
-	* args.pl, sub.pl, glilypond.man: Change option `-v' to mean
-	`--verbose' instead of former `--version' such as many GNU
-	programs do.  Correct sub `&usage()' and man-page.
-
-	* args.pl, glilypond.pl, oop_fh.pl, subs.pl: Remove spaces in
-	` -> ', some `( ... )', and some `{ ... }' places for better
-	readability of the Perl source code.
-
-2013-04-24  Bernd Warken  <groff-bernd.warken-72@web.de>
-
-	* args.pl, oop_fh.pl: Remove 1st line calling `perl'.
-
-	* subs.pl: Remove 1st line calling `perl'.  Remove sub
-	`&perl_version()'.  Adjust sub `&usage()'.
-
-	* glilypond.pl: Keep 1st line, which will be reset by running
-	`make'.  Remove all parts of Perl testing.
-
-	* perl_test.pl: Remove this file.
-
-	* README.txt: Add information about needed Perl version.
-
-	* Makefile.sub: Corrections for removing Perl test.  Use `$<'.
-
-2013-04-24  Bernd Warken  <groff-bernd.warken-72@web.de>
-
-	* Makefile.sub: Remove Perl test.
-
-2013-04-12  Bernd Warken  <groff-bernd.warken-72@web.de>
-
-	* glilypond.pl: Fix END for early exit of `--version'.
-
-2013-04-12  Bernd Warken  <groff-bernd.warken-72@web.de>
-
-	* subs.pl: Replace `state' by global variable.  So the Perl
-	version can be older.
-
-	* perl_test.pl: Replace the Perl version by `v5.6', analogously to
-	`groffer'.
-
-2013-04-11  Bernd Warken  <groff-bernd.warken-72@web.de>
-
-	* Makefile.sub: Corrections for Emacs.
-
-2013-04-11  Bernd Warken  <groff-bernd.warken-72@web.de>
-
-	* old groff_lilypond: There is now a free `git' package containing
-	all old versions of the former name `groff_lilypond v0.*'.  They
-	work with `lilypond' parts in `roff' files, but were not
-	installed.  This package can be got at:
-
-	$ git clone git@github.com:RUNOFF/groff_lilypond.git
-
-	The new versions `glilypond 1.*' are not included there.
-
-2013-03-29  Bernd Warken  <groff-bernd.warken-72@web.de>
-
-	Published version is `v1.0'.
-
-	Run `autoconf' again.
-
-2013-03-29  Bernd Warken  <groff-bernd.warken-72@web.de>
-
-	* <groff_src_dir>/m4/groff.m4, <groff_src_dir>/configure.ac: Add
-	libdir information for `glilypond'.
-
-	* <groff_src_dir>/Makefile.in: Add
-	`<groff_src_dir>/contrib/glilypond'.
-
-	Run `autoconf'.
-
-	`glilypond' can now be installed to the system.
-
-2013-03-29  Bernd Warken  <groff-bernd.warken-72@web.de>
-
-	Rename `groff_lilypond' to `glilypond'.  So remove the former
-	source directory `<groff_src_dir>/contrib/lilypond' and newly
-	install `<groff_src_dir>/contrib/glilypond', which now has many
-	files.  The new version starts at `v1.0'.
-
-	Version will now be v1.*.  All former files of versions v0.*
-	vanished or were renamed.  This is not yet an information about
-	publishing.
-
-	* ChangeLog.0x: old `ChangeLog' file for the old `groff_lilypond'
-	versions v0.*.  In the future, this file won't be changed any
-	more.
-
-	* ChangeLog: New file.  It is this file.  It displays the history
-	of `glilypond' versions v1.* or later.
-
-	* glilypond.pl: New main Perl file written from
-	`groff_lilypond.pl' in a totally different way.  It is split now
-	into 4 Perl files.
-
-	* args.pl: New Perl file.  It handles the command line options for
-	a run of `glilypond.pl'.
-
-	* oop_fh.pl: New Perl file.  OOP handling of file handles.
-
-	* perl_test.pl: Test whether the actual Perl program has a
-	suitable versions.  For `Makefile.sub' and `glilypond.pl'.
-
-	* subs.pl: New Perl file.  Defines the global subs for
-	`glilypond.pl'.
-
-	* Makefile.sub: Newly written `Makefile' for this subdirectory of
-	`groff'.  `glilypond' should be able to be installed by `make'
-	with this file.
-
-	* glilypond.man: Newly written man-page for `glilypond'.
-
-	* README.txt: New file about the installation.
-
-########################################################################
-
-Copyright 2013
-  Free Software Foundation, Inc.
-
-Copying and distribution of this file, with or without modification,
-are permitted in any medium without royalty provided the copyright
-notice and this notice are preserved.
-
-Local Variables:
-version-control: never
-coding: utf-8
-End:

Index: glilypond/ChangeLog.0x
===================================================================
RCS file: glilypond/ChangeLog.0x
diff -N glilypond/ChangeLog.0x
--- glilypond/ChangeLog.0x	10 Apr 2013 23:36:06 -0000	1.3
+++ /dev/null	1 Jan 1970 00:00:00 -0000
@@ -1,103 +0,0 @@
-2013-04-11  Bernd Warken  <groff-bernd.warken-72@web.de>
-
-	* old groff_lilypond: There is now a free `git' package containing
-	all old versions of the former name `groff_lilypond v0.*'.  They
-	work with `lilypond' parts in `roff' files, but were not
-	installed.  This package can be got at:
-
-	$ git clone git@github.com:RUNOFF/groff_lilypond.git
-
-	The new versions `glilypond 1.*' are not included there.
-
-2013-03-28  Bernd Warken  <groff-bernd.warken-72@web.de>
-
-	Rename `groff_lilypond' to `glilypond' for *.pl and *.man files.
-	Split the single Perl script into several minor *.pl files.
-	Construct `Makefile.sub' in order to have installed `glilypond'.
-	Public versions will be v1.x.
-	Rename `ChangeLog' to `ChangeLog.0x' for the old versions of
-	`groff_lilypond' v0.*.  New `ChangeLog' for the new versions
-	`glilypond' 1.*.
-
-	* groff_lilypond.pl: Vanished.  Renamed to `glilypond.pl'.
-	* groff_lilypond.man: Vanished.  Renamed to `glilypond.man'.
-	* ChangeLog.0x: Moved from `ChangeLog'.  It is this file.  It
-	describes only the old `groff_lilypond' versions v0.*.  See file
-	`ChangeLog' for the files of the new `glilypond' v1.*.
-
-2013-03-11  Bernd Warken  <groff-bernd.warken-72@web.de>
-
-	* groff_lilypond.pl: Publishing groff_lilypond version v0.6.
-	New options: -e|--eps_dir, -l|--license, -k|--keep_files,
-	-p|--prefix=..., -t|--temp_dir=...
-	Install --eps_dir as directory for the useful EPS files.
-	* groff_lilypond.man: Include the new options.  Add section
-	SEE ALSO.
-
-2013-03-03  Bernd Warken  <groff-bernd.warken-72@web.de>
-
-	* groff_lilypond.pl: New code with Perl references.
-	Publishing groff_lilypond version v0.5.
-	New options: --usage, -V|--Verbose|--verbose, --file_prefix=...,
-	-o|--output=..., --temp_dir=...
-	Perl >=5.10.0 needed.
-	* groff_lilypond.man: Include the new options.
-
-2013-02-23  Bernd Warken  <groff-bernd.warken-72@web.de>
-
-	* groff_lilypond_pl: Remove `.lilypond include' for lilypond
-	regions.  Within `groff' mode. it is still allowed.
-	* groff_lilypond.man: Update `.lilypond include'.
-
-2013-02-23  Bernd Warken  <groff-bernd.warken-72@web.de>
-
-	New version v0.4 of groff_lilypond.
-	* groff_lilypond_pl: Major rewrite.
-	New options: --file_prefix, --temp_dir, and --license. 
-	* groff_lilypond.man: documents the new features.
-
-2013-02-16  Bernd Warken  <groff-bernd.warken-72@web.de>
-
-	* groff_lilypond.man: Minor corrections.
-
-2013-02-12  Bernd Warken  <groff-bernd.warken-72@web.de>
-
-	* groff_lilypond.pl: Add deletion of unused temporary files.
-
-2013-02-12  Bernd Warken  <groff-bernd.warken-72@web.de>
-
-	* contrib/lilypond: Version v0.3 for groff_lilypond
-	* groff_lilypond.pl: A new request was added for importing
-	lilypond files:
-	.lilypond include ...
-	The argument handling was improved.
-
-2013-02-11  Bernd Warken  <groff-bernd.warken-72@web.de>
-
-	* contrib/lilypond: Version v0.2 for groff_lilypond
-	* groff_lilypond.pl: Now there are 2 modes for generationg the EPS
-	files: --ly2eps (the default) and --pdf2eps (that's the old mode
-	from version v0.1 with pdf to ps to eps).  With ly2eps mode,
-	lilypond generates the EPS files itself, for each page one EPS
-	file.
-	* groff_lilypond.man: Corresponding updated man-page
-
-2013-02-10  Bernd Warken  <groff-bernd.warken-72@web.de>
-
-	* contrib/lilypond: New files for adding lilypond parts into groff
-	files.  These files will not yet be installed.
-	* groff_lilypond.pl: Program written in Perl, version v0.1
-	* groff_lilypond.man: Corresponding man-page
-
-Copyright 2013
-  Free Software Foundation, Inc.
-
-Copying and distribution of this file, with or without modification,
-are permitted in any medium without royalty provided the copyright
-notice and this notice are preserved.
-
-Local Variables:
-version-control: never
-mode: change-log-mode
-coding: utf-8
-End:

Index: glilypond/Makefile.sub
===================================================================
RCS file: glilypond/Makefile.sub
diff -N glilypond/Makefile.sub
--- glilypond/Makefile.sub	30 Apr 2013 00:40:39 -0000	1.6
+++ /dev/null	1 Jan 1970 00:00:00 -0000
@@ -1,86 +0,0 @@
-# Makefile.sub for `glilypond' (integration into the `groff' source tree)
-
-# File position: <groff-source>/contrib/lilypond/Makefile.sub
-
-# Copyright (C) 2013
-#   Free Software Foundation, Inc.
-# Written by Werner Lemberg <wl@gnu.org> and
-# Bernd Warken <groff-bernd.warken-72@web.de>.
-
-# Last update: 25 Apr 2013
-
-# This file is part of `glilypond' 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/>.
-
-########################################################################
-
-MAN1=glilypond.n
-
-MOSTLYCLEANADD=glilypond $(MAN1)
-
-# not all make programs have $(RM) predefined.
-RM=rm -f
-
-all: glilypond
-
-
-# files going to lib directory `$(glilypond_dir)'
-
-GLILYPOND_LIB=$(srcdir)/subs.pl \
-	$(srcdir)/oop_fh.pl \
-	$(srcdir)/args.pl
-
-GLILYPOND_LIB_=`echo $(GLILYPOND_LIB) | sed 's|$(srcdir)/||g'`
-
-
-# create perl executable `glilypond', being stored into `bindir'
-
-glilypond: $(srcdir)/glilypond.pl
-	sed -f "$(SH_DEPS_SED_SCRIPT)" \
-		-e "s|@g@|$(g)|g" \
-		-e "s|@BINDIR@|$(DESTDIR)$(bindir)|g" \
-		-e "s|@glilypond_dir@|$(DESTDIR)$(glilypond_dir)|g" \
-		-e "s|@VERSION@|$(version)$(revision)|g" \
-		$(srcdir)/glilypond.pl >$@
-	chmod +x $@
-
-
-install_data: glilypond $(GLILYPOND_LIB)
-	-test -d $(DESTDIR)$(bindir) \
-		|| $(mkinstalldirs) $(DESTDIR)$(bindir)
-	$(RM) $(DESTDIR)$(bindir)/$<
-	$(INSTALL_SCRIPT) glilypond $(DESTDIR)$(bindir)/$<
-	-test -d $(DESTDIR)$(glilypond_dir) \
-		|| $(mkinstalldirs) $(DESTDIR)$(glilypond_dir)
-	for f in $(GLILYPOND_); do \
-		$(RM) $(DESTDIR)$(glilypond_dir)/$$f; \
-		$(INSTALL_SCRIPT) $(srcdir)/$$f $(DESTDIR)$(glilypond_dir)/$$f; \
-	done
-
-
-uninstall_sub:
-	$(RM) $(DESTDIR)$(bindir)/glilypond;
-	for f in $(GLILYPOND_); do \
-		$(RM) $(DESTDIR)$(glilypond_dir)/$$f; \
-	done
-	-rmdir $(DESTDIR)$(glilypond_dir)
-
-########################################################################
-# Emacs settings
-########################################################################
-#
-# Local Variables:
-# mode: makefile
-# End:

Index: glilypond/README.txt
===================================================================
RCS file: glilypond/README.txt
diff -N glilypond/README.txt
--- glilypond/README.txt	24 Apr 2013 21:23:38 -0000	1.2
+++ /dev/null	1 Jan 1970 00:00:00 -0000
@@ -1,39 +0,0 @@
-    Copyright (C) 2013
-      Free Software Foundation, Inc.
-
-    Written by Bernd Warken <groff-bernd.warken-72@web.de>
-
-    Last update: 24 Apr 2013
-
-    Copying and distribution of this file, with or without modification,
-    are permitted in any medium without royalty provided the copyright
-    notice and this notice are preserved.
-
-    This file is part of `glilypond', which is part of `groff'.
-
-
-########################################################################
-
-In order to run `glilypond', your system must have installed Perl of at
-least version `v5.6'.
-
-
-########################################################################
-
-In order to have this program installed by `make', the creation of a
-libdir (library directory) must be programmed in some system files.
-The following actions must be taken:
-
-1) <groff_src_dir>/m4/groff.m4:
-Add `AC_DEFUN([GROFF_GROFFERDIR_DEFAULT])'.
-
-2) <groff_src_dir>/configure.ac:
-Add `GROFF_GROFFERDIR_DEFAULT'.
-
-3) <groff_src_dir>/Makefile.in:
-Add several informations of `glilypond_dir'
-
-With that, the program `autoconf' can be run in order to update the
-configure files and Makefile's.
-
-Now `$glilypond_dir' can be used as libdir.

Index: glilypond/args.pl
===================================================================
RCS file: glilypond/args.pl
diff -N glilypond/args.pl
--- glilypond/args.pl	13 May 2013 20:08:23 -0000	1.4
+++ /dev/null	1 Jan 1970 00:00:00 -0000
@@ -1,504 +0,0 @@
-########################################################################
-# Legalese
-########################################################################
-
-my $License = q*
-groff_lilypond - integrate `lilypond' into `groff' files
-
-Source file position: `<groff-source>/contrib/glilypond/args.pl'
-Installed position: `<prefix>/lib/groff/glilypond'
-
-Copyright (C) 2013 Free Software Foundation, Inc.
-  Written by Bernd Warken <groff-bernd.warken-72@web.de>
-
-Last update: 10 May 2013
-
-This file is part of `GNU groff'.
-
-  `GNU 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.
-
-  `GNU 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 package.  If not, see
-<http://www.gnu.org/licenses/>.
-*;
-
-##### end legalese
-
-
-# use strict;
-# use warnings;
-# use diagnostics;
-
-use integer;
-
-our ( $Globals, $Args, $stderr, $v, $out );
-
-# ----------
-# subs for second run, for remaining long options after splitting and
-# transfer
-# ----------
-
-my %opts_with_arg =
-  (
-
-   '--eps_dir' => sub {
-     $Args->{'eps_dir'} = shift;
-   },
-
-   '--output' => sub {
-     $Args->{'output'} = shift;
-   },
-
-   '--prefix' => sub {
-     $Args->{'prefix'} = shift;
-   },
-
-   '--temp_dir' => sub {
-     $Args->{'temp_dir'} = shift;
-   },
-
-  );				# end of %opts_with_arg
-
-
-my %opts_noarg =
-  (
-
-   '--help' => sub {
-     &usage;
-     exit;
-   },
-
-   '--keep_all' => sub {
-     $Args->{'keep_all'} = TRUE;
-   },
-
-   '--license' => sub {
-     &license;
-     exit;
-   },
-
-   '--ly2eps' => sub {
-     $Args->{'eps_func'} = 'ly';
-   },
-
-   '--pdf2eps' => sub {
-     $Args->{'eps_func'} = 'pdf';
-   },
-
-   '--verbose' => sub {
-     $Args->{'verbose'} = TRUE;
-   },
-
-   '--version' => sub {
-     &version;
-     exit;
-   },
-
-  );				# end of %opts_noarg
-
-
-# used variables in both runs
-
-my @files = EMPTYARRAY;
-
-
-#----------
-# first run for command line arguments
-#----------
-
-# global variables for first run
-
-my @splitted_args;
-my $double_minus = FALSE;
-my $arg = EMPTYSTRING;
-my $has_arg = FALSE;
-
-
-# Split short option collections and transfer these to suitable long
-# options from above.  Note that `-v' now means `--verbose' in version
-# `v1.1', earlier versions had `--version' for `-v'.
-
-my %short_opts =
-  (
-   '?' => '--help',
-   'e' => '--eps_dir',
-   'h' => '--help',
-   'l' => '--license',
-   'k' => '--keep_all',
-   'o' => '--output',
-   'p' => '--prefix',
-   't' => '--temp_dir',
-   'v' => '--verbose',
-   'V' => '--verbose',
-  );
-
-
-# transfer long option abbreviations to the long options from above
-
-my @long_opts;
-
-$long_opts[3] =
-  {				# option abbreviations of 3 characters
-   '--e' => '--eps_dir',
-   '--f' => '--prefix',		# --f for --file_prefix
-   '--h' => '--help',
-   '--k' => '--keep_all',	# and --keep_files
-   '--o' => '--output',
-   '--p' => '--prefix',		# and --file_prefix
-   '--t' => '--temp_dir',
-   '--u' => '--help',		# '--usage' is mapped to `--help'
-  };
-
-$long_opts[4] =
-  {				# option abbreviations of 4 characters
-   '--li' => '--license',
-   '--ly' => '--ly2eps',
-   '--pd' => '--pdf2eps',
-   '--pr' => '--prefix',
-  };
-
-$long_opts[6] =
-  {				# option abbreviations of 6 characters
-   '--verb' => '--verbose',
-   '--vers' => '--version',
-  };
-
-
-# subs for short splitting and replacing long abbreviations
-
-my $split_short = sub {
-
-  my @chars = split //, $1;	# omit leading dash
-
-     # if result is TRUE: run `next SPLIT' afterwards
-
-   CHARS: while ( @chars ) {
-       my $c = shift @chars;
-
-       unless ( exists $short_opts{$c} ) {
-	 $stderr->print( "Unknown short option `-$c'." );
-	 next CHARS;
-       }
-
-       # short option exists
-
-       # map or transfer to special long option from above
-       my $transopt = $short_opts{$c};
-
-       if ( exists $opts_noarg{$transopt} ) {
-	 push @splitted_args, $transopt;
-	 $Args->{'verbose'}  = TRUE if ( $transopt eq '--verbose' );
-	 next CHARS;
-       }
-
-       if ( exists $opts_with_arg{$transopt} ) {
-	 push @splitted_args, $transopt;
-
-	 if ( @chars ) {
-	   # if @chars is not empty, option $transopt has argument
-	   # in this arg, the rest of characters in @chars
-	   push @splitted_args, join "", @chars;
-	   @chars = EMPTYARRAY;
-	   return TRUE;		# use `next SPLIT' afterwards
-	 }
-
-	 # optarg is the next argument
-	 $has_arg = $transopt;
-	 return TRUE;		# use `next SPLIT' afterwards
-       }			# end of if %opts_with_arg
-     }				# end of while CHARS
-     return FALSE;		# do not do anything
-};				# end of sub for short_opt_collection
-
-
-my $split_long = sub {
-  my $from_arg = shift;
-  $from_arg =~ /^([^=]+)/;
-  my $opt_part = lc($1);
-  my $optarg = undef;
-  if ( $from_arg =~ /=(.*)$/ ) {
-    $optarg = $1;
-  }
-
- N: for my $n ( qw/6 4 3/ ) {
-    $opt_part =~ / # match $n characters
-		   ^
-		   (
-		     .{$n}
-		   )
-		 /x;
-    my $argn = $1;		# get the first $n characters
-
-    # no match, so luck for fewer number of chars
-    next N unless ( $argn );
-
-    next N unless ( exists $long_opts[$n]->{$argn} );
-    # not in $n hash, so go on to next loop for $n
-
-    # now $n-hash has arg
-
-    # map or transfer to special long opt from above
-    my $transopt = $long_opts[$n]->{$argn};
-
-    # test on option without arg
-    if ( exists $opts_noarg{$transopt} ) { # opt has no arg
-      $stderr->print( 'Option ' . $transopt . 'has no argument: ' .
-		      $from_arg . '.' ) if ( defined($optarg) );
-      push @splitted_args, $transopt;
-      $Args->{'verbose'} = TRUE if ( $transopt eq '--verbose' );
-      return TRUE;		# use `next SPLIT' afterwards
-    }				# end of if %opts_noarg
-
-    # test on option with arg
-    if ( exists $opts_with_arg{$transopt} ) { # opt has arg
-      push @splitted_args, $transopt;
-
-      # test on optarg in arg
-      if ( defined($optarg) ) {
-	push @splitted_args, $1;
-	return TRUE; # use `next SPLIT' afterwards
-      } # end of if optarg in arg
-
-      # has optarg in next arg
-      $has_arg = $transopt;
-      return TRUE; # use `next SPLIT' afterwards
-    } # end of if %opts_with_arg
-
-    # not with and without option, so is not permitted
-    $stderr->print( "`" . $transopt .
-		    "' is unknown long option from `" . $from_arg . "'" );
-    return TRUE; # use `next SPLIT' afterwards
-  } # end of for N
-  return FALSE; # do nothing
-}; # end of split_long()
-
-
-#----------
-# do split and transfer arguments
-#----------
-sub run_first {
-
- SPLIT: foreach (@ARGV) {
-    # Transform long and short options into some given long options.
-    # Split long opts with arg into 2 args (no `=').
-    # Transform short option collections into given long options.
-    chomp;
-
-    if ( $has_arg ) {
-      push @splitted_args, $_;
-      $has_arg = EMPTYSTRING;
-      next SPLIT;
-    }
-
-    if ( $double_minus ) {
-      push @files, $_;
-      next SPLIT;
-    }
-
-    if ( $_ eq '-' ) {		# file arg `-'
-      push @files, $_;
-      next SPLIT;
-    }
-
-    if ( $_ eq '--' ) {		# POSIX arg `--'
-      push @splitted_args, $_;
-      $double_minus = TRUE;
-      next SPLIT;
-    }
-
-    if ( / # short option or collection of short options
-	   ^
-	   -
-	   (
-	     [^-]
-	     .*
-	   )
-	   $
-	 /x ) {
-      $split_short->($1);
-      next SPLIT;
-    }				# end of short option
-
-    if ( /^--/ ) {		# starts with 2 dashes, a long option
-      $split_long->($_);
-      next SPLIT;
-    }				# end of long option
-
-    # unknown option without leading dash is a file name
-    push @files, $_;
-    next SPLIT;
-  }				# end of foreach SPLIT
-
-				# all args are considered
-  $stderr->print( "Option `$has_arg' needs an argument." )
-    if ( $has_arg );
-
-
-  push @files, '-' unless ( @files );
-  @ARGV = @splitted_args;
-
-};		    # end of first run, splitting with map or transfer
-
-
-#----------
-# open or ignore verbose output
-#----------
-sub install_verbose {
-  if ( $Args->{'verbose'} ) { # `--verbose' was used
-    # make verbose output into $v
-    my $s = $v->get(); # get content of string so far as array ref, close
-
-    $v = new FH_STDERR(); # make verbose output into STDERR
-    if ( $s ) {
-      for ( @$s ) {
-	# print the file content into new verbose output
-	$v->print($_);
-      }
-    }
-    # verbose output is now active (into STDERR)
-    $v->print( "Option `-v' means `--verbose'." );
-    $v->print( "Version information is printed by option `--version'." );
-    $v->print( "#" x 72 );
-
-  } else { # `--verbose' was not used
-    # do not be verbose, make verbose invisible
-
-    $v->close(); # close and ignore the string content
-
-    $v = new FH_NULL();
-    # this is either into /dev/null or in an ignored string
-
-  } # end if-else about verbose
-  # `$v->print' works now in any case
-
-  $v->print( "Verbose output was chosen." );
-
-  my $s = $Globals->{'prog_is_installed'} ? '' : ' not';
-  $v->print( $Globals->{'prog'} . " is" . $s .
-	     " installed." );
-
-  $v->print( 'The command line options are:' );
-
-  $s = "  options:";
-  $s .= " `" . $_ . "'" for ( @ARGV );
-  $v->print( $s );
-
-  $s = "  file names:";
-  $s .= " `" . $_ . "'\n" for ( @files );
-  $v->print( $s );
-} # end install_verbose()
-
-
-#----------
-# second run of command line arguments
-#----------
-sub run_second {
-    # Second run of args with new @ARGV from the former splitting.
-    # Arguments are now splitted and transformed into special long options.
-
-    my $double_minus = FALSE;
-    my $has_arg = FALSE;
-
-  ARGS: for my $arg ( @ARGV ) {
-
-      # ignore `--', file names are handled later on
-      last ARGS if ( $arg eq '--' );
-
-      if ( $has_arg ) {
-	unless ( exists $opts_with_arg{$has_arg} ) {
-	  $stderr->print( "`\%opts_with_args' does not have key `" .
-			    $has_arg . "'." );
-	  next ARGS;
-	}
-
-	$opts_with_arg{$has_arg}->($arg);
-	$has_arg = FALSE;
-	next ARGS;
-      } # end of $has_arg
-
-      if ( exists $opts_with_arg{$arg} ) {
-	$has_arg = $arg;
-	next ARGS;
-      }
-
-      if ( exists $opts_noarg{$arg} ) {
-	$opts_noarg{$arg}->();
-	next ARGS;
-      }
-
-      # not a suitable option
-      $stderr->print( "Wrong option `" . $arg . "'." );
-      next ARGS;
-
-    } # end of for ARGS:
-
-
-    if ( $has_arg ) { # after last argument
-      die "Option `$has_arg' needs an argument.";
-    }
-
-  }; # end of second run
-
-
-sub handle_args {
-  # handling the output of args
-
-  if ( $Args->{'output'} ) { # `--output' was set in the arguments
-    my $out_path = &path2abs($Args->{'output'});
-    die "Output file name $Args->{'output'} cannot be used."
-      unless ( $out_path );
-
-    my ( $file, $dir );
-    ( $file, $dir ) = File::Basename::fileparse($out_path)
-      or die "Could not handle output file path `" . $out_path . "': " .
-	"directory name `" . $dir . "' and file name `" . $file . "'.";
-
-    die "Could not find output directory for `" . $Args->{'output'} . "'"
-      unless ( $dir );
-    die "Could not find output file: `" . $Args->{'output'} .
-      "'" unless ( $file );
-
-    if ( -d $dir ) {
-      die "Could not write to output directory `" . $dir . "'."
-	unless ( -w $dir );
-    } else {
-      $dir = &make_dir($dir);
-      die "Could not create output directory in: `" . $out_path . "'."
-	unless ( $dir );
-    }
-
-    # now $dir is a writable directory
-
-    if ( -e $out_path ) {
-      die "Could not write to output file `" . $out_path . "'."
-	unless ( -w $out_path );
-    }
-
-    $out = new FH_FILE( $out_path );
-    $v->print( "Output goes to file `" . $out_path . "'." );
-  } else { # `--output' was not set
-    $out = new FH_STDOUT();
-  }
-  # no $out is the right behavior for standard output
-
-#  $Args->{'prefix'} .= '_' . $Args->{'eps_func'} . '2eps';
-
-  @ARGV = @files;
-}
-
-
-1;
-########################################################################
-### Emacs settings
-# Local Variables:
-# mode: CPerl
-# End:

Index: glilypond/glilypond.man
===================================================================
RCS file: glilypond/glilypond.man
diff -N glilypond/glilypond.man
--- glilypond/glilypond.man	25 Apr 2013 00:21:14 -0000	1.2
+++ /dev/null	1 Jan 1970 00:00:00 -0000
@@ -1,916 +0,0 @@
-.TH glilypond @MAN1EXT@ "@MDATE@" "Groff Version @VERSION@"
-.SH NAME
-glilypond \[em] integrate \f[CI]lilypond\f[P] parts into \f[CI]groff\f[]
-.
-.\" This .SH was moved to this place in order to appease `apropos'.
-.
-.\" --------------------------------------------------------------------
-.\" Legalese
-.\" --------------------------------------------------------------------
-.
-.de authors
-This file was written by Bernd Warken
-.MT groff\-bernd.warken\-72@web.de
-.ME .
-.
-Last update: 25 Apr 2013
-..
-.
-.
-.\" The following macro .copying contains the license information for this file.
-.de copying
-.nh
-.nf
-glilypond - integrate lilypond into groff files
-
-Source file position: <groff-source>/contrib/lilypond/glilypond.man
-Installed position: <prefix>/share/man/man1/glilypond.1
-
-Copyright \(co 2013
-          Free Software Foundation, Inc.
-
-This file is part of GNU groff.
-
-GNU 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.
-
-GNU 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 package.
-
-.hy
-.fi
-If not, see the GNU licenses at
-.UR http://www.gnu.org/licenses/
-.UE .
-..
-.
-.
-.\" --------------------------------------------------------------------
-.\" Setup
-.\" --------------------------------------------------------------------
-.
-.ds Ellipsis "\&.\|.\|.\&\"
-.
-.
-.\" --------------------------------------------------------------------
-.\" Macro definitions
-.\" --------------------------------------------------------------------
-.
-.\" --------------------------------------------------------------------
-.\" .FONT (<font name> <text> [<font name> <text> ...])
-.\"
-.\" Print in different fonts: R, I, B, CR, CI, CB
-.\"
-.de1 FONT
-.  if (\\n[.$] = 0) \{\
-.	nop \&\f[P]\&
-.	return
-.  \}
-.  ds result \&
-.  while (\\n[.$] >= 2) \{\
-.	as result \,\f[\\$1]\\$2
-.	if !"\\$1"P" .as result \f[P]
-.	shift 2
-.  \}
-.  if (\\n[.$] = 1) .as result \,\f[\\$1]
-.  nh
-.  nop \\*[result]\&
-.  hy
-..
-.
-.
-.\" --------------------------------------------------------------------
-.\" .OP+ (<option> [ [ | option] ...] [<optarg> [<end>] ])
-.\"
-.\" like .OP, but with 1st arg split and and optional final character
-.\" Example: `.OP+ -p | --prefix ly .' gets `[-t|--prefix ly].'
-.\" Example: `.OP+ -h | --help | --usage' gets `[-h|--help|--usage]'
-.\" Example: `.OP+ -v | --verbose "" ,' gets `[-v|--verbose],'
-.\"
-.de1 OP+
-.  if ( \\n[.$] == 0 ) \{\
-.	nop \&\f[CR][]\fR\&
-.	return
-.  \}
-.  nh
-.  ds result \&\f[CR][\f[CB]\\$1
-.  shift
-.  while (\\n[.$] >= 2) \{\
-.	ie '\\$1'|' .as result \f[CR]|\f[CB]\\$2
-.	el \{\
-.		ie '\\$1'' .as result \f[CR]]\fR\\$2
-.		el .as result \fI\ \\$1\f[CR]]\fR\\$2
-.		nop \\*[result]\&
-.		hy
-.		return
-.	\}
-.	shift 2
-.  \}
-.  as result \fI\ \\$1\f[CR]]\fR
-.  nop \\*[result]\&
-.  hy
-..
-.
-.\" --------------------------------------------------------------------
-.SH "SYNOPSIS"
-.\" --------------------------------------------------------------------
-.
-.SY glilypond
-.OP+ options
-.OP+ -
-.OP+ --
-.OP+ \%filespec \*[Ellipsis]
-.YS
-.
-.
-.\" --------------------------------------------------------------------
-.SH DESCRIPTION
-.\" --------------------------------------------------------------------
-.
-.FONT CB glilypond
-transforms sheet music written in the
-.FONT CI lilypond
-language into the
-.BR groff (@MAN7EXT@)
-language using the
-.FONT CB .PSPIC
-request, such that
-.BR groff (@MAN1EXT@)
-can transform it into a format that can be displayed directly.
-.
-.
-.P
-Files in
-.FONT CI groff
-language and
-.FONT CI "standard input"
-can be provided as arguments.
-.
-.
-.\" --------------------------------------------------------------------
-.SH "OPTION OVERVIEW"
-.\" --------------------------------------------------------------------
-.
-.\" --------------------------------------------------------------------
-.SS "Breaking Options"
-.\" --------------------------------------------------------------------
-.
-.SY
-.OP+ -? | -h | --help | --usage
-.YS
-.SY
-.OP+ --version
-.YS
-.SY
-.OP+ -l | --license
-.YS
-.
-.
-.\" --------------------------------------------------------------------
-.SS "Options for building EPS Files"
-.\" --------------------------------------------------------------------
-.
-.TP
-.OP+ --ly2eps
-Here the
-.FONT CB lilypond
-program creates
-.FONT CI eps
-files directly.
-.
-This is the default.
-.
-.
-.TP
-.OP+ --pdf2eps
-The program
-.FONT CB glilypond
-generates a
-.FONT CI pdf
-file using
-.FONT CB lilypond R .
-.
-Then the
-.FONT CI eps
-file is generated by
-.FONT CB pdf2ps
-and
-.FONT CB ps2eps R .
-.
-.
-.\" --------------------------------------------------------------------
-.SS "Directories and Files"
-.\" --------------------------------------------------------------------
-.
-.TP
-.OP+ -e | --eps_dir directory_name
-Normally all
-.FONT CI EPS
-files are sent to the temporary directory.
-.
-With this option, you can generate your own directory, in which all useful
-.FONT CI EPS
-files are send.
-.
-So at last, the temporary directory can be removed.
-.
-.
-.TP
-.OP+ -p | --prefix begin_of_name
-Normally all temporary files get names that start with the
-.FONT CB ly CI \*[Ellipsis]
-prefix.
-.
-With this option, you can freely change this prefix.
-.
-.
-.TP
-.OP+ -k | --keep_all
-Normally all temporary files without the
-.FONT CI eps
-files are deleted.
-.
-With this opton, all generated files either by the
-.FONT CB lilypond
-program or other format transposers are kept.
-.
-.
-.TP
-.OP+ -t | --temp_dir dir
-With this option, you call a directory that is the base for the
-temporary directory.
-.
-This directory name is used as is without any extensions.
-.
-If this directory does not exist it is be created.
-.
-The temporary directory is created by Perl's security operations
-directly under this directory.
-.
-In this temporary directory, the temporary files are stored.
-.
-.
-.\" --------------------------------------------------------------------
-.SS "Output"
-.\" --------------------------------------------------------------------
-.
-.TP
-.OP+ -o | --output file_name
-Normally all
-.FONT CI groff
-output of this program is sent to
-.FONT CB STDOUT R .
-.
-With this option, that can be changed, such that the output is stored
-into a file named in the option argument
-.IR file_name .
-.
-.
-.TP
-.OP+ -v | -V | --verbose
-A lot more of information is sent to STDERR.
-.
-.
-.\" --------------------------------------------------------------------
-.SS "Short Option Collections"
-.\" --------------------------------------------------------------------
-.
-The argument handling of options 
-.
-.
-.P
-.FONT CI "Short options"
-are arguments that start with a single dash
-.FONT CB \- R .
-.
-Such an argument can consist of arbitrary many options without option
-argument, composed as a collection of option characters following the
-single dash.
-.
-.
-.P
-Such a collection can be terminated by an option character that
-expects an option argument.
-.
-If this option character is not the last character of the argument,
-the follwing final part of the argument is the option argument.
-.
-If it is the last character of the argument, the next argument is
-taken as the option argument. 
-.
-.
-.P
-This is the standard for
-.FONT CI POSIX
-and
-.FONT CI GNU
-option management.
-.
-.
-.P
-For example,
-.
-.TP
-.FONT CB \-kVesome_dir
-is a collection of the short options
-.FONT CB \-k
-and
-.FONT CB \-V
-without option argument, followed by the short option
-.FONT CB \-e
-with option argument that is the following part of the argument
-.FONT CB some_dir R .
-.
-So this argument could also be written as several arguments
-.FONT CB "\-k \-V \-e some_dir" R .
-.
-.
-.\" --------------------------------------------------------------------
-.SS "Handling of Long Options"
-.\" --------------------------------------------------------------------
-.
-Arguments that start with a double dash
-.FONT CB \-\-
-are so-called
-.FONT CI "long options" R .
-.
-Each double dash argument can only have a single long option.
-.
-.
-.P
-.FONT CI "Long options"
-have or have not an option argument.
-.
-An option argument can be the next argument or can be appended with an
-equal sign
-.FONT CB =
-to the same argument as the long option.
-.
-.
-.TP
-.FONT CB \-\-help
-is a long option without an option argument.
-.
-.TP
-.FONT CB "\-\-eps_dir some_dir"
-.TQ
-.FONT CB "\-\-eps_dir=some_dir"
-is the long option
-.FONT CB "\-\-eps_dir
-with the option argument
-.FONT CB some_dir R .
-.
-.
-.P
-Moreover the program allows abbreviations of long options, as much as
-possible.
-.
-.
-.P
-The
-.FONT CI "long option"
-.FONT CB \-\-keep_all
-can be abbreviated from
-.FONT CB \-\-keep_al
-up to
-.FONT CB \-\-k
-because the program does not have another
-.FONT CI "long option"
-whose name starts with the character
-.FONT CB k R .
-.
-.
-.P
-On the other hand, the option
-.FONT CB \-\-version
-cannot be abbreviated further than
-.FONT CB \-\-vers
-because there is also the
-.FONT CI "long option " CB \-\-verbose
-that can be abbreviated up to
-.FONT CB \-\-verb R .
-.
-.
-.P
-An option argument can also be appended to an abbreviation.
-.
-So is
-.FONT CB \-\-e=some_dir
-the same as
-.FONT CB "\-\-eps_dir some_dir" R .
-.
-.
-.P
-Moreover the program allows an arbitrary usage of upper and lower case
-in the option name.
-.
-This is
-.FONT CI Perl
-style.
-.
-.
-.P
-For example, the
-.FONT CI "long option"
-.FONT CB \-\-keep_all
-can as well be written as
-.FONT CB \-\-Keep_All
-or even as an abbreviation like
-.FONT CB \-\-KeE R .
-.
-.
-.\" --------------------------------------------------------------------
-.SH FILESPEC ARGUMENTS
-.\" --------------------------------------------------------------------
-.
-An argument that is not an option or an option argument is called a
-.FONT CI filespec
-argument. 
-.
-.
-.P
-Without any
-.I filespec
-argument,
-.FONT CI "standard input"
-is read.
-.
-.
-.P
-Each
-.I filespec
-argument must either be the name of a readable file or a dash
-.FONT CB -
-for
-.FONT CI "standard input" R .
-.
-Each input must be written in the
-.FONT CI roff
-or
-.FONT CI groff
-language and can include
-.FONT CI lilypond
-parts.
-.
-.
-.P
-Normally arguments starting with a dash
-.FONT CB \-
-are interpreted as an option.
-.
-But if you use an argument that consists only of a doubled dash
-.FONT CB \-\- R ,
-all following arguments are taken as
-.FONT CI filespec
-argument, even if such an argument starts with a dash.
-.
-This is handled according to the
-.FONT CI GNU
-standard.
-.
-.
-.\" --------------------------------------------------------------------
-.SH "THE LILYPOND PARTS IN ROFF INPUT"
-.\" --------------------------------------------------------------------
-.
-.\" --------------------------------------------------------------------
-.SS "Integrated Lilypond Codes"
-.\" --------------------------------------------------------------------
-.
-A
-.FONT CI lilypond
-part within a structure written in the
-.FONT CI groff
-language is the whole part between the marks
-.EX
-.FONT CB ".lilypond start"
-.EE
-and
-.EX
-.FONT CB ".lilypond end"
-.EE
-.
-.
-.P
-A
-.FONT CI groff
-input can have several of these
-.FONT CI lilypond
-parts.
-.
-.
-.P
-When processing such a
-.FONT CI lilypond
-part between
-.FONT CB ".lilypond start"
-and
-.FONT CB ".lilypond end"
-we say that the
-.FONT CB glilypond
-program is in
-.FONT CI "lilypond mode" R .
-.
-.
-.P
-These
-.FONT CI lilypond
-parts are sent into temporary
-.FONT CI lilypond
-files with the file name extension
-.FONT CB .ly R .
-.
-These files are transformed later on into
-.FONT CI EPS
-files.
-.
-.
-.\" --------------------------------------------------------------------
-.SS "Inclusion of ly-Files"
-.\" --------------------------------------------------------------------
-.
-An additional command line for file inclusion of
-.FONT CI lilypond
-files is given by
-.EX
-.FONT CB ".lilypond include" I " file_name"
-.EE
-in
-.FONT CI groff
-input.
-.
-For each such
-.FONT CI include
-command, one file of
-.FONT CI lilypond
-code can be included into the
-.FONT CI groff
-code.
-.
-Arbitrarily many of these commands can be included in the
-.FONT CI groff
-input.
-.
-.
-.P
-These include commands can only be used outside the
-.FONT CI lilypond
-parts.
-.
-Within the
-.FONT CI "lilypond mode" R ,
-this inclusion is not possible.
-.
-So
-.FONT CB ".lilypond include"
-may not be used in
-.FONT CI "lilypond mode" R ,
-i.e. between
-.FONT CB ".lilypond start"
-and
-.FONT CB ".lilypond end" R .
-.
-.
-These included
-.FONT CI ly R -files
-are also transformed into
-.FONT CI EPS
-files.
-.
-.
-.\" --------------------------------------------------------------------
-.SH "GENERATED FILES"
-.\" --------------------------------------------------------------------
-.
-By the transformation process of
-.FONT CI lilypond
-parts into
-.FONT CI EPS
-files, there are many files generated.
-.
-By default, these files are regarded as temporary files and as such
-stored in a temporary directory.
-.
-.
-.P
-This process can be changed by command line options.
-.
-.
-.\" --------------------------------------------------------------------
-.SS "Command Line Options for Directories"
-.\" --------------------------------------------------------------------
-.
-The temporary directory for this program is either created
-automatically or can be named by the option
-.OP+ -t | --temp_dir dir .
-.
-.
-.P
-Moreover, the
-.FONT CI EPS
-files that are later on referred by
-.FONT CB .PSPIC
-command in the final
-.FONT CI groff
-output can be stored in a different directory that can be set by the
-command line option
-.OP+ -e | --eps_dir directory_name .
-.
-With this option, the temporary directory can be removed completely at
-the end of the program.
-.
-.
-.P
-The beginning of the names of the temporary files can be set by the
-command line option
-.OP+ -p | --prefix begin_of_name .
-.
-.
-.P
-All of the temporary files except the
-.FONT CI EPS
-files are deleted finally.
-.
-This can be changed by setting the command line option
-.OP+ -k | --keep_files
-.
-With this, all temporary files and directories are kept, not deleted.
-.
-.
-.P
-These
-.FONT CI EPS
-files are stored in a temporary or
-.FONT CI EPS
-directory.
-.
-But they cannot be deleted by the transformation process because they
-are needed for the display which can take a long time.
-.
-.
-.\" --------------------------------------------------------------------
-.SH "TRANSFORMATION PROCESSES FOR GENERATING EPS FILES"
-.\" --------------------------------------------------------------------
-.
-.\" --------------------------------------------------------------------
-.SS "Mode ly2eps"
-.\" --------------------------------------------------------------------
-.
-This mode is the default.
-.
-It can also be chosen by the option
-.FONT CB --ly2eps R .
-.
-.
-.P
-In this mode, the
-.FONT CB .ly
-files are transformed by the
-.FONT CB lilypond
-program into many files of different formats, including
-.FONT CI eps
-files, using
-.EX
-.FONT CB "$ lilypond \-\-ps \-dbackend=eps \-dgs\-load\-fonts \-\-output=" I file\-name
-.EE
-for each
-.FONT CB .ly
-file.
-.
-The output
-.I file\-name
-must be provided without an extension, its directory is temporary..
-.
-.
-.P
-There are many
-.FONT CI EPS
-files created.
-.
-One having the complete transformed
-.FONT CB ly
-file, named
-.FONT I file\-name CB .eps R .
-.
-.
-.P
-Moreover there are
-.FONT CI EPS
-files for each page, named
-.FONT I file\-name CB \- I digit CB .eps R .
-.
-.
-.P
-The last step to be done is replacing all
-.FONT CI lilypond
-parts by the collection of the corresponding
-.FONT CI EPS
-page files.
-.
-This is done by
-.FONT CI groff
-commands
-.EX
-.FONT CB ".PSPIC " CI file-name CB \- I digit CB .eps 
-.EE
-.
-.
-.\" --------------------------------------------------------------------
-.SS "Mode pdf2eps"
-.\" --------------------------------------------------------------------
-.
-This mode can be chosen by the option
-.FONT CB --pdf2eps R .
-.
-.
-.P
-In this mode, the
-.FONT CB .ly
-files are transformed by the
-.BR lilypond (1)
-program into
-.FONT CI pdf
-files, using
-.EX
-.FONT CB "lilypond \-\-pdf \-\-output=" I file-name
-.EE
-for each
-.FONT CB .ly
-file.
-.
-The
-.I file-name
-must be provided without the extension
-.FONT CB .pdf R .
-.
-By this process, a file
-.FONT CI file-name CB .pdf
-is generated.
-.
-.
-.P
-The next step is to transform these
-.FONT CI PDF
-files into a
-.FONT CI PS
-file.
-.
-This is done by the
-.BR pdf2ps (1)
-program using
-.EX
-.FONT R "$ " CB "pdf2ps " CI file-name CB ".pdf " CI file-name CB ".ps"
-.EE
-.
-.
-The next step creates an
-.FONT CI EPS
-file from the
-.FONT CI PS
-file.
-.
-This is done by the
-.BR ps2eps (1)
-program using
-.EX
-.FONT R "$ " CB "ps2eps " CI file-name CB ".ps"
-.EE
-.
-.
-.P
-By that, a file
-.FONT CI file-name CB .eps
-is created for each
-.FONT CI lilypond
-part in the
-.FONT CI groff
-file or standard input.
-.
-.
-.P
-The last step to be done is replacing all
-.FONT CI lilypond
-parts by the
-.FONT CI groff
-command
-.EX
-.FONT CB ".PSPIC " CI file-name CB .eps 
-.EE
-.
-.
-.\" --------------------------------------------------------------------
-.SH "THE GENERATED NEW ROFF STRUCTURE"
-.\" --------------------------------------------------------------------
-.
-The new
-.BR groff (@MAN7EXT@)
-structure generated by
-.FONT CB glilypond
-is either
-.
-.TP
-1)
-sent to standard output and can there be saved into a file or piped into
-.BR groff (@MAN1EXT@)
-or
-.BR groffer (@MAN1EXT@)
-or
-.
-.TP
-2)
-stored into a file by given the option
-.OP -o\fR|\fB\~--output file_name
-.
-.
-.\" --------------------------------------------------------------------
-.SH "SEE ALSO"
-.\" --------------------------------------------------------------------
-.
-.TP
-.BR groff (@MAN1EXT@)
-the usage of the groff program and pointers to the documentation and
-availability of the
-.FONT CI groff
-system.
-.
-The main source of information for the
-.FONT CI groff
-szstem is the
-.FONT CB groff
-.BR info (1)
-file.
-.
-.
-.TP
-.BR groff (@MAN7EXT@)
-documents the
-.FONT CI groff
-language.
-.
-.
-.TP
-.BR groff_tmac (@MAN5EXT@)
-contains documentation of the
-.FONT CB .PSPIC
-request.
-.
-.
-.TP
-.BR lilypond (1)
-The documentation of the
-.FONT CB lilypond
-program.
-.
-The main source of information for the
-.FONT CI lilypond
-language is the
-.FONT CB lilypond
-.BR info (1)
-file.
-.
-.
-.TP
-.BR pdf2ps (1)
-transform a
-.FONT CI PDF
-file into a
-.FONT CI Postscript
-format.
-.
-.
-.TP
-.BR ps2eps (1)
-transform a
-.FONT CI PS
-file into an
-.FONT CI EPS
-format.
-.
-.
-.\" --------------------------------------------------------------------
-.SH "AUTHORS"
-.\" --------------------------------------------------------------------
-.authors
-.
-.
-.\" --------------------------------------------------------------------
-.SH "COPYING"
-.\" --------------------------------------------------------------------
-.copying
-.
-.
-.\" --------------------------------------------------------------------
-.\" Emacs settings
-.\" --------------------------------------------------------------------
-.
-.\" Local Variables:
-.\" mode: nroff
-.\" End:

Index: glilypond/glilypond.pl
===================================================================
RCS file: glilypond/glilypond.pl
diff -N glilypond/glilypond.pl
--- glilypond/glilypond.pl	13 May 2013 20:08:23 -0000	1.7
+++ /dev/null	1 Jan 1970 00:00:00 -0000
@@ -1,763 +0,0 @@
-#! /usr/bin/env perl
-
-package main;
-
-########################################################################
-# debugging
-########################################################################
-
-# See `Mastering Perl', chapter 4.
-
-# use strict;
-# use warnings;
-# use diagnostics;
-
-use Carp;
-$SIG[__DIE__] = sub { &Carp::croak; };
-
-use Data::Dumper;
-
-########################################################################
-# Legalese
-########################################################################
-
-our $Legalese;
-
-{
-  use constant VERSION => 'v1.1'; # version of glilypond
-  use constant LASTUPDATE => '10 May 2013'; # date of last update
-
-### This constant `LICENSE' is the license for this file `GPL' >= 3
-  use constant LICENSE => q*
-glilypond - integrate `lilypond' into `groff' files
-
-Source file position: `<groff-source>/contrib/glilypond/glilypond.pl'
-Installed position: `<prefix>/bin/glilypond'
-
-Copyright (C) 2013 Free Software Foundation, Inc.
-  Written by Bernd Warken <groff-bernd.warken-72@web.de>
-
-This file is part of `GNU groff'.
-
-  `GNU 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.
-
-  `GNU 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 package.  If not, see
-<http://www.gnu.org/licenses/>.
-*;
-
-
-  $Legalese =
-    {
-     'version' => VERSION,
-     'last_update' => LASTUPDATE,
-     'license' => LICENSE,
-    }
-
-}
-
-##### end legalese
-
-
-########################################################################
-# global variables and BEGIN
-########################################################################
-
-use integer;
-use utf8;
-
-use Cwd qw[];
-use File::Basename qw[];
-use File::Copy qw[];
-use File::HomeDir qw[];
-use File::Spec qw[];
-use File::Path qw[];
-use File::Temp qw[];
-use FindBin qw[];
-use POSIX qw[];
-
-
-BEGIN {
-
-  use constant FALSE => 0;
-  use constant TRUE => 1;
-  use constant EMPTYSTRING => '';
-  use constant EMPTYARRAY => ();
-  use constant EMPTYHASH => ();
-
-  our $Globals =
-    {
-     'before_make' => FALSE,
-     'groff_version' => EMPTYSTRING,
-     'prog' => EMPTYSTRING,
-    };
-
-  {
-    ( my $volume, my $directory, $Globals->{'prog'} ) =
-      File::Spec->splitpath($0);
-    # $Globals->{'prog'} is `glilypond' when installed,
-    # `glilypond.pl' when not
-  }
-
-
-  $\ = "\n";	# adds newline at each print
-  $/ = "\n";	# newline separates input
-  $| = 1;       # flush after each print or write command
-
-
-  {
-    {
-      # script before run of `make'
-      my $at = '@';
-      $Globals->{'before_make'} = TRUE if '@VERSION@' eq "${at}VERSION${at}";
-    }
-
-    my $file_test_pl;
-    my $glilypond_libdir;
-
-    if ( $Globals->{'before_make'} ) { # in source, not yet installed
-      my $glilypond_dir = $FindBin::Bin;
-      $glilypond_dir = Cwd::realpath($glilypond_dir);
-      $glilypond_libdir = $glilypond_dir;
-
-    } else {			# already installed
-      $Globals->{'groff_version'} = '@VERSION@';
-      $glilypond_libdir = '@glilypond_dir@';
-    }
-
-    unshift(@INC, $glilypond_libdir);
-
-    umask 0077; # octal output: `printf "%03o", umask;'
-  }
-
-  require 'subs.pl';
-}
-
-die "test: ";
-########################################################################
-# OOP declarations for some file handles
-########################################################################
-
-require 'oop_fh.pl';
-
-our $stdout = new FH_STDOUT();
-our $stderr = new FH_STDERR();
-
-# verbose printing, not clear wether this will be set by `--verbose',
-# so store this now into a string, which can be gotten later on, when
-# it will become either STDERR or /dev/null
-our $v = new FH_STRING();
-
-# for standard output, either STDOUT or output file
-our $out;
-
-# end of FH
-
-
-########################################################################
-# Args: command line arguments
-########################################################################
-
-# command line arguments are handled in 2 runs:
-# 1) split short option collections, `=' optargs, and transfer abbrevs
-# 2) handle the transferred options with subs
-
-our $Args =
-  {
-   'eps_dir' => EMPTYSTRING, # can be overwritten by `--eps_dir'
-
-   # `eps-func' has 2 possible values:
-   # 1) `ly' from `--ly2eps' (default)
-   # 2) `pdf' `--pdf2eps'
-   'eps_func' => 'ly',
-
-   # files names of temporary files start with this string,
-   # can be overwritten by `--prefix'
-   'prefix' => 'ly',
-
-   # delete or do not delete temporary files
-   'keep_all' => FALSE,
-
-   # the roff output goes normally to STDOUT, can be a file with `--output'
-   'output' => EMPTYSTRING,
-
-   # temporary directory, can be overwritten by `--temp_dir',
-   # empty for default of the program
-   'temp_dir' => EMPTYSTRING,
-
-   # regulates verbose output (on STDERR), overwritten by `--verbose'
-   'verbose' => FALSE,
-  };
-
-{ # `Args'
-  require 'args.pl';
-  &run_first();
-  &install_verbose();
-  &run_second();
-  &handle_args();
-}
-
-# end `Args'
-
-
-########################################################################
-# temporary directory .../tmp/groff/USER/lilypond/TIME
-########################################################################
-
-our $Temp =
-  {
-   # store the current directory
-   'cwd' => Cwd::getcwd(),
-
-   # directory for EPS files
-   'eps_dir' => EMPTYSTRING,
-
-   # temporary directory
-   'temp_dir' => EMPTYSTRING,
-  };
-
-{ # `Temp'
-
-  if ( $Args->{'temp_dir'} ) {
-
-    #----------
-    # temporary directory was set by `--temp_dir'
-    #----------
-
-    my $dir = $Args->{'temp_dir'};
-
-    $dir = &path2abs($dir);
-    $dir = &make_dir($dir) or
-      die "The directory `$dir' cannot be used temporarily: $!";
-
-
-    # now `$dir' is a writable directory
-
-    opendir( my $dh, $dir ) or
-      die "Could not open temporary directory `$dir': $!";
-    my $file_name;
-    my $found = FALSE;
-    my $prefix = $Args->{'prefix'};
-    my $re = qr<
-		 ^
-		 $prefix
-		 _
-	       >x;
-
-  READDIR: while ( defined($file_name = readdir($dh)) ) {
-      chomp $file_name;
-      if ( $file_name =~ /$re/ ) { # file name starts with $prefix_
-	$found = TRUE;
-	last READDIR;
-      }
-      next;
-    }
-
-    $Temp->{'temp_dir'} = $dir;
-    my $n = 0;
-    while ( $found ) {
-      $dir = File::Spec->catdir( $Temp->{'temp_dir'}, ++$n );
-      next if ( -e $dir );
-
-      $dir = &make_dir($dir) or next;
-
-      $found = FALSE;
-      last;
-    }
-
-    $Temp->{'temp_dir'} = $dir;
-
-
-  } else { # $Args->{'temp_dir'} not given by `--temp_dir'
-
-    #----------
-    # temporary directory was not set
-    #----------
-
-    { # search for or create a temporary directory
-
-      my @tempdirs = EMPTYARRAY;
-      {
-	my $tmpdir = File::Spec->tmpdir();
-	push @tempdirs, $tmpdir if ( $tmpdir && -d $tmpdir && -w $tmpdir );
-
-	my $root_dir = File::Spec->rootdir(); # `/' in Unix
-	my $root_tmp = File::Spec->catdir($root_dir, 'tmp');
-	push @tempdirs, $root_tmp
-	  if ( $root_tmp ne $tmpdir && -d $root_tmp && -w $root_tmp );
-
-	# home directory of the actual user
-	my $home = File::HomeDir->my_home;
-	my $home_tmp = File::Spec->catdir($home, 'tmp');
-	push @tempdirs, $home_tmp if ( -d $home_tmp && -w $home_tmp );
-
-	# `/var/tmp' in Unix
-	my $var_tmp = File::Spec->catdir('', 'var', 'tmp');
-	push @tempdirs, $var_tmp if ( -d $var_tmp && -w $var_tmp );
-      }
-
-
-      my @path_extension = qw( groff ); # TEMPDIR/groff/USER/lilypond/<NUMBER>
-      {
-	# `$<' is UID of actual user,
-	# `getpwuid' gets user name in scalar context
-	my $user = getpwuid($<);
-	push @path_extension, $user if ( $user );
-
-	push @path_extension, qw( lilypond );
-      }
-
-
-    TEMPS: foreach ( @tempdirs ) {
-
-	my $dir; # final directory name in `while' loop
-	$dir = &path2abs($_);
-	next TEMPS unless ( $dir );
-
-	# beginning of directory name
-	my @dir_begin =
-	  ( File::Spec->splitdir($dir), @path_extension );
-
-
-	my $n = 0;
-	my $dir_blocked = TRUE;
-      BLOCK: while ( $dir_blocked ) {
-	  # should become the final dir name
-	  $dir = File::Spec->catdir(@dir_begin, ++$n);
-	  next BLOCK if ( -d $dir );
-
-	  # dir name is now free, create it, and end the blocking
-	  my $res = &make_dir( $dir );
-	  die "Could not create directory: $dir" unless ( $res );
-
-	  $dir = $res;
-	  $dir_blocked = FALSE;
-	}
-
-	next TEMPS unless ( -d $dir && -w $dir  );
-
-	# $dir is now a writable directory
-	$Temp->{'temp_dir'} = $dir; # tmp/groff/USER/lilypond/TIME
-	last TEMPS;
-      } # end foreach tmp directories
-    } # end to create a temporary directory
-
-    die "Could not find a temporary directory" unless
-      ( $Temp->{'temp_dir'} && -d $Temp->{'temp_dir'} &&
-	-w $Temp->{'temp_dir'} );
-
-  } # end temporary directory
-
-  $v->print( "Temporary directory: `" . $Temp->{'temp_dir'} . "'\n" );
-  $v->print( "file_prefix: `" . $Args->{'prefix'} . "'" );
-
-
-  #----------
-  # EPS directory
-  #----------
-
-  my $make_dir = FALSE;
-  if ( $Args->{'eps_dir'} ) { # set by `--eps_dir'
-    my $dir = $Args->{'eps_dir'};
-
-    $dir = &path2abs($dir);
-
-    if ( -e $dir ) {
-      goto EMPTY unless ( -w $dir );
-
-      # `$dir' is writable
-      if ( -d $dir ) {
-	my $upper_dir = $dir;
-
-	my $found = FALSE;
-	opendir( my $dh, $upper_dir ) or $found = TRUE;
-	my $prefix = $Args->{'prefix'};
-	my $re = qr<
-		     ^
-		     $prefix
-		     _
-		   >x;
-	while ( not $found ) {
-	  my $file_name = readdir($dh);
-	  if ( $file_name =~ /$re/ ) { # file name starts with $prefix_
-	    $found = TRUE;
-	    last;
-	  }
-	  next;
-	}
-
-	my $n = 0;
-	while ( $found ) {
-	  $dir = File::Spec->catdir($upper_dir, ++$n);
-	  next if ( -d $dir );
-	  $found = FALSE;
-	}
-	$make_dir = TRUE;
-	$Temp->{'eps_dir'} = $dir;
-      } else { # `$dir' is not a dir, so unlink it to create it as dir
-	if ( unlink $dir ) { # could remove `$dir'
-	  $Temp->{'eps_dir'} = $dir;
-	  $make_dir = TRUE;
-	} else { # could not remove
-	  stderr->print(  "Could not use EPS dir `" . $dir .
-			  "', use temp dir." );
-	} # end of unlink
-      } # end test of -d $dir
-    } else {
-      $make_dir = TRUE;
-    } # end of if -e $dir
-
-
-    if ( $make_dir ) { # make directory `$dir'
-      my $made = FALSE;
-      $dir = &make_dir($dir) and $made = TRUE;
-
-      if ( $made ) {
-	$Temp->{'eps_dir'} = $dir;
-	$v->print( "Directory for useful EPS files is `" . $dir . "'." );
-      } else {
-	$v->print( "The EPS directory `" . $dir . "' cannot be used: $!" );
-      }
-    } else { # `--eps_dir' was not set, so take the temporary directory
-      $Temp->{'eps_dir'} = $Args->{'temp_dir'};
-    } # end of make dir
-  }
-
- EMPTY: unless ( $Temp->{'eps_dir'} ) {
-    # EPS-dir not set or available, use temp dir,
-    # but leave $Temp->{'}eps_dir'} empty
-    $v->print( "Directory for useful EPS files is the " .
-      "temporary directory `" . $Temp->{'temp_dir'} . "'." );
-  }
-
-} # end `Temp'
-
-
-########################################################################
-# Read: read files or stdin
-########################################################################
-
-our $Read =
-  {
-   'file_numbered' => EMPTYSTRING,
-   'file_ly' => EMPTYSTRING, # `$file_numbered.ly'
-  };
-
-{ # read files or stdin
-
-  my $ly_number = 0; # number of lilypond file
-
-  # `$Args->{'prefix'}_[0-9]'
-
-  my $lilypond_mode = FALSE;
-
-  my $arg1; # first argument for `.lilypond'
-  my $arg2; # argument for `.lilypond include'
-
-  my $path_ly; # path of ly-file
-
-
-  my $check_file = sub { # for argument of `.lilypond include'
-    my $file = shift; # argument is a file name
-    $file = &path2abs($file);
-    unless ( $file ) {
-      die "Line `.lilypond include' without argument";
-      return '';
-    }
-    unless ( -f $file && -r $file ) {
-      die "Argument `$file' in `.lilypond include' is not a readable file";
-    }
-
-    return $file;
-  }; # end sub &$check_file()
-
-
-  my $increase_ly_number = sub {
-    ++$ly_number;
-    $Read->{'file_numbered'} = $Args->{'prefix'} . '_' . $ly_number;
-    $Read->{'file_ly'} =  $Read->{'file_numbered'} . '.ly';
-    $path_ly = File::Spec->catdir($Temp->{'temp_dir'}, $Read->{'file_ly'} );
-  };
-
-
-  my %eps_subs =
-    (
-     'ly' => \&create_ly2eps,   # lilypond creates EPS files
-     'pdf' => \&create_pdf2eps, # lilypond creates PDF file
-    );
-
-  # about lines starting with `.lilypond'
-
-  my $ly;
-  my $fh_include_file;
-  my %lilypond_args =
-    (
-
-     'start' => sub {
-       $v->print( "\nline: `.lilypond start'" );
-       die "Line `.lilypond stop' expected." if ( $lilypond_mode );
-
-       $lilypond_mode = TRUE;
-       &$increase_ly_number;
-
-       $v->print( "ly-file: `" . $path_ly . "'" );
-
-       $ly = new FH_FILE($path_ly);
-     },
-
-
-     'end' => sub {
-       $v->print( "line: `.lilypond end'\n" );
-       die "Expected line `.lilypond start'." unless ( $lilypond_mode );
-
-       $lilypond_mode = FALSE;
-       $ly->close();
-
-       if ( exists $eps_subs{ $Args->{'eps_func'} } ) {
-	 $eps_subs{ $Args->{'eps_func'} }->();
-       } else {
-	 die "Wrong argument for \%eps_subs: " . $Args->{'eps_func'} . "'";
-       }
-     },
-
-
-     'include' => sub { # `.lilypond include file...'
-
-       # this may not be used within lilypond mode
-       next LILYPOND if ( $lilypond_mode );
-
-       my $file_arg = shift;
-
-       my $file = &$check_file($file_arg);
-       next LILYPOND unless ( $file );
-       # file can be read now
-
-
-       # `$fh_write_ly' must be opened
-       &$increase_ly_number;
-
-       $ly = new FH_FILE($path_ly);
-
-       my $include = new FH_READ_FILE($file);
-       my $res = $include->read-all(); # is a refernce to an array
-       foreach ( @$res ) {
-	 chomp;
-	 $ly->print($_);
-       }
-       $ly->close();
-
-       if ( exists $eps_subs{ $Args->{'eps_func'} } ) {
-	 $eps_subs{ $Args->{'eps_func'} }->();
-       } else {
-	 die "Wrong argument for \$eps_subs: `" . $Args->{'eps_func'} . "'";
-       }
-     }, # end `.lilypond include'
-
-    ); # end definition %lilypond_args
-
-
- LILYPOND: foreach (<>) {
-    chomp;
-    my $line = $_;
-
-
-    # now the lines with '.lilypond ...'
-
-    if ( /
-	   ^
-	   [.']
-	   \s*
-	   lilypond
-	   (
-	     .*
-	   )
-	   $
-	 /x ) { # .lilypond ...
-      my $args = $1;
-      $args =~ s/
-		  ^
-		  \s*
-		//x;
-      $args =~ s/
-		  \s*
-		  $
-		//x;
-      $args =~ s/
-		  ^
-		  (
-		    \S*
-		  )
-		  \s*
-		//x;
-      my $arg1 = $1; # `start', `end' or `include'
-      $args =~ s/["'`]//g;
-      my $arg2 = $args; # file argument for `.lilypond include'
-
-      if ( exists $lilypond_args{$arg1} ) {
-	$lilypond_args{$arg1}->($arg2);
-	next;
-      } else {
-	# not a suitable argument of `.lilypond'
-	$stderr->print( "Unknown command: `$arg1' `$arg2':  `$line'" );
-      }
-
-      next LILYPOND;
-    } # end if for .lilypond
-
-
-    if ( $lilypond_mode ) { # do lilypond-mode
-      # see `.lilypond start'
-      $ly->print( $line );
-      next LILYPOND;
-    } # do lilypond-mode
-
-    # unknown line without lilypond
-    unless ( /
-	       ^
-	       [.']
-	       \s*
-	       lilypond
-	     /x ) { # not a `.lilypond' line
-      $out->print($line);
-      next LILYPOND;
-    }
-
-  } # end foreach <>
-} # end Read
-
-
-########################################################################
-# clean up
-########################################################################
-
-END {
-
-  exit unless ( defined($Temp->{'temp_dir'}) );
-
-  if ( $Args->{'keep_all'} ) {
-    # With --keep_all, no temporary files are removed.
-    $v->print( "keep_all: `TRUE'" );
-    $v->print( "No temporary files will be deleted:" );
-
-    opendir my $dh_temp, $Temp->{'temp_dir'} or
-      die "Cannot open " . $Temp->{'temp_dir'} . ": $!";
-    for ( sort readdir $dh_temp ) {
-      next if ( /         # omit files starting with a dot
-		  ^
-		  \.
-		/x );
-      if ( /
-	     ^
-	     $Args->{'prefix'}
-	     _
-	   /x ) {
-	my $file = File::Spec->catfile( $Temp->{'temp_dir'}, $_ );
-	$v->print( "- " . $file );
-	next;
-      }
-      next;
-    } # end for sort readdir
-    closedir $dh_temp;
-
-  } else { # keep_all is not set
-    # Remove all temporary files except the eps files.
-
-    $v->print( "keep_all: `FALSE'" );
-    $v->print( "All temporary files except *.eps will be deleted" );
-
-
-    if ( $Temp->{'eps_dir'} ) {
-      # EPS files are in another dir, remove temp dir
-
-      if ( &is_subdir( $Temp->{'eps_dir'}, $Temp->{'temp_dir'} ) ) {
-	$v->print( "EPS dir is subdir of temp dir, so keep both." );
-      } else { # remove temp dir
-	$v->print( "Try to remove temporary directory `" .
-	  $Temp->{'temp_dir'} ."':" );
-	if ( File::Path::remove_tree($Temp->{'temp_dir'}) ) {
-	  # remove succeeds
-	  $v->print( "...done." );
-	} else { # did not remove
-	  $v->print( "Failure to remove temporary directory." );
-	} # end test on remove
-      } # end is subdir
-
-    } else { # no EPS dir, so keep EPS files
-
-      opendir my $dh_temp, $Temp->{'temp_dir'} or
-	die "Cannot open " . $Temp->{'temp_dir'} . ": $!";
-      for ( sort readdir $dh_temp ) {
-	next if ( /          # omit files starting with a dot
-		    ^
-		    \.
-		  /x );
-	next if ( /          # omit EPS-files
-		    \.eps
-		    $
-		  /x );
-	if ( /
-	       ^
-	       $Args->{'prefix'}
-	       _
-	     /x ) { # this includes `PREFIX_temp*'
-	  my $file = File::Spec->catfile( $Temp->{'temp_dir'},  $_ );
-	  $v->print( "Remove `" . $file . "'" );
-	  unlink $file or $stderr->print( "Could not remove `$file': $!" );
-	  next;
-	} # end if prefix
-	next;
-      } # end for readdir temp dir
-      closedir $dh_temp;
-    } # end if-else EPS files
-  } # end if-else keep files
-
-
-  if ( $Temp->{'eps_dir'} ) {
-    # EPS files in $Temp->{'eps_dir'} are always kept
-    $v->print( "As EPS directrory is set as `" .
-      $Temp->{'eps_dir'} . "', no EPS files there will be deleted." );
-
-    opendir my $dh_temp, $Temp->{'eps_dir'} or
-      die "Cannot open `" . $Temp->{'eps_dir'} . ": $!";
-    for ( sort readdir $dh_temp ) {
-      next if ( /         # omit files starting with a dot
-		  ^
-		  \.
-		/x );
-      if ( /
-	     ^
-	     $Args->{'prefix'}
-	     _
-	     .*
-	     \.eps
-	     $
-	   /x ) {
-	my $file = File::Spec->catfile( $Temp->{'eps_dir'}, $_ );
-	$v->print( "- " . $file );
-	next;
-      } # end if *.eps
-      next;
-    } # end for sort readdir
-    closedir $dh_temp;
-
-  }
-
-  1;
-} # end package Clean
-
-
-1;
-########################################################################
-### Emacs settings
-# Local Variables:
-# mode: CPerl
-# End:

Index: glilypond/oop_fh.pl
===================================================================
RCS file: glilypond/oop_fh.pl
diff -N glilypond/oop_fh.pl
--- glilypond/oop_fh.pl	13 May 2013 20:08:23 -0000	1.4
+++ /dev/null	1 Jan 1970 00:00:00 -0000
@@ -1,311 +0,0 @@
-my $License = q*
-########################################################################
-# Legalese
-########################################################################
-
-Source file position: `<groff-source>/contrib/glilypond/oop_fh.pl'
-Installed position: `<prefix>/lib/groff/glilypond/oop_fh.pl'
-
-Copyright (C) 2013 Free Software Foundation, Inc.
-  Written by Bernd Warken <groff-bernd.warken-72@web.de>
-
-Last update: 10 May 2013
-
-This file is part of `glilypond', which is part of `GNU groff'.
-
-glilypond - integrate `lilypond' into `groff' files
-
-  `GNU 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.
-
-  `GNU 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 package.  If not, see
-<http://www.gnu.org/licenses/>.
-*;
-
-##### end legalese
-
-
-# use strict;
-# use warnings;
-# use diagnostics;
-
-use integer;
-
-########################################################################
-# OOP for writing file handles that are open by default, like STD*
-########################################################################
-
-# -------------------------- _FH_WRITE_OPENED --------------------------
-
-{	# FH_OPENED: base class for all opened file handles, like $TD*
-
-  package _FH_WRITE_OPENED;
-  use strict;
-
-  sub new {
-    my ( $pkg, $std ) = @_;
-    bless {
-	   'fh' => $std,
-	  }
-  }
-
-  sub open {
-  }
-
-  sub close {
-  }
-
-  sub print {
-    my $self = shift;
-    for ( @_ ) {
-      print { $self->{'fh'} } $_;
-    }
-  }
-
-}
-
-
-# ------------------------------ FH_STDOUT ----------------------------
-
-{			     # FH_STDOUT: print to noral output STDOUT
-
-  package FH_STDOUT;
-  use strict;
-  @FH_STDOUT::ISA = qw( _FH_WRITE_OPENED );
-
-  sub new {
-    &_FH_WRITE_OPENED::new( '_FH_WRITE_OPENED', *STDOUT );
-  }
-
-}				# end FH_STDOUT
-
-
-# ------------------------------ FH_STDERR -----------------------------
-
-{				# FH_STDERR: print to STDERR
-
-  package FH_STDERR;
-  use strict;
-  @FH_STDERR::ISA = qw( _FH_WRITE_OPENED );
-
-  sub new {
-    &_FH_WRITE_OPENED::new( 'FH_OPENED', *STDERR );
-  }
-
-}				# end FH_STDERR
-
-
-########################################################################
-# OOP for file handles that write into a file or string
-########################################################################
-
-# ------------------------------- FH_FILE ------------------------------
-
-{	       # FH_FILE: base class for writing into a file or string
-
-  package FH_FILE;
-  use strict;
-
-  sub new {
-    my ( $pkg, $file ) = @_;
-    bless {
-	   'fh' => undef,
-	   'file' => $file,
-	   'opened' => main::FALSE,
-	  }
-  }
-
-  sub DESTROY {
-    my $self = shift;
-    $self->close();
-  }
-
-  sub open {
-    my $self = shift;
-    my $file = $self->{'file'};
-    if ( $file && -e $file ) {
-      die "file $file is not writable" unless ( -w $file );
-      die "$file is a directory" if ( -d $file );
-    }
-    open $self->{'fh'}, ">", $self->{'file'}
-      or die "could not open file `$file' for writing: $!";
-    $self->{'opened'} = main::TRUE;
-  }
-
-  sub close {
-    my $self = shift;
-    close $self->{'fh'} if ( $self->{'opened'} );
-    $self->{'opened'} = main::FALSE;
-  }
-
-  sub print {
-    my $self = shift;
-    $self->open() unless ( $self->{'opened'} );
-    for ( @_ ) {
-      print { $self->{'fh'} } $_;
-    }
-  }
-
-}				# end FH_FILE
-
-
-# ------------------------------ FH_STRING -----------------------------
-
-{				# FH_STRING: write into a string
-
-  package FH_STRING;		# write to \string
-  use strict;
-  @FH_STRING::ISA = qw( FH_FILE );
-
-  sub new {
-    my $pkg = shift;		# string is a reference to scalar
-    bless
-      {
-       'fh' => undef,
-       'string' => '',
-       'opened' => main::FALSE,
-      }
-    }
-
-  sub open {
-    my $self = shift;
-    open $self->{'fh'}, ">", \ $self->{'string'}
-      or die "could not open string for writing: $!";
-    $self->{'opened'} = main::TRUE;
-  }
-
-  sub get { # get string, move to array ref, close, and return array ref
-    my $self = shift;
-    return '' unless ( $self->{'opened'} );
-    my $a = &string2array( $self->{'string'} );
-    $self->close();
-    return $a;
-  }
-
-}				# end FH_STRING
-
-
-# -------------------------------- FH_NULL -----------------------------
-
-{				# FH_NULL: write to null device
-
-  package FH_NULL;
-  use strict;
-  @FH_NULL::ISA = qw( FH_FILE FH_STRING );
-
-  use File::Spec;
-
-  my $devnull = File::Spec->devnull();
-  $devnull = '' unless ( -e $devnull && -w $devnull );
-
-  sub new {
-    my $pkg = shift;
-    if ( $devnull ) {
-      &FH_FILE::new( $pkg, $devnull );
-    } else {
-      &FH_STRING::new( $pkg );
-    }
-  } # end new()
-
-}				# end FH_NULL
-
-
-########################################################################
-# OOP for reading file handles
-########################################################################
-
-# ---------------------------- FH_READ_FILE ----------------------------
-
-{ # FH_READ_FILE: read a file
-
-  package FH_READ_FILE;
-  use strict;
-
-  sub new {
-    my ( $pkg, $file ) = @_;
-    die "File `$file' cannot be read." unless ( -f $file && -r $file );
-    bless {
-	   'fh' => undef,
-	   'file' => $file,
-	   'opened' => main::FALSE,
-	  }
-  }
-
-  sub DESTROY {
-    my $self = shift;
-    $self->close();
-  }
-
-  sub open {
-    my $self = shift;
-    my $file = $self->{'file'};
-    if ( $file && -e $file ) {
-      die "file $file is not writable" unless ( -r $file );
-      die "$file is a directory" if ( -d $file );
-    }
-    open $self->{'fh'}, "<", $self->{'file'}
-      or die "could not read file `$file': $!";
-    $self->{'opened'} = main::TRUE;
-  }
-
-  sub close {
-    my $self = shift;
-    close $self->{'fh'} if ( $self->{'opened'} );
-    $self->{'opened'} = main::FALSE;
-  }
-
-  sub read_line {
-    # Read 1 line of the file into a chomped string.
-    # Do not close the read handle at the end.
-    my $self = shift;
-    $self->open() unless ( $self->{'opened'} );
-
-    my $res;
-    if ( defined($res = CORE::readline($self->{'fh'}) ) ) {
-      chomp $res;
-      return $res;
-    } else {
-      $self->close();
-      return undef;
-    }
-  }
-
-  sub read_all {
-    # Read the complete file into an array reference.
-    # Close the read handle at the end.
-    # Return array reference.
-    my $self = shift;
-    $self->open() unless ( $self->{'opened'} );
-
-    my $res = [];
-    my $line;
-    while ( defined ( $line = CORE::readline $self->{'fh'} ) ) {
-      chomp $line;
-      push @$res, $line;
-    }
-    $self->close();
-    $self->{'opened'} = main::FALSE;
-    return $res;
-  }
-
-}
-
-# end of OOP definitions
-
-package main;
-
-1;
-########################################################################
-### Emacs settings
-# Local Variables:
-# mode: CPerl
-# End:

Index: glilypond/subs.pl
===================================================================
RCS file: glilypond/subs.pl
diff -N glilypond/subs.pl
--- glilypond/subs.pl	13 May 2013 20:08:23 -0000	1.6
+++ /dev/null	1 Jan 1970 00:00:00 -0000
@@ -1,469 +0,0 @@
-my $License = q*
-########################################################################
-# Legalese
-########################################################################
-
-Subroutines for `glilypond'.
-
-Source file position: `<groff-source>/contrib/glilypond/subs.pl'
-Installed position: `<prefix>/lib/groff/glilypond/subs.pl'
-
-Copyright (C) 2013 Free Software Foundation, Inc.
-  Written by Bernd Warken <groff-bernd.warken-72@web.de>
-
-  Last update: 10 May 2013
-
-This file is part of `glilypond', which is part of `GNU groff'.
-
-  `GNU 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.
-
-  `GNU 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 package.  If not, see
-<http://www.gnu.org/licenses/>.
-*;
-
-##### end legalese
-
-
-# use strict;
-# use warnings;
-# use diagnostics;
-
-use integer;
-use utf8;
-use feature 'state';
-
-
-########################################################################
-# subs for using several times
-########################################################################
-
-sub create_ly2eps {		       # `--ly2eps' default
-  our ( $out, $Read, $Temp );
-
-  my $prefix = $Read->{'file_numbered'};   # with dir change to temp dir
-
-  # `$ lilypond --ps -dbackend=eps -dgs-load-fonts \
-  #      output=file_without_extension file.ly'
-  # extensions are added automatically
-  my $opts = '--ps -dbackend=eps -dinclude-eps-fonts -dgs-load-fonts ' .
-    "--output=$prefix $prefix";
-  &run_lilypond("$opts");
-
-  Cwd::chdir $Temp->{'cwd'} or
-      die "Could not change to former directory `" .
-	$Temp->{'cwd'} . "': $!";
-
-  my $eps_dir = $Temp->{'eps_dir'};
-  my $dir = $Temp->{'temp_dir'};
-  opendir( my $dh, $dir ) or
-    die "could not open temporary directory `$dir': $!";
-
-  my $re = qr<
-	       ^
-	       $prefix
-	       -
-	       .*
-	       \.eps
-	       $
-	     >x;
-  my $file;
-  while ( readdir( $dh ) ) {
-    chomp;
-    $file = $_;
-    if ( /$re/ ) {
-      my $file_path = File::Spec->catfile($dir, $file);
-      if ( $eps_dir ) {
-	my $could_copy = FALSE;
-	File::Copy::copy($file_path, $eps_dir)
-	    and $could_copy = TRUE;
-	if ( $could_copy ) {
-	  unlink $file_path;
-	  $file_path = File::Spec->catfile($eps_dir, $_);
-	}
-      }
-      $out->print( '.PSPIC ' . $file_path );
-    }
-  }				# end while readdir
-  closedir( $dh );
-}				# end sub create_ly2eps()
-
-
-sub create_pdf2eps {		       # `--pdf2eps'
-  our ( $v, $stdout, $stderr, $out, $Read, $Temp );
-
-  my $prefix = $Read->{'file_numbered'};   # with dir change to temp dir
-
-  &run_lilypond("--pdf --output=$prefix $prefix");
-
-  my $file_pdf = $prefix . '.pdf';
-  my $file_ps = $prefix . '.ps';
-
-  # pdf2ps in temp dir
-  my $temp_file = &next_temp_file;
-  $v->print( "\n##### run of `pdf2ps'" );
-  # `$ pdf2ps file.pdf file.ps'
-  my $output = `pdf2ps $file_pdf $file_ps 2> $temp_file`;
-  die 'Program pdf2ps does not work.' if ( $? );
-  &shell_handling($output, $temp_file);
-  $v->print( "##### end run of `pdf2ps'\n" );
-
-  # ps2eps in temp dir
-  $temp_file = &next_temp_file;
-  $v->print( "\n##### run of `ps2eps'" );
-  # `$ ps2eps file.ps'
-  $output = `ps2eps $file_ps 2> $temp_file`;
-  die 'Program ps2eps does not work.' if ( $? );
-  &shell_handling($output, $temp_file);
-  $v->print( "##### end run of `ps2eps'\n" );
-
-  # change back to former dir
-  Cwd::chdir $Temp->{'cwd'} or
-      die "Could not change to former directory `" .
-	$Temp->{'cwd'} . "': $!";
-
-  # handling of .eps file
-  my $file_eps = $prefix . '.eps';
-  my $eps_path = File::Spec->catfile($Temp->{'temp_dir'}, $file_eps);
-  if ( $Temp->{'eps_dir'} ) {
-    my $has_copied = FALSE;
-    File::Copy::copy( $eps_path, $Temp->{'eps_dir'} )
-	and $has_copied = TRUE;
-    if ( $has_copied ) {
-      unlink $eps_path;
-      $eps_path = File::Spec->catfile( $Temp->{'eps_dir'}, $file_eps );
-    } else {
-      $stderr->print( "Could not use EPS-directory." );
-    } # end Temp->{'eps_dir'}
-  }
-  # print into groff output
-  $out->print( '.PSPIC ' . $eps_path );
-}				# end sub create_pdf2eps()
-
-
-sub is_subdir {			# arg1 is subdir of arg2 (is longer)
-  my ( $dir1, $dir2 ) = @_;
-  $dir1 = &path2abs( $dir1 );;
-  $dir2 = &path2abs( $dir2 );;
-  my @split1 = File::Spec->splitdir($dir1);
-  my @split2 = File::Spec->splitdir($dir2);
-  for ( @split2 ) {
-    next if ( $_ eq shift @split1 );
-    return FALSE;
-  }
-  return TRUE;
-}
-
-
-sub license {
-  our ( $Legalese, $stdout );
-  &version;
-  $stdout->print( $Legalese->{'license'} );
-} # end sub license()
-
-
-sub make_dir {			# make directory or check if it exists
-  our ( $v, $Args );
-
-  my $dir_arg = shift;
-  chomp $dir_arg;
-  $dir_arg =~ s/^\s*(.*)\s*$/$1/;
-
-  unless ( $dir_arg ) {
-    $v->print( "make_dir(): empty argument" );
-    return FALSE;
-  }
-
-  unless ( File::Spec->file_name_is_absolute($dir_arg) ) {
-    my $res = Cwd::realpath($dir_arg);
-    $res = File::Spec->canonpath($dir_arg) unless ( $res );
-    $dir_arg = $res if ( $res );
-  }
-
-  return $dir_arg if ( -d $dir_arg && -w $dir_arg );
-
-
-  # search thru the dir parts
-  my @dir_parts = File::Spec->splitdir($dir_arg);
-  my @dir_grow;
-  my $dir_grow;
-  my $can_create = FALSE;	# dir could be created if TRUE
-
- DIRPARTS: for ( @dir_parts ) {
-    push @dir_grow, $_;
-    next DIRPARTS unless ( $_ ); # empty string for root directory
-
-    # from array to path dir string
-    $dir_grow = File::Spec->catdir(@dir_grow);
-
-    next DIRPARTS if ( -d $dir_grow );
-
-    if ( -e $dir_grow ) {  # exists, but not a dir, so must be removed
-      die "Couldn't create dir `$dir_arg', it is blocked by `$dir_grow'."
-	unless ( -w $dir_grow );
-
-      # now it's writable, but not a dir, so it can be removed
-      unlink ( $dir_grow ) or
-	die "Couldn't remove `$dir_grow', " .
-	  "so I cannot create dir `$dir_arg': $!";
-    }
-
-    # $dir_grow does no longer exist, so the former dir must be writable
-    # in order to create the directory
-    pop @dir_grow;
-    $dir_grow = File::Spec->catdir(@dir_grow);
-
-    die "`$dir_grow' is not writable, " .
-      "so directory `$dir_arg' can't be createdd."
-	unless ( -w $dir_grow );
-
-    # former directory is writable, so `$dir_arg' can be created
-
-    File::Path::make_path( $dir_arg,
-			   {
-			    mask => oct('0700'),
-			    verbose => $Args->{'verbose'},
-			   }
-			 )	#  `mkdir -P'
-	or die "Could not create directory `$dir_arg': $!";
-
-    last DIRPARTS;
-  }
-
-  die "`$dir_arg' is not a writable directory"
-    unless ( -d $dir_arg && -w $dir_arg );
-
-  return $dir_arg;
-
-} # end sub make_dir()
-
-
-my $number = 0;
-sub next_temp_file {
-  our ( $Temp, $v, $Args );
-  ++$number;
-  my $temp_basename = $Args->{'prefix'} . '_temp_' . $number;
-  my $temp_file = File::Spec->catfile( $Temp->{'temp_dir'} ,
-				       $temp_basename );
-  $v->print( "next temporary file: `$temp_file'" );
-  return $temp_file;
-}				# end sub next_temp_file()
-
-
-sub path2abs {
-  our ( $Temp, $Args );
-
-  my $path = shift;
-  $path =~ s/
-	      ^
-	      \s*
-	      (
-		.*
-	      )
-	      \s*
-	      $
-	    /$1/x;
-
-  die "path2abs(): argument is empty." unless ( $path );
-
-  # Perl does not support shell `~' for home dir
-  if ( $path =~ /
-		  ^
-		  ~
-		/x ) {
-    if ( $path eq '~' ) {	# only own home
-      $path = File::HomeDir->my_home;
-    } elsif ( $path =~ m<
-			  ^
-			  ~ /
-			  (
-			    .*
-			  )
-			  $
-			>x ) {	# subdir of own home
-      $path = File::Spec->catdir( $Temp->{'cwd'}, $1 );
-    } elsif ( $path =~ m<
-			  ^
-			  ~
-			  (
-			    [^/]+
-			  )
-			  $
-			>x ) {	# home of other user
-      $path = File::HomeDir->users_home($1);
-    } elsif ( $path =~ m<
-			  ^
-			  ~
-			  (
-			    [^/]+
-			  )
-			  /+
-			  (
-			    .*
-			  )
-			  $
-			>x ) {	# subdir of other home
-      $path = File::Spec->
-	catdir( File::HomeDir->users_home($1), $2 );
-    }
-  }
-
-  $path = File::Spec->rel2abs($path);
-
-  # now $path is absolute
-  return $path;
-} # end sub path2abs()
-
-
-sub run_lilypond {
-  # arg is the options collection for `lilypond' to run
-  # either from ly or pdf
-
-  our ( $Temp, $v );
-
-  my $opts = shift;
-  chomp $opts;
-
-  my $temp_file = &next_temp_file;
-  my $output = EMPTYSTRING;
-
-  # change to temp dir
-  Cwd::chdir $Temp->{'temp_dir'} or
-      die "Could not change to temporary directory `" .
-	$Temp->{'temp_dir'} . "': $!";
-
-  $v->print( "\n##### run of `lilypond " . $opts . "'" );
-  $output = `lilypond $opts 2>$temp_file`;
-  die "Program lilypond does not work, see `$temp_file': $?"
-    if ( $? );
-  chomp $output;
-  &shell_handling($output, $temp_file);
-  $v->print( "##### end run of `lilypond'\n" );
-
-  # stay in temp dir
-} # end sub run_lilypond()
-
-
-sub shell_handling {
-  # Handle ``-shell-command output in a string (arg1).
-  # stderr goes to temporary file $TempFile.
-
-  our ( $out, $v, $Args );
-
-  my $out_string = shift;
-  my $temp_file = shift;
-
-  my $a = &string2array($out_string); # array ref
-  for ( @$a ) {
-    $out->print( $_ );
-  }
-
-  $temp_file && -f $temp_file && -r $temp_file ||
-    die "shell_handling(): $temp_file is not a readable file.";
-  my $temp = new FH_READ_FILE($temp_file);
-  my $res = $temp->read_all();
-  for ( @$res ) {
-    chomp;
-    $v->print($_);
-  }
-
-  unlink $temp_file unless ( $Args->{'keep_all'} );
-} # end sub shell_handling()
-
-
-sub string2array {
-  my $s = shift;
-  my @a = ();
-  for ( split "\n", $s ) {
-    chomp;
-    push @a, $_;
-  }
-  return \@a;
-} # end string2array()
-
-
-sub usage {			# for `--help'
-  our ( $Globals, $Args );
-
-  my $p = $Globals->{'prog'};
-  my $usage = EMPTYSTRING;
-  $usage = '###### usage:' . "\n" if ( $Args->{'verbose'} );
-  $usage .= qq*Options for $p:
-Read a `roff' file or standard input and transform `lilypond' parts
-(everything between `.lilypond start' and `.lilypond end') into
-`EPS'-files that can be read by groff using `.PSPIC'.
-
-There is also a command `.lilypond include <file_name>' that can
-include a complete `lilypond' file into the `groff' document.
-
-
-# Breaking options:
-$p -?|-h|--help|--usage    # usage
-$p --version               # version information
-$p --license               # the license is GPL >= 3
-
-
-# Normal options:
-$p [options] [--] [filename ...]
-
-There are 2 options for influencing the way how the `EPS' files for the
-`roff' display are generated:
---ly2eps           `lilypond' generates `EPS' files directly (default)
---pdf2eps          `lilypond' generates a `PDF' file that is transformed
-
--k|--keep_all      do not delete any temporary files
--v|--verbose       print much information to STDERR
-
-Options with an argument:
--e|--eps_dir=...   use a directory for the EPS files
--o|--output=...    sent output in the groff language into file ...
--p|--prefix=...    start for the names of temporary files
--t|--temp_dir=...  provide the directory for temporary files.
-
-The directories set are created when they do not exist.
-*;
-
-  # old options:
-  # --keep_files       -k: do not delete any temporary files
-  # --file_prefix=...  -p: start for the names of temporary files
-
-  $main::stdout->print( $usage );
-} # end sub usage()
-
-
-sub version { # for `--version'
-  our ( $Globals, $Legalese, $stdout, $Args );
-  my $end;
-  if ( $Globals->{'groff_version'} ) {
-    $end = " version $Globals->{'groff_version'}";
-  } else {
-    $end = '.';
-  }
-
-  my $output = EMPTYSTRING;
-  $output = "###### version:\n" if ( $Args->{'verbose'} );
-  $output .= "`" . $Globals->{'prog'} . "' version `" .
-    $Legalese->{'version'} . "' of `" .
-      $Legalese->{'last_update'} . "' is part of `GNU groff'" . $end;
-
-  $stdout->print($output);
-} # end sub version()
-
-
-# end of subs
-
-1;
-########################################################################
-### Emacs settings
-# Local Variables:
-# mode: CPerl
-# End:

Index: groffer/ChangeLog
===================================================================
RCS file: groffer/ChangeLog
diff -N groffer/ChangeLog
--- groffer/ChangeLog	11 Apr 2013 00:08:30 -0000	1.65
+++ /dev/null	1 Jan 1970 00:00:00 -0000
@@ -1,314 +0,0 @@
-2013-04-11  Bernd Warken  <groff-bernd.warken-72@web.de>
-
-	* contrib/groffer: There is now a free `git' package containing
-	all old `groffer' versions `v0.*' and `v1.*'.  The new versions
-	`groffer 2.*' will actually not be included.  This package can be
-	got at:
-
-	$ git clone git@github.com:RUNOFF/groffer.git
-
-2013-03-29  Bernd Warken  <groff-bernd.warken-72@web.de>
-
-	* perl/groffer.pl: Change viewers for `PS'.
-
-2013-03-29  Bernd Warken  <groff-bernd.warken-72@web.de>
-
-	* perl/groffer.pl: Change viewers for `PS' and `PDF'.
-
-	* version.sh: New version is `1.1.3'.
-
-2012-08-09  Werner LEMBERG  <wl@gnu.org>
-
-	Synchronize man pages.
-
-	* perl/groffer.man, shell/groffer.man: Fix many minor issues.
-
-2012-08-07  Eric S. Raymond  <esr@thyrsus.com>
-
-	Yet more elimination of low-level troff hackery in the
-	documentation so it can be lifted to structural markup.
-
-	* perl/groffer.man: Use .IP rather than .TP in
-	.Topic; this make structural parsing work.  Also remove a
-	pointless and somewhat out-of-date .ig section.
-
-2011-10-17  Ingo Schwarze  <schwarze@openbsd.org>
-
-	Do not use INSTALL_DATA and INSTALL_SCRIPT during build phase.
-
-	* Makefile.sub (groffer): Replace INSTALL_DATA and
-	INSTALL_SCRIPT with `cp'.  Otherwise the build phase might
-	fail with `permission denied' if you use the `-o root' flag
-	of the `install' command.  The use of INSTALL_* is an abuse
-	anyway because it's not installing anything at that point;
-	it's just copying files around locally, within in the build
-	directories.
-
-2011-03-21  Jan Vcelak  <jvcelak@redhat.com>
-	    Bernd Warken <groff-bernd.warken-72@web.de>
-
-	Remove hardcoded path to 'libdir/groff/groffer' directory.
-
-	* Makefile.sub: use @groffer_dir@
-
-	* groffer.pl: use @groffer_dir@
-
-2011-01-27  James Budiono  <james.budiono@gmail.com>
-	    Bernd Warken <groff-bernd.warken-72@web.de>
-
-	Fix display of manpages.
-
-	Reported as
-	http://lists.gnu.org/archive/html/bug-groff/2011-01/msg00015.html.
-
-	* perl/groffer.pl (_get_first_prog): Fix return value.
-	(Viewer_X): Add `okular' viewer.
-	* perl/man.pl (manpath_set_from_path): Handle `@main::Path)'
-	correctly.
-
-	* version.sh: Updated.
-
-2009-01-03  Werner LEMBERG  <wl@gnu.org>
-
-	* version.sh: Prepare for groff release 1.20.
-
-2008-01-04  Werner LEMBERG  <wl@gnu.org>
-
-	* shell/groffer.man, perl/groffer.man: Insert `\:' in URLs where
-	appropriate.
-
-2007-02-15  Eric S. Raymond  <esr@snark.thyrsus.com>
-
-	* perl/groffer.man, perl/groffer.man: Fix non-portable `if'
-	expressions.
-
-2007-02-13  Eric S. Raymond  <esr@snark.thyrsus.com>
-
-	Use an-ext.tmac macros in groffer.man.
-
-	* perl/groffer.man, perl/groffer.man: Replace ShellCommand with
-	.EX/.EE pairs.
-	Don't use .TP for examples, as some viewers won't handle a display
-	macro as a tag line.  Use .SY/.OP/.YS rather than elaborate custom
-	macros.
-
-2007-02-02  Werner LEMBERG  <wl@gnu.org>
-
-	* roff2.man: Further refinements and normalizations.
-
-2007-02-02  Eric S. Raymond  <esr@snark.thyrsus.com>
-
-	* roff2.man: Converted to use .SY/.OP/.YS and for cross-viewer
-	portability.  Conversion checked using the protocol described in
-	tmac/TESTING-HINTS.
-
-2006-11-14  Werner LEMBERG  <wl@gnu.org>
-
-	* Makefile.sub (GROFFER_REST): Add roff2.man.
-	(groffer): Use $(INSTALL_DATA) for man pages.
-	Don't call `chmod' for $(ROFF2PROGS).
-	(roff2.man): Typographical fixes.
-
-2006-11-11  Bernd Warken  <groff-bernd.warken-72@web.de>
-	________________________________________________________________
-	* release of groffer 1.1.1
-
-	* perl/roff2.pl, shell/roff2.sh: Create a new working mode without
-	`groffer' for `roff2*'.
-
-	* perl/groffer.pl: Fix test of temporary directory.
-
-2006-11-09  Bernd Warken  <groff-bernd.warken-72@web.de>
-	________________________________________________________________
-	* release of groffer 1.1.0
-
-	* perl/groffer.pl, perl/func.pl, perl/groffer.man, \
-	shell/groffer2.sh, shell/groffer.man: Add `--debug-grog' to
-	display the `grog' output.
-
-	* perl/roff2.pl, shell/roff2.sh: New files for creating the roff2*
-	programs to transform roff code to different formats.
-
-	* roff2.man: New file to create man pages for the roff2*
-	programs.
-
-	* Makefile.sub: Add roff2* and some minor fixes.
-
-2006-11-04  Bernd Warken  <groff-bernd.warken-72@web.de>
-	________________________________________________________________
-	* release of groffer 1.0.3
-
-	* Makefile.sub:
-	- Delete removing of $(CLEANADD) in `groffer'.
-	- Add $(MAN1) to `groffer'.
-
-	* perl/groffer.pl, perl/func.pl, shell/groffer2.sh:
-	- Add `groff' option with argument `-K'.
-	- Redesign the changed `grog'.
-
-2006-10-23  Bernd Warken  <groff-bernd.warken-72@web.de>
-	________________________________________________________________
-	* release of groffer 1.0.2
-
-	* perl/groffer.pl:
-	- Move all variable declarations out of BEGIN.
-	- Move all `use' commands outside of BEGIN.  Fix the arising
-	errors.
-	- Correct new position of perl/perl_test.pl.
-
-	* perl/func.pl:
-	- version(): Fix the determination of the version of groff.
-	- usage(): Sort it among the functions in this file.
-
-	* perl/groffer.man, shell/groffer.man: Fix string variable
-	Ellipsis.
-
-	* shell/README_SH: Add information on Autobook.
-
-	* shell/groffer.sh:
-	- Extent simple shell tests by testing on support for functions.
-	Test standard shell on function support.  Add error reports on
-	shell tests.
-	- Set unset variables LANG LC_ALL LC_MESSAGES LC_CTYPES LANGUAGES
-	to `C', according to Autobook, ch. 22.
-	- Remove option `-e' from `sed'.
-
-	* shell/groffer2.sh:
-	- Add test on directory in man path find.
-	- Add Bourne compatibility for zsh shell.
-	- Replace `echo -n ""' by `:'.
-	- Remove -e option from sed.
-
-2006-10-23  Werner Lemberg
-
-	* perl_test.pl: Moved to...
-	* perl/perl_test.pl: Here.
-
-	* Makefile.sub: Rewritten.  Change PERL to HAVE_PERL and SHELL to
-	HAVE_SHELL.
-
-2006-10-14  Bernd Warken  <groff-bernd.warken-72@web.de>
-	________________________________________________________________
-	* release of groffer 1.0.1
-
-	* perl/groffer.pl: Change $perl_test_pl to $file_perl_test_pl.
-
-	* perl/groffer.pl, perl/func.pl: Remove `\n' in `die' calls.
-
-2006-10-12  Bernd Warken  <groff-bernd.warken-72@web.de>
-	________________________________________________________________
-	* 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.
-
-2006-10-02  Bernd Warken  <groff-bernd.warken-72@web.de>
-
-	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.
-
-	The former part of the ChangeLog file is in `shell/ChangeLog.0'.
-
-2006-10-01  Bernd Warken  <groff-bernd.warken-72@web.de>
-________________________________________________________________
-License
-
-Copyright (C) 2006-2009, 2011
-	Free Software Foundation, Inc.
-Written by Bernd Warken <groff-bernd.warken-72@web.de>.
-
-Copying and distribution of this file, with or without
-modification, are permitted provided the copyright notice and this
-notice are preserved.
-
-This file is part of `groffer', which is part of the `groff'
-project.
-
-####### Emacs settings
-
-Local Variables:
-mode: change-log
-End:

Index: groffer/Makefile.sub
===================================================================
RCS file: groffer/Makefile.sub
diff -N groffer/Makefile.sub
--- groffer/Makefile.sub	22 Jan 2013 00:29:40 -0000	1.33
+++ /dev/null	1 Jan 1970 00:00:00 -0000
@@ -1,149 +0,0 @@
-# Makefile.sub for `groffer' (integration into the `groff' source tree)
-
-# File position: <groff-source>/contrib/groffer/Makefile.sub
-
-# Copyright (C) 2001, 2002, 2005, 2006, 2009, 2011
-#   Free Software Foundation, Inc.
-# Written by Werner Lemberg <wl@gnu.org> and
-# Bernd Warken <groff-bernd.warken-72@web.de>.
-
-# Last update: 17 Oct 2011
-
-# 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/>.
-
-########################################################################
-
-ROFF2MODES=dvi html pdf ps text x
-ROFF2PROGS=`echo $(ROFF2MODES) | sed 's/[a-z][a-z]*/roff2&/g'`
-ROFF2MAN=`echo $(ROFF2MODES) | sed 's/[a-z][a-z]*/roff2&.man/g'`
-ROFF2MANN=`echo $(ROFF2MODES) | sed 's/[a-z][a-z]*/roff2&.n/g'`
-
-MAN1=groffer.n \
-     roff2dvi.n \
-     roff2html.n \
-     roff2pdf.n \
-     roff2ps.n \
-     roff2text.n \
-     roff2x.n
-
-MOSTLYCLEANADD=groffer HAVE_PERL HAVE_SHELL groffer.man \
-               $(MAN1) $(ROFF2MAN) $(ROFF2PROGS)
-
-# not all make programs have $(RM) predefined.
-RM=rm -f
-
-all: groffer
-
-GROFFER_PERL=$(srcdir)/perl/func.pl \
-             $(srcdir)/perl/man.pl \
-             $(srcdir)/perl/perl_test.pl \
-             $(srcdir)/perl/split_env.sh
-GROFFER_SHELL=$(srcdir)/shell/groffer2.sh
-GROFFER_REST=$(srcdir)/roff2.man \
-             $(srcdir)/version.sh \
-             $(srcdir)/perl/groffer.man \
-             $(srcdir)/perl/groffer.pl \
-             $(srcdir)/perl/roff2.pl \
-             $(srcdir)/shell/roff2.sh \
-             $(srcdir)/shell/groffer.man \
-             $(srcdir)/shell/groffer.sh
-
-GROFFER_PERL_=`echo $(GROFFER_PERL) | sed 's|$(srcdir)/perl/||g'`
-GROFFER_SHELL_=`echo $(GROFFER_SHELL) | sed 's|$(srcdir)/shell||g'`
-
-# TODO: Add perl check to configure script.
-groffer: $(GROFFER_PERL) $(GROFFER_SHELL) \
-         $(GROFFER_REST) $(SH_DEPS_SED_SCRIPT)
-	if perl $(srcdir)/perl/perl_test.pl 2>&1 >/dev/null; then \
-	  : >HAVE_PERL; \
-	  echo "Using perl version of groffer."; \
-	  sed -f "$(SH_DEPS_SED_SCRIPT)" \
-            -e "s|@g@|$(g)|g" \
-	    -e "s|@BINDIR@|$(DESTDIR)$(bindir)|g" \
-	    -e "s|@libdir@|$(DESTDIR)$(libdir)|g" \
-	    -e "s|@groffer_dir@|$(DESTDIR)$(groffer_dir)|g" \
-	    -e "s|@VERSION@|$(version)$(revision)|g" \
-	    -e "$(SH_SCRIPT_SED_CMD)" \
-	    $(srcdir)/perl/groffer.pl >$@; \
-	  cp $(srcdir)/perl/groffer.man groffer.man; \
-	  for f in $(ROFF2PROGS); do \
-	    cp $(srcdir)/perl/roff2.pl $$f; \
-	  done; \
-	else \
-	  : >HAVE_SHELL; \
-	  echo "Using shell version of groffer."; \
-	  sed -f "$(SH_DEPS_SED_SCRIPT)" \
-            -e "s|@g@|$(g)|g" \
-	    -e "s|@BINDIR@|$(DESTDIR)$(bindir)|g" \
-	    -e "s|@libdir@|$(DESTDIR)$(libdir)|g" \
-	    -e "s|@groffer_dir@|$(DESTDIR)$(groffer_dir)|g" \
-	    -e "s|@VERSION@|$(version)$(revision)|g" \
-	    -e "$(SH_SCRIPT_SED_CMD)" \
-            $(srcdir)/shell/groffer.sh >$@; \
-	  cp $(srcdir)/shell/groffer.man groffer.man; \
-	  for f in $(ROFF2PROGS); do \
-	    cp $(srcdir)/shell/roff2.sh $$f; \
-	  done; \
-	fi
-	chmod +x $@
-	for m in $(ROFF2MODES); do \
-	  cat $(srcdir)/roff2.man \
-	  | sed 's/@ROFF2MODE@/'"$$m"'/g' > roff2$${m}.man; \
-	done
-
-install_data: groffer
-	-test -d $(DESTDIR)$(bindir) || $(mkinstalldirs) $(DESTDIR)$(bindir)
-	$(RM) $(DESTDIR)$(bindir)/groffer
-	$(INSTALL_SCRIPT) groffer $(DESTDIR)$(bindir)/groffer
-	for f in $(ROFF2PROGS); do \
-	  $(RM) $(DESTDIR)$(bindir)/$$f; \
-	  $(INSTALL_SCRIPT) $$f $(DESTDIR)$(bindir)/$$f; \
-	done
-	-test -d $(DESTDIR)$(groffer_dir) \
-          || $(mkinstalldirs) $(DESTDIR)$(groffer_dir)
-	$(RM) $(DESTDIR)$(groffer_dir)/version.sh
-	$(INSTALL_DATA) $(srcdir)/version.sh \
-          $(DESTDIR)$(groffer_dir)/version.sh
-	for f in $(GROFFER_PERL_) $(GROFFER_SHELL_); do \
-          $(RM) $(DESTDIR)$(groffer_dir)/$$f; \
-        done
-	if test -f HAVE_PERL; then \
-          for f in $(GROFFER_PERL_); do \
-            $(INSTALL_SCRIPT) $(srcdir)/perl/$$f \
-              $(DESTDIR)$(groffer_dir)/$$f; \
-          done; \
-        elif test -f HAVE_SHELL; then \
-          for f in $(GROFFER_SHELL_); do \
-            $(INSTALL_SCRIPT) $(srcdir)/shell/$$f \
-              $(DESTDIR)$(groffer_dir)/$$f; \
-          done; \
-        fi;
-
-uninstall_sub:
-	$(RM) $(DESTDIR)$(bindir)/groffer
-	for f in $(ROFF2PROGS); do $(RM) $(DESTDIR)$(bindir)/$$f; done
-	for f in $(GROFFER_PERL_) $(GROFFER_SHELL_) version.sh; do \
-          $(RM) $(DESTDIR)$(groffer_dir)/$$f; \
-        done
-	-rmdir $(DESTDIR)$(libdir)/groff/groffer
-
-########################################################################
-# Emacs settings
-########################################################################
-#
-# Local Variables:
-# mode: makefile
-# End:

Index: groffer/README
===================================================================
RCS file: groffer/README
diff -N groffer/README
--- groffer/README	22 Jan 2013 00:29:40 -0000	1.15
+++ /dev/null	1 Jan 1970 00:00:00 -0000
@@ -1,123 +0,0 @@
-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 <groff-bernd.warken-72@web.de>.
-
-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:

Index: groffer/roff2.man
===================================================================
RCS file: groffer/roff2.man
diff -N groffer/roff2.man
--- groffer/roff2.man	22 Jan 2013 00:29:40 -0000	1.6
+++ /dev/null	1 Jan 1970 00:00:00 -0000
@@ -1,249 +0,0 @@
-.ig
-roff2@ROFF2MODE@.1 - man page for roff2@ROFF2MODE@ (section 1).
-
-Source file position: <groff_source_top>/contrib/groffer/roff2.man
-Installed position:   $prefix/share/man/man1/roff2@ROFF2MODE@.1
-
-Last update: 5 Jan 2009
-Simplified to use .SY/.OP/.YS
-..
-.
-.
-.de au
-This file was written by Bernd Warken <groff-bernd.warken-72@web.de>.
-..
-.
-.
-.de co
-Copyright (C) 2006, 2007, 2009 Free Software Foundation, Inc.
-.
-.P
-This file is part of
-.IR \%groffer ,
-which is part of
-.IR \%groff ,
-a free software project.
-.
-You can redistribute it and/or modify it under the terms of the
-.nh
-.B "GNU General Public License"
-.hy
-as published by the
-.nh
-.BR "Free Software Foundation" ,
-.hy
-either version\~2, or (at your option) any later version.
-.
-.P
-You should have received a copy of the \f[CR]GNU General Public
-License\f[] along with
-.IR groff ,
-see the files \%\f[CB]COPYING\f[] and \%\f[CB]LICENSE\f[] in the top
-directory of the
-.I groff
-source package.
-.
-Or read the
-.I man\~page
-.BR gpl (1).
-You can also write to the
-.nh
-.B "Free Software Foundation, 51 Franklin St - Fifth Floor, Boston,"
-.BR "MA 02110-1301, USA" .
-.hy
-..
-.
-.
-.TH roff2@ROFF2MODE@ @MAN1EXT@ "@MDATE@" "Groff Version @VERSION@"
-.SH NAME
-roff2@ROFF2MODE@ \- transform roff code into @ROFF2MODE@ mode
-.
-.
-.\" --------------------------------------------------------------------
-.SH "SYNOPSIS"
-.
-.SY roff2@ROFF2MODE@
-.RI [ \%groffer_option .\|.\|.\&]
-.OP \-\-
-.RI [ \%filespec .\|.\|.\&]
-.
-.SY roff2@ROFF2MODE@
-.B \-h
-|
-.B \-\-help
-.
-.SY roff2@ROFF2MODE@
-.B \-v
-|
-.B \-\-version
-.YS
-.
-.P
-The options
-.B \-v
-and
-.B \%\-\-version
-print the version information of the program to standard output and exit.
-.
-The options
-.B \-h
-and
-.B \-\-help
-print a usage information of the program to standard output and stop
-the program instantly.
-.
-.
-.P
-All other options are assumed to be
-.B \%groffer
-options.
-.
-They are internally passed to
-.BR \%groffer .
-They override the behavior of the program.
-.
-The options are optional, they can be omitted.
-.
-.
-.P
-The
-.I \%filespec
-arguments correspond to the
-.I \%filespec
-arguments of
-.BR \%groffer .
-So they are either the names of existing, readable files or
-.B \-
-for standard input, or the name of a man page or a
-.BR \%groffer (@MAN1EXT@)
-man page search pattern.
-.
-If no
-.I \%filespec
-is specified standard input is assumed automatically.
-.
-.
-.\" --------------------------------------------------------------------
-.SH DESCRIPTION
-.
-.B \%roff2@ROFF2MODE@
-transforms
-.I roff
-code into
-.ie '@ROFF2MODE@'x' \{\
-.  I X
-mode corresponding to the
-.  I groff
-devices
-.  BR X *;
-this mode is suitable for
-.  BR \%gxditview (@MAN1EXT@).
-.\}
-.el \{\
-.  I \%@ROFF2MODE@
-mode.
-.\}
-.
-Print the result to standard output.
-.
-.
-.P
-There are more of these programs for generating other formats of
-.I \%roff
-input.
-.
-.if !'@ROFF2MODE@'dvi' \{\
-.  TP
-.  BR \%roff2dvi (@MAN1EXT@)
-is for
-.  I dvi
-mode.
-.\}
-.
-.if !'@ROFF2MODE@'html' \{\
-.  TP
-.  BR \%roff2html (@MAN1EXT@)
-generates
-.  I html
-output.
-.\}
-.
-.if !'@ROFF2MODE@'pdf' \{\
-.  TP
-.  BR \%roff2pdf (@MAN1EXT@)
-outputs
-.  I pdf
-mode.
-.\}
-.
-.if !'@ROFF2MODE@'ps' \{\
-.  TP
-.  BR \%roff2ps (@MAN1EXT@)
-prints
-.  I \%PostScript
-format to standard output.
-.\}
-.
-.if !'@ROFF2MODE@'text' \{\
-.  TP
-.  BR \%roff2text (@MAN1EXT@)
-generates text output in the
-.  B groff
-device
-.  IR latin1 .
-.\}
-.
-.if !'@ROFF2MODE@'x' \{\
-.  TP
-.  BR \%roff2x (@MAN1EXT@)
-prints the output in the
-.  B groff
-device
-.  B X
-that is suitable for programs like
-.  BR \%gxditview (@MAN1EXT@)
-or
-.  BR \%xditview (1).
-.\}
-.
-.
-.\" --------------------------------------------------------------------
-.SH "SEE ALSO"
-.\" --------------------------------------------------------------------
-.
-.BR \%groff (@MAN1EXT@),
-.BR \%groffer (@MAN1EXT@),
-.if !'@ROFF2MODE@'dvi' \
-.  BR \%roff2dvi (@MAN1EXT@),
-.if !'@ROFF2MODE@'html' \
-.  BR \%roff2html (@MAN1EXT@),
-.if !'@ROFF2MODE@'pdf' \
-.  BR \%roff2pdf (@MAN1EXT@),
-.if !'@ROFF2MODE@'ps' \
-.  BR \%roff2ps (@MAN1EXT@),
-.if !'@ROFF2MODE@'text' \
-.  BR \%roff2text (@MAN1EXT@),
-.if !'@ROFF2MODE@'x' \
-.  BR \%roff2x (@MAN1EXT@),
-.BR \%gxditview (@MAN1EXT@).
-.
-.
-.\" --------------------------------------------------------------------
-.SH "AUTHOR"
-.\" --------------------------------------------------------------------
-.au
-.
-.
-.\" --------------------------------------------------------------------
-.SH "COPYING"
-.\" --------------------------------------------------------------------
-.co
-.
-.
-.\" --------------------------------------------------------------------
-.\" Emacs settings
-.\" --------------------------------------------------------------------
-.
-.\" Local Variables:
-.\" mode: nroff
-.\" End:

Index: groffer/version.sh
===================================================================
RCS file: groffer/version.sh
diff -N groffer/version.sh
--- groffer/version.sh	29 Mar 2013 22:11:11 -0000	1.21
+++ /dev/null	1 Jan 1970 00:00:00 -0000
@@ -1,38 +0,0 @@
-#! /bin/sh
-
-# groffer - display groff files
-
-# Source file position: <groff-source>/contrib/groffer/version.sh
-# Installed position: <prefix>/lib/groff/groffer/version.sh
-
-# Copyright (C) 2001-2006, 2009, 2011, 2013
-#   Free Software Foundation, Inc.
-# Written by Bernd Warken <groff-bernd.warken-72@web.de>.
-
-# 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/>.
-
-########################################################################
-
-export _PROGRAM_VERSION;
-export _LAST_UPDATE;
-
-_PROGRAM_VERSION='1.1.3';
-_LAST_UPDATE='29 Mar 2013';
-
-# this setting of the groff version is only used before make is run,
-# otherwise @VERSION@ will set it, see groffer.sh.
-export _GROFF_VERSION_PRESET;
-_GROFF_VERSION_PRESET='1.22.2';

Index: groffer/perl/README_PERL
===================================================================
RCS file: groffer/perl/README_PERL
diff -N groffer/perl/README_PERL
--- groffer/perl/README_PERL	22 Jan 2013 00:29:40 -0000	1.4
+++ /dev/null	1 Jan 1970 00:00:00 -0000
@@ -1,263 +0,0 @@
-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 <groff-bernd.warken-72@web.de>.
-
-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:

Index: groffer/perl/func.pl
===================================================================
RCS file: groffer/perl/func.pl
diff -N groffer/perl/func.pl
--- groffer/perl/func.pl	22 Jan 2013 00:29:40 -0000	1.8
+++ /dev/null	1 Jan 1970 00:00:00 -0000
@@ -1,789 +0,0 @@
-#! /usr/bin/env perl
-
-# groffer - display groff files
-
-# Source file position: <groff-source>/contrib/groffer/perl/func.pl
-# Installed position: <prefix>/lib/groff/groffer/func.pl
-
-# Copyright (C) 2006, 2009 Free Software Foundation, Inc.
-# Written by Bernd Warken <groff-bernd.warken-72@web.de>.
-
-# Last update: 5 Jan 2009
-
-# 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/>.
-
-########################################################################
-
-use strict;
-use warnings;
-
-########################################################################
-# some functions
-########################################################################
-
-##########
-# cat_z(<file>)
-#
-# Decompress or cat the <file>.
-#
-# Return: the decompressed file as array
-#
-sub cat_z {
-  my $n = @_;
-  die "cat_z(): one argument is needed; you used $n;"
-    unless $n == 1;
-
-  my $file = $_[0];
-  die "cat_z(): `$file' is not a readable file;" unless -f $file && -r $file;
-  return () if -z $file;
-
-  my @res;
-  if ($main::Has_Compression) {
-    if ($main::Has_bzip) {
-      # test whether bz2 compressed, shell return must be inverted
-      unless ( system("bzip2 -t $file 2>$main::Dev_Null") ) {
-	@res = `bzip2 -c -d $file 2>$main::Dev_Null`;
-	return @res;
-      }
-      # if not compressed with gz, gzip will act like `cat'
-      @res = `gzip -c -d -f $file 2>$main::Dev_Null`;
-      return @res;
-    }
-  } else {
-    my $fh;
-    open $fh, "<$file" or die "cat_z(): could not open $file";
-    @res = <$fh>;
-    close $fh;
-    return @res;
-  }
-  ();
-} # cat_z()
-
-
-##########
-# clean_up()
-#
-# Remove the temporary directory and restore the system.
-#
-sub clean_up {
-  umask $main::Umask;
-  chdir $main::Start_Dir;
-  if ($main::Debug{'KEEP'} && -d $main::tmpdir) {
-    my $glob = File::Spec->catfile($main::tmpdir, '*');
-    unlink glob($glob);		# rm $tmpdir/*
-    rmdir $main::tmpdir;
-  }
-} # clean_up()
-
-
-##########
-# get_dirname(<path>)
-#
-# Split the path and return the directory name part
-#
-# Return: string of directory name
-#
-sub get_dirname {
-  my $n = @_;
-  die "get_filename(): one argument is needed; you used $n;" unless $n == 1;
-  return '' unless $_[0];
-
-  my ($dirname, $filename) = &split_path($_[0]);
-  $dirname;
-}				# get_dirname()
-
-
-##########
-# get_filename(<path>)
-#
-# Split the path and return the file name part
-#
-# Return: string of file name
-#
-sub get_filename {
-  my $n = @_;
-  die "get_dirname(): one argument is needed; you used $n;" unless $n == 1;
-  return '' unless $_[0];
-
-  my ($dirname, $filename) = &split_path($_[0]);
-  $filename;
-}				# get_filename()
-
-
-##########
-# is_X()
-#
-# Test whether X Windows is running.
-#
-sub is_X {
-  return 1 if $ENV{'DISPLAY'};
-  return 0;
-}				# is_X()
-
-
-##########
-# list_has(<list_ref>, <string>)
-#
-# Determine if <list_ref> has <string> as element.
-#
-sub list_has {
-  my $n = @_;
-  die "list_has(): 2 arguments are needed; you used $n;"
-    unless $n == 2;
-
-  my $list_ref = $_[0];
-  my $string = $_[1];
-  die "list_has(): first argument must be an array reference;"
-    unless ref($list_ref) eq 'ARRAY';
-
-  foreach ( @$list_ref ) {
-    return 1 if $_ eq $string;
-  }
-  0;
-}
-
-
-##########
-# path_uniq(<dir>...)
-#
-# make path having unique existing directories
-#
-sub path_uniq {
-  my @a;
-  my %h;
-  foreach (@_) {
-    next if exists $h{$_};
-    next unless -d $_;
-    push @a, $_;
-    $h{$_} = 1;
-  }
-  @a;
-}				# path_uniq()
-
-
-##########
-# print_hash(<hash_or_ref>)
-#
-# print the elements of a hash or hash reference
-#
-sub print_hash {
-  my $hr;
-  my $n = scalar @_;
-  if ($n == 0) {
-    print "empty hash\n;";
-    return 1;
-  } elsif ($n == 1) {
-    if (ref($_[0]) eq 'HASH') {
-      $hr = $_[0];
-    } else {
-      warn 'print_hash(): the argument is not a hash or hash reference;';
-      return 0;
-    }
-  } else {
-    if ($n % 2) {
-      warn 'print_hash(): the arguments are not a hash;';
-      return 0;
-    } else {
-      my %h = @_;
-      $hr = \%h;
-    }
-  }
-
-### print_hash()
-  unless (%$hr) {
-    print "empty hash\n";
-    return 1;
-  }
-  print "hash (ignore the ^ characters):\n";
-  for my $k (sort keys %$hr) {
-    my $hk = $hr->{$k};
-    print "  $k => ";
-    if (defined $hk) {
-      print "^$hk^";
-    } else {
-      print "undef";
-    }
-    print "\n";
-  }
-
-  1;
-}				# print_hash()
-
-
-##########
-# print_times(<string>)
-#
-# print the time, result: user, system, child process user, child system
-#
-sub print_times {
-  my @t = times;
-  my $s = '';
-  $s = $_[0] if $_[0];
-#  print STDERR "$s: @t\n";
-}				# print_times()
-
-BEGIN { &print_times("start"); }
-END { &print_times("end"); }
-
-
-##########
-# split_path(<path>)
-#
-# Split the path into directory and file name parts
-#
-# Return: array with 2 elements consisting of directory and file name
-#
-sub split_path {
-  my $n = @_;
-  die "split_path(): one argument is needed; you used $n;" unless $n == 1;
-  my $arg = $_[0];
-  return () unless $arg;
-
-  my $basename = basename($arg);
-  if ( $basename ne $arg ) { # path with dir
-    # fileparse() is from File::Basename
-    my($filename, $dirname, $suffix) = fileparse($arg);
-    return ($dirname, $basename);
-  }
-  return ('', $arg);
-}
-
-
-{
-  my $nr_file = 0;
-  my $nr_so = 0;
-
-  my $tmp_file_base;
-  my $tmp_so_base;
-
-  my $soelim_r = '';
-  $soelim_r = '-r'
-    if ! system("echo -n '' | soelim -r 2>$main::Dev_Null >$main::Dev_Null");
-
-  ##########
-  # to_tmp (<filename>)
-  #
-  # Print file (decompressed) to the temporary cat file with handling .SO
-  # for man pages.
-  #
-  sub to_tmp {
-    my $n = @_;
-    die "to_tmp(): one argument is needed; you used $n;"
-      unless $n == 1;
-
-    my $arg = $_[0];
-    return 1 unless $arg;
-    die "to_tmp(): $arg is not an existing file;" unless -f $arg;
-    die "to_tmp(): could not read file $arg;" unless -r $arg;
-    return 1 if -z $arg;
-
-    $tmp_file_base = File::Spec->catfile($main::tmpdir, ',file')
-      unless $tmp_file_base;
-    $tmp_so_base = File::Spec->catfile($main::tmpdir, ',so')
-      unless $tmp_so_base;
-
-    open $main::fh_cat, ">>$main::tmp_cat" or
-      die "to_tmp(): could not open temporary cat file";
-
-    if ($main::Opt{'WHATIS'}) {
-      &whatis_filename($arg);
-      return 1;
-    }
-
-    ### to_tmp()
-    my $dir = &get_dirname($arg);
-
-    my ($fh_file, $tmp_file, $fh_tmp, $tmp_tmp);
-    ++$nr_file;
-    $tmp_file = $tmp_file_base . $nr_file;
-    $tmp_tmp = File::Spec->catfile($main::tmpdir, ',tmp');
-
-    print STDERR "file: $arg\n" if $main::Debug{'FILENAMES'};
-
-    if ($main::Filespec_Is_Man) {
-      my ($fh_so, $tmp_so);
-
-      open $fh_file, ">$tmp_file" or
-	die "to_tmp(): could not open $tmp_file;";
-      foreach ( &cat_z($arg) ) {
-	print $fh_file "$_";
-      }
-      close $fh_file;
-
-      open $fh_file, "<$tmp_file" or
-	die "to_tmp(): could not open $tmp_file;";
-      my @list;
-      foreach (<$fh_file>) {
-	if (/^[\.']\s*so\s/) {
-	  chomp;
-	  s/^[\.']\s*so\s*//;
-	  push @list, $_;
-	}
-      }
-      close $fh_file;
-
-      if ( @list && $main::Debug{'KEEP'} ) {
-	my $f = $tmp_file . '+man';
-	copy($tmp_file, $f);
-      }
-
-      ### to_tmp()
-    DO_MAN_SO:  foreach (@list) {
-	# start of _do_man_so() in shell version
-	my $so = $_;
-	my $soname = $so;
-	$soname =~ s/\\\s/ /g;
-
-	my $sofound;
-	my $path = File::Spec->rootdir();
-	if ($soname =~ m#^$path#) {	  # absolute path name
-	  next DO_MAN_SO if -f $soname;
-	  foreach ('.gz', '.Z', '.bz2') {
-	    my $name = $soname . $_;
-	    if (-f $name) {
-	      $sofound = $name;
-	      last;
-	    }
-	  }			# foreach
-	  next DO_MAN_SO unless $sofound;
-	} else {		# relative to man path
-	LOOP: foreach my $ext ('', '.gz', '.Z', '.bz2') {
-	    foreach my $p ( @{$main::Man{'PATH'}} ) {
-	      my $f = File::Spec->catfile($p, "$soname$ext");
-	      if (-f $f) {
-		$sofound = $f if -f $f;
-		last LOOP;
-	      }
-	    }			# foreach
-	  }			# LOOP:
-	  next DO_MAN_SO unless $sofound;
-	}			# if on path
-
-	print STDERR "file from .so: $so\n" if $main::Debug{'FILENAMES'};
-
-	### to_tmp()
-	++$nr_so;
-	$tmp_so = $tmp_so_base . $nr_so;
-	unlink $tmp_so if -e $tmp_so;
-	open $fh_so, ">$tmp_so" or
-	  die "to_tmp(): could not open $tmp_so;";
-	foreach ( &cat_z($sofound) ) {
-	  print $fh_so $_;
-	}
-	close $fh_so;
-
-	my $esc = $so;
-	$esc =~ s/\\/\\\\/g;
-	open $fh_file, "<$tmp_file" or
-	  die "to_tmp(): could not open $tmp_file;";
-	open $fh_tmp, ">$tmp_tmp" or
-	  die "to_tmp(): could not open $tmp_tmp;";
-	foreach (<$fh_file>) {
-	  s#^([\.'])\s*so\s+($so|$esc|$soname)\s*\n$#${1}so $tmp_so\n#s;
-	  print $fh_tmp $_;
-	}
-	### to_tmp()
-	close $fh_tmp;
-	close $fh_file;
-	unlink $tmp_file if -e $tmp_file;
-	rename $tmp_tmp, $tmp_file;
-	# end of _do_man_so() in shell version
-      }				# foreach (@list)
-
-      if ( @list && $main::Debug{'KEEP'} ) {
-	my $f = $tmp_file . '+tmp';
-	copy($tmp_file, $f);
-      }
-
-      unlink $tmp_tmp if -e $tmp_tmp;
-      rename $tmp_file, $tmp_tmp;
-      system("soelim -I$dir $soelim_r $tmp_tmp >$tmp_file");
-      unlink $tmp_tmp if -e $tmp_tmp;
-
-    } else {			# $Filespec_Is_Man is empty
-      open $fh_tmp, ">$tmp_tmp" or
-	die "to_tmp(): could not open $tmp_tmp;";
-      foreach (cat_z $arg) {
-	print $fh_tmp $_;
-      }
-      close $fh_tmp;
-      if ($dir) {
-	system("soelim -I$dir $soelim_r $tmp_tmp >$tmp_file");
-      } else {
-	system("soelim $soelim_r $tmp_tmp >$tmp_file");
-      }
-      unlink $tmp_tmp;
-    }				# if ($Filespec_Is_Man)
-
-    ### to_tmp()
-    my $grog = `grog $tmp_file`;
-    die "to_tmp(): grog error on $tmp_file;" if $?;
-    chomp $grog;
-    print STDERR "grog output: $grog\n" if $main::Debug{'GROG'};
-    if ($grog =~ /^.*\s-m.*$/) {
-      $grog =~ s/\s+/ /g;
-      $grog =~ s/ -m / -m/g;
-      $grog =~ s/ -mm([^ ]) / -m$1/g;
-      foreach my $g (split / /, $grog) {
-	if ($g =~ /^-m/) {
-	  my $ref = \@main::Macro_Packages;
-	  if ( &list_has($ref, $g) ) {
-	    if (! $main::Macro_Pkg) {
-	      $main::Macro_Pkg = $g;
-	    } elsif ($main::Macro_Pkg eq $g) {
-	      1;
-	    } elsif ($main::Macro_Pkg =~ /^-m/) {
-	      warn "to_tmp(): Ignore $arg because it needs $g " .
-		"instead of $main::Macro_Pkg";
-	      unlink $tmp_file unless $main::Debug{'KEEP'};
-	      return 0;
-	    } elsif ($main::Macro_Pkg ne $g) {
-	      die "to_tmp(): \$Macro_Pkg does not start with -m: " .
-		"$main::Macro_Pkg";
-	    }			# if (! $main::Macro_Pkg)
-	  }			# if (&list_has
-	}			# if (/^-m/)
-      }				# foreach my $g
-    }				# if $grog
-
-    open $fh_file, "<$tmp_file" or
-      die "to_tmp(): could not open $tmp_file for reading;";
-    open $main::fh_cat, ">>$main::tmp_cat" or
-      die "to_tmp(): could not open $main::tmp_cat for appending;";
-    foreach (<$fh_file>) {
-      print $main::fh_cat $_;
-    }
-    close $main::fh_cat;
-    close $fh_file;
-
-    unless ( $main::Debug{'KEEP'} ) {
-      unlink $tmp_file;
-      foreach ( glob("$tmp_so_base*") ) {
-	unlink $_;
-      }
-    }
-    1;
-  }				# to_tmp()
-}
-
-##########
-# to_tmp_line (<text>...)
-#
-# Print array of lines with <text> to the temporary cat file.  \n is added
-# if a line does not end with \n.
-#
-sub to_tmp_line {
-  my $n = @_;
-  return 1 if $n == 0;
-  open $main::fh_cat, ">>$main::tmp_cat" or
-    die "to_tmp_line(): could not open temporary cat file";
-  foreach (@_) {
-    my $line = $_;
-    chomp($line);
-    print $main::fh_cat "$line\n";
-  }
-  close $main::fh_cat;
-  1;
-} # to_tmp_line()
-
-
-##########
-# usage()
-#
-# Print usage information for --help.
-#
-sub usage {
-  print "\n";
-  &version();
-  print <<EOF;
-
-Usage: groffer [option]... [filespec]...
-
-Display roff files, standard input, and/or Unix manual pages with an X
-Window viewer or in several text modes.  All input is decompressed
-on-the-fly with all formats that gzip can handle.
-
-"filespec" is one of
-  "filename"       name of a readable file
-  "-"              for standard input
-  "man:name(n)"    man page "name" in section "n"
-  "man:name.n"     man page "name" in section "n"
-  "man:name"       man page "name" in first section found
-  "name(n)"        man page "name" in section "n"
-  "name.n"         man page "name" in section "n"
-  "n name"         man page "name" in section "n"
-  "name"           man page "name" in first section found
-where `section' is a single character out of [1-9on], optionally followed
-by some more letters that are called the `extension'.
-
--h --help         print this usage message.
--T --device=name  pass to groff using output device "name".
--v --version      print version information.
--V                display the groff execution pipe instead of formatting.
--X                display with "gxditview" using groff -X.
--Z --ditroff --intermediate-output
-                  generate groff intermediate output without
-                  post-processing and viewing, like groff -Z.
-All other short options are interpreted as "groff" formatting options.
-
-The most important groffer long options are
-
---apropos=name    start man's "apropos" program for "name".
---apropos-data=name
-                  "apropos" for "name" in man's data sections 4, 5, 7.
---apropos-devel=name
-                  "apropos" for "name" in development sections 2, 3, 9.
---apropos-progs=name
-                  "apropos" for "name" in man's program sections 1, 6, 8.
---auto            choose mode automatically from the default mode list.
---default         reset all options to the default value.
---default-modes=mode1,mode2,...
-                  set sequence of automatically tried modes.
---dvi             display in a viewer for TeX device independent format.
---dvi-viewer=prog choose the viewer program for dvi mode.
---groff           process like groff, disable viewing features.
---help            display this helping output.
---html            display in a web browser.
---html-viewer=program
-                  choose the web browser for html mode.
---man             check file parameters first whether they are man pages.
---mode=auto|dvi|groff|html|pdf|ps|source|text|tty|www|x|X
-                  choose display mode.
---no-man          disable man-page facility.
---no-special      disable --all, --apropos*, and --whatis
---pager=program   preset the paging program for tty mode.
---pdf             display in a PDF viewer.
---pdf-viewer=prog choose the viewer program for pdf mode.
---ps              display in a Postscript viewer.
---ps-viewer=prog  choose the viewer program for ps mode.
---source          output as roff source.
---text            output in a text device without a pager.
---to-stdout       output the content of the mode file without display.
---tty             display with a pager on text terminal even when in X.
---tty-viewer=prog select a pager for tty mode; same as --pager.
---whatis          display the file name and description of man pages
---www             same as --html.
---www-viewer=prog same as --html-viewer
---x --X           display with "gxditview" using an X* device.
---x-viewer=prog   choose viewer program for x mode (X mode).
---X-viewer=prog   same as "--xviewer".
-
-The usual X Windows toolkit options transformed into GNU long options:
---background=color, --bd=size, --bg=color, --bordercolor=color,
---borderwidth=size, --bw=size, --display=Xdisplay, --fg=color,
---fn=font, --font=font, --foreground=color, --geometry=geom, --iconic,
---resolution=dpi, --rv, --title=text, --xrm=resource
-
-Long options of GNU "man":
---all, --ascii, --ditroff, --extension=suffix, --locale=language,
---local-file=name, --location, --manpath=dir1:dir2:...,
---sections=s1:s2:..., --systems=s1,s2,..., --where, ...
-
-Development options that are not useful for normal usage:
---debug, --debug-filenames, --debug-grog, --debug-keep, --debug-params,
---debug-tmpdir, --do-nothing, --print=text
-
-EOF
-} # usage()
-
-
-##########
-# version()
-#
-# Get version information from version.sh and print a text with this.
-#
-sub version {
-  my $groff_version;
-  my $program_version = '';
-  my $last_update = '';
-  my $groff_version_preset = '';
-
-  die "$main::File_version_sh does not exist;"
-    unless -f "$main::File_version_sh";
-  my $fh;
-  open $fh, "<$main::File_version_sh";
-  foreach (<$fh>) {
-    chomp;
-    if (/^\s*_PROGRAM_VERSION\s*=\s*['"]*([^'"]*)['"]*\s*;?\s*$/) {
-      $program_version = $1;
-      next;
-    }
-    if (/^\s*_LAST_UPDATE\s*=\s*['"]*([^'"]*)['"]*\s*;?\s*$/) {
-      $last_update = $1;
-      next;
-    }
-    if (/^\s*_GROFF_VERSION_PRESET\s*=\s*['"]*([^'"]*)['"]*\s*;?\s*$/) {
-      # this setting of the groff version is only used before make is run,
-      # otherwise @VERSION@ will set it, see groffer.sh.
-      $groff_version_preset = $1;
-      next;
-    }
-  }
-  close $fh;
-
-  if ($main::Groff_Version) {
-    $groff_version = $main::Groff_Version;
-  } else {
-    $groff_version = $groff_version_preset;
-  }
-  my $year = $last_update;
-  $year =~ s/^.* //;
-  print <<EOF;
-groffer $program_version of $last_update (Perl version)
-is part of groff version $groff_version.
-Copyright (C) $year Free Software Foundation, Inc.
-GNU groff and groffer come with ABSOLUTELY NO WARRANTY.
-You may redistribute copies of groff and its subprograms
-under the terms of the GNU General Public License.
-EOF
-} # version()
-
-
-##########
-# where_is_prog(<program>)
-#
-# Test whether <program> without its arguments exists or is a program
-# in $PATH.
-#
-# Arguments : 1, <program> can have spaces and arguments.
-# Return    : a hash with `dir', `file', `fullname', `args' if
-#             argument exists or is a program in $PATH, empty hash else.
-#
-sub where_is_prog {
-  scalar @_ eq 1 or die "where_is_prog(): only one argument is allowed";
-  my $p1 = $_[0];
-  return () unless $p1;
-
-  $p1 =~ s/\s+/ /g;
-  $p1 =~ s/(\\)+ / /g;
-  $p1 =~ s/^ | $//g;
-  return () unless $p1;
-
-  my $noarg = $p1;
-  $noarg =~ s/ -.*$//;
-  return () unless $noarg;
-
-  my $args;
-  if ($p1 =~ /^.* -.*$/) {
-    $args = $p1;
-    $args =~ s#^$noarg ##;
-  }
-  $args = '' unless defined $args;
-
-  my %result;
-
-  # test whether $noarg has directory, so it is not tested with $PATH
-  my ($dir, $name) = &split_path($noarg);
-  $result{'dir'} = $dir;
-
-### where_is_prog()
-  if (-f $noarg && -x $noarg) {
-    $result{'args'} = $args;
-    $result{'file'} = $name;
-    $result{'fullname'} = File::Spec->catfile($dir, $name);
-    return %result;
-  }
-
-  if ($dir) {			# $noarg has name with directory
-    # now $wip_noarg (with directory) is not an executable file
-
-    # test name with space
-    if ($name =~ / /) {
-      my @base = split(/ /, $name);
-      my $n = pop @base;
-      my @baseargs = ($n);
-      while (@base) {
-	my $base = join(' ', @base);
-	my $file = File::Spec->catpath($dir, $base);
-	if (-f $file && -x $file) {
-	  my $baseargs = join(' ', @baseargs);
-	  ### where_is_prog()
-	  if ($args) {
-	    $args = "$baseargs $args";
-	  } else {
-	    $args = $baseargs;
-	  }
-	  $result{'args'} = $args;
-	  $result{'file'} = $base;
-	  $result{'fullname'} = $file;
-	  return %result;
-	}			# file test $file
-	$n = pop @base;
-	unshift(@baseargs, $n);
-      }				# while (@base)
-    }				# end of test name with space
-    return ();
-  }				# test on $dir
-
-  # now $noarg doesn't have a directory part
-
-  $name = $noarg;
-
-  # check with $PATH
-
-  # test path with $win_noarg as a whole, evt. with spaces
-  foreach my $d (@main::Path) {
-    my $file = File::Spec->catfile($d, $name);
-    if (-f $file && -x $file) {
-      $result{'args'} = $args;
-      $result{'fullname'} = $file;
-      ($result{'dir'}, $result{'file'}) = &split_path($file);
-      return %result;
-    }				# file test $file
-  }				# foreach (@main::Path)
-
-### where_is_prog()
-  if ($name =~ / /) {
-    my @base = split(/ /, $name);
-    my $n = pop @base;
-    my @baseargs = ($n);
-    while (@base) {
-      my $base = join(' ', @base);
-      foreach my $d (@maon::Path) {
-	my $file = File::Spec->catfile($d, $base);
-	if (-f $file && -x $file) {
-	  my $baseargs = join(' ', @baseargs);
-	  if ($args) {
-	    $args = "$baseargs $args";
-	  } else {
-	    $args = $baseargs;
-	  }
-	  $result{'args'} = $args;
-	  $result{'fullname'} = $file;
-	  ($result{'dir'}, $result{'file'}) = &split_path($file);
-	  return %result;
-	}			# file test $file
-      }				# foreach (@main::Path)
-      $n = pop @base;
-      unshift(@baseargs, $n);
-    }				# while (@base)
-  }				# test $name on space
-  return ();
-} # where_is_prog()
-
-
-##########
-# wait()
-#
-# stop for checking temp files, etc.
-#
-sub wait {
-  print "push Ctrl-D";
-  my @x = <STDIN>;
-  print "\n";
-}				# wait()
-
-1;

Index: groffer/perl/groffer.man
===================================================================
RCS file: groffer/perl/groffer.man
diff -N groffer/perl/groffer.man
--- groffer/perl/groffer.man	1 Feb 2013 08:12:27 -0000	1.19
+++ /dev/null	1 Jan 1970 00:00:00 -0000
@@ -1,3920 +0,0 @@
-.TH GROFFER @MAN1EXT@ "@MDATE@" "Groff Version @VERSION@"
-.SH NAME
-groffer \- display groff files and man\~pages on X and tty
-.
-.SH "SYNOPSIS"
-.\" The .SH was moved to this place in order to appease `apropos'.
-.
-.\" --------------------------------------------------------------------
-.\" Legalese
-.\" --------------------------------------------------------------------
-.
-.de author
-This file was written by Bernd Warken <groff-bernd.warken-72@web.de>.
-..
-.de copyleft
-Copyright (C) 2001, 2002, 2004-2006, 2009-2012
-  Free Software Foundation, Inc.
-.
-.P
-This file is part of
-.IR \%groffer ,
-which is part of
-.IR \%groff ,
-a free software project.
-.
-You can redistribute it and/or modify it under the terms of the
-.nh
-.B GNU General Public License
-.hy
-as published by the
-.nh
-.BR "Free Software Foundation" ,
-.hy
-either version 3 of the License, or (at your option) any later version.
-.
-.P
-You should have received a copy of the \f[CR]GNU General Public
-License\f[] along with
-.IR groff ,
-see the files \%\f[CB]COPYING\f[] and \%\f[CB]LICENSE\f[] in the top
-directory of the
-.I groff
-source package.
-.
-Or read the
-.I man\~page
-.BR gpl (1).
-You can also visit
-.nh
-.B <http://www.gnu.org/licenses/>.
-.hy
-..
-.
-.\" --------------------------------------------------------------------
-.\" Setup
-.\" --------------------------------------------------------------------
-.
-.ds Ellipsis "\&.\|.\|.\&\"
-.
-.\" --------------------------------------------------------------------
-.\" Macro definitions
-.
-.\" --------------------------------------------------------------------
-.\" .CB  (<text>...)
-.\"
-.\" Print in constant-width bold font.
-.\"
-.de CB
-.  ft CB
-.  Text \\$*
-.  ft
-..
-.\" --------------------------------------------------------------------
-.\" .CI  (<text>...)
-.\"
-.\" Print in constant-width italic font.
-.\"
-.de CI
-.  ft CI
-.  Text \\$*
-.  ft
-..
-.\" --------------------------------------------------------------------
-.\" .CR  (<text>...)
-.\"
-.\" Print in constant-width roman font.
-.\"
-.de CR
-.  ft CR
-.  Text \\$*
-.  ft
-..
-.\" --------------------------------------------------------------------
-.\" .Error  (<text>...)
-.\"
-.\" Print error message to terminal and abort.
-.\"
-.de Error
-.  tm \\$*
-.  ab
-..
-.\" --------------------------------------------------------------------
-.\" .Env_var  (<env_var_name> [<punct>])
-.\"
-.\" Display an environment variable, with optional punctuation.
-.\"
-.de Env_var
-.  nh
-.  SM
-.  Text \f[CB]\\$1\f[]\\$2
-.  hy
-..
-.\" --------------------------------------------------------------------
-.\" .File_name  (<path_name>)
-.\"
-.\" Display a file or directory name in CB font.
-.\"
-.de File_name
-.  Header_CB \\$@
-..
-.\" --------------------------------------------------------------------
-.\" .Header_CB  (<path_name>)
-.\"
-.\" Display a line in CB font, for example after .TP
-.\"
-.de Header_CB
-.  nh
-.  Text \f[CB]\\$1\f[]\\$2
-.  hy
-..
-.\"  --------------------------------------------------------------------
-.\" .Text  (<text>...)
-.\"
-.\" Treat the arguments as text, no matter how they look.
-.\"
-.de Text
-.  if \\n[.$]=0 \
-.    return
-.  nh
-.  nop \)\\$*\)
-.  hy
-..
-.\" --------------------------------------------------------------------
-.\" .Topic  ([<indent>])
-.\"
-.\" A bulleted paragraph
-.\"
-.de Topic
-.  ie \\n[.$]=0 \
-.    ds @indent 2m\"
-.  el \
-.    ds @indent \\$1\"
-.  IP \[bu] \\*[@indent]
-.  rm @indent
-..
-
-.\" End of macro definitions
-.
-.
-.\" --------------------------------------------------------------------
-.\" SH "SYNOPSIS"
-.\" --------------------------------------------------------------------
-.
-.SY groffer
-.OP option \*[Ellipsis]
-.OP --
-.OP \%filespec \*[Ellipsis]
-.YS
-.
-.SY groffer
-.BR -h | --help
-.YS
-.
-.SY groffer
-.BR -v | --version
-.YS
-.
-.
-.\" --------------------------------------------------------------------
-.SH DESCRIPTION
-.\" --------------------------------------------------------------------
-.
-The
-.B \%groffer
-program is the easiest way to use
-.BR \%groff (@MAN1EXT@).
-It can display arbitrary documents written in the
-.I \%groff
-language, see
-.BR \%groff (@MAN7EXT@),
-or other
-.I \%roff
-languages, see
-.BR \%roff (@MAN7EXT@),
-that are compatible to the original
-.I \%troff
-language.
-.
-It finds and runs all necessary
-.I groff
-preprocessors, such as
-.BR @g@chem .
-.
-.
-.P
-The
-.B \%groffer
-program also includes many of the features for finding and displaying
-the \%\f[CR]Unix\f[] manual pages
-.nh
-.RI ( man\~pages ),
-.hy
-such that it can be used as a replacement for a
-.BR \%man (1)
-program.
-.
-Moreover, compressed files that can be handled by
-.BR \%gzip (1)
-or
-.BR \%bzip2 (1)
-are decompressed on-the-fly.
-.
-.
-.P
-The normal usage is quite simple by supplying a file name or name of a
-.I \%man\~page
-without further options.
-.
-But the option handling has many possibilities for creating special
-behaviors.
-.
-This can be done either in configuration files, with the shell
-environment variable
-.Env_var \%$GROFFER_OPT ,
-or on the command line.
-.
-.
-.P
-The output can be generated and viewed in several different ways
-available for
-.IR \%groff .
-.
-This includes the
-.I \%groff
-native \%\f[CR]X\~Window\f[] viewer
-.BR \%gxditview (@MAN1EXT@),
-each
-.IR \%Postcript ,
-.IR \%pdf ,
-or
-.I \%dvi
-display program, a web browser by generating
-.I \%html
-in
-.IR \%www\~mode ,
-or several
-.I \%text\~modes
-in text terminals.
-.
-.
-.P
-Most of the options that must be named when running
-.B \%groff
-directly are determined automatically for
-.BR \%groffer ,
-due to the internal usage of the
-.BR \%grog (@MAN1EXT@)
-program.
-.
-But all parts can also be controlled manually by arguments.
-.
-.
-.P
-Several file names can be specified on the command line arguments.
-.
-They are transformed into a single document in the normal way of
-.BR \%groff .
-.
-.
-.P
-Option handling is done in \f[CR]GNU\f[] style.
-.
-Options and file names can be mixed freely.
-.
-The option
-.RB ` \-\- '
-closes the option handling, all following arguments are treated as
-file names.
-.
-Long options can be abbreviated in several ways.
-.
-.
-.\" --------------------------------------------------------------------
-.SH "OPTION OVERVIEW"
-.\" --------------------------------------------------------------------
-.
-.TP
-.I breaking options
-.RS
-.P
-.SY
-.OP -h\~\fR|\fB\~--help
-.OP -v\~\fR|\fB\~--version
-.YS
-.RE
-.
-.
-.TP
-.I \%groffer mode options
-.RS
-.P
-.SY
-.OP --auto
-.OP --default
-.OP --default\-modes mode1,mode2,\*[Ellipsis]
-.OP --dvi
-.OP --dvi\-viewer prog
-.OP --groff
-.OP --html
-.OP --html\-viewer prog
-.OP --mode display_mode
-.OP --pdf
-.OP --pdf\-viewer prog
-.OP --ps
-.OP --ps\-viewer prog
-.OP --source
-.OP --text
-.OP --to\-stdout
-.OP --tty
-.OP --tty\-viewer prog
-.OP --www
-.OP --www\-viewer prog
-.OP --x\~\fR|\fB\~--X
-.OP --x\-viewer\~\fR|\fB\~--X\-viewer prog
-.YS
-.RE
-.
-.
-.TP
-.I options related to \%groff
-.RS
-.P
-.SY
-.OP -T\~\fR|\fB\~--device device
-.OP -Z\~\fR|\fB\~--intermediate\-output\~\fR|\fB\~--ditroff
-.YS
-.P
-All further
-.B \%groff
-short options are accepted.
-.RE
-.
-.
-.TP
-.I options for man\~pages
-.RS
-.P
-.SY
-.OP --apropos
-.OP --apropos\-data
-.OP --apropos\-devel
-.OP --apropos\-progs
-.OP --man
-.OP --no\-man
-.OP --no\-special
-.OP --whatis
-.YS
-.RE
-.
-.
-.TP
-.I long options taken over from GNU man
-.RS
-.P
-.SY
-.OP --all
-.OP --ascii
-.OP --ditroff
-.OP --extension suffix
-.OP --locale language
-.OP --local\-file
-.OP --location\~\fR|\fB\~--where
-.OP --manpath dir1:dir2:\*[Ellipsis]
-.OP --no\-location
-.OP --pager program
-.OP --sections sec1:sec2:\*[Ellipsis]
-.OP --systems sys1,sys2,\*[Ellipsis]
-.OP --troff\-device device
-.YS
-.P
-Further long options of \f[CR]GNU\f[]
-.B man
-are accepted as well.
-.RE
-.
-.
-.TP
-.I X Window Toolkit options
-.RS
-.P
-.SY
-.OP --bd\~\fR|\fB\~--bordercolor pixels
-.OP --bg\~\fR|\fB\~--background color
-.OP --bw\~\fR|\fB\~--borderwidth pixels
-.OP --display X-display
-.OP --fg\~\fR|\fB\~--foreground color
-.OP --fn\~\fR|\fB\~--ft\~\fR|\fB\~--font font_name
-.OP --geometry size_pos
-.OP --resolution value
-.OP --rv
-.OP --title string
-.OP --xrm X\-resource
-.YS
-.RE
-.
-.
-.TP
-.I options for development
-.RS
-.P
-.SY
-.OP --debug
-.OP --debug\-filenames
-.OP --debug\-grog
-.OP --debug\-keep
-.OP --debug\-params
-.OP --debug\-tmpdir
-.OP --do\-nothing
-.OP --print text
-.OP -V
-.YS
-.RE
-.
-.
-.TP
-.I \%filespec arguments
-.RS
-.P
-The
-.I \%filespec
-parameters are all arguments that are neither an option nor an option
-argument.
-.
-They usually mean a file name or a
-.I man page
-searching scheme.
-.
-.
-.P
-In the following, the term
-.I section_extension
-is used.
-.
-It means a word that consists of a
-.I man section
-that is optionally followed by an
-.IR extension .
-.
-The name of a
-.I man section
-is a single character from
-.BR \%[1-9on] ,
-the
-.I extension
-is some word.
-.
-The
-.I extension
-is mostly lacking.
-.
-.
-.P
-No
-.I \%filespec
-parameters means standard input.
-.
-.
-.TP 10m
-.B -
-stands for standard input (can occur several times).
-.
-.
-.TP
-.I filename
-the path name of an existing file.
-.
-.
-.TP
-.BI man: name ( section_extension )
-.TQ
-.BI man: name . section_extension
-.TQ
-.IB name ( section_extension )
-.TQ
-.IB name . section_extension
-.TQ
-.I "section_extension name"
-search the \%man\~page
-.I \%name
-in the section with optional extension
-.IR section_extension .
-.
-.
-.TP
-.BI man: name
-\%man\~page in the lowest
-.I \%man\~section
-that has
-.IR \%name .
-.
-.
-.TP
-.I name
-if
-.I \%name
-is not an existing file search for the man\~page
-.I \%name
-in the lowest man\~section.
-.
-.RE
-.
-.
-.\" --------------------------------------------------------------------
-.SH "OPTION DETAILS"
-.\" --------------------------------------------------------------------
-.
-The
-.B \%groffer
-program can usually be run with very few options.
-.
-But for special purposes, it supports many options.
-.
-These can be classified in 5 option classes.
-.
-.
-.P
-All short options of
-.B \%groffer
-are compatible with the short options of
-.BR \%groff (@MAN1EXT@).
-.
-All long options of
-.B \%groffer
-are compatible with the long options of
-.BR \%man (1).
-.
-.
-.P
-Arguments for long option names can be abbreviated in several ways.
-.
-First, the argument is checked whether it can be prolonged as is.
-.
-Furthermore, each minus sign
-.B -
-is considered as a starting point for a new abbreviation.
-.
-This leads to a set of multiple abbreviations for a single argument.
-.
-For example,
-.B --de\-n\-f
-can be used as an abbreviation for
-.BR --debug\-not\-func ,
-but
-.B --de\-n
-works as well.
-.
-If the abbreviation of the argument leads to several resulting options
-an error is raised.
-.
-.
-.P
-These abbreviations are only allowed in the environment variable
-.Env_var \%$GROFFER_OPT ,
-but not in the configuration files.
-.
-In configuration, all long options must be exact.
-.
-.
-.\" --------------------------------------------------------------------
-.SS "groffer breaking Options"
-.\" --------------------------------------------------------------------
-.
-As soon as one of these options is found on the command line it is
-executed, printed to standard output, and the running
-.B \%groffer
-is terminated thereafter.
-.
-All other arguments are ignored.
-.
-.
-.TP
-.B -h\~\fR|\fB\~--help
-Print help information with a short explanation of options to
-standard output.
-.
-.
-.TP
-.B -v\~\fR|\fB\~--version
-Print version information to standard output.
-.
-.
-.\" --------------------------------------------------------------------
-.SS "groffer Mode Options"
-.\" --------------------------------------------------------------------
-.
-The display mode and the viewer programs are determined by these
-options.
-.
-If none of these mode and viewer options is specified
-.B \%groffer
-tries to find a suitable display mode automatically.
-.
-The default modes are
-.IR "mode pdf" ,
-.IR "mode ps" ,
-.IR "mode html" ,
-.IR "mode x" ,
-and
-.I "mode dvi"
-in \%\f[CR]X\~Window\f[] with different viewers and
-.I mode tty
-with device
-.I latin1
-under
-.B less
-on a terminal; other modes are tested if the programs for the main
-default mode do not exist.
-.
-.
-.P
-In \%\f[CR]X\~Window\f[],
-many programs create their own window when called.
-.B \%groffer
-can run these viewers as an independent program in the background.
-.
-As this does not work in text mode on a terminal (tty) there must be a
-way to know which viewers are \%\f[CR]X\~Window\f[] graphical
-programs.
-.
-The
-.B \%groffer
-script has a small set of information on some viewer names.
-.
-If a viewer argument of the command\-line chooses an element that is
-kept as \%\f[CR]X\~Window\f[] program in this list it is treated as a
-viewer that can run in the background.
-.
-All other, unknown viewer calls are not run in the background.
-.
-.
-.P
-For each mode, you are free to choose whatever viewer you want.
-.
-That need not be some graphical viewer suitable for this mode.
-.
-There is a chance to view the output source; for example, the
-combination of the options
-.B --mode=ps
-and
-.B --ps\-viewer=less
-shows the content of the
-.I Postscript
-output, the source code, with the pager
-.BR less .
-.
-.
-.TP
-.B --auto
-Equivalent to
-.BR --mode=auto .
-.
-.
-.TP
-.B --default
-Reset all configuration from previously processed command line options
-to the default values.
-.
-This is useful to wipe out all former options of the configuration, in
-.Env_var \%$GROFFER_OPT ,
-and restart option processing using only the rest of the command line.
-.
-.
-.TP
-.BI --default\-modes \ mode1,mode2,\*[Ellipsis]
-Set the sequence of modes for
-.I \%auto\~mode
-to the comma separated list given in the argument.
-.
-See
-.B --mode
-for details on modes.  Display in the default manner; actually, this
-means to try the modes
-.IR x ,
-.IR ps ,
-and
-.I \%tty
-in this sequence.
-.
-.
-.
-.TP
-.B --dvi
-Equivalent to
-.BR --mode=\%dvi .
-.
-.
-.TP
-.BI --dvi\-viewer \ prog
-Choose a viewer program for
-.IR \%dvi\~mode .
-.
-This can be a file name or a program to be searched in
-.Env_var $PATH .
-.
-Known \%\f[CR]X\~Window\f[]
-.I \%dvi
-viewers include
-.BR \%xdvi (1)
-and
-.BR \%dvilx (1).
-.
-In each case, arguments can be provided additionally.
-.
-.
-.TP
-.B --groff
-Equivalent to
-.BR --mode=groff .
-.
-.
-.TP
-.B --html
-Equivalent to
-.BR --mode=html .
-.
-.
-.TP
-.B --html\-viewer
-Choose a web browser program for viewing in
-.IR \%html\~mode .
-.
-It can be the path name of an executable file or a program in
-.Env_var $PATH .
-.
-In each case, arguments can be provided additionally.
-.
-.
-.TP
-.BI --mode \ value
-.
-Set the display mode.
-.
-The following mode values are recognized:
-.
-.RS
-.
-.TP
-.Header_CB auto
-Select the automatic determination of the display mode.
-.
-The sequence of modes that are tried can be set with the
-.B --default\-modes
-option.
-.
-Useful for restoring the
-.I \%default\~mode
-when a different mode was specified before.
-.
-.
-.TP
-.Header_CB dvi
-Display formatted input in a
-.I \%dvi
-viewer program.
-.
-By default, the formatted input is displayed with the
-.BR \%xdvi (1)
-program.
-.
-.
-.TP
-.Header_CB groff
-After the file determination, switch
-.B \%groffer
-to process the input like
-.BR \%groff (@MAN1EXT@)
-would do.
-.
-This disables the
-.I \%groffer
-viewing features.
-.
-.
-.TP
-.Header_CB html
-Translate the input into html format and display the result in a web
-browser program.
-.
-By default, the existence of a sequence of standard web browsers is
-tested, starting with
-.BR \%konqueror (1)
-and
-.BR \%mozilla (1).
-The text html viewer is
-.BR \%lynx (1).
-.
-.
-.TP
-.Header_CB pdf
-Display formatted input in a
-.I \%PDF
-(Portable Document Format) viewer
-program.
-.
-By default, the input is formatted by
-.B \%groff
-using the Postscript device, then it is transformed into the PDF file
-format using
-.BR \%gs (1),
-or
-.BR ps2pdf (1).
-If that's not possible, the
-.I Postscript mode (ps)
-is used instead.
-.
-Finally it is displayed using different viewer programs.
-.
-.I \%pdf
-has a big advantage because the text is displayed graphically and
-is searchable as well.
-.
-.
-.TP
-.Header_CB ps
-Display formatted input in a Postscript viewer program.
-.
-By default, the formatted input is displayed in one of many viewer
-programs.
-.
-.
-.TP
-.Header_CB text
-Format in a
-.I \%groff\~text\~mode
-and write the result to standard output without a pager or viewer
-program.
-.
-The text device,
-.I \%latin1
-by default, can be chosen with option
-.BR -T .
-.
-.
-.TP
-.Header_CB tty
-Format in a
-.I \%groff\~text\~mode
-and write the result to standard output using a text pager program,
-even when in \%\f[CR]X\~Window\f[].
-.
-.
-.TP
-.Header_CB www
-Equivalent to
-.BR --mode=html .
-.
-.
-.TP
-.Header_CB x
-Display the formatted input in a native
-.I roff
-viewer.
-.
-By default, the formatted input is displayed with the
-.BR \%gxditview (@MAN1EXT@)
-program being distributed together with
-.BR \%groff .
-But the standard \%\f[CR]X\~Window\f[] tool
-.BR \%xditview (1)
-can also be chosen with the option
-.BR --x\-viewer .
-The default resolution is
-.BR 75dpi ,
-but
-.B 100dpi
-are also possible.
-.
-The default
-.I groff
-device
-for the resolution of
-.B 75dpi
-is
-.BR X75\-12 ,
-for
-.B 100dpi
-it is
-.BR X100 .
-.
-The corresponding
-.I "groff intermediate output"
-for the actual device is generated and the result is displayed.
-.
-For a resolution of
-.BR 100dpi ,
-the default width of the geometry of the display program is chosen to
-.BR 850dpi .
-.
-.
-.TP
-.Header_CB X
-Equivalent to
-.BR --mode=x .
-.
-.
-.P
-The following modes do not use the
-.I \%groffer
-viewing features.
-.
-They are only interesting for advanced applications.
-.
-.
-.TP
-.Header_CB groff
-Generate device output with plain
-.I \%groff
-without using the special viewing features of
-.IR \%groffer .
-If no device was specified by option
-.B -T
-the
-.I \%groff
-default
-.B \%ps
-is assumed.
-.
-.
-.TP
-.Header_CB source
-Output the roff source code of the input files without further
-processing.
-.
-.
-.RE
-.
-.
-.TP
-.B --pdf
-Equivalent to
-.BR --mode=pdf .
-.
-.
-.TP
-.BI --pdf\-viewer \ prog
-Choose a viewer program for
-.IR \%pdf\~mode .
-.
-This can be a file name or a program to be searched in
-.Env_var $PATH ;
-arguments can be provided additionally.
-.
-.
-.TP
-.B --ps
-Equivalent to
-.BR --mode=ps .
-.
-.
-.TP
-.BI --ps\-viewer \ prog
-Choose a viewer program for
-.IR \%ps\~mode .
-.
-This can be a file name or a program to be searched in
-.Env_var $PATH .
-.
-Common Postscript viewers include
-.BR \%gv (1),
-.BR \%ghostview (1),
-and
-.BR \%gs (1),
-.
-In each case, arguments can be provided additionally.
-.
-.
-.TP
-.B --source
-Equivalent to
-.BR --mode=source .
-.
-.
-.TP
-.B --text
-Equivalent to
-.BR --mode=text .
-.
-.
-.TP
-.B --to\-stdout
-The file for the chosen mode is generated and its content is printed
-to standard output.
-.
-It will not be displayed in graphical mode.
-.
-.
-.TP
-.B --tty
-Equivalent to
-.BR --mode=tty .
-.
-.
-.TP
-.BI --tty\-viewer \ prog
-Choose a text pager for mode
-.IR tty .
-The standard pager is
-.BR less (1).
-This option is equivalent to
-.I man
-option
-.BR --pager=\fIprog\fP .
-The option argument can be a file name or a program to be searched in
-.Env_var $PATH ;
-arguments can be provided additionally.
-.
-.
-.TP
-.B --www
-Equivalent to
-.BR --mode=html .
-.
-.
-.TP
-.BI --www\-viewer \ prog
-Equivalent to
-.BR --html\-viewer .
-.
-.
-.TP
-.B --X\~\fR|\fB\~--x
-Equivalent to
-.BR --mode=x .
-.
-.
-.TP
-.BI --X\-viewer\~\fR|\fB\~--x\-viewer \ prog
-Choose a viewer program for
-.IR \%x\~mode .
-Suitable viewer programs are
-.BR \%gxditview (@MAN1EXT@)
-which is the default and
-.BR \%xditview (1).
-The argument can be any executable file or a program in
-.Env_var $PATH ;
-arguments can be provided additionally.
-.
-.
-.TP
-.B --
-Signals the end of option processing; all remaining arguments are
-interpreted as
-.I \%filespec
-parameters.
-.
-.
-.P
-Besides these,
-.B \%groffer
-accepts all short options that are valid for the
-.BR \%groff (@MAN1EXT@)
-program.
-.
-All
-.RB \%non- groffer
-options are sent unmodified via
-.B \%grog
-to
-.BR \%groff .
-.
-So postprocessors, macro packages, compatibility with
-.I classical
-.IR \%troff ,
-and much more can be manually specified.
-.
-.
-.\" --------------------------------------------------------------------
-.SS "Options related to groff"
-.\" --------------------------------------------------------------------
-.
-All short options of
-.B \%groffer
-are compatible with the short options of
-.BR \%groff (@MAN1EXT@).
-.
-The following of
-.B \%groff
-options have either an additional special meaning within
-.B \%groffer
-or make sense for normal usage.
-.
-.
-.P
-Because of the special outputting behavior of the
-.B \%groff
-option
-.B -Z
-.B \%groffer
-was designed to be switched into
-.IR \%groff\~mode ;
-the
-.I \%groffer
-viewing features are disabled there.
-.
-The other
-.B \%groff
-options do not switch the mode, but allow to customize the formatting
-process.
-.
-.
-.TP
-.B --a
-This generates an ascii approximation of output in the
-.IR \%text\~modes .
-.
-That could be important when the text pager has problems with control
-sequences in
-.IR "tty mode" .
-.
-.
-.TP
-.BI --m \ file
-Add
-.I \%file
-as a
-.I \%groff
-macro file.
-.
-This is useful in case it cannot be recognized automatically.
-.
-.
-.TP
-.BI --P \ opt_or_arg
-Send the argument
-.I \%opt_or_arg
-as an option or option argument to the actual
-.B \%groff
-postprocessor.
-.
-.
-.TP
-.B --T \fIdevname\fR\~\fR|\fB\~--device \fIdevname\fR
-.
-This option determines
-.BR \%groff 's
-output device.
-.
-The most important devices are the text output devices for referring
-to the different character sets, such as
-.BR \%ascii ,
-.BR \%utf8 ,
-.BR \%latin1 ,
-and others.
-.
-Each of these arguments switches
-.B \%groffer
-into a
-.I \%text\~mode
-using this device, to
-.I \%mode\~tty
-if the actual mode is not a
-.IR \%text\~mode .
-.
-The following
-.I \%devname
-arguments are mapped to the corresponding
-.B \%groffer
-.B --mode=\fIdevname\fR
-option:
-.BR \%dvi ,
-.BR \%html ,
-and
-.BR \%ps .
-All
-.B \%X*
-arguments are mapped to
-.IR \%mode\~x .
-Each other
-.I \%devname
-argument switches to
-.I \%mode\~groff
-using this device.
-.
-.
-.TP
-.B --X
-is equivalent to
-.BR "groff \-X" .
-It displays the
-.I groff intermediate output
-with
-.BR gxditview .
-As the quality is relatively bad this option is deprecated; use
-.B --X
-instead because the
-.I \%x\~mode
-uses an
-.IR X *
-device for a better display.
-.
-.
-.TP
-.B -Z\~\fR|\fB\~--intermediate-output\~\fR|\fB\~--ditroff
-Switch into
-.I \%groff\~mode
-and format the input with the
-.I \%groff intermediate output
-without postprocessing; see
-.BR \%groff_out (@MAN5EXT@).
-This is equivalent to option
-.B --ditroff
-of
-.IR \%man ,
-which can be used as well.
-.
-.
-.P
-All other
-.B \%groff
-options are supported by
-.BR \%groffer ,
-but they are just transparently transferred to
-.B \%groff
-without any intervention.
-.
-The options that are not explicitly handled by
-.B \%groffer
-are transparently passed to
-.BR \%groff .
-.
-Therefore these transparent options are not documented here, but in
-.BR \%groff (@MAN1EXT@).
-Due to the automatism in
-.BR \%groffer ,
-none of these
-.B \%groff
-options should be needed, except for advanced usage.
-.
-.
-.\" --------------------------------------------------------------------
-.SS "Options for man\~pages"
-.\" --------------------------------------------------------------------
-.
-.TP
-.B --apropos
-Start the
-.BR \%apropos (1)
-command or facility of
-.BR \%man (1)
-for searching the
-.I \%filespec
-arguments within all
-.I \%man\~page
-descriptions.
-.
-Each
-.I \%filespec
-argument is taken for search as it is;
-.I section
-specific parts are not handled, such that
-.B 7 groff
-searches for the two arguments
-.B 7
-and
-.BR groff ,
-with a large result; for the
-.I \%filespec
-.B groff.7
-nothing will be found.
-.
-The
-.I language
-locale is handled only when the called programs do support this; the
-GNU
-.B apropos
-and
-.B man \-k
-do not.
-.
-The display differs from the
-.B \%apropos
-program by the following concepts:
-.RS
-.Topic
-Construct a
-.I \%groff
-frame similar to a
-.I \%man\~page
-to the output of
-.BR \%apropos ,
-.Topic
-each
-.I \%filespec
-argument is searched on its own.
-.Topic
-The restriction by
-.B --sections
-is handled as well,
-.Topic
-wildcard characters are allowed and handled without a further option.
-.RE
-.
-.
-.TP
-.B --apropos\-data
-Show only the
-.B \%apropos
-descriptions for data documents, these are the
-.BR \%man (7)
-.IR sections\~4 ", " 5 ", and " 7 .
-.
-Direct
-.I section
-declarations are ignored, wildcards are accepted.
-.
-.
-.TP
-.B --apropos\-devel
-Show only the
-.B \%apropos
-descriptions for development documents, these are the
-.BR man (7)
-.IR sections\~2 ", " 3 ", and " 9 .
-.
-Direct
-.I section
-declarations are ignored, wildcards are accepted.
-.
-.
-.TP
-.B --apropos\-progs
-Show only the
-.B \%apropos
-descriptions for documents on programs, these are the
-.BR \%man (7)
-.IR sections\~1 ", " 6 ", and " 8 .
-.
-Direct
-.I section
-declarations are ignored, wildcards are accepted.
-.
-.
-.TP
-.B --whatis
-For each
-.I \%filespec
-argument search all
-.I \%man\~pages
-and display their description \[em] or say that it is not a
-.IR \%man\~page .
-This is written from anew, so it differs from
-.IR man 's
-.B whatis
-output by the following concepts
-.RS
-.Topic
-each retrieved file name is added,
-.Topic
-local files are handled as well,
-.Topic
-the \fIlanguage\fP and \fIsystem\fP locale is supported,
-.Topic
-the display is framed by a
-.I groff
-output format similar to a
-.IR \%man\~page ,
-.Topic
-wildcard characters are allowed without a further option.
-.RE
-.
-.
-.P
-The following options were added to
-.B \%groffer
-for choosing whether the file name arguments are interpreted as names
-for local files or as a search pattern for
-.IR \%man\~pages .
-.
-The default is looking up for local files.
-.
-.
-.TP
-.B --man
-Check the non-option command line arguments
-.nh
-.RI ( filespecs )
-.hy
-first on being
-.IR \%man\~pages ,
-then whether they represent an existing file.
-.
-By default, a
-.I \%filespec
-is first tested whether it is an existing file.
-.
-.
-.TP
-.B --no-man\~\fR|\fB\~--local-file
-Do not check for
-.IR \%man\~pages .
-.
-.B --local-file
-is the corresponding
-.B man
-option.
-.
-.
-.TP
-.B --no-special
-Disable former calls of
-.BR --all ,
-.BR --apropos* ,
-and
-.BR --whatis .
-.
-.
-.\" --------------------------------------------------------------------
-.SS "Long options taken over from GNU man"
-.\" --------------------------------------------------------------------
-.
-The long options of
-.B \%groffer
-were synchronized with the long options of \f[CR]GNU\f[]
-.BR man .
-.
-All long options of \f[CR]GNU\f[]
-.B man
-are recognized, but not all of these options are important to
-.BR \%groffer ,
-so most of them are just ignored.
-.
-These ignored
-.B man
-options are
-.BR --catman ,
-.BR --troff ,
-and
-.BR --update .
-.
-.
-.P
-In the following, the
-.B man
-options that have a special meaning for
-.B \%groffer
-are documented.
-.
-.
-.P
-If your system has \f[CR]GNU\f[]
-.B man
-installed the full set of long and short options of the \f[CR]GNU\f[]
-.B man
-program can be passed via the environment variable
-.Env_var \%$MANOPT ;
-see
-.BR \%man (1).
-.
-.
-.TP
-.B --all
-In searching
-.IR \%man\~pages ,
-retrieve all suitable documents instead of only one.
-.
-.
-.TP
-.B -7\~\fR|\fB\~--ascii
-In
-.IR \%text\~modes ,
-display ASCII translation of special characters for critical environment.
-.
-This is equivalent to
-.BR "groff \%-mtty_char" ;
-see
-.BR groff_tmac (@MAN5EXT@).
-.
-.
-.TP
-.B --ditroff
-Produce
-.IR "groff intermediate output" .
-This is equivalent to
-.B \%groffer
-.BR -Z .
-.
-.
-.TP
-.BI --extension \ suffix
-Restrict
-.I \%man\~page
-search to file names that have
-.I \%suffix
-appended to their section element.
-.
-For example, in the file name
-.I \%/usr/share/man/man3/terminfo.3ncurses.gz
-the
-.I \%man\~page
-extension is
-.IR \%ncurses .
-.
-.
-.TP
-.BI --locale \ language
-.
-Set the language for
-.IR \%man\~pages .
-.
-This has the same effect, but overwrites
-.Env_var $LANG .
-.
-.
-.TP
-.B --location
-Print the location of the retrieved files to standard error.
-.
-.
-.TP
-.B --no-location
-Do not display the location of retrieved files; this resets a former
-call to
-.BR --location .
-.
-This was added by
-.BR \%groffer .
-.
-.
-.TP
-.BI --manpath \ 'dir1:dir2:\*[Ellipsis]'
-Use the specified search path for retrieving
-.I \%man\~pages
-instead of the program defaults.
-.
-If the argument is set to the empty string "" the search for
-.I \%man\~page
-is disabled.
-.
-.
-.TP
-.B --pager
-Set the pager program in
-.IR \%tty\~mode ;
-default is
-.BR \%less .
-This is equivalent to
-.BR --tty\-viewer .
-.
-.
-.TP
-.BI --sections \ sec1:sec2:\*[Ellipsis]
-Restrict searching for
-.I \%man\~pages
-to the given
-.IR sections ,
-a colon-separated list.
-.
-.
-.TP
-.BI --systems \ sys1,sys2,\*[Ellipsis]
-Search for
-.I \%man\~pages
-for the given operating systems; the argument
-.I \%systems
-is a comma-separated list.
-.
-.
-.TP
-.B --where
-Equivalent to
-.BR --location .
-.
-.
-.\" --------------------------------------------------------------------
-.SS "X\~\%Window\~\%Toolkit Options"
-.\" --------------------------------------------------------------------
-.
-The following long options were adapted from the corresponding
-\%\f[CR]X\~Window\~Toolkit\f[] options.
-.
-.B \%groffer
-will pass them to the actual viewer program if it is an
-\%\f[CR]X\~Window\f[] program.
-.
-Otherwise these options are ignored.
-.
-.
-.P
-Unfortunately these options use the old style of a single minus for
-long options.
-.
-For
-.B \%groffer
-that was changed to the standard with using a double minus for long
-options, for example,
-.B \%groffer
-uses the option
-.B --font
-for the \%\f[CR]X\~Window\f[] option
-.BR -font .
-.
-.
-.P
-See
-.BR X (7)
-and the documentation on the \%\f[CR]X\~Window\~Toolkit\f[] options
-for more details on these options and their arguments.
-.
-.
-.TP
-.BI --background \ color
-Set the background color of the viewer window.
-.
-.
-.TP
-.BI --bd \ pixels
-This is equivalent to
-.BR --bordercolor .
-.
-.
-.TP
-.BI --bg \ color
-This is equivalent to
-.BR --background .
-.
-.
-.TP
-.BI --bw \ pixels
-This is equivalent to
-.BR --borderwidth .
-.
-.
-.TP
-.BI --bordercolor \ pixels
-Specifies the color of the border surrounding the viewer window.
-.
-.
-.TP
-.BI --borderwidth \ pixels
-Specifies the width in pixels of the border surrounding the viewer
-window.
-.
-.
-.TP
-.BI --display \ X-display
-Set the \%\f[CR]X\~Window\f[] display on which the viewer program
-shall be started, see the \%\f[CR]X\~Window\f[] documentation for the
-syntax of the argument.
-.
-.
-.TP
-.BI --foreground \ color
-Set the foreground color of the viewer window.
-.
-.
-.TP
-.BI --fg \ color
-This is equivalent to
-.BR -foreground .
-.
-.
-.TP
-.BI --fn \ font_name
-This is equivalent to
-.BR --font .
-.
-.
-.TP
-.BI --font \ font_name
-Set the font used by the viewer window.
-.
-The argument is an \%\f[CR]X\~Window\f[] font name.
-.
-.
-.TP
-.BI --ft \ font_name
-This is equivalent to
-.BR --font .
-.
-.
-.TP
-.BI --geometry \ size_pos
-Set the geometry of the display window, that means its size and its
-starting position.
-.
-See
-.BR \%X (7)
-for the syntax of the argument.
-.
-.
-.TP
-.BI --resolution \ value
-Set \%\f[CR]X\~Window\f[] resolution in dpi (dots per inch) in some
-viewer programs.
-.
-The only supported dpi values are
-.B 75
-and
-.BR 100 .
-.
-Actually, the default resolution for
-.B \%groffer
-is set to
-.BR 75dpi .
-The resolution also sets the default device in
-.IR "mode x" .
-.
-.
-.TP
-.B --rv
-Reverse foreground and background color of the viewer window.
-.
-.
-.TP
-.BI --title "\ 'some text'"
-Set the title for the viewer window.
-.
-.
-.TP
-.BI --xrm \ 'resource'
-Set \f[CR]\%X\~Window\f[] resource.
-.
-.
-.\" --------------------------------------------------------------------
-.SS "Options for Development"
-.\" --------------------------------------------------------------------
-.
-.TP
-.B --debug
-Enable all debugging options
-.BR --debug\-\fItype\fP .
-.
-The temporary files are kept and not deleted, the
-.B grog
-output is printed, the name of the temporary directory is printed, the
-displayed file names are printed, and the parameters are printed.
-.
-.
-.TP
-.B --debug\-filenames
-Print the names of the files and
-.I \%man\~pages
-that are displayed by
-.BR \&groffer .
-.
-.
-.TP
-.B --debug\-grog
-Print the output of all
-.B grog
-commands.
-.
-.
-.TP
-.B --debug\-keep
-Enable two debugging informations.
-.
-Print the name of the temporary directory and keep the temporary
-files, do not delete them during the run of
-.BR \%groffer .
-.
-.
-.TP
-.B --debug\-params
-Print the parameters, as obtained from the configuration files, from
-.Env_var \%GROFFER_OPT ,
-and the command line arguments.
-.
-.
-.TP
-.B --debug\-tmpdir
-Print the name of the temporary directory.
-.
-.
-.TP
-.B --do-nothing
-This is like
-.BR --version ,
-but without the output; no viewer is started.
-.
-This makes only sense in development.
-.
-.
-.TP
-.B --print=\fItext\fR
-Just print the argument to standard error.
-.
-This is good for parameter check.
-.
-.
-.TP 
-.B -V
-This is an advanced option for debugging only.
-.
-Instead of displaying the formatted input, a lot of
-.I \%groffer
-specific information is printed to standard output:
-.
-.RS
-.Topic
-the output file name in the temporary directory,
-.
-.Topic
-the display mode of the actual
-.B \%groffer
-run,
-.
-.Topic
-the display program for viewing the output with its arguments,
-.
-.Topic
-the active parameters from the config files, the arguments in
-.Env_var \%$GROFFER_OPT ,
-and the arguments of the command line,
-.
-.Topic
-the pipeline that would be run by the
-.B \%groff
-program, but without executing it.
-.RE
-.
-.
-.P
-Other useful debugging options are the
-.B \%groff
-option
-.B -Z
-and
-.BR --mode=groff .
-.
-.
-.\" --------------------------------------------------------------------
-.SS "Filespec Arguments"
-.\" --------------------------------------------------------------------
-.
-A
-.I \%filespec
-parameter is an argument that is not an option or option argument.
-.
-In
-.BR \%groffer ,
-.I \%filespec
-parameters are a file name or a template for searching
-.IR \%man\~pages .
-.
-These input sources are collected and composed into a single output
-file such as
-.B \%groff
-does.
-.
-.
-.P
-The strange \%\f[CR]POSIX\f[] behavior to regard all arguments behind
-the first non-option argument as
-.I \%filespec
-arguments is ignored.
-.
-The \f[CR]GNU\f[] behavior to recognize options even when mixed with
-.I \%filespec
-arguments is used throughout.
-.
-But, as usual, the double minus argument
-.B --
-ends the option handling and interprets all following arguments as
-.I \%filespec
-arguments; so the \%\f[CR]POSIX\f[] behavior can be easily adopted.
-.
-.
-.P
-The options
-.B --apropos*
-have a special handling of
-.I filespec
-arguments.
-.
-Each argument is taken as a search scheme of its own.
-.
-Also a regexp (regular expression) can be used in the filespec.
-.
-For example,
-.B groffer --apropos '^gro.f$'
-searches
-.B groff
-in the
-.I man\~page
-name, while
-.B groffer --apropos groff
-searches
-.B groff
-somewhere in the name or description of the
-.IR man\~pages .
-.
-.
-.P
-All other parts of
-.IR groffer ,
-such as the normal display or the output with
-.B --whatis
-have a different scheme for
-.IR filespecs .
-No regular expressions are used for the arguments.
-.
-The
-.I filespec
-arguments are handled by the following scheme.
-.
-.
-.P
-It is necessary to know that on each system the
-.I \%man\~pages
-are sorted according to their content into several sections.
-.
-The
-.I classical man sections
-have a single-character name, either a digit from
-.B 1
-to
-.B 9
-or one of the characters
-.B n
-or
-.BR o .
-.
-.
-.P
-This can optionally be followed by a string, the so-called
-.IR extension .
-The
-.I extension
-allows to store several
-.I man\~pages
-with the same name in the same
-.IR section .
-But the
-.I extension
-is only rarely used, usually it is omitted.
-.
-Then the
-.I extensions
-are searched automatically by alphabet.
-.
-.
-.P
-In the following, we use the name
-.I section_extension
-for a word that consists of a single character
-.I section
-name or a
-.I section
-character that is followed by an
-.IR extension .
-.
-Each
-.I \%filespec
-parameter can have one of the following forms in decreasing sequence.
-.
-.
-.Topic
-No
-.I \%filespec
-parameters means that
-.B \%groffer
-waits for standard input.
-.
-The minus option
-.B -
-always stands for standard input; it can occur several times.
-.
-If you want to look up a
-.I \%man\~page
-called
-.B -
-use the argument
-.BR man:\- .
-.
-.
-.Topic
-Next a
-.I \%filespec
-is tested whether it is the path name of an existing file.
-.
-Otherwise it is assumed to be a searching pattern for a
-.IR \%man\~page .
-.
-.
-.Topic
-.BI \%man: name ( section_extension ) ,
-.BI \%man: name . section_extension,
-.IB \%name ( section_extension ) ,
-or
-.IB \%name . section_extension
-search the \%man\~page
-.I \%name
-in \%man\~section and possibly extension of
-.IR \%section_extension .
-.
-.
-.Topic
-Now
-.BI \%man: name
-searches for a
-.I \%man\~page
-in the lowest
-.I \%man\~section
-that has a document called
-.IR \%name .
-.
-.
-.Topic
-.I \%section_extension\~name
-is a pattern of 2 arguments that originates from a strange argument
-parsing of the
-.B man
-program.
-.
-Again, this searches the man page
-.I name
-with
-.IR \%section_extension ,
-a combination of a
-.I section
-character optionally followed by an
-.IR extension .
-.
-.
-.Topic
-We are left with the argument
-.I \%name
-which is not an existing file.
-.
-So this searches for the
-.I \%man\~page
-called
-.I \%name
-in the lowest
-.I \%man\~section
-that has a document for this name.
-.
-.
-.P
-Several file name arguments can be supplied.
-.
-They are mixed by
-.B \%groff
-into a single document.
-.
-Note that the set of option arguments must fit to all of these file
-arguments.
-.
-So they should have at least the same style of the
-.I \%groff
-language.
-.
-.
-.\" --------------------------------------------------------------------
-.SH "OUTPUT MODES"
-.\" --------------------------------------------------------------------
-.
-By default, the
-.B \%groffer
-program collects all input into a single file, formats it with the
-.B \%groff
-program for a certain device, and then chooses a suitable viewer
-program.
-.
-The device and viewer process in
-.B \%groffer
-is called a
-.IR \%mode .
-.
-The mode and viewer of a running
-.B \%groffer
-program is selected automatically, but the user can also choose it
-with options.
-.
-.
-The modes are selected by option the arguments of
-.BR --mode=\fIanymode .
-Additionally, each of this argument can be specified as an option of
-its own, such as
-.BR anymode .
-Most of these modes have a viewer program, which can be chosen by an
-option that is constructed like
-.BR --\fIanymode\fR\-viewer .
-.
-.
-.P
-Several different modes are offered, graphical modes for
-\f[CR]\%X\~Window\f[],
-.IR \%text\~modes ,
-and some direct
-.I \%groff\~modes
-for debugging and development.
-.
-.
-.P
-By default,
-.B \%groffer
-first tries whether
-.I \%x\~mode
-is possible, then
-.IR \%ps\~mode ,
-and finally
-.IR \%tty\~mode .
-.
-This mode testing sequence for
-.I \%auto\~mode
-can be changed by specifying a comma separated list of modes with the
-option
-.B --default\-modes.
-.
-.
-.P
-The searching for
-.I \%man\~pages
-and the decompression of the input are active in every mode.
-.
-.
-.\" --------------------------------------------------------------------
-.SS "Graphical Display Modes"
-.\" --------------------------------------------------------------------
-.
-The graphical display modes work mostly in the \%\f[CR]X\~Window\f[]
-environment (or similar implementations within other windowing
-environments).
-.
-The environment variable
-.Env_var \%$DISPLAY
-and the option
-.B --display
-are used for specifying the \%\f[CR]X\~Window\f[] display to be used.
-.
-If this environment variable is empty
-.B \%groffer
-assumes that no \%\f[CR]X\~Window\f[] is running and changes to a
-.IR \%text\~mode .
-.
-You can change this automatic behavior by the option
-.BR --default\-modes .
-.
-.
-.P
-Known viewers for the graphical display modes and their standard
-\%\f[CR]X\~Window\f[] viewer programs are
-.
-.Topic
-in a PDF viewer
-.nh
-.RI ( \%pdf\~mode )
-.hy
-.
-.Topic
-in a web browser
-.nh
-.RI ( html
-or
-.IR \%www\~mode )
-.hy
-.RE
-.
-.Topic
-in a Postscript viewer
-.nh
-.RI ( \%ps\~mode )
-.hy
-.
-.Topic
-\%\f[CR]X\~Window\f[]
-.I roff
-viewers such as
-.BR \%gxditview (@MAN1EXT@)
-or
-.BR \%xditview (1)
-(in
-.IR \%x\~mode )
-.
-.Topic
-in a dvi viewer program
-.nh
-.RI ( \%dvi\~mode )
-.hy
-.
-.
-.P
-The
-.I \%pdf\~mode
-has a major advantage \[em] it is the only graphical display mode that
-allows to search for text within the viewer; this can be a really
-important feature.
-.
-Unfortunately, it takes some time to transform the input into the PDF
-format, so it was not chosen as the major mode.
-.
-.
-.P
-These graphical viewers can be customized by options of the
-\%\f[CR]X\~Window\~Toolkit\f[].
-.
-But the
-.B \%groffer
-options use a leading double minus instead of the single minus used by
-the \%\f[CR]X\~Window\~Toolkit\f[].
-.
-.
-.\" --------------------------------------------------------------------
-.SS "Text modes"
-.\" --------------------------------------------------------------------
-.
-There are two modes for text output,
-.I \%mode\~text
-for plain output without a pager and
-.I \%mode\~tty
-for a text output on a text terminal using some pager program.
-.
-.
-.P
-If the variable
-.Env_var \%$DISPLAY
-is not set or empty,
-.B \%groffer
-assumes that it should use
-.IR \%tty\~\%mode .
-.
-.
-.P
-In the actual implementation, the
-.I groff
-output device
-.I \%latin1
-is chosen for
-.IR \%text\~modes .
-.
-This can be changed by specifying option
-.B -T
-or
-.BR \%--device .
-.
-.
-.P
-The pager to be used can be specified by one of the options
-.B --pager
-and
-.BR --tty\-viewer ,
-or by the environment variable
-.Env_var \%$PAGER .
-If all of this is not used the
-.BR \%less (1)
-program with the option
-.B -r
-for correctly displaying control sequences is used as the default
-pager.
-.
-.
-.\" --------------------------------------------------------------------
-.SS "Special Modes for Debugging and Development"
-.\" --------------------------------------------------------------------
-.
-These modes use the
-.I \%groffer
-file determination and decompression.
-.
-This is combined into a single input file that is fed directly into
-.B \%groff
-with different strategy without the
-.I \%groffer
-viewing facilities.
-.
-These modes are regarded as advanced, they are useful for debugging
-and development purposes.
-.
-.
-.P
-The
-.I \%source\~mode
-with option
-.B --source
-just displays the decompressed input.
-.
-.
-.P
-Otion
-.B --to\-stdout
-does not display in a graphical mode.
-.
-It just generates the file for the chosen mode and then prints its
-content to standard output.
-.
-.
-.P
-The
-.I \%groff\~mode
-passes the input to
-.B \%groff
-using only some suitable options provided to
-.BR \%groffer .
-.
-This enables the user to save the generated output into a file or pipe
-it into another program.
-.
-.
-.P
-In
-.IR \%groff\~\%mode ,
-the option
-.B -Z
-disables post-processing, thus producing the
-.nh
-.I groff intermediate
-.IR output .
-.hy
-.
-In this mode, the input is formatted, but not postprocessed; see
-.BR \%groff_out (@MAN5EXT@)
-for details.
-.
-.
-.P
-All
-.B \%groff
-short options are supported by
-.BR \%groffer .
-.
-.
-.\" --------------------------------------------------------------------
-.SH "MAN PAGE SEARCHING"
-.\" --------------------------------------------------------------------
-.
-The default behavior of
-.B \%groffer
-is to first test whether a file parameter represents a local file; if
-it is not an existing file name, it is assumed to represent the name
-of a
-.IR \%man\~page .
-The following options can be used to determine whether the arguments
-should be handled as file name or
-.I \%man\~page
-arguments.
-.
-.TP
-.B --man
-forces to interpret all file parameters as
-.I \%filespecs
-for searching
-.IR \%man\~pages .
-.
-.TP
-.B --no\-man
-.TQ
-.B --local\-file
-disable the
-.I man
-searching; so only local files are displayed.
-.
-.
-.P
-If neither a local file nor a
-.I \%man\~page
-was retrieved for some file parameter a warning is issued on standard
-error, but processing is continued.
-.
-.
-.\" --------------------------------------------------------------------
-.SS "Search Algorithm"
-.\" --------------------------------------------------------------------
-.
-Let us now assume that a
-.I \%man\~page
-should be searched.
-.
-The
-.B \%groffer
-program provides a search facility for
-.IR \%man\~pages .
-.
-All long options, all environment variables, and most of the
-functionality of the \f[CR]GNU\fP
-.BR \%man (1)
-program were implemented.
-.
-The search algorithm shall determine which file is displayed for a given
-.IR \%man\~page .
-The process can be modified by options and environment variables.
-.
-.
-.P
-The only
-.I man
-action that is omitted in
-.B \%groffer
-are the preformatted
-.IR \%man\~pages ,
-also called
-.IR cat\~pages .
-.
-With the excellent performance of the actual computers, the
-preformatted
-.I \%man\~pages
-aren't necessary any longer.
-.
-Additionally,
-.B \%groffer
-is a
-.I roff
-program; it wants to read
-.I roff
-source files and format them itself.
-.
-.
-.P
-The algorithm for retrieving the file for a
-.I \%man\~page
-needs first a set of directories.
-.
-This set starts with the so-called
-.I man\~path
-that is modified later on by adding names of
-.I operating system
-and
-.IR language .
-.
-This arising set is used for adding the section directories which
-contain the
-.I \%man\~page
-files.
-.
-.
-.P
-The
-.I man\~path
-is a list of directories that are separated by colon.
-.
-It is generated by the following methods.
-.
-.Topic
-The environment variable
-.Env_var \%$MANPATH
-can be set.
-.
-.Topic
-It can be read from the arguments of the environment variable
-.Env_var \%$MANOPT .
-.
-.Topic
-The
-.I man\~path
-can be manually specified by using the option
-.BR --manpath .
-An empty argument disables the
-.I \%man\~page
-searching.
-.
-.Topic
-When no
-.I man\~path
-was set the
-.BR \%manpath (1)
-program is tried to determine one.
-.
-.Topic
-If this does not work a reasonable default path from
-.Env_var $PATH
-is determined.
-.
-.
-.P
-We now have a starting set of directories.
-.
-The first way to change this set is by adding names of
-.I operating
-.IR systems .
-.
-This assumes that
-.I \%man\~pages
-for several
-.I operating systems
-are installed.
-.
-This is not always true.
-.
-The names of such
-.I operating systems
-can be provided by 3 methods.
-.
-.Topic
-The environment variable
-.Env_var \%$SYSTEM
-has the lowest precedence.
-.
-.Topic
-This can be overridden by an option in
-.Env_var \%$MANOPT .
-.
-.Topic
-This again is overridden by the command line option
-.BR --systems .
-.
-.
-.P
-Several names of
-.I operating systems
-can be given by appending their names, separated by a comma.
-.
-.
-.P
-The
-.I man\~path
-is changed by appending each
-.I system
-name as subdirectory at the end of each directory of the set.
-.
-No directory of the
-.I man\~path
-set is kept.
-.
-But if no
-.I system
-name is specified the
-.I man\~path
-is left unchanged.
-.
-.
-.P
-After this, the actual set of directories can be changed by
-.I language
-information.
-.
-This assumes that there exist
-.I man\~pages
-in different languages.
-.
-The wanted
-.I language
-can be chosen by several methods.
-.
-.Topic
-Environment variable
-.Env_var $LANG .
-.
-.Topic
-This is overridden by
-.Env_var \%$LC_MESSAGES .
-.
-.Topic
-This is overridden by
-.Env_var $LC_ALL .
-.
-.Topic
-This can be overridden by providing an option in
-.Env_var \%$MANOPT .
-.
-.Topic
-All these environment variables are overridden by the command line
-option
-.BR --locale .
-.
-.
-.P
-The
-.I default language
-can be specified by specifying one of the pseudo-language parameters
-\f[CR]C\fP or \f[CR]\%POSIX\fP.
-.
-This is like deleting a formerly given
-.I language
-information.
-.
-The
-.I \%man\~pages
-in the
-.I default language
-are usually in English.
-.
-.
-.P
-Of course, the
-.I language
-name is determined by
-.BR man .
-In \f[CR]GNU\fP
-.BR man ,
-it is specified in the \%\f[CR]POSIX\~1003.1\fP based format:
-.P
-.nh
-\f[I]<language>\f[][\f[CB]_\f[]\f[I]<territory>\f[][\f[CB].\fP\
-\f[I]<character-set>\f[][\f[CB],\fP\f[I]<version>\fP]]],
-.hy
-.P
-but the two-letter code in
-.nh
-.I <language>
-.hy
-is sufficient for most purposes.
-.
-If for a complicated
-.I language
-formulation no
-.I \%man\~pages
-are found
-.B \%groffer
-searches the country part consisting of these first two characters as
-well.
-.
-.
-.P
-The actual directory set is copied thrice.
-.
-The
-.I language
-name is appended as subdirectory to each directory in the first copy
-of the actual directory set (this is only done when a language
-information is given).
-.
-Then the 2-letter abbreviation of the
-.I language
-name is appended as subdirectories to the second copy of the directory
-set (this is only done when the given language name has more than 2
-letters).
-.
-The third copy of the directory set is kept unchanged (if no
-.I language
-information is given this is the kept directory set).
-.
-These maximally 3 copies are appended to get the new directory set.
-.
-.
-.P
-We now have a complete set of directories to work with.
-.
-In each of these directories, the
-.I man
-files are separated in
-.IR sections .
-.
-The name of a
-.I section
-is represented by a single character, a digit between
-.I 1
-and
-.IR 9 ,
-or the character
-.I o
-or
-.IR n ,
-in this order.
-.
-.
-.P
-For each available
-.IR section ,
-a subdirectory
-.File_name man \fI<section>\fP
-exists containing all
-.I man
-files for this
-.IR section ,
-where
-.I <section>
-is a single character as described before.
-.
-Each
-.I man
-file in a
-.I section
-directory has the form
-.IR \%\f[CB]man\fP<section>\f[CB]/\fP<name>\f[CB].\fP<section>\
-[<extension>][\f[CB].\fP<compression>] ,
-where
-.I \%<extension>
-and
-.I \%<compression>
-are optional.
-.
-.I \%<name>
-is the name of the
-.I \%man\~page
-that is also specified as filespec argument on the command line.
-.
-.
-.P
-The
-.I extension
-is an addition to the section.
-.
-This postfix acts like a subsection.
-.
-An
-.I extension
-occurs only in the file name, not in name of the
-.I section
-subdirectory.
-.
-It can be specified on the command line.
-.
-.
-.P
-On the other hand, the
-.I compression
-is just an information on how the file is compressed.
-.
-This is not important for the user, such that it cannot be specified
-on the command line.
-.
-.
-.P
-There are 4 methods to specify a
-.I section
-on the command line:
-.
-.Topic
-Environment variable
-.Env_var \%$MANSECT
-.
-.Topic
-Command line option
-.B --sections
-.
-.Topic
-Appendix to the
-.I name
-argument in the form
-.I <name>.<section>
-.
-.Topic
-Preargument before the
-.I name
-argument in the form
-.I <section> <name>
-.
-.
-.P
-It is also possible to specify several
-.I sections
-by appending the single characters separated by colons.
-.
-One can imagine that this means to restrict the
-.I \%man\~page
-search to only some
-.IR sections .
-.
-The multiple
-.I sections
-are only possible for
-.Env_var \%$MANSECT
-and
-.BR --sections .
-.
-.
-.P
-If no
-.I section
-is specified all
-.I sections
-are searched one after the other in the given order, starting with
-.IR section\~1 ,
-until a suitable file is found.
-.
-.
-.P
-There are 4 methods to specify an
-.I extension
-on the command line.
-.
-But it is not necessary to provide the whole extension name, some
-abbreviation is good enough in most cases.
-.
-.Topic
-Environment variable
-.Env_var \%$EXTENSION
-.
-.Topic
-Command line option
-.B --extension
-.
-.Topic
-Appendix to the
-.I <name>.<section>
-argument in the form
-.I <name>.<section><extension>
-.
-.Topic
-Preargument before the
-.I name
-argument in the form
-.I <section><extension> <name>
-.
-.
-.P
-For further details on
-.I \%man\~page
-searching, see
-.BR \%man (1).
-.
-.
-.\" --------------------------------------------------------------------
-.SS "Examples of man files"
-.\" --------------------------------------------------------------------
-.
-.TP
-.File_name /usr/share/man/man1/groff.1
-This is an uncompressed file for the
-.I \%man\~page
-\f[CR]groff\fP in
-.IR section\~1 .
-.
-It can be called by
-.EX
-\fIsh#\fR groffer\~groff
-.EE
-No
-.I section
-is specified here, so all
-.I sections
-should be searched, but as
-.I section\~1
-is searched first this file will be found first.
-.
-The file name is composed of the following components.
-.File_name /usr/share/man
-must be part of the
-.IR \%man\~path ;
-the subdirectory
-.File_name man1/
-and the part
-.File_name .1
-stand for the
-.IR section ;
-.File_name groff
-is the name of the
-.IR \%man\~page .
-.
-.
-.TP
-.File_name /usr/local/share/man/man7/groff.7.gz
-The file name is composed of the following components.
-.File_name /usr/local/share/man
-must be part of the
-.IR \%man\~path ;
-the subdirectory
-.File_name man7/
-and the part
-.File_name .7
-stand for the
-.IR section ;
-.File_name groff
-is the name of the
-.IR \%man\~page ;
-the final part
-.File_name .gz
-stands for a compression with
-.BR gzip (1).
-As the
-.I section
-is not the first one it must be specified as well.
-.
-This can be done by one of the following commands.
-.EX
-\fIsh#\fR\~groffer\~groff.7
-\fIsh#\fR\~groffer\~7\~groff
-\fIsh#\fR\~groffer\~\-\-sections=7\~groff
-.EE
-.
-.TP
-.File_name /usr/local/man/man1/ctags.1emacs21.bz2
-Here
-.File_name /usr/local/man
-must be in
-.IR \%man\~path ;
-the subdirectory
-.File_name man1/
-and the file name part
-.File_name .1
-stand for
-.IR section\~1 ;
-the name of the
-.I \%man\~page
-is
-.File_name ctags ;
-the section has an extension
-.File_name emacs21 ;
-and the file is compressed as
-.File_name .bz2
-with
-.BR bzip2 (1).
-The file can be viewed with one of the following commands
-.EX
-\fIsh#\fR\~groffer\~ctags.1e
-\fIsh#\fR\~groffer\~1e\~ctags
-\fIsh#\fR\~groffer\~\-\-extension=e\~\-\-sections=1\~ctags
-.EE
-where \f[CR]e\fP works as an abbreviation for the extension
-\f[CR]emacs21\fP.
-.
-.
-.TP
-.File_name /usr/man/linux/de/man7/man.7.Z
-The directory
-.File_name /usr/man
-is now part of the
-.IR \%man\~path ;
-then there is a subdirectory for an
-.I operating system
-name
-.File_name linux/ ;
-next comes  a subdirectory
-.File_name de/
-for the German
-.IR language ;
-the
-.I section
-names
-.File_name man7
-and
-.File_name .7
-are known so far;
-.File_name man
-is the name of the
-.IR \%man\~page ;
-and
-.File_name .Z
-signifies the compression that can be handled by
-.BR gzip (1).
-We want now show how to provide several values for some options.
-.
-That is possible for
-.I sections
-and
-.I operating system
-names.
-.
-So we use as
-.I sections\~5
-and
-.I 7
-and as
-.I system
-names
-.I linux
-and
-.IR aix .
-The command is then
-.sp
-.EX
-\fIsh#\fR groffer\~\-\-locale=de\~\-\-sections=5:7\~\-\-systems=linux,aix\~man
-\fIsh#\fR LANG=de\~MANSECT=5:7\~SYSTEM=linux,aix\~groffer\~man
-.EE
-.
-.
-.\" --------------------------------------------------------------------
-.SH DECOMPRESSION
-.\" --------------------------------------------------------------------
-.
-The program has a decompression facility.
-.
-If standard input or a file that was retrieved from the command line
-parameters is compressed with a format that is supported by either
-.BR \%gzip (1)
-or
-.BR \%bzip2 (1)
-it is decompressed on-the-fly.
-.
-This includes the \f[CR]GNU\fP
-.BR \%.gz ,
-.BR \%.bz2 ,
-and the traditional
-.B \%.Z
-compression.
-.
-The program displays the concatenation of all decompressed input in
-the sequence that was specified on the command line.
-.
-.
-.\" --------------------------------------------------------------------
-.SH "ENVIRONMENT"
-.\" --------------------------------------------------------------------
-.
-The
-.B \%groffer
-program supports many system variables, most of them by courtesy of
-other programs.
-.
-All environment variables of
-.BR \%groff (@MAN1EXT@)
-and \f[CR]GNU\fP
-.BR \%man (1)
-and some standard system variables are honored.
-.
-.
-.\" --------------------------------------------------------------------
-.SS "Native groffer Variables"
-.\" --------------------------------------------------------------------
-.
-.TP
-.Env_var \%$GROFFER_OPT
-Store options for a run of
-.BR \%groffer .
-.
-The options specified in this variable are overridden by the options
-given on the command line.
-.
-The content of this variable is run through the shell builtin `eval';
-so arguments containing white-space or special shell characters should
-be quoted.
-.
-Do not forget to export this variable, otherwise it does not exist
-during the run of
-.BR groffer .
-.
-.
-.\" --------------------------------------------------------------------
-.SS "System Variables"
-.\" --------------------------------------------------------------------
-.
-The following variables have a special meaning for
-.BR \%groffer .
-.
-.
-.TP
-.Env_var \%$DISPLAY
-If this variable is set this indicates that the \%\f[CR]X\~Window\fP
-system is running.
-.
-Testing this variable decides on whether graphical or text output is
-generated.
-.
-This variable should not be changed by the user carelessly, but it can
-be used to start the graphical
-.B \%groffer
-on a remote \%\f[CR]X\~Window\fP terminal.
-.
-For example, depending on your system,
-.B \%groffer
-can be started on the second monitor by the command
-.sp
-.EX
-\fIsh#\fR DISPLAY=:0.1\~groffer\~what.ever &
-.EE
-.
-.
-.TP
-.Env_var \%$LC_ALL
-.TQ
-.Env_var \%$LC_MESSAGES
-.TQ
-.Env_var $LANG
-If one of these variables is set (in the above sequence), its content
-is interpreted as the locale, the language to be used, especially when
-retrieving
-.IR \%man\~pages .
-.
-A locale name is typically of the form
-.nh
-.IR language [\c
-.B _\c
-.IR territory [\c
-.B .\c
-.IR codeset [\c
-.B @\c
-.IR modifier ]]],
-.hy
-where
-.I \%language
-is an ISO 639 language code,
-.I \%territory
-is an ISO 3166 country code, and
-.I \%codeset
-is a character set or encoding identifier like ISO-8859-1 or UTF-8;
-see
-.BR \%setlocale (3).
-.
-The locale values \f[CR]C\fP and \%\f[CR]POSIX\fP
-stand for the default, i.e. the
-.I \%man\~page
-directories without a language prefix.
-.
-This is the same behavior as when all 3\~variables are unset.
-.
-.
-.TP
-.Env_var \%$PAGER
-This variable can be used to set the pager for the tty output.
-.
-For example, to disable the use of a pager completely set this
-variable to the
-.BR \%cat (1)
-program
-.sp
-.EX
-\fIsh#\fR PAGER=cat\~groffer\~anything
-.EE
-.sp
-.
-.TP
-.Env_var $PATH
-All programs within the
-.B \%groffer
-script are called without a fixed path.
-.
-Thus this environment variable determines the set of programs used
-within the run of
-.BR \%groffer .
-.
-.
-.\" --------------------------------------------------------------------
-.SS "Groff Variables"
-.\" --------------------------------------------------------------------
-.
-The
-.B \%groffer
-program internally calls
-.BR \%groff ,
-so all environment variables documented in
-.BR \%groff (@MAN1EXT@)
-are internally used within
-.B \%groffer
-as well.
-.
-The following variable has a direct meaning for the
-.B \%groffer
-program.
-.
-.TP
-.Env_var \%$GROFF_TMPDIR
-If the value of this variable is an existing, writable directory,
-.B \%groffer
-uses it for storing its temporary files, just as
-.B groff
-does.
-.
-See the
-.BR \%groff (@MAN1EXT@)
-man page for more details on the location of temporary files.
-.
-.
-.\" --------------------------------------------------------------------
-.SS "Man Variables"
-.\" --------------------------------------------------------------------
-.
-Parts of the functionality of the
-.B man
-program were implemented in
-.BR \%groffer ;
-support for all environment variables documented in
-.BR \%man (1)
-was added to
-.BR \%groffer ,
-but the meaning was slightly modified due to the different approach in
-.BR \%groffer ;
-but the user interface is the same.
-.
-The
-.B man
-environment variables can be overwritten by options provided with
-.Env_var \%$MANOPT ,
-which in turn is overwritten by the command line.
-.
-.
-.TP
-.Env_var \%$EXTENSION
-Restrict the search for
-.I \%man\~pages
-to files having this extension.
-.
-This is overridden by option
-.BR --extension ;
-see there for details.
-.
-.
-.TP
-.Env_var \%$MANOPT
-This variable contains options as a preset for
-.BR \%man (1).
-As not all of these are relevant for
-.B \%groffer
-only the essential parts of its value are extracted.
-.
-The options specified in this variable overwrite the values of the
-other environment variables that are specific to
-.IR man .
-.
-All options specified in this variable are overridden by the options
-given on the command line.
-.
-.
-.TP
-.Env_var \%$MANPATH
-If set, this variable contains the directories in which the
-.I \%man\~page
-trees are stored.
-.
-This is overridden by option
-.BR \%--manpath .
-.
-.
-.TP
-.Env_var \%$MANSECT
-If this is a colon separated list of section names, the search for
-.I \%man\~pages
-is restricted to those manual sections in that order.
-.
-This is overridden by option
-.BR --sections .
-.
-.
-.TP
-.Env_var \%$SYSTEM
-If this is set to a comma separated list of names these are interpreted
-as
-.I \%man\~page
-trees for different operating systems.
-.
-This variable can be overwritten by option
-.BR --systems ;
-see there for details.
-.
-.
-.P
-The environment variable
-.Env_var \%$MANROFFSEQ
-is ignored by
-.B \%groffer
-because the necessary preprocessors are determined automatically.
-.
-.
-.\" --------------------------------------------------------------------
-.SH "CONFIGURATION FILES"
-.\" --------------------------------------------------------------------
-.
-The
-.B \%groffer
-program can be preconfigured by two configuration files.
-.
-.
-.TP
-.File_name \%/etc/groff/groffer.conf
-System-wide configuration file for
-.BR \%groffer .
-.
-.
-.TP
-.File_name \%$HOME/.groff/groffer.conf
-User-specific configuration file for
-.BR \%groffer ,
-where
-.Env_var \%$HOME
-denotes the user's home directory.
-.
-This file is called after the system-wide configuration file to enable
-overriding by the user.
-.
-.
-.P
-Both files are handled for the configuration, but the configuration
-file in
-.File_name /etc
-comes first; it is overwritten by the configuration file in the home
-directory; both configuration files are overwritten by the environment
-variable
-.Env_var \%$GROFFER_OPT ;
-everything is overwritten by the command line arguments.
-.
-.
-.P
-The configuration files contain options that should be called as
-default for every
-.B \%groffer
-run.
-.
-These options are written in lines such that each contains either a
-long option, a short option, or a short option cluster; each with or
-without an argument.
-.
-So each line with configuration information starts with a minus
-character
-.RB ` \- ';
-a line with a long option starts with two minus characters
-.RB ` \-\- ',
-a line with a short option or short option cluster starts with a
-single minus
-.RB ` \- '.
-.
-.
-.P
-The option names in the configuration files may not be abbreviated,
-they must be exact.
-.
-.
-.P
-The argument for a long option can be separated from the option name
-either by an equal sign
-.RB ` = '
-or by whitespace, i.e. one or several space or tab characters.
-.
-An argument for a short option or short option cluster can be directly
-appended to the option name or separated by whitespace.
-.
-The end of an argument is the end of the line.
-.
-It is not allowed to use a shell environment variable in an option
-name or argument.
-.
-.
-.P
-It is not necessary to use quotes in an option or argument, except for
-empty arguments.
-.
-An empty argument can be provided by appending a pair of quotes to the
-separating equal sign or whitespace; with a short option, the
-separator can be omitted as well.
-.
-For a long option with a separating equal sign
-.RB ` = ',
-the pair of quotes can be omitted, thus ending the line with the
-separating equal sign.
-.
-All other quote characters are cancelled internally.
-.
-.
-.P
-In the configuration files, arbitrary whitespace is allowed at the
-beginning of each line, it is just ignored.
-.
-Each whitespace within a line is replaced by a single space character
-` ' internally.
-.
-.
-.P
-All lines of the configuration lines that do not start
-with a minus character are ignored, such that comments starting with
-.RB ` # '
-are possible.
-.
-So there are no shell commands in the configuration files.
-.
-.
-.P
-As an example, consider the following configuration file that can be
-used either in
-.File_name \%/etc/groff/groffer.conf
-or
-.File_name \%~/.groff/groffer.conf .
-.
-.
-.P
-.ft CR
-.nh
-.nf
-# groffer configuration file
-#
-# groffer options that are used in each call of groffer
-\-\-foreground=DarkBlue
-\-\-resolution=100
-\-\-x\-viewer=gxditview \-geometry 900x1200
-\-\-pdf\-viewer xpdf \-Z 150
-.fi
-.hy
-.ft
-.
-.
-.P
-The lines starting with
-.B #
-are just ignored, so they act as command lines.
-.
-This configuration sets four
-.B \%groffer
-options (the lines starting with
-.RB ` \- ').
-This has the following effects:
-.
-.
-.Topic
-Use a text color of
-.B \%DarkBlue
-in all viewers that support this, such as
-.BR \%gxditview .
-.
-.
-.Topic
-Use a resolution of
-.B 100dpi
-in all viewers that support this, such as
-.BR \%gxditview .
-.
-By this, the default device in
-.I x mode
-is set to
-.BR X100 .
-.
-.
-.Topic
-Force
-.BR \%gxditview (@MAN1EXT@)
-as the
-.I \%x-mode
-viewer using the geometry option for setting the width to
-.B 900px
-and the height to
-.BR 1200px .
-This geometry is suitable for a resolution of
-.BR 100dpi .
-.
-.
-.Topic
-Use
-.BR \%xpdf (1)
-as the
-.I \%pdf-mode
-viewer with the argument
-.B \-Z
-.BR 150 .
-.
-.
-.\" --------------------------------------------------------------------
-.SH "EXAMPLES"
-.\" --------------------------------------------------------------------
-.
-The usage of
-.B \%groffer
-is very easy.
-.
-Usually, it is just called with a file name or
-.IR \%man\~page .
-.
-The following examples, however, show that
-.B \%groffer
-has much more fancy capabilities.
-.
-.sp
-.EX
-\fIsh#\fR\~groffer\~/usr/local/share/doc/groff/meintro.ms.gz
-.EE
-.sp
-Decompress, format and display the compressed file
-.File_name meintro.ms.gz
-in the directory
-.File_name /usr/local/share/doc/groff ,
-using the standard viewer
-.B \%gxditview
-as graphical viewer when in \%\f[CR]X\~Window\fP, or the
-.BR \%less (1)
-pager program when not in \%\f[CR]X\~Window\fP.
-.
-.sp
-.EX
-\fIsh#\fR\~groffer\~groff
-.EE
-.sp
-If the file
-.File_name \%./groff
-exists use it as input.
-.
-Otherwise interpret the argument as a search for the
-.I \%man\~page
-named
-.B \%groff
-in the smallest possible
-.IR \%man\~section ,
-being section 1 in this case.
-.
-.sp
-.EX
-\fIsh#\fR\~groffer\~man:groff
-.EE
-.sp
-search for the
-.I \%man\~page
-of
-.B \%groff
-even when the file
-.File_name ./groff
-exists.
-.
-.sp
-.EX
-\fIsh#\fR\~groffer\~groff.7
-\fIsh#\fR\~groffer\~7\~groff
-.EE
-.sp
-search the
-.I \%man\~page
-of
-.B \%groff
-in
-.I \%man\~section
-.BR 7 .
-This section search works only for a digit or a single character from
-a small set.
-.
-.sp
-.EX
-\fIsh#\fR\~groffer\~fb.modes
-.EE
-.sp
-If the file
-.File_name ./fb.modes
-does not exist interpret this as a search for the
-.I \%man\~page
-of
-.BR fb.modes .
-As the extension
-.I \%modes
-is not a single character in classical section style the argument is
-not split to a search for
-.BR fb .
-.
-.sp
-.EX
-\fIsh#\fR\~groffer\~groff\~\[cq]troff(1)\[cq]\~man:roff
-.EE
-.sp
-The arguments that are not existing files are looked-up as the
-following
-.IR \%man\~pages :
-.B \%groff
-(automatic search, should be found in \fIman\fP\~section\~1),
-.B \%troff
-(in section\~1),
-and
-.B \%roff
-(in the section with the lowest number, being\~7 in this case).
-.
-The quotes around
-.nh
-.I \[cq]troff(1)\[cq]
-.hy
-are necessary because the parentheses are special shell characters;
-escaping them with a backslash character
-.I \[rs](
-and
-.I \[rs])
-would be possible, too.
-.
-The formatted files are concatenated and displayed in one piece.
-.
-.sp
-.EX
-\fIsh#\fR\~LANG=de\~groffer\~--man\~--www\~--www-viewer=galeon\~ls
-.EE
-.sp
-Retrieve the German
-.I \%man\~page
-(language
-.IR de )
-for the
-.B ls
-program, decompress it, format it to
-.I \%html
-format
-.nh
-.RI ( \%www\~mode )
-.hy
-and view the result in the web browser
-.BR \%galeon .
-The option
-.B --man
-guarantees that the
-.I \%man\~page
-is retrieved, even when a local file
-.File_name \%ls
-exists in the actual directory.
-.
-.
-.sp
-.EX
-\fIsh#\fR\~groffer\~--source\~'man:roff(7)'
-.EE
-.sp
-Get the
-.I \%man\~page
-called
-.I \%roff
-in \fIman\fP\~section 7, decompress it, and print its unformatted
-content, its source code.
-.
-.
-.sp
-.EX
-\fIsh#\fR\~groffer\~--de-p\~--in\~--ap
-.EE
-.sp
-This is a set of abbreviated arguments, it is determined as
-.br
-.sp
-.EX
-\fIsh#\fR\~groffer\~--debug-params\~--intermediate-output\~--apropos
-.EE
-.sp
-.
-.sp
-.EX
-\fIsh#\fR\~cat\~file.gz\~|\~groffer\~-Z\~-mfoo
-.EE
-.sp
-.
-The file
-.File_name file.gz
-is sent to standard input, this is decompressed, and then this is
-transported to the
-.I \%groff intermediate output mode
-without post-processing
-.RB ( groff
-option
-.BR -Z ),
-using macro package
-.I \%foo
-.RB ( groff
-option
-.BR -m ).
-.
-.
-.sp
-.EX
-\fIsh#\fR\~echo\~'\[rs]f[CB]WOW!'\~|
-> groffer --x --bg red --fg yellow --geometry 200x100 -
-.EX
-.sp
-.
-Display the word \f[CB]WOW!\fP in a small window in constant-width
-bold font, using color yellow on red background.
-.
-.
-.\" --------------------------------------------------------------------
-.SH "COMPATIBILITY"
-.\" --------------------------------------------------------------------
-.
-The
-.B \%groffer
-program is written in Perl, the Perl version during writing was v5.8.8.
-.
-.
-.P
-.B \%groffer
-provides its own parser for command line arguments that is compatible
-to both \%\f[CR]POSIX\fP
-.BR \%getopts (1)
-and \%\f[CR]GNU\fP
-.BR \%getopt (1).
-It can handle option arguments and file names containing white space
-and a large set of special characters.
-.
-The following standard types of options are supported.
-.
-.
-.Topic
-The option consisting of a single minus
-.B -
-refers to standard input.
-.
-.
-.Topic
-A single minus followed by characters refers to a single character
-option or a combination thereof; for example, the
-.B \%groffer
-short option combination
-.B -Qmfoo
-is equivalent to
-.BR -Q\~\-m\~foo .
-.
-.
-.Topic
-Long options are options with names longer than one character; they
-are always preceded by a double minus.
-.
-An option argument can either go to the next command line argument or
-be appended with an equal sign to the argument; for example,
-.B --long=arg
-is equivalent to
-.BR --long\~arg .
-.
-.
-.Topic
-An argument of
-.B --
-ends option parsing; all further command line arguments are
-interpreted as
-.I \%filespec
-parameters, i.e. file names or constructs for searching
-.IR \%man\~pages ).
-.
-.
-.Topic
-All command line arguments that are neither options nor option
-arguments are interpreted as
-.I \%filespec
-parameters and stored until option parsing has finished.
-.
-For example, the command line
-.sp
-.EX
-\fIsh#\fR\~groffer file1 -a -o arg file2
-.EE
-.sp
-is equivalent to
-.sp
-.EX
-\fIsh#\fR\~groffer -a -o arg -- file1 file2
-.EE
-.sp
-.
-.P
-The free mixing of options and
-.I \%filespec
-parameters follows the GNU principle.
-.
-That does not fulfill the strange option behavior of \%\f[CR]POSIX\fP
-that ends option processing as soon as the first non-option argument
-has been reached.
-.
-The end of option processing can be forced by the option
-.RB ` \-\- '
-anyway.
-.
-.
-.\" --------------------------------------------------------------------
-.SH "BUGS"
-.\" --------------------------------------------------------------------
-.
-Report bugs to the
-.MT bug-groff@gnu.org
-bug-groff mailing list 
-.ME .
-.
-Include a complete, self-contained example that will allow the bug to
-be reproduced, and say which version of
-.B \%groffer
-you are using.
-.
-.
-.P
-You can also use the
-.MT groff@gnu.org
-groff mailing list
-.ME ,
-but you must first subscribe to this list.
-.
-You can do that by visiting the
-.UR http://\:lists.gnu.org/\:mailman/\:listinfo/\:groff
-groff mailing list web page
-.UE .
-.
-.
-.P
-See
-.BR \%groff (@MAN1EXT@)
-for information on availability.
-.
-.
-.\" --------------------------------------------------------------------
-.SH "SEE ALSO"
-.\" --------------------------------------------------------------------
-.
-.P
-.BR \%groff (@MAN1EXT@),
-.BR \%@g@troff (@MAN1EXT@)
-.RS
-Details on the options and environment variables available in
-.BR \%groff ;
-all of them can be used with
-.BR \%groffer .
-.RE
-.
-.
-.TP
-.BR \%groff (@MAN7EXT@)
-Documentation of the
-.I \%groff
-language.
-.
-.
-.TP
-.BR \%grog (@MAN1EXT@)
-Internally,
-.B \%groffer
-tries to guess the
-.B \%groff
-command line options from the input using this program.
-.
-.
-.TP
-.BR groff_out (@MAN5EXT@)
-Documentation on the
-.I \%groff intermediate output
-.nh
-.RI ( ditroff
-output).
-.hy
-.
-.
-.TP
-.BR groff_tmac (@MAN5EXT@)
-Documentation on the
-.I \%groff
-macro files.
-.
-.
-.TP
-.BR \%man (1)
-The standard program to display
-.IR \%man\~pages .
-.
-The information there is only useful if it is the
-.I \%man\~page
-for GNU
-.BR man .
-Then it documents the options and environment variables that are
-supported by
-.BR \%groffer .
-.
-.
-.P
-.BR \%gxditview (@MAN1EXT@),
-.BR \%xditview (1x)
-.RS
-Viewers for
-.BR \%groffer 's
-.IR \%x\~mode .
-.RE
-.
-.
-.P
-.BR \%kpdf (1),
-.BR \%kghostview (1),
-.BR \%evince (1),
-.BR \%ggv (1),
-.BR \%gv (1),
-.BR \%ghostview (1),
-.BR \%gs (1)
-.RS
-Viewers for
-.BR \%groffer 's
-.IR \%ps\~mode .
-.RE
-.
-.
-.P
-.BR \%kpdf (1),
-.BR \%acroread (1),
-.BR \%evince (1),
-.BR \%xpdf (1),
-.BR \%gpdf (1),
-.BR \%kghostview (1),
-.BR \%ggv (1)
-.RS
-Viewers for
-.BR \%groffer 's
-.IR \%pdf\~mode .
-.RE
-.
-.
-.P
-.BR \%kdvi (1),
-.BR \%xdvi (1),
-.BR \%dvilx (1)
-.RS
-Viewers for
-.BR \%groffer 's
-.IR \%dvi\~mode .
-.RE
-.
-.
-.P
-.BR \%konqueror (1),
-.BR \%epiphany (1),
-.BR \%firefox (1),
-.BR \%mozilla (1),
-.BR \%netscape (1),
-.BR \%lynx (1)
-.RS
-Web-browsers for
-.BR \%groffer 's
-.I \%html
-or
-.IR \%www\~mode .
-.RE
-.
-.
-.TP
-.BR \%less (1)
-Standard pager program for the
-.IR \%tty\~mode .
-.
-.
-.P
-.BR \%gzip (1),
-.BR \%bzip2 (1)
-.RS
-The decompression programs supported by
-.BR \%groffer .
-.RE
-.
-.
-.\" --------------------------------------------------------------------
-.SH "AUTHOR"
-.\" --------------------------------------------------------------------
-.author
-.
-.
-.\" --------------------------------------------------------------------
-.SH "COPYING"
-.\" --------------------------------------------------------------------
-.copyleft
-.
-.
-.\" --------------------------------------------------------------------
-.\" Emacs settings
-.\" --------------------------------------------------------------------
-.
-.\" Local Variables:
-.\" mode: nroff
-.\" End:

Index: groffer/perl/groffer.pl
===================================================================
RCS file: groffer/perl/groffer.pl
diff -N groffer/perl/groffer.pl
--- groffer/perl/groffer.pl	1 Apr 2013 17:41:21 -0000	1.15
+++ /dev/null	1 Jan 1970 00:00:00 -0000
@@ -1,2209 +0,0 @@
-#! /usr/bin/env perl
-
-# groffer - display groff files
-
-# Source file position: <groff-source>/contrib/groffer/perl/groffer.pl
-# Installed position: <prefix>/bin/groffer
-
-# Copyright (C) 2006, 2009, 2011, 2013
-#   Free Software Foundation, Inc.
-
-# Written by Bernd Warken <groff-bernd.warken-72@web.de>.
-
-# Last update: 29 Mar 2013
-
-# 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/>.
-
-########################################################################
-
-use strict;
-use warnings;
-#use diagnostics;
-
-# temporary dir and files
-use File::Temp qw/ tempfile tempdir /;
-
-# needed for temporary dir
-use File::Spec;
-
-# for `copy' and `move'
-use File::Copy;
-
-# for fileparse, dirname and basename
-use File::Basename;
-
-# current working directory
-use Cwd;
-
-# $Bin is the directory where this script is located
-use FindBin;
-
-
-########################################################################
-# system variables and exported variables
-########################################################################
-
-our $Dev_Null;
-our $Umask;
-our @Path;
-our $Start_Dir;
-
-our $tmpdir = '';
-our ($fh_cat, $tmp_cat);
-our ($fh_stdin, $tmp_stdin);
-
-our @Addopts_Groff;
-our %Debug;
-our %Opt;
-
-our $Has_Compression;
-our $Has_bzip;
-
-our $Output_File_Name;
-
-our $Apropos_Prog;
-our $Filespec_Arg;
-our $Filespec_Is_Man;
-our $Macro_Pkg;
-our $Manspec;
-our $No_Filespecs;
-our $Special_Filespec;
-our $Special_Setup;
-
-our %Man;
-
-BEGIN {
-  $Dev_Null = File::Spec->devnull();
-
-  $Umask = umask 077;
-
-  $Start_Dir = getcwd;
-
-  # flush after each print or write command
-  $| = 1;
-}
-
-
-########################################################################
-# read-only variables with double-@ construct
-########################################################################
-
-our $File_split_env_sh;
-our $File_version_sh;
-our $Groff_Version;
-
-BEGIN {
-  {
-    my $before_make;		# script before run of `make'
-    {
-      my $at = '@';
-      $before_make = 1 if '@VERSION@' eq "${at}VERSION${at}";
-    }
-
-    my %at_at;
-    my $file_perl_test_pl;
-    my $groffer_libdir;
-
-    if ($before_make) {
-      my $groffer_perl_dir = $FindBin::Bin;
-      my $groffer_top_dir = File::Spec->catdir($groffer_perl_dir, '..');
-      $groffer_top_dir = Cwd::realpath($groffer_top_dir);
-      $at_at{'BINDIR'} = $groffer_perl_dir;
-      $at_at{'G'} = '';
-      $at_at{'LIBDIR'} = '';
-      $groffer_libdir = $groffer_perl_dir;
-      $file_perl_test_pl = File::Spec->catfile($groffer_perl_dir,
-					       'perl_test.pl');
-      $File_version_sh = File::Spec->catfile($groffer_top_dir, 'version.sh');
-      $Groff_Version = '';
-    } else {
-      $Groff_Version = '@VERSION@';
-      $at_at{'BINDIR'} = '@BINDIR@';
-      $at_at{'G'} = '@g@';
-      $at_at{'LIBDIR'} = '@libdir@';
-      $groffer_libdir = '@groffer_dir@';
-      $file_perl_test_pl = File::Spec->catfile($groffer_libdir,
-					       'perl_test.pl');
-      $File_version_sh = File::Spec->catfile($groffer_libdir, 'version.sh');
-    }
-
-    die "$groffer_libdir is not an existing directory;"
-      unless -d $groffer_libdir;
-
-    unshift(@INC, $groffer_libdir);
-
-    $File_split_env_sh = File::Spec->catfile($groffer_libdir, 'split_env.sh');
-    die "$File_split_env_sh does not exist;" unless -f "$File_split_env_sh";
-
-    # test perl on suitable version
-    die "$file_perl_test_pl does not exist;" unless -f "$file_perl_test_pl";
-    do "$file_perl_test_pl" or die "Perl test: $@";
-
-    require 'func.pl';
-    require 'man.pl';
-
-    @Path = &path_uniq( File::Spec->path() );
-
-    if ( &where_is_prog('gzip') ) {
-      $Has_Compression = 1;
-      $Has_bzip = 1 if &where_is_prog('bzip2');
-    }
-  }
-}
-
-
-########################################################################
-# modes, viewers, man sections, and defaults
-########################################################################
-
-# configuration files
-my @Conf_Files = (File::Spec->catfile(File::Spec->rootdir(),
-				      'etc', 'groff', 'groffer.conf'),
-		  File::Spec->catfile("$ENV{'HOME'}", '.groff',
-				      'groffer.conf')
-		 );
-
-my @Default_Modes = ('pdf', 'html', 'ps', 'x', 'dvi', 'tty');
-my $Default_Resolution = 75;
-my $Default_tty_Device = 'latin1';
-
-my @Macro_Packages = ('-man', '-mdoc', '-me', '-mm', '-mom', '-ms');
-
-my %Viewer_tty = ('DVI' => [],
-		  'HTML' => ['lynx', 'w3m'],
-		  'PDF' => [],
-		  'PS' => [],
-		  'TTY' => ['less -r -R', 'more', 'pager'],
-		  'X' => [],
-		 );
-
-my %Viewer_X = ('DVI' => ['kdvi', 'xdvi', 'dvilx'],
-		'HTML' => ['konqueror', 'epiphany'. 'mozilla-firefox',
-			   'firefox', 'mozilla', 'netscape', 'galeon',
-			   'opera', 'amaya','arena', 'mosaic'],
-		'PDF' => ['okular', 'kpdf', 'acroread', 'evince',
-			  'xpdf -z 150', 'gpdf', 'xpdf', 'zathura'.
-			  'epdfview', 'qpdfview', 'apvlv', 'qpdfview',
-			  'kghostview --scale 1.45', 'gv', 'ggv'],
-		'PS' => ['gs', 'gs_x11', 'ghostscript', 'ghostview',
-			 'kghostview --scale 1.45',
-			 'gv', 'okular', 'kpdf', 'evince', 'ggv'],
-		'TTY' => ['xless'],
-		'X' => ['gxditview', 'xditview'],
-	      );
-
-%Man = ('ALL' => 0,
-	'AUTO_SEC' => ['1', '2', '3', '4', '5', '6', '7', '8', '9',
-			  'n', 'o'],
-	'ENABLE' => 1,
-	   'EXT' => '',
-	   'FORCE' => 0,
-	   'IS_SETUP' => 0,
-	   'MANSPEC' => {},
-	   'LANG' => '',
-	   'LANG2' => '',
-	   'PATH' => [],
-	   'SEC' => [],
-	   'SEC_CHARS' => '',
-	   'SYS' => [],
-	  );
-$Man{'AUTO_SEC_CHARS'} = join('', @{$Man{'AUTO_SEC'}});
-
-
-########################################################################
-# given options, main_set_options()
-########################################################################
-
-my %Opts_Cmdline_Short;
-my %Opts_Cmdline_Long;
-my $Opts_Cmdline_Long_Str;
-my %Opts_Cmdline_Double;
-my %Opts_Groff_Short;
-
-sub main_set_options {
-  # the following options are ignored in groffer.pl, but are kept from
-  # groffer.sh: --shell arg, --debug-shell
-
-  my @opts_ignored_short_na = ();
-  my @opts_ignored_short_arg = ();
-
-  my @opts_ignored_long_na = ('debug-shell');
-
-  my @opts_ignored_long_arg = ('shell');
-
-
-  ###### groffer native options
-
-  my @opts_groffer_short_na = ('h', 'Q', 'v', 'V', 'X', 'Z');
-  my @opts_groffer_short_arg = ('T');
-
-  my @opts_groffer_long_na = ('auto', 'apropos', 'apropos-data',
-  'apropos-devel', 'apropos-progs', 'debug', 'debug-all',
-  'debug-filenames', 'debug-func', 'debug-grog', 'debug-not-func',
-  'debug-keep', 'debug-lm', 'debug-params', 'debug-stacks',
-  'debug-tmpdir', 'debug-user', 'default', 'do-nothing', 'dvi',
-  'groff', 'help', 'intermediate-output', 'html', 'man',
-  'no-location', 'no-man', 'no-special', 'pdf', 'ps', 'rv', 'source',
-  'text', 'to-stdout', 'text-device', 'tty', 'tty-device', 'version',
-  'whatis', 'where', 'www', 'x', 'X');
-
-### main_set_options()
-  my @opts_groffer_long_arg = ('default-modes', 'device',
-  'dvi-viewer', 'dvi-viewer-tty', 'extension', 'fg', 'fn', 'font',
-  'foreground', 'html-viewer', 'html-viewer-tty', 'mode',
-  'pdf-viewer', 'pdf-viewer-tty', 'print', 'ps-viewer',
-  'ps-viewer-tty', 'title', 'tty-viewer', 'tty-viewer-tty',
-  'www-viewer', 'www-viewer-tty', 'x-viewer', 'x-viewer-tty',
-  'X-viewer', 'X-viewer-tty');
-
-  ##### groffer options inhereted from groff
-
-  my @opts_groff_short_na = ('a', 'b', 'c', 'C', 'e', 'E', 'g', 'G',
-  'i', 'k', 'l', 'N', 'p', 'R', 's', 'S', 't', 'U', 'z');
-
-  my @opts_groff_short_arg = ('d', 'f', 'F', 'I', 'K', 'L', 'm', 'M', 'n',
-  'o', 'P', 'r', 'w', 'W');
-
-  my @opts_groff_long_na = ();
-  my @opts_groff_long_arg = ();
-
-  ##### groffer options inhereted from the X Window toolkit
-
-  my @opts_x_short_na = ();
-  my @opts_x_short_arg = ();
-
-  my @opts_x_long_na = ('iconic', 'rv');
-
-  my @opts_x_long_arg = ('background', 'bd', 'bg', 'bordercolor',
-  'borderwidth', 'bw', 'display', 'fg', 'fn', 'font', 'foreground',
-  'ft', 'geometry', 'resolution', 'title', 'xrm');
-
-### main_set_options()
-  ###### groffer options inherited from man
-
-  my @opts_man_short_na = ();
-  my @opts_man_short_arg = ();
-
-  my @opts_man_long_na = ('all', 'ascii', 'catman', 'ditroff',
-  'local-file', 'location', 'troff', 'update');
-
-  my @opts_man_long_arg = ('locale', 'manpath', 'pager',
-  'preprocessor', 'prompt', 'sections', 'systems', 'troff-device');
-
-  ###### additional options for parsing evironment variable $MANOPT only
-
-  my @opts_manopt_short_na = ('7', 'a', 'c', 'd', 'D', 'f', 'h', 'k',
-  'l', 't', 'u', 'V', 'w', 'Z');
-
-  my @opts_manopt_short_arg = ('e', 'L', 'm', 'M', 'p', 'P', 'r', 'S',
-  'T');
-
-  my @opts_manopt_long_na = (@opts_man_long_na, 'apropos', 'debug',
-  'default', 'help', 'html', 'ignore-case', 'location-cat',
-  'match-case', 'troff', 'update', 'version', 'whatis', 'where',
-  'where-cat');
-
-  my @opts_manopt_long_arg = (@opts_man_long_na, 'config_file',
-  'encoding', 'extension', 'locale');
-
-### main_set_options()
-  ###### collections of command line options
-
-  # There are two hashes that control the whole of the command line
-  # options, one for short and one for long options.  Options without
-  # and with arguments are mixed by advicing a value of 0 for an option
-  # without argument and a value of 1 for an option with argument.
-  # The options are with leading minus.
-
-  foreach (@opts_groffer_short_na, @opts_groff_short_na,
-	   @opts_x_short_na, @opts_man_short_na, @opts_ignored_short_na) {
-    $Opts_Cmdline_Short{"-$_"} = 0 if $_;
-  }
-  foreach (@opts_groffer_short_arg, @opts_groff_short_arg,
-	   @opts_x_short_arg, @opts_man_short_arg, @opts_ignored_short_arg) {
-    $Opts_Cmdline_Short{"-$_"} = 1 if $_;
-  }
-
-  foreach (@opts_groffer_long_na, @opts_groff_long_na,
-	   @opts_x_long_na, @opts_man_long_na, @opts_ignored_long_na) {
-    $Opts_Cmdline_Long{"--$_"} = 0 if $_;
-  }
-  foreach (@opts_groffer_long_arg, @opts_groff_long_arg,
-	   @opts_x_long_arg, @opts_man_long_arg, @opts_ignored_long_arg) {
-    $Opts_Cmdline_Long{"--$_"} = 1 if $_;
-  }
-
-  # For determining abbreviations of an option take two spaces as join
-  # for better check.
-  # The options are without leading minus.
-  $Opts_Cmdline_Long_Str = join '  ', keys %Opts_Cmdline_Long;
-  if ($Opts_Cmdline_Long_Str) {
-    $Opts_Cmdline_Long_Str = " $Opts_Cmdline_Long_Str ";
-    $Opts_Cmdline_Long_Str =~ s/--//g;
-  }
-
-### main_set_options()
-  # options with equal meaning are mapped to a single option name
-  # all of these have leading minus characters
-  %Opts_Cmdline_Double = ('-h' => '--help',
-			  '-Q' => '--source',
-			  '-T' => '--device',
-			  '-v' => '--version',
-			  '-Z' => '--intermediate-output',
-			  '--bd' => '--bordercolor',
-			  '--bg' => '--background',
-			  '--bw' => '--borderwidth',
-			  '--debug-all' => '--debug',
-			  '--ditroff' => '--intermediate-output',
-			  '--dvi-viewer-tty' => '--dvi-viewer',
-			  '--fg' => '--foreground',
-			  '--fn' => '--font',
-			  '--ft' => '--font',
-			  '--html-viewer-tty' => '--html-viewer',
-			  '--pdf-viewer-tty' => '--pdf-viewer',
-			  '--ps-viewer-tty' => '--ps-viewer',
-			  '--troff-device' => '--device',
-			  '--tty-device' => '--text-device',
-			  '--tty-viewer' => '--pager',
-			  '--tty-viewer-tty' => '--pager',
-			  '--where' => '--location',
-			  '--www' => '--html',
-			  '--www-viewer' => '--html-viewer',
-			  '--www-viewer-tty' => '--html-viewer',
-			  '--x-viewer-tty' => '--x-viewer',
-			  '--X' => '--x',
-			  '--X-viewer' => '--x-viewer',
-			  '--X-viewer-tty' => '--x-viewer',
-			 );
-
-  # groff short options with leading minus
-  foreach (@opts_groff_short_na) {
-    $Opts_Groff_Short{"-$_"} = 0;
-  }
-  foreach (@opts_groff_short_arg) {
-    $Opts_Groff_Short{"-$_"} = 1;
-  }
-
-}				# main_set_options()
-
-
-########################################################################
-# $MANOPT, main_parse_MANOPT()
-########################################################################
-
-# handle environment variable $MANOPT
-my @Manopt;
-
-sub main_parse_MANOPT {
-  if ($ENV{'MANOPT'}) {
-    @Manopt = `sh $File_split_env_sh MANOPT`;
-    chomp @Manopt;
-
-    my @manopt;
-    # %opts stores options that are used by groffer for $MANOPT
-    # All options not in %opts are ignored.
-    # Check options used with %Opts_Cmdline_Double.
-    # 0: option used ('' for ignore), 1: has argument or not
-### main_parse_MANOPT()
-    my %opts = ('-7' => ['--ascii', 0],
-		'--ascii' => ['--ascii', 0],
-		'-a' => ['--all', 0],
-		'--all' => ['--all', 0],
-		'-c' => ['', 1],
-		'--catman' => ['', 1],
-		'-e' => ['--extension', 1],
-		'--extension' => ['--extension', 1],
-		'-f' => ['--whatis', 1],
-		'--whatis' => ['--whatis', 1],
-		'-L' => ['--locale', 1],
-		'--locale' => ['--locale', 1],
-		'-m' => ['--systems', 1],
-		'--systems' => ['--systems', 1],
-		'-M' => ['--manpath', 1],
-		'-manpath' => ['--manpath', 1],
-		'--manpath' => ['--manpath', 1],
-		'-p' => ['', 1],
-		'--preprocessor' => ['', 1],
-		'-P' => ['--pager', 1],
-		'-pager' => ['--pager', 1],
-		'-r' => ['', 1],
-		'-prompt' => ['', 1],
-		'-S' => ['--sections', 1],
-		'-sections' => ['--sections', 1],
-		'-T' => ['-T', 1],
-		'--device' => ['-T', 1],
-		'-w' => ['--location', 0],
-		'--where' => ['--location', 0],
-		'--location' => ['--location', 0],
-	       );
-
-### main_parse_MANOPT()
-    my ($opt, $has_arg);
-    my $i = 0;
-    my $n = $#Manopt;
-    while ($i <= $n) {
-      my $o = $Manopt[$i];
-      ++$i;
-      # ignore, when not in %opts
-      next unless (exists $opts{$o});
-      if (($o eq '-D') or ($o eq '--default')) {
-	@manopt = ();
-	next;
-      }
-      $opt = $opts{$o}[0];
-      $has_arg = $opts{$o}[1];
-      # ignore, when empty in %opts
-      unless ($opt) {
-	# ignore without argument
-	next unless ($has_arg);
-	# ignore the argument as well
-	++$i;
-	next;
-      }
-      if ($has_arg) {
-	last if ($i > $n);
-	push @manopt, $opt, $Manopt[$i];
-	++$i;
-	next;
-      } else {
-	push @manopt, $opt;
-	next;
-      }
-    }
-    @Manopt = @manopt;
-  }
-}				# main_parse_MANOPT()
-
-
-########################################################################
-# configuration files, $GROFFER_OPT, and command line, main_config_params()
-########################################################################
-
-my @Options;
-my @Filespecs;
-my @Starting_Conf;
-my @Starting_ARGV = @ARGV;
-sub main_config_params {	# handle configuration files
-  # options may not be abbreviated, but must be exact
-  my @conf_args;
-  foreach my $f (@Conf_Files) {
-    if (-s $f) {
-      my $fh;
-      open $fh, "<$f" || next;
-      my $nr = 0;
-    LINE: foreach my $line (<$fh>) {
-	++ $nr;
-	chomp $line;
-	# remove starting and ending whitespace
-	$line =~ s/^\s+|\s+$//g;
-	# replace whitespace by single space
-	$line =~ s/\s+/ /g;
-	# ignore all lines that do not start with minus
-	next unless $line =~ /^-/;
-	# three minus
-	if ($line =~ /^---/) {
-	  warn "Wrong option $line in configuration file $f.\n";
-	  next;
-	}
-	if ($line =~ /^--[ =]/) {
-	  warn "No option name in `$line' in configuration " .
-	    "file $f.\n";
-	  next;
-	}
-	push @Starting_Conf, $line;
-	# -- or -
-	if ($line =~ /^--?$/) {
-	  warn "`$line' is not allowed in configuration files.\n";
-	  next;
-	}
-	### main_config_params()
-	if ($line =~ /^--/) {	# line is long option
-	  my ($name, $arg);
-	  if ($line =~ /[ =]/) { # has arg on line
-	    $line =~ /^(--[^ =]+)[ =] ?(.*)$/;
-	    ($name, $arg) = ($1, $2);
-	    $arg =~ s/[\'\"]//g;
-	  } else {		# does not have an argument on line
-	    $name = $line;
-	  }
-	  $name =~ s/[\'\"]//g;
-	  unless (exists $Opts_Cmdline_Long{$name}) {
-	    # option does not exist
-	    warn "Option `$name' does not exist.\n";
-	    next LINE;
-	  }
-	  # option exists
-	  if ($Opts_Cmdline_Long{$name}) { # option has arg
-	    if (defined $arg) {
-	      push @conf_args, $name, $arg;
-	      next LINE;
-	    } else {
-	      warn "Option `$name' needs an argument in " .
-		"configuration file $f\n";
-	      next LINE;
-	    }
-	  } else {		# option has no arg
-	    if (defined $arg) {
-	      warn "Option `$name' may not have an argument " .
-		"in configuration file $f\n";
-	      next LINE;
-	    } else {
-	      push @conf_args, $name;
-	      next LINE;
-	    }
-	  }
-	  ### main_config_params()
-	} else {		# line is short option or cluster
-	  $line =~ s/^-//;
-	  while ($line) {
-	    $line =~ s/^(.)//;
-	    my $opt = "-$1";
-	    next if ($opt =~ /\'\"/);
-	    if ($opt =~ /- /) {
-	      warn "Option `$conf_args[$#conf_args]' does not " .
-		"have an argument.\n";
-	      next LINE;
-	    }
-	    if (exists $Opts_Cmdline_Short{$opt}) {
-	      # short opt exists
-	      push @conf_args, $opt;
-	      if ($Opts_Cmdline_Short{$opt}) { # with arg
-		my $arg = $line;
-		$arg =~ s/^ //;
-		$arg =~ s/\'\"//g;
-		push @conf_args, "$arg";
-		next LINE;
-	      } else {		# no arg
-		next;
-	      }
-	    } else {		# short option does not exist
-	      warn "Wrong short option `-$opt' from " .
-		"configuration.  Rest of line ignored.\n";
-	      next LINE;
-	    }
-	  }
-	}
-      }
-      close $fh;
-    }
-  }
-
-### main_config_params()
-  # handle environment variable $GROFFER_OPT
-  my @GROFFER_OPT;
-  if ($ENV{'GROFFER_OPT'}) {
-    @GROFFER_OPT = `sh $File_split_env_sh GROFFER_OPT`;
-    chomp @GROFFER_OPT;
-  }
-
-  # Handle command line parameters together with $GROFFER_OPT.
-  # Options can be abbreviated, with each - as abbreviation place.
-  {
-    my @argv0 = (@GROFFER_OPT, @ARGV);
-    my @argv;
-    my $only_files = 0;
-    my $n = $#argv0;		  # last element
-    my $n1 = scalar @GROFFER_OPT; # first element of @ARGV
-    my $i = 0;			# number of the element
-    my @s = ('the environment variable $GROFFER_OPT', 'the command line');
-    my $j = 0;			# index in @s, 0 before $n1, 1 then
-  ELT: while ($i <= $n) {
-      my $elt = $argv0[$i];
-      $j = 1 if $i >= $n1;
-      ++$i;
-      # remove starting and ending whitespace
-      $elt =~ s/^\s+|\s+$//g;
-      # replace whitespace by single space
-      $elt =~ s/\s+/ /g;
-
-      if ($only_files) {
-	push @Filespecs, $elt;
-	next ELT;
-      }
-
-### main_config_params()
-      if ($elt =~ /^-$/) {	# -
-	push @Filespecs, $elt;
-	next ELT;
-      }
-      if ($elt =~ /^--$/) {	# --
-	$only_files = 1;
-	next ELT;
-      }
-
-      if ($elt =~ /^--[ =]/) {	# no option name
-	warn "No option name in `$elt' at $s[$j].\n";
-	next ELT;
-      }
-      if ($elt =~ /^---/) {	# wrong with three minus
-	warn "Wrong option `$elt' at $s[$j].\n";
-	next ELT;
-      }
-
-      if ($elt =~ /^--[^-]/) {	# long option
-	my ($name, $opt, $abbrev, $arg);
-	if ($elt =~ /[ =]/) {	# has arg on elt
-	  $elt =~ /^--([^ =]+)[ =] ?(.*)$/;
-	  ($name, $arg) = ($1, $2);
-	  $opt = "--$name";
-	  $abbrev = $name;
-	  $arg =~ s/[\'\"]//g;
-	} else {		# does not have an argument in the element
-	  $opt = $name = $elt;
-	  $name =~ s/^--//;
-	  $abbrev = $name;
-	}
-### main_config_params()
-	# remove quotes in name
-	$name =~ s/[\'\"]//g;
-	my $match = $name;
-	$match =~ s/-/[^- ]*-/g;
-	### main_config_params()
-	if (exists $Opts_Cmdline_Long{$opt}) {
-	  # option exists exactly
-	} elsif ($Opts_Cmdline_Long_Str =~ / (${match}[^- ]*?) /) {
-	  # option is an abbreviation without further -
-	  my $n0 = $1;
-	  if ($Opts_Cmdline_Long_Str =~
-	      / (${match}[^- ]*) .* (${match}[^- ]*) /) {
-	    warn "Option name `--$abbrev' is not unique: " .
-	      "--$1 --$2 \n";
-	    next ELT;
-	  }
-	  $name = $n0;
-	  $opt = "--$n0";
-	} elsif ($Opts_Cmdline_Long_Str =~ / (${match}[^ ]*) /) {
-	  # option is an abbreviation with further -
-	  my $n0 = $1;
-	  if ($Opts_Cmdline_Long_Str =~
-	      / (${match}[^ ]*) .* (${match}[^ ]*) /) {
-	    warn "Option name `--$abbrev' is not unique: " .
-	      "--$1 --$2 \n";
-	    next ELT;
-	  }
-	  $name = $n0;
-	  $opt = "--$n0";
-	} else {
-	  warn "Option `--$abbrev' does not exist.\n";
-	  next ELT;
-	}
-### main_config_params()
-	if ($Opts_Cmdline_Long{$opt}) { # option has arg
-	  if (defined $arg) {
-	    push @argv, "--$name", $arg;
-	    next ELT;
-	  } else {		# $arg not defined, argument at next element
-	    if (($i == $n1) || ($i > $n)) {
-	      warn "No argument left for option " .
-		"`$elt' at $s[$j].\n";
-	      next ELT;
-	    }
-	    ### main_config_params()
-	    # add argument as next element
-	    push @argv, "--$name", $argv0[$i];
-	    ++$i;
-	    next ELT;
-	  }			# if (defined $arg)
-	} else {		# option has no arg
-	  if (defined $arg) {
-	    warn "Option `$abbrev' may not have an argument " .
-	      "at $s[$j].\n";
-	    next ELT;
-	  } else {
-	    push @argv, "--$name";
-	    next ELT;
-	  }
-	}			# if ($Opts_Cmdline_Long{$opt})
-### main_config_params()
-      } elsif ($elt =~ /^-[^-]/) { # short option or cluster
-	my $cluster = $elt;
-	$cluster =~ s/^-//;
-	while ($cluster) {
-	  $cluster =~ s/^(.)//;
-	  my $opt = "-$1";
-	  if (exists $Opts_Cmdline_Short{$opt}) { # opt exists
-	    if ($Opts_Cmdline_Short{$opt}) { # with arg
-	      if ($cluster) {	# has argument in this element
-		$cluster =~ s/^ //;
-		$cluster =~ s/\'\"//g;
-				# add argument as rest of this element
-		push @argv, $opt, $cluster;
-		next ELT;
-	      } else {		# argument at next element
-		if (($i == $n1) || ($i > $n)) {
-		  warn "No argument left for option " .
-		    "`$opt' at $s[$j].\n";
-		  next ELT;
-		}
-		### main_config_params()
-				# add argument as next element
-		push @argv, $opt, $argv0[$i];
-		++$i;
-		next ELT;
-	      }
-	    } else {		# no arg
-	      push @argv, $opt;
-	      next;
-	    }
-	  } else {		# short option does not exist
-	    warn "Wrong short option `$opt' at $s[$j].\n";
-	    next ELT;
-	  }			# if (exists $Opts_Cmdline_Short{$opt})
-	}			# while ($cluster)
-      } else {			# not an option, file name
-	push @Filespecs, $elt;
-	next;
-      }
-    }
-### main_config_params()
-    @Options = (@Manopt, @conf_args, @argv);
-    foreach my $i (0..$#Options) {
-      if ( exists $Opts_Cmdline_Double{ $Options[$i] } ) {
-	$Options[$i] = $Opts_Cmdline_Double{ $Options[$i] };
-      }
-    }
-    @Filespecs = ('-') unless (@Filespecs);
-    @ARGV = (@Options, '--', @Filespecs);
-  }
-} # main_config_params()
-
-if (0) {
-  print STDERR "<$_>\n" foreach @ARGV;
-}
-
-
-########################################################################
-# main_parse_params()
-########################################################################
-
-my $i;
-my $n;
-
-$Opt{'XRM'} = [];
-
-sub main_parse_params {
-  $i = 0;
-  $n = $#Options;
-
-  # options that are ignored in this part
-  # shell version of groffer: --debug*, --shell
-  # man options: --catman (only special in man),
-  #              --preprocessor (force groff preproc., handled by grog),
-  #              --prompt (prompt for less, ignored),
-  #              --troff (-mandoc, handled by grog),
-  #              --update (inode check, ignored)
-  my %ignored_opts = (
-		      '--catman' => 0,
-		      '--debug-func' => 0,
-		      '--debug-not-func' => 0,
-		      '--debug-lm' => 0,
-		      '--debug-shell' => 0,
-		      '--debug-stacks' => 0,
-		      '--debug-user' => 0,
-		      '--preprocessor' => 1,
-		      '--prompt' => 1,
-		      '--shell' => 1,
-		      '--troff' => 0,
-		      '--update' => 0,
-		     );
-
-### main_parse_params()
-  my %long_opts =
-    (
-     '--debug' =>
-     sub { $Debug{$_} = 1 foreach (qw/FILENAMES GROG KEEP PARAMS TMPDIR/); },
-     '--debug-filenames' => sub { $Debug{'FILENAMES'} = 1; },
-     '--debug-grog' => sub { $Debug{'GROG'} = 1; },
-     '--debug-keep' => sub { $Debug{'KEEP'} = 1; $Debug{'PARAMS'} = 1; },
-     '--debug-params' => sub { $Debug{'PARAMS'} = 1; },
-     '--debug-tmpdir' => sub { $Debug{'TMPDIR'} = 1; },
-     '--help' => sub { &usage(); $Opt{'DO_NOTHING'} = 1; },
-     '--source' => sub { $Opt{'MODE'} = 'source'; },
-     '--device' =>
-     sub {  $Opt{'DEVICE'} = &_get_arg();
-	    my %modes = ( 'dvi'=> 'dvi',
-			  'html' => 'html',
-			  'lbp' => 'groff',
-			  'lj4' => 'groff',
-			  'ps' => 'ps',
-			  'ascii' => 'tty',
-			  'cp1047' => 'tty',
-			  'latin1' => 'tty',
-			  'utf8' => 'tty',
-			);
-	    if ($Opt{'DEVICE'} =~ /^X.*/) {
-	      $Opt{'MODE'} = 'x';
-	    } elsif ( exists $modes{ $Opt{'DEVICE'} } ) {
-	      if ( $modes{ $Opt{'DEVICE'} } eq 'tty' ) {
-		$Opt{'MODE'} = 'tty'
-		  unless ($Opt{'MODE'} eq 'text');
-	      } else {
-		$Opt{'MODE'} = $modes{ $Opt{'DEVICE'} };
-	      }
-	    } else {
-	      # for all elements not in %modes
-	      $Opt{'MODE'} = 'groff';
-	    }
-	  },
-### main_parse_params()
-     '--version' => sub { &version(); $Opt{'DO_NOTHING'} = 1; },
-     '--intermediate-output' => sub { $Opt{'Z'} = 1; },
-     '--all' => sub { $Opt{'ALL'} = 1; },
-     '--apropos' =>		# run apropos
-     sub { $Opt{'APROPOS'} = 1;
-	   delete $Opt{'APROPOS_SECTIONS'};
-	   delete $Opt{'WHATIS'}; },
-     '--apropos-data' =>	# run apropos for data sections
-     sub { $Opt{'APROPOS'} = 1;
-	   $Opt{'APROPOS_SECTIONS'} = '457';
-	   delete $Opt{'WHATIS'}; },
-     '--apropos-devel' =>	# run apropos for devel sections
-     sub { $Opt{'APROPOS'} = 1;
-	   $Opt{'APROPOS_SECTIONS'} = '239';
-	   delete $Opt{'WHATIS'}; },
-     '--apropos-progs' =>	# run apropos for prog sections
-     sub { $Opt{'APROPOS'} = 1;
-	   $Opt{'APROPOS_SECTIONS'} = '168';
-	   delete $Opt{'WHATIS'}; },
-     '--ascii' =>
-     sub { push @Addopts_Groff, '-mtty-char';
-	   $Opt{'MODE'} = 'text' unless $Opt{'MODE'}; },
-     '--auto' =>		# the default automatic mode
-     sub { delete $Opt{'MODE'}; },
-     '--bordercolor' =>		# border color for viewers, arg
-     sub { $Opt{'BD'} = &_get_arg(); },
-     '--background' =>		# background color for viewers, arg
-     sub { $Opt{'BG'} = &_get_arg(); },
-### main_parse_params()
-     '--borderwidth' =>		# border width for viewers, arg
-     sub { $Opt{'BW'} = &_get_arg(); },
-     '--default' =>		# reset variables to default
-     sub { %Opt = (); },
-     '--default-modes' =>	# sequence of modes in auto mode; arg
-     sub { $Opt{'DEFAULT_MODES'} = &_get_arg(); },
-     '--display' =>		# set X display, arg
-     sub { $Opt{'DISPLAY'} = &_get_arg(); },
-     '--do-nothing' => sub { $Opt{'DO_NOTHING'} = 1; },
-     '--dvi' => sub { $Opt{'MODE'} = 'dvi'; },
-     '--dvi-viewer' =>		# viewer program for dvi mode; arg
-     sub { $Opt{'VIEWER_DVI'} = &_get_arg(); },
-     '--extension' =>		# the extension for man pages, arg
-     sub { $Opt{'EXTENSION'} = &_get_arg(); },
-     '--foreground' =>		# foreground color for viewers, arg
-     sub { $Opt{'FG'} = &_get_arg(); },
-     '--font' =>		# set font for viewers, arg
-     sub { $Opt{'FN'} = &_get_arg(); },
-     '--geometry' =>		# window geometry for viewers, arg
-     sub { $Opt{'GEOMETRY'} = &_get_arg(); },
-     '--groff' => sub { $Opt{'MODE'} = 'groff'; },
-     '--html' => sub { $Opt{'MODE'} = 'html'; },
-     '--html-viewer' =>		# viewer program for html mode; arg
-     sub { $Opt{'VIEWER_HTML'} = &_get_arg(); },
-     '--iconic' =>		# start viewers as icons
-     sub { $Opt{'ICONIC'} = 1; },
-     '--locale' =>		# set language for man pages, arg
-     # argument is xx[_territory[.codeset[@modifier]]] (ISO 639,...)
-     sub { $Opt{'LANG'} = &_get_arg(); },
-     '--local-file' =>		# force local files; same as `--no-man'
-     sub { delete $Man{'ENABLE'}; delete $Man{'FORCE'}; },
-     '--location' =>		# print file locations to stderr
-     sub { $Opt{'LOCATION'} = 1; },
-### main_parse_params()
-     '--man' =>			# force all file params to be man pages
-     sub { $Man{'ENABLE'} = 1; $Man{'FORCE'} = 1; },
-     '--manpath' =>		# specify search path for man pages, arg
-     # arg is colon-separated list of directories
-     sub { $Opt{'MANPATH'} = &_get_arg(); },
-     '--mode' =>		# display mode
-     sub { my $arg = &_get_arg();
-	   my %modes = ( '' => '',
-			 'auto' => '',
-			 'groff' => 'groff',
-			 'html' => 'html',
-			 'www' => 'html',
-			 'dvi' => 'dvi',
-			 'pdf' => 'pdf',
-			 'ps' => 'ps',
-			 'text' => 'text',
-			 'tty' => 'tty',
-			 'X' => 'x',
-			 'x' => 'x',
-			 'Q' => 'source',
-			 'source' => 'source',
-		       );
-	   if ( exists $modes{$arg} ) {
-	     if ( $modes{$arg} ) {
-	       $Opt{'MODE'} = $modes{$arg};
-	     } else {
-	       delete $Opt{'MODE'};
-	     }
-	   } else {
-	     warn "Unknown mode in `$arg' for --mode\n";
-	   }
-	 },
-### main_parse_params()
-     '--no-location' =>		# disable former call to `--location'
-     sub { delete $Opt{'LOCATION'}; },
-     '--no-man' =>		# disable search for man pages
-     sub { delete $Man{'ENABLE'}; delete $Man{'FORCE'}; },
-     '--no-special' =>		# disable some special former calls
-     sub { delete $Opt{'ALL'}; delete $Opt{'APROPOS'};
-	   delete $Opt{'WHATIS'}; },
-     '--pager' =>		# set paging program for tty mode, arg
-     sub { $Opt{'PAGER'} = &_get_arg(); },
-     '--pdf' => sub { $Opt{'MODE'} = 'pdf'; },
-     '--pdf-viewer' =>		# viewer program for pdf mode; arg
-     sub { $Opt{'VIEWER_PDF'} = &_get_arg(); },
-     '--print' =>		# print argument, for argument test
-     sub { my $arg = &_get_arg; print STDERR "$arg\n"; },
-     '--ps' => sub { $Opt{'MODE'} = 'ps'; },
-     '--ps-viewer' =>		# viewer program for ps mode; arg
-     sub { $Opt{'VIEWER_PS'} = &_get_arg(); },
-     '--resolution' =>		# set resolution for X devices, arg
-     sub { my $arg = &_get_arg();
-	   my %res = ( '75' => 75,
-		       '75dpi' => 75,
-		       '100' => 100,
-		       '100dpi' => 100,
-		     );
-	   if (exists $res{$arg}) {
-	     $Opt{'RESOLUTION'} = $res{$arg};
-	   } else {
-	     warn "--resolution allows only 75, 75dpi, " .
-	       "100, 100dpi as argument.\n";
-	   }
-	 },
-### main_parse_params()
-     '--rv' => sub { $Opt{'RV'} = 1; },
-     '--sections' =>		# specify sections for man pages, arg
-     # arg is a `:'-separated (colon) list of section names
-     sub { my $arg = &_get_arg();
-	   my @arg = split /:/, $arg;
-	   my $s;
-	   foreach (@arg) {
-	     /^(.)/;
-	     my $c = $1;
-	     if ($Man{'AUTO_SEC_CHARS'} =~ /$c/) {
-	       $s .= $c;
-	     } else {
-	       warn "main_parse_params(): not a man section `$c';";
-	     }
-	   }
-	   $Opt{'SECTIONS'} = $s; },
-     '--systems' =>		# man pages for different OS's, arg
-     # argument is a comma-separated list
-     sub { $Opt{'SYSTEMS'} = &_get_arg(); },
-     '--text' =>		# text mode without pager
-     sub { $Opt{'MODE'} = 'text'; },
-     '--title' =>		# title for X viewers; arg
-     sub { my $arg = &_get_arg();
-	   if ($arg) {
-	     if ( $Opt{'TITLE'} ) {
-	       $Opt{'TITLE'} = "$Opt{'TITLE'} $arg";
-	     } else {
-	       $Opt{'TITLE'} = $arg;
-	     }
-	   }
-	 },
-     '--tty' =>			# tty mode, text with pager
-     sub { $Opt{'MODE'} = 'tty'; },
-     '--to-stdout' =>		# print mode file without display
-     sub { $Opt{'STDOUT'} = 1; },
-     '--text-device' =>		# device for tty mode; arg
-     sub { $Opt{'TEXT_DEVICE'} = &_get_arg(); },
-     '--whatis' => sub { delete $Opt{'APROPOS'}; $Opt{'WHATIS'} = 1; },
-     '--x' => sub { $Opt{'MODE'} = 'x'; },
-### main_parse_params()
-     '--xrm' =>			# pass X resource string, arg
-     sub { my $arg = &_get_arg(); push @{$Opt{'XRM'}}, $arg if $arg; },
-     '--x-viewer' =>		# viewer program for x mode; arg
-     sub { $Opt{'VIEWER_X'} = &_get_arg(); },
-    );
-
-  my %short_opts = (
-		    '-V' => sub { $Opt{'V'} = 1; },
-		    '-X' => sub { $Opt{'X'} = 1; },
-		   );
-
-  if (0) {
-    # check if all options are handled in parse parameters
-
-    #short options
-    my %these_opts = (%ignored_opts, %short_opts, %Opts_Groff_Short,
-		      %Opts_Cmdline_Double);
-    foreach my $key (keys %Opts_Cmdline_Short) {
-      warn "unused option: $key" unless exists $these_opts{$key};
-    }
-
-    # long options
-    %these_opts = (%ignored_opts, %long_opts, %Opts_Cmdline_Double);
-    foreach my $key (keys %Opts_Cmdline_Long) {
-      warn "unused option: $key" unless exists $these_opts{$key};
-    }
-  }				# if (0)
-
-### main_parse_params()
- OPTION: while ($i <= $n) {
-    my $opt = $Options[$i];
-    ++$i;
-    if ($opt =~ /^-([^-])$/) {	# single minus for short option
-      if (exists $short_opts{$opt}) { # short option handled by hash
-	$short_opts{$opt}->();
-	next OPTION;
-      } else {			# $short_opts{$opt} does not exist
-	my $c = $1;		# the option character
-	next OPTION unless $c;
-	if ( exists $Opts_Groff_Short{ $opt } ) { # groff short option
-	  if ( $Opts_Groff_Short{ $opt } ) { # option has argument
-	    my $arg = $Options[$i];
-	    ++$i;
-	    push @Addopts_Groff, $opt, $arg;
-	    next OPTION;
-	  } else {		# no argument for this option
-	    push @Addopts_Groff, $opt;
-	    next OPTION;
-	  }
-	} elsif ( exists $Opts_Cmdline_Short{ $opt } ) {
-	  # is a groffer short option
-	  warn "Groffer option $opt not handled " .
-	    "in parameter parsing";
-	} else {
-	  warn "$opt is not a groffer option.\n";
-	}
-      }				# if (exists $short_opts{$opt})
-    }				# if ($opt =~ /^-([^-])$/)
-    # Now it is a long option
-
-    # handle ignored options
-    if ( exists $ignored_opts{ $opt } ) {
-      ++$i if ( $ignored_opts{ $opt } );
-      next OPTION;
-    }
-### main_parse_params()
-
-    # handle normal long options
-    if (exists $long_opts{$opt}) {
-      $long_opts{$opt}->();
-    } else {
-      warn "Unknown option $opt.\n";
-    }
-    next OPTION;
-  }				# while ($i <= $n)
-
-  if ($Debug{'PARAMS'}) {
-    print STDERR '$MANOPT: ' . "$ENV{'MANOPT'}\n" if $ENV{'MANOPT'};
-    foreach (@Starting_Conf) {
-      print STDERR "configuration: $_\n";
-    }
-    print STDERR '$GROFFER_OPT: ' . "$ENV{'GROFFER_OPT'}\n"
-      if $ENV{'GROFFER_OPT'};
-    print STDERR "command line: @Starting_ARGV\n";
-    print STDERR "parameters: @ARGV\n";
-  }
-
-  if ( $Opt{'WHATIS'} ) {
-    die "main_parse_params(): cannot handle both `whatis' and `apropos';"
-      if $Opt{'APROPOS'};
-    $Man{'ALL'} = 1;
-    delete $Opt{'APROPOS_SECTIONS'};
-  }
-
-  if ( $Opt{'DO_NOTHING'} ) {
-    exit;
-  }
-
-  if ( $Opt{'DEFAULT_MODES'} ) {
-    @Default_Modes = split /,/, $Opt{'DEFAULT_MODES'};
-  }
-}				# main_parse_params()
-
-
-sub _get_arg {
-  if ($i > $n) {
-    die '_get_arg(): No argument left for last option;';
-  }
-  my $arg = $Options[$i];
-  ++$i;
-  $arg;
-}				# _get_arg() of main_parse_params()
-
-
-########################################################################
-# main_set_mode()
-########################################################################
-
-my $Viewer_Background;
-my $PDF_Did_Not_Work;
-my $PDF_Has_gs;
-my $PDF_Has_ps2pdf;
-my %Display = ('MODE' => '',
-	       'PROG' => '',
-	       'ARGS' => ''
-	      );
-
-sub main_set_mode {
-  my @modes;
-
-  # set display
-  $ENV{'DISPLAY'} = $Opt{'DISPLAY'} if $Opt{'DISPLAY'};
-
-  push @Addopts_Groff, '-V' if $Opt{'V'};
-
-  if ( $Opt{'X'} ) {
-    $Display{'MODE'} = 'groff';
-    push @Addopts_Groff, '-X';
-  }
-
-  if ( $Opt{'Z'} ) {
-    $Display{'MODE'} = 'groff';
-    push @Addopts_Groff, '-Z';
-  }
-
-  $Display{'MODE'} = 'groff' if $Opt{'MODE'} and $Opt{'MODE'} eq 'groff';
-
-  return 1 if $Display{'MODE'} and $Display{'MODE'} eq 'groff';
-
-### main_set_mode()
-  if ($Opt{'MODE'}) {
-    if ($Opt{'MODE'} =~ /^(source|text|tty)$/) {
-      $Display{'MODE'} = $Opt{'MODE'};
-      return 1;
-    }
-    $Display{'MODE'} = $Opt{'MODE'} if $Opt{'MODE'} =~ /^html$/;
-    @modes = ($Opt{'MODE'});
-  } else {			# empty mode
-    if ($Opt{'DEVICE'}) {
-      if ($Opt{'DEVICE'} =~ /^X/) {
-	&is_X() || die "no X display found for device $Opt{'DEVICE'}";
-	$Display{'MODE'} = 'x';
-	return 1;
-      }
-      ;
-      if ($Opt{'DEVICE'} =~ /^(ascii|cp1047|latin1|utf8)$/) {
-	$Display{'MODE'} ne 'text' and $Display{'MODE'} = 'tty';
-	return 1;
-      }
-      ;
-      unless (&is_X) {
-	$Display{'MODE'} = 'tty';
-	return 1;
-      }
-    }				# check device
-    @modes = @Default_Modes;
-  }				# check mode
-
-### main_set_mode()
- LOOP: foreach my $m (@modes) {
-    $Viewer_Background = 0;
-    if ($m =~ /^(test|tty|X)$/) {
-      $Display{'MODE'} = $m;
-      return 1;
-    } elsif ($m eq 'pdf') {
-      next LOOP if $PDF_Did_Not_Work;
-      $PDF_Has_gs = &where_is_prog('gs') ? 1 : 0
-	unless (defined $PDF_Has_gs);
-      $PDF_Has_ps2pdf = &where_is_prog('ps2pdf') ? 1 : 0
-	unless (defined $PDF_Has_ps2pdf);
-      if ( (! $PDF_Has_gs) and (! $PDF_Has_ps2pdf) ) {
-	$PDF_Did_Not_Work = 1;
-	next LOOP;
-      }
-
-      if (&_get_prog_args($m)) {
-	return 1;
-      } else {
-	$PDF_Did_Not_Work = 1;
-	next LOOP;
-      }
-    } else {			# other modes
-      &_get_prog_args($m) ? return 1 : next LOOP;
-    }				# if $m
-  }				# LOOP: foreach
-  die 'set mode: no suitable display mode found under ' .
-    join(', ', @modes) . ';' unless $Display{'MODE'};
-  die 'set mode: no viewer available for mode ' . $Display{'MODE'} . ';'
-    unless $Display{'PROG'};
-  0;
-} # main_set_mode()
-
-
-########################################################################
-# functions to main_set_mode()
-########################################################################
-
-##########
-# _get_prog_args(<MODE>)
-#
-# Simplification for loop in set mode.
-#
-# Globals in/out: $Viewer_Background
-# Globals in    : $Opt{VIEWER_<MODE>}, $Viewer_X{<MODE>},
-#                 $Viewer_tty{<MODE>}
-#
-sub _get_prog_args {
-  my $n = @_;
-  die "_get_prog_args(): one argument is needed; you used $n;"
-    unless $n == 1;
-
-  my $mode = lc($_[0]);
-  my $MODE = uc($mode);
-
-  my $xlist = $Viewer_X{$MODE};
-  my $ttylist = $Viewer_tty{$MODE};
-
-  my $vm = "VIEWER_${MODE}";
-  my $opt = $Opt{$vm};
-
-  if ($opt) {
-    my %prog = where_is_prog $opt;
-    my $prog_ref = \%prog;
-    unless (%prog) {
-      warn "_get_prog_args(): `$opt' is not an existing program;";
-      return 0;
-    }
-
-    # $prog from $opt is an existing program
-
-### _get_prog_args() of main_set_mode()
-    if (&is_X) {
-      if ( &_check_prog_on_list($prog_ref, $xlist) ) {
-	$Viewer_Background = 1;
-      } else {
-	$Viewer_Background = 0;
-	&_check_prog_on_list($prog_ref, $ttylist);
-      }
-    } else {			# is not X
-      $Viewer_Background = 0;
-      &_check_prog_on_list($prog_ref, $ttylist);
-    }				# if is X
-  } else {			# $opt is empty
-    $Viewer_Background = 0;
-    my $x;
-    if (&is_X) {
-      $x = &_get_first_prog($xlist);
-      $Viewer_Background = 1 if $x;
-    } else {			# is not X
-      $x = &_get_first_prog($ttylist);
-    }				# test on X
-    $Display{'MODE'} = $mode if $x;
-    return $x;
-  }
-  $Display{'MODE'} = $mode;
-  return 1;
-} # _get_prog_args() of main_set_mode()
-
-
-##########
-# _get_first_prog(<prog_list_ref>)
-#
-# Retrieve from the elements of the list in the argument the first
-# existing program in $PATH.
-#
-# Local function of main_set_mode().
-#
-# Return  : `0' if not a part of the list, `1' if found in the list.
-#
-sub _get_first_prog {
-  my $n = @_;
-  die "_get_first_prog(): one argument is needed; you used $n;"
-    unless $n == 1;
-
-  foreach my $i (@{$_[0]}) {
-    next unless $i;
-    my %prog = &where_is_prog($i);
-    if (%prog) {
-      $Display{'PROG'} = $prog{'fullname'};
-      $Display{'ARGS'} = $prog{'args'};
-      return 1;
-    }
-  }
-  return 0;
-} # _get_first_prog() of main_set_mode()
-
-
-##########
-# _check_prog_on_list (<prog-hash-ref> <prog_list_ref>)
-#
-# Check whether the content of <prog-hash-ref> is in the list
-# <prog_list_ref>.
-# The globals are set correspondingly.
-#
-# Local function for main_set_mode().
-#
-# Arguments: 2
-#
-# Return  : `0' if not a part of the list, `1' if found in the list.
-# Output  : none
-#
-# Globals in    : $Viewer_X{<MODE>}, $Viewer_tty{<MODE>}
-# Globals in/out: $Display{'PROG'}, $Display{'ARGS'}
-#
-sub _check_prog_on_list {
-  my $n = @_;
-  die "_get_first_prog(): 2 arguments are needed; you used $n;"
-    unless $n == 2;
-
-  my %prog = %{$_[0]};
-
-  $Display{'PROG'} = $prog{'fullname'};
-  $Display{'ARGS'} = $prog{'args'};
-
-  foreach my $i (@{$_[1]}) {
-    my %p = &where_is_prog($i);
-    next unless %p;
-    next unless $Display{'PROG'} eq $p{'fullname'};
-    if ($p{'args'}) {
-      if ($Display{'ARGS'}) {
-	$Display{'ARGS'} = $p{'args'};
-      } else {
-	$Display{'ARGS'} = "$p{'args'} $Display{'ARGS'}";
-      }
-    }				# if args
-    return 1;
-  }				# foreach $i
-  # prog was not in the list
-  return 0;
-} # _check_prog_on_list() of main_set_mode()
-
-
-########################################################################
-# groffer temporary directory, main_temp()
-########################################################################
-
-sub main_temp {
-  my $template = 'groffer_' . "$$" . '_XXXX';
-  foreach ($ENV{'GROFF_TMPDIR'}, $ENV{'TMPDIR'}, $ENV{'TMP'}, $ENV{'TEMP'},
-	   $ENV{'TEMPDIR'}, File::Spec->catfile($ENV{'HOME'}, 'tmp')) {
-    if ($_ && -d $_ && -w $_) {
-      if ($Debug{'KEEP'}) {
-	eval { $tmpdir = tempdir( $template, DIR => "$_" ); };
-      } else {
-	eval { $tmpdir = tempdir( $template,
-				  CLEANUP => 1, DIR => "$_" ); };
-      }
-      last if $tmpdir;
-    }
-  }
-  $tmpdir = tempdir( $template, CLEANUP => 1, DIR => File::Spec->tmpdir )
-    unless ($tmpdir);
-
-  # see Lerning Perl, page 205, or Programming Perl, page 413
-  # $SIG{'INT'} is for Ctrl-C interruption
-  $SIG{'INT'} = sub { &clean_up(); die "interrupted..."; };
-  $SIG{'QUIT'} = sub { &clean_up(); die "quit..."; };
-
-  if ($Debug{'TMPDIR'}) {
-    if ( $Debug{'KEEP'}) {
-      print STDERR "temporary directory is kept: $tmpdir\n";
-    } else {
-      print STDERR "temporary directory will be cleaned: $tmpdir\n";
-    }
-  }
-
-  # further argument: SUFFIX => '.sh'
-  if ($Debug{'KEEP'}) {
-    ($fh_cat, $tmp_cat) = tempfile(',cat_XXXX', DIR => $tmpdir);
-    ($fh_stdin, $tmp_stdin) = tempfile(',stdin_XXXX', DIR => $tmpdir);
-  } else {
-    ($fh_cat, $tmp_cat) = tempfile(',cat_XXXX', UNLINK => 1,
-				   DIR => $tmpdir);
-    ($fh_stdin, $tmp_stdin) = tempfile(',stdin_XXXX', UNLINK => 1,
-				       DIR => $tmpdir);
-  }
-}				# main_temp()
-
-
-########################################################################
-# tmp functions and compression
-########################################################################
-
-########################################################################
-# further functions needed for main_do_fileargs()
-########################################################################
-
-my @REG_TITLE = ();
-
-##########
-# register_file(<filename>)
-#
-# Write a found file and register the title element.
-#
-# Arguments: 1: a file name
-# Output: none
-#
-sub register_file {
-  my $n = @_;
-  die "register_file(): one argument is needed; you used $n;"
-    unless $n == 1;
-  die 'register_file(): file name is empty;' unless $_[0];
-
-  if ($_[0] eq '-') {
-    &to_tmp($tmp_stdin) && &register_title('stdin');
-  } else {
-    &to_tmp($_[0]) && &register_title($_[0]);
-  }
-  1;
-}				# register_file()
-
-
-##########
-# register_title(<filespec>)
-#
-# Create title element from <filespec> and append to $_REG_TITLE_LIST.
-# Basename is created.
-#
-# Globals in/out: @REG_TITLE
-#
-# Variable prefix: rt
-#
-sub register_title {
-  my $n = @_;
-  die "register_title(): one argument is needed; you used $n;"
-    unless $n == 1;
-  return 1 unless $_[0];
-
-  return 1 if scalar @REG_TITLE > 3;
-
-  my $title = &get_filename($_[0]);
-  $title =~ s/\s/_/g;
-  $title =~ s/\.bz2$//g;
-  $title =~ s/\.gz$//g;
-  $title =~ s/\.Z$//g;
-
-  if ($Debug{'FILENAMES'}) {
-    if ($_[0] eq 'stdin') {
-      print STDERR "register_title(): file title is stdin\n";
-    } else {
-      print STDERR "register_title(): file title is $title\n";
-    }
-  }				# if ($Debug{'FILENAMES'})
-
-  return 1 unless $title;
-  push @REG_TITLE, $title;
-  1;
-}				# register_title()
-
-
-##########
-# save_stdin()
-#
-# Store standard input to temporary file (with decompression).
-#
-sub save_stdin {
-  my ($fh_input, $tmp_input);
-  $tmp_input = File::Spec->catfile($tmpdir, ',input');
-  open $fh_input, ">$tmp_input" or
-    die "save_stdin(): could not open $tmp_input";
-  foreach (<STDIN>) {
-    print $fh_input $_;
-  }
-  close $fh_input;
-  open $fh_stdin, ">$tmp_stdin" or
-    die "save_stdin(): could not open $tmp_stdin";
-  foreach ( &cat_z("$tmp_input") ) {
-    print $fh_stdin "$_";
-  }
-  close $fh_stdin;
-  unlink $tmp_input unless $Debug{'KEEP'};
-}				# save_stdin()
-
-
-########################################################################
-# main_do_fileargs()
-########################################################################
-
-sub main_do_fileargs {
-  &special_setup();
-  if ($Opt{'APROPOS'}) {
-    if ($No_Filespecs) {
-      &apropos_filespec();
-      return 1;
-    }
-  } else {
-    foreach (@Filespecs) {
-      if (/^-$/) {
-	&save_stdin();
-	last;
-      }
-    }				# foreach (@Filespecs)
-  }				# if ($Opt{'APROPOS'})
-
-  my $section = '';
-  my $ext = '';
-  my $twoargs = 0;
-  my $filespec;
-  my $former_arg;
-
- FILESPEC: foreach (@Filespecs) {
-    $filespec = $_;
-    $Filespec_Arg = $_;
-    $Filespec_Is_Man = 0;
-    $Manspec = '';
-    $Special_Filespec = 0;
-
-    next FILESPEC unless $filespec;
-
-### main_do_fileargs()
-    if ($twoargs) {		# second run
-      $twoargs = 0;
-      # $section and $ext are kept from earlier run
-      my $h = { 'name' => $filespec, 'sec' => $section, 'ext' => $ext };
-      &man_setup();
-      if ( &is_man($h) ) {
-	$Filespec_Arg = "$former_arg $Filespec_Arg";
-	&special_filespec();
-	$Filespec_Is_Man = 1;
-	&man_get($h);
-	next FILESPEC;
-      } else {
-	warn "main_do_fileargs(): $former_arg is neither a file nor a " .
-	  "man page nor a section argument for $filespec;";
-      }
-    }
-    $twoargs = 0;
-
-    if ( $Opt{'APROPOS'} ) {
-      &apropos_filespec();
-      next FILESPEC;
-    }
-
-    if ($filespec eq '-') {
-      &register_file('-');
-      &special_filespec();
-      next FILESPEC;
-    } elsif ( &get_filename($filespec) ne $filespec ) { # path with dir
-      &special_filespec();
-      if (-f $filespec && -r $filespec) {
-	&register_file($filespec)
-      } else {
-	warn "main_do_fileargs: the argument $filespec is not a file;";
-      }
-      next FILESPEC;
-    } else {			# neither `-' nor has dir
-      # check whether filespec is an existing file
-      unless ( $Man{'FORCE'} ) {
-	if (-f $filespec && -r $filespec) {
-	  &special_filespec();
-	  &register_file($filespec);
-	  next FILESPEC;
-	}
-      }
-    }				# if ($filespec eq '-')
-
-### main_do_fileargs()
-    # now it must be a man page pattern
-
-    if ($Macro_Pkg and $Macro_Pkg ne '-man') {
-      warn "main_do_fileargs(): $filespec is not a file, " .
-	"man pages are ignored due to $Macro_Pkg;";
-      next FILESPEC;
-    }
-
-    # check for man page
-    &man_setup();
-    unless ( $Man{'ENABLE'} ) {
-      warn "main_do_fileargs(): the argument $filespec is not a file;";
-      next FILESPEC;
-    }
-    my $errmsg;
-    if ( $Man{'FORCE'} ) {
-      $errmsg = 'is not a man page';
-    } else {
-      $errmsg = 'is neither a file nor a man page';
-    }
-
-    $Filespec_Is_Man = 1;
-
-### main_do_fileargs()
-    # test filespec with `man:...' or `...(...)' on man page
-
-    my @names = ($filespec);
-    if ($filespec =~ /^man:(.*)$/) {
-      push @names, $1;
-    }
-
-    foreach my $i (@names) {
-      next unless $i;
-      my $h = { 'name' => $i };
-      if ( &is_man($h) ) {
-	&special_filespec();
-	&man_get($h);
-	next FILESPEC;
-      }
-      if ( $i =~ /^(.*)\(([$Man{'AUTO_SEC_CHARS'}])(.*)\)$/ ) {
-	$h = { 'name' => $1, 'sec' => $2, 'ext' => $3 };
-	if ( &is_man($h) ) {
-	  &special_filespec();
-	  &man_get($h);
-	  next FILESPEC;
-	}
-      }				# if //
-      if ( $i =~ /^(.*)\.([$Man{'AUTO_SEC_CHARS'}])(.*)$/ ) {
-	$h = { 'name' => $1, 'sec' => $2, 'ext' => $3 };
-	if ( &is_man($h) ) {
-	  &special_filespec();
-	  &man_get($h);
-	  next FILESPEC;
-	}
-      }				# if //
-    }				# foreach (@names)
-
-### main_do_fileargs()
-    # check on "s name", where "s" is a section with or without an extension
-    if ($filespec =~ /^([$Man{'AUTO_SEC_CHARS'}])(.*)$/) {
-      unless ( $Man{'ENABLE'} ) {
-	warn "main_do_fileargs(): $filespec $errmsg;";
-	next FILESPEC;
-      }
-      $twoargs = 1;
-      $section = $1;
-      $ext = $2;
-      $former_arg = $filespec;
-      next FILESPEC;
-    } else {
-      warn "main_do_fileargs(): $filespec $errmsg;";
-      next FILESPEC;
-    }
-  }				# foreach (@Filespecs)
-
-  if ($twoargs) {
-    warn "main_do_fileargs(): no filespec arguments left for second run;";
-    return 0;
-  }
-  1;
-} # main_do_fileargs()
-
-
-########################################################################
-# main_set_resources()
-########################################################################
-
-##########
-# main_set_resources ()
-#
-# Determine options for setting X resources with $_DISPLAY_PROG.
-#
-# Globals: $Display{PROG}, $Output_File_Name
-#
-sub main_set_resources {
-  # $prog   viewer program
-  # $rl     resource list
-  unlink $tmp_stdin unless $Debug{'KEEP'};
-  $Output_File_Name = '';
-
-  my @title = @REG_TITLE;
-  @title = ($Opt{'TITLE'}) unless @title;
-  @title = () unless @title;
-
-  foreach my $n (@title) {
-    next unless $n;
-    $n =~ s/^,+// if $n =~ /^,/;
-    next unless $n;
-    $Output_File_Name = $Output_File_Name . ',' if $Output_File_Name;
-    $Output_File_Name = "$Output_File_Name$n";
-  }				# foreach (@title)
-
-  $Output_File_Name =~ s/^,+//;
-  $Output_File_Name = '-' unless $Output_File_Name;
-  $Output_File_Name = File::Spec->catfile($tmpdir, $Output_File_Name);
-
-### main_set_resources()
-  unless ($Display{'PROG'}) {	# for example, for groff mode
-    $Display{'ARGS'} = '';
-    return 1;
-  }
-
-  my %h = &where_is_prog($Display{'PROG'});
-  my $prog = $h{'file'};
-  if ($Display{'ARGS'}) {
-    $Display{'ARGS'} = "$h{'args'} $Display{'ARGS'}";
-  } else {
-    $Display{'ARGS'} = $h{'args'};
-  }
-
-  my @rl = ();
-
-  if ($Opt{'BD'}) {
-    if ($prog =~ /^(ghostview|gv|gxditview|xditview|xdvi)$/) {
-      push @rl, '-bd', $Opt{'BD'};
-    }
-  }
-
-  if ($Opt{'BG'}) {
-    if ($prog =~ /^(ghostview|gv|gxditview|xditview|xdvi)$/) {
-      push @rl, '-bg', $Opt{'BG'};
-    } elsif ($prog eq 'kghostview') {
-      push @rl, '--bg', $Opt{'BG'};
-    } elsif ($prog eq 'xpdf') {
-      push @rl, '-papercolor', $Opt{'BG'};
-    }
-  }
-
-### main_set_resources()
-  if ($Opt{'BW'}) {
-    if ($prog =~ /^(ghostview|gv|gxditview|xditview|xdvi)$/) {
-      push @rl, '-bw', $Opt{'BW'};
-    }
-  }
-
-  if ($Opt{'FG'}) {
-    if ($prog =~ /^(ghostview|gv|gxditview|xditview|xdvi)$/) {
-      push @rl, '-fg', $Opt{'FG'};
-    } elsif ($prog eq 'kghostview') {
-      push @rl, '--fg', $Opt{'FG'};
-    }
-  }
-
-  if ($Opt{'FN'}) {
-    if ($prog =~ /^(ghostview|gv|gxditview|xditview|xdvi)$/) {
-      push @rl, '-fn', $Opt{'FN'};
-    } elsif ($prog eq 'kghostview') {
-      push @rl, '--fn', $Opt{'FN'};
-    }
-  }
-
-  if ($Opt{'GEOMETRY'}) {
-    if ($prog =~ /^(ghostview|gv|gxditview|xditview|xdvi)$/) {
-      push @rl, '-geometry', $Opt{'GEOMETRY'};
-    } elsif ($prog eq 'kghostview') {
-      push @rl, '--geometry', $Opt{'GEOMETRY'};
-    }
-  }
-
-### main_set_resources()
-  if ($Opt{'RESOLUTION'}) {
-    if ($prog =~ /^(ghostview|gv|gxditview|xditview|xdvi)$/) {
-      push @rl, '-resolution', $Opt{'RESOLUTION'};
-    } elsif ($prog eq 'xpdf') {
-      if ($Display{'PROG'} !~ / -z/) { # if xpdf does not have option -z
-	if ($Default_Resolution == 75) {
-	  push @rl, '-z', 104;
-	} elsif ($Default_Resolution == 100) { # 72dpi is '100'
-	  push @rl, '-z', 139;
-	}
-      }
-    }				# if $prog
-  } else {			# empty $Opt{RESOLUTION}
-    $Opt{'RESOLUTION'} = $Default_Resolution;
-    if ($prog =~ /^(gxditview|xditview)$/) {
-      push @rl, '-resolution', $Default_Resolution;
-    } elsif ($prog eq 'xpdf') {
-      if ($Display{'PROG'} !~ / -z/) { # if xpdf does not have option -z
-	if ($Default_Resolution == 75) {
-	  push @rl, '-z', 104;
-	} elsif ($Default_Resolution == 100) { # 72dpi is '100'
-	  push @rl, '-z', 139;
-	}
-      }
-    }				# if $prog
-  }				# if $Opt{RESOLUTION}
-
-  if ($Opt{'ICONIC'}) {
-    if ($prog =~ /^(ghostview|gv|gxditview|xditview|xdvi)$/) {
-      push @rl, '-iconic';
-    }
-  }
-
-### main_set_resources()
-  if ($Opt{'RV'}) {
-    if ($prog =~ /^(ghostview|gv|gxditview|xditview|xdvi)$/) {
-      push @rl, '-rv';
-    }
-  }
-
-  if (@{$Opt{'XRM'}}) {
-    if ($prog =~ /^(ghostview|gv|gxditview|xditview|xdvi|xpdf)$/) {
-      foreach (@{$Opt{'XRM'}}) {
-	push @rl, '-xrm', $_;
-      }
-    }
-  }
-
-  if (@title) {
-    if ($prog =~ /^(gxditview|xditview)$/) {
-      push @rl, '-title', $Output_File_Name;
-    }
-  }
-
-  my $args = join ' ', @rl;
-  if ($Display{'ARGS'}) {
-    $Display{'ARGS'} = "$args $Display{'ARGS'}";
-  } else {
-    $Display{'ARGS'} = $args;
-  }
-
-  1;
-}				# main_set_resources()
-
-
-########################################################################
-# set resources
-########################################################################
-
-my $groggy;
-my $modefile;
-my $addopts;
-
-##########
-# main_display ()
-#
-# Do the actual display of the whole thing.
-#
-# Globals:
-#   in: $Display{MODE}, $Opt{DEVICE}, @Addopts_Groff,
-#       $fh_cat, $tmp_cat, $Opt{PAGER}, $Output_File_Name
-#
-sub main_display {
-  $addopts = join ' ', @Addopts_Groff;
-
-  if (-z $tmp_cat) {
-    warn "groffer: empty input\n";
-    &clean_up();
-    return 1;
-  }
-
-  $modefile = $Output_File_Name;
-
-  # go to the temporary directory to be able to access internal data files
-  chdir $tmpdir;
-
-### main_display()
- SWITCH: foreach ($Display{'MODE'}) {
-    /^groff$/ and do {
-      push @Addopts_Groff, "-T$Opt{'DEVICE'}" if $Opt{'DEVICE'};
-      $addopts = join ' ', @Addopts_Groff;
-      $groggy = `cat $tmp_cat | grog`;
-      die "main_display(): grog error;" if $?;
-      chomp $groggy;
-      print STDERR "grog output: $groggy\n" if $Debug{'GROG'};
-      &_do_opt_V();
-      unlink $modefile;
-      rename $tmp_cat, $modefile;
-      system("cat $modefile | $groggy $addopts");
-      &clean_up();
-      next SWITCH;
-    };				# /groff/
-
-    /^(text|tty)$/ and do {
-      my $device;
-      if (! $Opt{'DEVICE'}) {
-	$device = $Opt{'TEXT_DEVICE'};
-	$device = $Default_tty_Device unless $device;
-      } elsif ($Opt{'DEVICE'} =~ /^(ascii||cp1047|latin1|utf8)$/) {
-	$device = $Opt{'DEVICE'};
-      } else {
-	warn "main_display(): wrong device for $Display{'MODE'} mode: " .
-	  "$Opt{'DEVICE'}";
-      }
-      $groggy = `cat $tmp_cat | grog -T$device`;
-      die "main_display(): grog error;" if $?;
-      chomp $groggy;
-      print STDERR "grog output: $groggy\n" if $Debug{'GROG'};
-      if ($Display{'MODE'} eq 'text') {
-	&_do_opt_V();
-	system("cat $tmp_cat | $groggy $addopts");
-	&clean_up();
-	next SWITCH;
-      }
-
-### main_display()
-      # mode is not 'text', but `tty'
-      my %pager;
-      my @p;
-      push @p, $Opt{'PAGER'} if $Opt{'PAGER'};
-      push @p, $ENV{'PAGER'} if $ENV{'PAGER'};
-      foreach (@p) {
-	%pager = &where_is_prog($_);
-	next unless %pager;
-	if ($pager{'file'} eq 'less') {
-	  if ($pager{'args'}) {
-	    $pager{'args'} = "-r -R $pager{'args'}";
-	  } else {
-	    $pager{'args'} = '-r -R';
-	  }
-	}
-	last if $pager{'file'};
-      }				# foreach @p
-      unless (%pager) {
-	foreach (@{$Viewer_tty{'TTY'}}, @{$Viewer_X{'TTY'}}, 'cat') {
-	  next unless $_;
-	  %pager = &where_is_prog($_);
-	  last if %pager;
-	}
-      }
-      die "main_display(): no pager program found for tty mode;"
-	unless %pager;
-      &_do_opt_V();
-      system("cat $tmp_cat | $groggy $addopts | " .
-	     "$pager{'fullname'} $pager{'args'}");
-      &clean_up();
-      next SWITCH;
-    };				# /text|tty/
-
-    /^source$/ and do {
-      open $fh_cat, "<$tmp_cat";
-      foreach (<$fh_cat>) {
-	print "$_";
-      }
-      &clean_up();
-      next SWITCH;
-    };
-
-### main_display()
-    /^dvi$/ and do {
-      if ($Opt{'DEVICE'} && $Opt{'DEVICE'} ne 'dvi') {
-	warn "main_display(): " .
-	  "wrong device for $Display{'MODE'} mode: $Opt{'DEVICE'};"
-      }
-      $modefile .= '.dvi';
-      $groggy = `cat $tmp_cat | grog -Tdvi`;
-      die "main_display(): grog error;" if $?;
-      chomp $groggy;
-      print STDERR "grog output: $groggy\n" if $Debug{'GROG'};
-      &_do_display();
-      next SWITCH;
-    };
-
-    /^html$/ and do {
-      if ($Opt{'DEVICE'} && $Opt{'DEVICE'} ne 'html') {
-	warn "main_display(): " .
-	  "wrong device for $Display{'MODE'} mode: $Opt{'DEVICE'};"
-      }
-      $modefile .= '.html';
-      $groggy = `cat $tmp_cat | grog -Thtml`;
-      die "main_display(): grog error;" if $?;
-      chomp $groggy;
-      print STDERR "grog output: $groggy\n" if $Debug{'GROG'};
-      &_do_display();
-      next SWITCH;
-    };
-
-    /^pdf$/ and do {
-      if ($Opt{'DEVICE'} && $Opt{'DEVICE'} ne 'ps') {
-	warn "main_display(): " .
-	  "wrong device for $Display{'MODE'} mode: $Opt{'DEVICE'};"
-      }
-      $modefile .= '.ps';
-      $groggy = `cat $tmp_cat | grog -Tps`;
-      die "main_display(): grog error;" if $?;
-      chomp $groggy;
-      print STDERR "grog output: $groggy\n" if $Debug{'GROG'};
-      &_do_display(\&_make_pdf);
-      next SWITCH;
-    };
-
-### main_display()
-    /^ps$/ and do {
-      if ($Opt{'DEVICE'} && $Opt{'DEVICE'} ne 'ps') {
-	warn "main_display(): " .
-	  "wrong device for $Display{'MODE'} mode: $Opt{'DEVICE'};"
-      }
-      $modefile .= '.ps';
-      $groggy = `cat $tmp_cat | grog -Tps`;
-      die "main_display(): grog error;" if $?;
-      chomp $groggy;
-      print STDERR "grog output: $groggy\n" if $Debug{'GROG'};
-      &_do_display();
-      next SWITCH;
-    };
-
-    /^x$/ and do {
-      my $device;
-      if ($Opt{'DEVICE'} && $Opt{'DEVICE'} =~ /^X/) {
-	$device = $Opt{'DEVICE'};
-      } else {
-	if ($Opt{'RESOLUTION'} == 100) {
-	  if ( $Display{'PROG'} =~ /^(g|)xditview$/ ) {
-	    # add width of 800dpi for resolution of 100dpi to the args
-	    $Display{'ARGS'} .= ' -geometry 800';
-	    $Display{'ARGS'} =~ s/^ //;
-	  }
-	} else {		# RESOLUTIOM != 100
-	  $device = 'X75-12';
-	}			# if RESOLUTIOM
-      }				# if DEVICE
-      $groggy = `cat $tmp_cat | grog -T$device -Z`;
-      die "main_display(): grog error;" if $?;
-      chomp $groggy;
-      print STDERR "grog output: $groggy\n" if $Debug{'GROG'};
-      &_do_display();
-      next SWITCH;
-    };
-
-### main_display()
-    /^X$/ and do {
-      if (! $Opt{'DEVICE'}) {
-	$groggy = `cat $tmp_cat | grog -X`;
-	die "main_display(): grog error;" if $?;
-	chomp $groggy;
-	print STDERR "grog output: $groggy\n" if $Debug{'GROG'};
-      } elsif ($Opt{'DEVICE'} =~ /^(X.*|dvi|html|lbp|lj4|ps)$/) {
-	# these devices work with
-	$groggy = `cat $tmp_cat | grog -T$Opt{'DEVICE'} -X`;
-	die "main_display(): grog error;" if $?;
-	chomp $groggy;
-	print STDERR "grog output: $groggy\n" if $Debug{'GROG'};
-      } else {
-	warn "main_display(): wrong device for " .
-	  "$Display{'MODE'} mode: $Opt{'DEVICE'};";
-	$groggy = `cat $tmp_cat | grog -Z`;
-	die "main_display(): grog error;" if $?;
-	chomp $groggy;
-	print STDERR "grog output: $groggy\n" if $Debug{'GROG'};
-      }				# if DEVICE
-      &_do_display();
-      next SWITCH;
-    };
-
-    /^.*$/ and do {
-      die "main_display(): unknown mode `$Display{'MODE'}';";
-    };
-
-  }				# SWITCH
-  1;
-} # main_display()
-
-
-########################
-# _do_display ([<prog>])
-#
-# Perform the generation of the output and view the result.  If an
-# argument is given interpret it as a function name that is called in
-# the midst (actually only for `pdf').
-#
-sub _do_display {
-  &_do_opt_V();
-  unless ($Display{'PROG'}) {
-    system("$groggy $addopts $tmp_cat");
-    &clean_up();
-    return 1;
-  }
-  unlink $modefile;
-  die "_do_display(): empty output;" if -z $tmp_cat;
-  system("cat $tmp_cat | $groggy $addopts >$modefile");
-  die "_do_display(): empty output;" if -z $modefile;
-  &print_times("before display");
-  if ($_[0] && ref($_[0]) eq 'CODE') {
-    $_[0]->();
-  }
-  unlink $tmp_cat unless $Debug{'KEEP'};
-
-  if ( $Opt{'STDOUT'} ) {
-    my $fh;
-    open $fh, "<$modefile";
-    foreach (<$fh>) {
-      print;
-    }
-    close $fh;
-    return 1;
-  }
-
-  if ($Viewer_Background) {
-    if ($Debug{'KEEP'}) {
-      exec "$Display{'PROG'} $Display{'ARGS'} $modefile &";
-    } else {
-      exec "{ $Display{'PROG'} $Display{'ARGS'} $modefile; " .
-	"rm -rf $tmpdir; } &";
-    }
-  } else {
-    system("$Display{'PROG'} $Display{'ARGS'} $modefile");
-    &clean_up();
-  }
-} # _do_display() of main_display()
-
-
-#############
-# _do_opt_V ()
-#
-# Check on option `-V'; if set print the corresponding output and leave.
-#
-# Globals: @ARGV, $Display{MODE}, $Display{PROG},
-#          $Display{ARGS}, $groggy,  $modefile, $addopts
-#
-sub _do_opt_V {
-  if ($Opt{'V'}) {
-    $Opt{'V'} = 0;
-    print "Parameters: @ARGV\n";
-    print "Display Mode: $Display{'MODE'}\n";
-    print "Output file: $modefile\n";
-    print "Display prog: $Display{'PROG'} $Display{'ARGS'}\n";
-    print "Output of grog: $groggy $addopts\n";
-    my $res = `$groggy $addopts\n`;
-    chomp $res;
-    print "groff -V: $res\n";
-    exit 0;
-  }
-  1;
-} # _do_opt_V() of main_display()
-
-##############
-# _make_pdf ()
-#
-# Transform to pdf format; for pdf mode in _do_display().
-#
-# Globals: $md_modefile (from main_display())
-#
-sub _make_pdf {
-  die "_make_pdf(): pdf mode did not work;" if $PDF_Did_Not_Work;
-  my $psfile = $modefile;
-  die "_make_pdf(): empty output;" if -z $modefile;
-  $modefile =~ s/\.ps$/.pdf/;
-  unlink $modefile;
-  my $done;
-  if ($PDF_Has_ps2pdf) {
-    system("ps2pdf $psfile $modefile 2>$Dev_Null");
-    $done = ! $?;
-  }
-  if (! $done && $PDF_Has_gs) {
-    system("gs -q -dNOPAUSE -dBATCH -sDEVICE=pdfwrite " .
-       "-sOutputFile=$modefile -c save pop -f $psfile 2>$Dev_Null");
-    $done = ! $?;
-  }
-  if (! $done) {
-    $PDF_Did_Not_Work = 1;
-    warn '_make_pdf(): Could not transform into pdf format, ' .
-      'the Postscript mode (ps) is used instead;';
-    $Opt{'MODE'} = 'ps';
-    &main_set_mode();
-    &main_set_resources();
-    &main_display();
-    exit 0;
-  }
-  unlink $psfile unless $Debug{'KEEP'};
-  1;
-} # _make_pdf() of main_display()
-
-
-########################################################################
-
-&main_set_options();
-&main_parse_MANOPT();
-&main_config_params();
-&main_parse_params();
-&main_set_mode();
-&main_temp();
-&main_do_fileargs();
-&main_set_resources();
-&main_display();
-
-&clean_up();
-
-1;
-########################################################################
-### Emacs settings
-# Local Variables:
-# mode: CPerl
-# End:

Index: groffer/perl/man.pl
===================================================================
RCS file: groffer/perl/man.pl
diff -N groffer/perl/man.pl
--- groffer/perl/man.pl	1 Feb 2013 08:12:27 -0000	1.7
+++ /dev/null	1 Jan 1970 00:00:00 -0000
@@ -1,731 +0,0 @@
-#! /usr/bin/env perl
-
-# groffer - display groff files
-
-# Source file position: <groff-source>/contrib/groffer/perl/man.pl
-# Installed position: <prefix>/lib/groff/groffer/man.pl
-
-# Copyright (C) 2006, 2009, 2011 Free Software Foundation, Inc.
-# Written by Bernd Warken <groff-bernd.warken-72@web.de>.
-
-# Last update: 27 Jan 2011
-
-# 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/>.
-
-########################################################################
-
-use strict;
-use warnings;
-
-########################################################################
-# functions for apropos, man, whatis
-########################################################################
-
-##########
-# apropos_filespec()
-#
-# Compose temporary file for filspec.
-#
-# Globals:  in: $main::Opt{'APROPOS'}, $main::Special_Setup, $main::Filespec_Arg,
-#               $main::Apropos_Prog, $main::Opt{'APROPOS_SECTIONS'}, $main::Opt{'SECTIONS'}
-#          out: $main::Special_Filespec
-#
-sub apropos_filespec {
-  return 0 unless $main::Opt{'APROPOS'};
-  die 'apropos_filespec(): apropos_setup() must be run first;'
-    unless $main::Special_Setup;
-  die 'apropos_filespec(): no $main::Filespec_Arg is set;'
-    unless defined $main::Filespec_Arg;
-  $main::Special_Filespec = 1;
-
-  my $s;
-  if ($main::No_Filespecs) {
-    &to_tmp_line('.SH no filespec');
-    $s = `$main::Apropos_Prog`;
-    $s =~ s/^/\\\&/;
-    &to_tmp_line($s);
-    return 1;
-  }
-
-  $s = $main::Filespec_Arg;
-  $s =~ s/[^\\]-/\\-/g;
-  &to_tmp_line(".SH $s");
-
-  if ( $main::Opt{'APROPOS_SECTIONS'} ) {
-    $s = qr/^[^\(]*\([$main::Opt{'APROPOS_SECTIONS'}]/;
-  } else {
-    if ( $main::Opt{'SECTIONS'} ) {
-      $s = $main::Opt{'SECTIONS'};
-      $s = qr/^[^\(]*\([$s]/;
-    } else {
-      $s = qr/^.*\(.+\).*$/;
-    }
-  }
-
-### apropos_filespec()
-  my $filespec = $main::Filespec_Arg;
-  $filespec =~ s#/#\\/#g;
-  $filespec =~ s#\.#\\./#g;
-  my @ap;
-  foreach ( `$main::Apropos_Prog $main::Filespec_Arg 2>$main::Dev_Null` ) {
-    chomp;
-    if (/^$filespec:\s/) {	# for error messages of this script
-      my $line = $_;
-      $line =~ s/^(.*)$/\\\&$1/s;
-      push @ap, $line;
-    }
-    if (/$s/) {
-      push @ap, $_;
-    }
-  }
-  my @res;
-  foreach (sort @ap) {
-    s/^
-      ([^\(]+\(+[$main::Man{'AUTO_SEC_CHARS'}][^\)]*\)+)
-      (\s*-*)*\s*
-      (.*)
-      $/.br\n.TP 15\n.BR "$1"\n\\\&$3\n/sx;
-    push @res, $_;
-  }
-  &to_tmp_line(@res);
-  1;
-}				# apropos_filespec()
-
-
-##########
-# apropos_setup()
-#
-# Setup for the --apropos* options, just 2 global variables are set.
-#
-# Globals:  in: $main::Opt{'APROPOS'}
-#          out: $main::Special_Setup, $main::Apropos_Prog
-#
-sub apropos_setup {
-  return 0 unless $main::Opt{'APROPOS'};
-  if ( &where_is_prog('apropos') ) {
-    $main::Apropos_Prog = 'apropos';
-  } elsif ( &where_is_prog('man') ) {
-    if (! system("man --apropos man >$main::Dev_Null 2>$main::Dev_Null")) {
-      $main::Apropos_Prog = 'man --apropos';
-    } elsif (! system("man -k man >$main::Dev_Null 2>$main::Dev_Null")) {
-      $main::Apropos_Prog = 'man --k';
-    }
-  }				# test man
-  die 'apropos_setup(): no apropos program available;'
-    unless $main::Apropos_Prog;
-  &to_tmp_line('.TH GROFFER APROPOS');
-  $main::Special_Setup = 1;
-  $main::Opt{'TITLE'} = 'apropos' unless $main::Opt{'TITLE'};
-  1;
-}				# apropos_setup()
-
-
-##########
-# is_man(<man_sec_ext-hash-ref>)
-#
-# Test whether the argument hash exists as man page (from is_man()).
-#
-# Globals: in: $main::Man{AUTO_SEC_CHARS},$main::Man{SEC_CHARS},
-#              $main::Man{EXT}, $tmpdir
-#         out: $main::Manspec
-#
-# Arguments: 1, a hash reference with keys 'name', 'sec', 'ext', where
-#               'sec' is a string of one or several section characters
-#
-sub is_man {
-  my $n = @_;
-  die "is_man(): one argument is needed, you used $n;"
-    unless $n == 1;
-  die "is_man(): the argument is not a hash reference `$_[0]';"
-    if ref($_[0]) ne 'HASH';
-  die 'is_man(): temporary directory is not set;' unless $main::tmpdir;
-  die 'is_man(): man_setup() must be run first;' unless $main::Man{'IS_SETUP'};
-
-  my $name = $_[0]->{'name'};
-  unless ($name) {
-    $main::Manspec = '';
-    return 0;
-  }
-
-  my $sec;
-  $sec = $_[0]->{'sec'};
-  $sec = $main::Man{'SEC_CHARS'} unless $sec;
-  $sec = $main::Man{'AUTO_SEC_CHARS'} unless $sec;
-  $sec = '' unless defined $sec;
-  # take care, $sec may be several sections
-
-### is_man()
-  my $ext;
-  $ext = $_[0]->{'ext'};
-  $ext = $main::Man{'EXT'} unless $ext;
-  $ext = '' unless defined $ext;
-
-  $main::Manspec = "$name.$sec,$ext";
-  my @m;
-  if (exists $main::Man{'MANSPEC'}{$main::Manspec}) {
-    return 1;
-  } else {
-    foreach my $p ( @{$main::Man{'PATH'}} ) {
-      foreach my $s (split //, $sec) {
-	my $dir = File::Spec->catdir($p, "man$s");
-	next unless -d $dir;
-	my $file = File::Spec->catfile($dir, "$name.$s$ext");
-	push @m, glob("$file*");
-      }
-    }
-    $main::Man{'MANSPEC'}{$main::Manspec} = \@m;
-  }
-  return 0 unless (@m);
-  return 1;
-} # is_man()
-
-
-##########
-# man_get (<man_sec_ext-hash-ref>)
-#
-# Write a man page to the temporary file.
-#
-# Globals in: $main::Manspec, $main::Man{MANSPEC}, $main::Man{SEC_CHARS},
-#             $main::Man{EXT}, $main::Man{ALL}
-#
-# Arguments: 1, a hash reference with keys 'name', 'sec', 'ext', where
-#               'sec' is a string of one or several section characters
-#
-sub man_get {
-  my $n = @_;
-  die "man_get(): one argument is needed, you used $n;"
-    unless $n == 1;
-  die "man_get(): the argument is not a hash reference `$_[0]';"
-    if ref($_[0]) ne 'HASH';
-  die "man_get(): is_man() must be run first on the argument;"
-    unless $main::Manspec;
-  die "man_get(): wrong hash reference `$_[0]', no 'name' key;"
-    unless exists $_[0]->{'name'};
-
-  my ($name, $sec, $ext, $f, $path);
-  $name = $_[0]->{'name'};
-  die "man_get(): empty 'name' key in the argument;" unless $name;
-
-  $sec = $_[0]->{'sec'};
-  $sec = $main::Man{'SEC_CHARS'} if (! $sec) and $main::Man{'SEC_CHARS'};
-  $sec = '' unless defined $sec;
-  # take care $sec may be several sections
-
-### man_get()
-  $ext = $_[0]->{'ext'};
-  $ext = $main::Man{'EXT'} unless $ext;
-  $ext = '' unless defined $ext;
-
-  die 'man_get(): $main::Manspec does not suit the arguments;'
-    if ($main::Manspec ne "$name.$sec,$ext") and
-      (! exists $main::Man{'MANSPEC'}{$main::Manspec});
-
-  if ($main::Man{'ALL'}) {
-    my $ok;
-    my %list;
-    foreach ( @{$main::Man{'MANSPEC'}{$main::Manspec}} ) {
-      next if exists $list{$_};
-      if (-f $_ and -r $_) {
-	$list{$_} = 1;
-	&to_tmp($_);
-	$ok = 1;
-      }
-    }
-    &register_title("man:$name") if $ok;
-    return 1;
-  }
-
-  # not $main::Man{'ALL'}
-
-  if ($_[0]->{'sec'}) {
-    my $path = File::Spec->catfile('', "man$sec", $name);
-    if ($ext) {
-      foreach $f ( @{$main::Man{'MANSPEC'}{$main::Manspec}} ) {
-	if ($f =~ m#$path\.$sec$ext($|\..*$)#) {
-	  if (-f $f && -r $f) {
-	    &register_file($f);
-	    return 1;
-	  }
-	}			# if $f =~
-      }				# foreach $f
-### man_get()
-      foreach $f ( @{$main::Man{'MANSPEC'}{$main::Manspec}} ) {
-	if ($f =~ m#$path\.$sec$ext.*$#) {
-	  if (-f $f && -r $f) {
-	    &register_file($f);
-	    return 1;
-	  }
-	}			# if $f =~
-      }				# foreach $f
-    } else {			# $ext is empty
-      foreach $f ( @{$main::Man{'MANSPEC'}{$main::Manspec}} ) {
-	if ($f =~ m#$path\.$sec($|\..*$)#) {
-	  if (-f $f && -r $f) {
-	    #	    &to_tmp($f) && &register_file($f);
-	    &register_file($f);
-	    return 1;
-	  }
-	}			# if $f =~
-      }				# foreach $f
-      foreach $f ( @{$main::Man{'MANSPEC'}{$main::Manspec}} ) {
-	if ($f =~ m#$path\.$sec.*$#) {
-	  if (-f $f && -r $f) {
-	    #	    &to_tmp($f) && &register_file($f);
-	    &register_file($f);
-	    return 1;
-	  }
-	}			# if $f =~
-      }				# foreach $f
-    }				# if $ext
-### man_get()
-  } else {			# sec is empty
-    my $m = $main::Man{'SEC_CHARS'};
-    $m = $main::Man{'AUTO_SEC_CHARS'} unless $m;
-    foreach my $s (split //, $m) {
-      my $path = File::Spec->catfile('', "man$s", $name);
-      unless ($ext) {
-	foreach my $f ( @{$main::Man{'MANSPEC'}{$main::Manspec}} ) {
-	  if ( $f =~ m#$path\.$s($|\..*$)# ) {
-	    if (-f $f && -r $f) {
-	      #	      &to_tmp($f) && &register_file($f);
-	      &register_file($f);
-	      return 1;
-	    }
-	  }			# if $f =~
-	}			# foreach $f
-      }				# unless $ext
-      foreach $f ( @{$main::Man{'MANSPEC'}{$main::Manspec}} ) {
-	if ($f =~ m#$path\.$s$ext.*$#) {
-	  if (-f $f && -r $f) {
-	    #	    &to_tmp($f) && &register_file($f);
-	    &register_file($f);
-	    return 1;
-	  }
-	}			# if $f =~
-      }				# foreach $f
-    }				# foreach $s
-  }				# if sec
-
-  1;
-} # man_get()
-
-
-##########
-# man_setup ()
-#
-# Setup the variables in %MAN needed for man page searching.
-#
-# Globals:
-#   in:     %OPT, $LANG, $LC_MESSAGES, $LC_ALL,
-#           $MANPATH, $MANSEC, $PAGER, $SYSTEM, $MANOPT.
-#   out:    $main::Man{PATH}, $main::Man{LANG}, $main::Man{LANG2}, $main::Man{SYS},
-#           $main::Man{SEC}, $main::Man{ALL}
-#   in/out: $main::Man{ENABLE}
-#
-# The precedence for the variables related to `man' is that of GNU
-# `man', i.e.
-#
-# $LANG; overridden by
-# $LC_MESSAGES; overridden by
-# $LC_ALL; this has the same precedence as
-# $MANPATH, $MANSEC, $PAGER, $SYSTEM; overridden by
-# $MANOPT; overridden by
-# the groffer command line options.
-#
-# $MANROFFSEQ is ignored because grog determines the preprocessors.
-#
-sub man_setup {
-  return 1 if $main::Man{'IS_SETUP'};
-  $main::Man{'IS_SETUP'} = 1;
-  return 1 unless $main::Man{'ENABLE'};
-
-  # determine basic path for man pages
-  my $path;
-  if (defined $main::Opt{'MANPATH'}) {
-    $path = $main::Opt{'MANPATH'};
-  } elsif ($ENV{'MANPATH'}) {
-    $path = $ENV{'MANPATH'};
-  } elsif ( &where_is_prog('manpath') ) {
-    $path = `manpath 2>$main::Dev_Null`;
-  }
-  if ($path) {
-    chomp $path;
-    $main::Man{'PATH'} = [split /:/, $path];
-  } else {
-    $main::Man{'PATH'} = [];
-    &manpath_set_from_path();
-  }
-  unless ( @{$main::Man{'PATH'}} ) {
-    $main::Man{'ENABLE'} = 0;
-    warn "man_setup(): man path is empty;";
-    return 1;
-  }
-
-### man_setup()
-  # make man path list consisting of unique existing directories
-  @{$main::Man{'PATH'}} = &path_uniq( @{$main::Man{'PATH'}} );
-
-  unless ($main::Man{'ALL'}) {
-    $main::Man{'ALL'} = $main::Opt{'ALL'} ? 1 : 0;
-  }
-
-  # handle man systems
-  my $sys = $ENV{'SYSTEM'};
-  $sys = $main::Opt{'SYSTEMS'} if $main::Opt{'SYSTEMS'};
-  if ($sys) {
-    chomp $sys;
-    $main::Man{'SYS'} = [split /,/, $sys];
-  } else {
-    $main::Man{'SYS'} = [];
-    $sys = '';
-  }
-
-### man_setup()
-  # handle language
-  my $lang = '';
-  $lang = $main::Opt{'LANG'} if $main::Opt{'LANG'};
-  unless ($lang) {
-    foreach ('LC_ALL', 'LC_MESSAGES', 'LANG') {
-      if ($ENV{$_}) {
-	$lang = $ENV{$_};
-	last;
-      }
-    }
-  }
-  if ($lang) {
-    if ($lang eq 'C' or $lang eq 'POSIX') {
-      $main::Man{'LANG'} = '';
-      $main::Man{'LANG2'} = '';
-    } elsif ($lang =~ /^.$/) {
-      $main::Man{'LANG'} = $lang;
-      $main::Man{'LANG2'} = '';
-    } elsif ($lang =~ /^..$/) {
-      $main::Man{'LANG'} = $lang;
-      $main::Man{'LANG2'} = $lang;
-    } else {
-      $main::Man{'LANG'} = $lang;
-      $main::Man{'LANG2'} = $lang;
-      $main::Man{'LANG2'} =~ s/^(..).*$/$1/;
-    }
-  }				# if ($lang)
-  # from now on, use only $main::Man{LANG*}, forget about $main::Opt{LANG}, $ENV{LC_*}.
-
-  &manpath_add_lang_sys();
-
-### man_setup()
-  # section
-  my $sec;
-  $sec = $main::Opt{'SECTIONS'} if $main::Opt{'SECTIONS'};
-  unless ($sec) {
-    $sec = $ENV{'MANSEC'} if $ENV{'MANSEC'};
-  }
-  $main::Man{'SEC'} = [];
-  $main::Man{'SEC_CHARS'} = '';
-  if ($sec) {
-    foreach (split /:/, $sec) {
-      push @{$main::Man{'SEC'}}, $_ if /^[$main::Man{'AUTO_SEC_CHARS'}]$/;
-    }
-    $main::Man{'SEC_CHARS'} = join '', @{$main::Man{'SEC'}} if @{$main::Man{'SEC'}};
-  }				# if ($sec)
-
-  # extension
-  my $ext = '';
-  $ext = $main::Opt{'EXTENSION'} if $main::Opt{'EXTENSION'};
-  unless ($ext) {
-    $ext = $ENV{'EXTENSION'} if $ENV{'EXTENSION'};
-  }
-  $main::Man{'EXT'} = $ext;
-
-  # creation of man temporary is omitted, because of globs in perl
-  1;
-} # man_setup()
-
-
-##########
-# manpath_add_lang_sys()
-#
-# Add language and operating system specific directories to man path.
-#
-# Globals:
-#   in:     $main::Man{SYS}: a list of names of operating systems.
-#           $main::Man{LANG} and $main::Man{LANG2}: each a single name
-#   in/out: @{$main::Man{PATH}}: list of directories which shall have the `man?'
-#           subdirectories.
-#
-sub manpath_add_lang_sys {
-  return 1 unless $main::Man{'PATH'};
-  return 1 unless @{$main::Man{'PATH'}};
-
-  my @mp;
-
-  if ( @{$main::Man{'SYS'}} ) {
-    foreach ( @{$main::Man{'SYS'}} ) {
-      if ($_ eq 'man') {
-	@mp = (@mp, @{$main::Man{'PATH'}});
-      } elsif ($_) {
-	my $sys = $_;
-	foreach my $p (@{$main::Man{'PATH'}}) {
-	  my $dir = File::Spec->catdir($p, $sys);
-	  push @mp, $dir;
-	}
-      }				# if eq 'man'
-    }				# foreach SYS
-  } else {			# no SYS
-    @mp = @{$main::Man{'PATH'}};
-  }
-
-  if (@mp && $main::Man{'LANG'}) {
-    my @lang_path;
-    my $man_lang2 = '';
-    $man_lang2 = $main::Man{'LANG2'} if $main::Man{'LANG'} ne $main::Man{'LANG2'};
-    foreach my $i ($main::Man{'LANG'}, $man_lang2) {
-      next unless $i;
-      my $lang = $i;
-      foreach my $p (@mp) {
-	my $dir = File::Spec->catdir($p, $lang);
-	push @lang_path, $dir;
-      }				# foreach $p
-    }				# foreach $i
-    @mp = (@lang_path, @mp);
-  }				# if $mp
-
-  $main::Man{PATH} = [&path_uniq(@mp)];
-  1;
-} # manpath_add_lang_sys()
-
-
-##########
-# manpath_set_from_path()
-#
-# Determine basic search path for man pages from $PATH.
-#
-# Return:    `1' if a valid man path was retrieved.
-# Output:    none
-# Globals:
-#   in:  $PATH
-#   out: $_MAN_PATH
-#
-sub manpath_set_from_path {
-  my @path =
-    qw( /usr/local /usr /usr/X11R6 /usr/openwin /opt /opt/gnome /opt/kde );
-  # get a basic man path from $ENV{PATH}
-  my @path2 = @main::Path;
-  foreach (@path2) {
-    s#bin/*$##;
-    push @path, $_;
-  }
-  @path = &path_uniq(@path);
-  foreach my $d (@path) {
-    foreach my $e ( File::Spec->catdir( qw(share man) ),
-		 File::Spec->catdir( qw(share MAN) ),
-		 'man',  'MAN' ) {
-      my $dir = File::Spec->catdir($d, $e);
-      push @{$main::Man{'PATH'}}, $dir if -d $dir;
-    }
-  }
-  1;
-} # manpath_set_from_path()
-
-
-##########
-# special_filespec()
-#
-# Handle special modes like whatis and apropos.  Run their filespec
-# functions if suitable.
-#
-# Globals:  in: $main::Opt{'APROPOS'}, $main::Opt{'WHATIS'}, $main::Special_Setup
-#          out: $main::Special_Filespec (internal)
-#
-sub special_filespec {
-  return 0 unless $main::Opt{'APROPOS'} || $main::Opt{'WHATIS'};
-  die 'special_filespec(): setup for apropos or whatis must be run first;'
-    unless $main::Special_Setup;
-  if ( $main::Opt{'APROPOS'} ) {
-    die "special_setup(): both apropos and whatis option variables are set;"
-      if $main::Opt{'WHATIS'};
-    return &apropos_filespec() ? 1 : 0;
-  }
-  if ( $main::Opt{'WHATIS'} ) {
-    return &whatis_filespec() ? 1 : 0;
-  }
-  0;
-} # special_filespec
-
-
-##########
-# special_setup()
-#
-# Handle special modes like whatis and apropos.  Run their setup
-# functions if suitable.
-#
-sub special_setup {
-  if ( $main::Opt{'APROPOS'} ) {
-    die "special_setup(): both --apropos and --whatis option variables " .
-      "are set;" if $main::Opt{'WHATIS'};
-    return &apropos_setup() ? 1 : 0;
-  }
-  if ( $main::Opt{'WHATIS'} ) {
-    return &whatis_setup() ? 1 : 0;
-  }
-  0;
-} # special_setup()
-
-
-##########
-# whatis_filename(<filename>)
-#
-# Interpret <filename> as a man page and display its `whatis'
-# information as a fragment written in the groff language.
-#
-# Globals:  in: $main::Opt{'WHATIS'}, $main::Special_Setup, $main::Special_Filespec,
-#               $main::Filespec_Arg
-#
-sub whatis_filename {
-  my $n = @_;
-  die "whatis_filename(): one argument is needed; you used $n;"
-    unless $n == 1;
-  die "whatis_filename(): whatis is not setup;" unless $main::Opt{'WHATIS'};
-  die "whatis_filename(): setup for whatis must be run first;"
-    unless $main::Special_Setup;
-  die "whatis_filename(): whatis_filespec() must be run first;"
-    unless $main::Special_Filespec;
-  die 'whatis_filename(): no $main::Filespec_Arg is set;'
-    unless defined $main::Filespec_Arg;
-
-  my $arg = $_[0];
-  die "whatis_file_name(): $arg is not an existing file" unless -f $arg;
-  die "whatis_file_name(): could not read file $arg" unless -r $arg;
-  return 1 if -z $arg;
-  $arg = 'stdin' if $main::Filespec_Arg eq '-';
-
-  &to_tmp_line('.br', '\\f[CR]' . $arg . '\\f[]:', '.br');
-
-### whatis_filename()
-  # get the parts of the file name according to the naming of man pages
-  my ($dir, $name) = &split_path( $_[0] );
-  my $section = $_[0];
-  my $path = File::Spec->catfile('', 'man');
-  $section =~ s#^.*$path([$main::Man{'AUTO_SEC_CHARS'}]).*$#$1#;
-  $section = '' if $section eq $_[0];
-  if ($section) {
-    if ($name =~ m#^.*\.$section.*$#) {
-      $name =~ s/^(.*)\.$section.*$/$1/;
-    } else {
-      $section = '';
-    }
-  }
-
-  # traditional man style; grep the line containing `.TH' macro, if any
-  my @catz = &cat_z($_[0]);
-  my $res;
-  my $test;
-  foreach (@catz) {
-    if (/^[\.']\s*TH\s/) {		# search .TH, traditional man style
-      $test = 1;
-      last;
-    }
-  }				# foreach (@catz)
-### whatis_filename()
-  if ($test) {			# traditional man style
-    # get the first line after the first `.SH' macro before the next `.SH'
-    my $test1;
-    foreach (@catz) {
-      if ($test1) {
-	chomp;
-	next unless $_;
-	next if /^[\.']?\s*$/;
-	last if /^[\.']/;		# especially for .SH
-	if ($res) {
-	  $res = "$res $_";
-	} else {
-	  $res = $_;
-	}
-      } else {			# $test1 is empty
-	$test1 = 1 if (/^[\.']\s*SH\s/);
-      }				# if ($test1)
-    }				# foreach (@catz)
-
-    if ($section) {
-      if ($res =~ m|^
-		    $name
-		    \s
-		    [^-]*
-		    -
-		    \s*
-		    (.*)
-		    $|sx) {
-	$res = "$name ($section) \\[em] $1";
-      }
-    }				# if ($section)
-### whatis_filename()
-    &to_tmp_line($res, '.br', '', '.br');
-    return 1;
-  }				# if ($test)
-
-  # mdoc style (BSD doc); grep the line containing `.Nd' macro, if any
-  foreach (@catz) {
-    if (/^[\.']\s*Nd\s/) {		# BSD doc style
-      $res =~ s/^(.*)$/$name ($section) \\[em] $1/;
-      &to_tmp_line($res);
-      return 1;
-    }
-  }
-
-  &to_tmp_line('is not a man page', '.br', '', '.br');
-  1;
-} # whatis_filename()
-
-
-##########
-# whatis_filespec()
-#
-# Print the filespec name as .SH to the temporary cat file.
-#
-# Globals: in: $main::Opt{'WHATIS'}, $main::Filespec_Arg
-#      in/out: $main::Special_Filespec
-#
-sub whatis_filespec {
-  return 0 unless ($main::Opt{'WHATIS'});
-  die 'whatis_filespec(): whatis_setup() must be run first.'
-    unless $main::Special_Setup;
-  die 'whatis_filespec(): no $main::Filespec_Arg is set;'
-    unless defined $main::Filespec_Arg;
-  $main::Special_Filespec = 1;
-  my $arg = $main::Filespec_Arg;
-  $arg =~ s/[^\\]-/\\-/g;
-  to_tmp_line(".SH $arg");
-} # whatis_filespec()
-
-
-##########
-# whatis_setup ()
-#
-# Print the whatis header to the temporary cat file; this is the setup
-# for whatis.
-#
-# Globals:  in: $main::Opt{'WHATIS'}
-#          out: $main::Special_Setup
-sub whatis_setup {
-  if ( $main::Opt{'WHATIS'} ) {
-    &to_tmp_line('.TH GROFFER WHATIS');
-    $main::Special_Setup = 1;
-    $main::Opt{'TITLE'} = 'whatis' unless $main::Opt{'TITLE'};
-    return 1;
-  }
-  0;
-} # whatis_setup ()
-
-1;

Index: groffer/perl/perl_test.pl
===================================================================
RCS file: groffer/perl/perl_test.pl
diff -N groffer/perl/perl_test.pl
--- groffer/perl/perl_test.pl	22 Jan 2013 00:29:40 -0000	1.4
+++ /dev/null	1 Jan 1970 00:00:00 -0000
@@ -1,34 +0,0 @@
-#! /usr/bin/env perl
-
-# groffer - display groff files
-
-# Source file position: <groff-source>/contrib/groffer/perl/perl_test.sh
-# Installed position: <prefix>/lib/groff/groffer/perl_test.sh
-
-# Copyright (C) 2006, 2009 Free Software Foundation, Inc.
-# Written by Bernd Warken <groff-bernd.warken-72@web.de>.
-
-# Last update: 5 Jan 2009
-
-# 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/>.
-
-########################################################################
-
-# This file tests whether perl has a suitable version.  It is used by
-# groffer.pl and Makefile.sub.
-
-# require 5.004_05;
-require v5.6.1;

Index: groffer/perl/roff2.pl
===================================================================
RCS file: groffer/perl/roff2.pl
diff -N groffer/perl/roff2.pl
--- groffer/perl/roff2.pl	22 Jan 2013 00:29:40 -0000	1.6
+++ /dev/null	1 Jan 1970 00:00:00 -0000
@@ -1,223 +0,0 @@
-#! /usr/bin/env perl
-
-# roff2* - transform roff files into other formats
-
-# Source file position: <groff-source>/contrib/groffer/perl/roff2.pl
-# Installed position: <prefix>/bin/roff2*
-
-# Copyright (C) 2006, 2008, 2009 Free Software Foundation, Inc.
-# Written by Bernd Warken <groff-bernd.warken-72@web.de>.
-
-# Last update: 5 Jan 2009
-
-# 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/>.
-
-########################################################################
-
-require v5.6;
-
-use strict;
-use warnings;
-use File::Spec;
-
-# temporary dir and files
-use File::Temp qw/ tempfile /;
-
-my $Dev_Null = File::Spec->devnull();
-my $Mode;
-my $Name;
-{
-  my ($v, $d);
-  ($v, $d, $Name) = File::Spec->splitpath($0);
-  die "wrong program name: $Name;"
-    if $Name !~ /^roff2[a-z]/;
-}
-$Mode = $Name;
-$Mode =~ s/^roff2//;
-
-my $Groff_Version = `groff --version 2>$Dev_Null`;
-die "$Name error: groff does not work;" if $?;
-my $Groffer_Version = `groffer --version 2>$Dev_Null`;
-my $Has_Groffer = ! $?;
-
-if ($Has_Groffer) {
-  foreach (@ARGV) {
-    last if $_ eq '--';
-    next if $_ eq '-';
-    if ($_ eq '-v' || '--version' =~ m|^$_|) {
-      print $Name, ' in ', $Groffer_Version;
-      exit 0;
-    }
-    if ($_ eq '-h' || '--help' =~ m|^$_|) {
-      &usage_with_groffer();
-      exit 0;
-    }
-  }
-  system('groffer', '--to-stdout', "--$Mode", @ARGV);
-  exit $?;
-} else {
-  my @filespec;
-  my $double_minus;
-  foreach (@ARGV) {
-    if ($double_minus) {
-      push @filespec, $_;
-      next;
-    }
-    if ($_ eq '--') {
-      $double_minus = 1;
-      next;
-    }
-    if ($_ eq '-') {
-      push @filespec, '-';
-      next;
-    }
-    if ($_ eq '-v' || '--version' =~ m|^$_|) {
-      print $Name, ' in ', $Groff_Version;
-      exit 0;
-    }
-    if ($_ eq '-h' || '--help' =~ m|^$_|) {
-      &usage_without_groffer();
-      exit 0;
-    }
-    if ($_ =~ /^-/) {
-      &error_no_groffer();
-      &error_no_options();
-      next;
-    }
-    if (-f && -r) {
-      push @filespec, $_;
-    } else {
-      &error_no_groffer();
-      print STDERR "$_ is not an existing, readable file.\n";
-    }
-  }
-
-  @filespec = ('-') unless @filespec;
-  my $has_stdin;
-  foreach (@filespec) {
-    if ($_ eq '-') {
-      $has_stdin =1;
-      last;
-    }
-  }
-
-  if ($has_stdin) {
-    my $tempdir;
-    foreach ($ENV{'GROFF_TMPDIR'}, $ENV{'TMPDIR'}, $ENV{'TMP'},
-	     $ENV{'TEMP'}, $ENV{'TEMPDIR'},
-	     File::Spec->catfile($ENV{'HOME'}, 'tmp')) {
-      if ($_ && -d $_ && -w $_) {
-	$tempdir = $_;
-	last;
-      }
-    }
-    my $template = $Name . '_XXXX';
-    my ($fh, $stdin);
-    if ($tempdir) {
-      ($fh, $stdin) = tempfile($template, UNLINK => 1, DIR => $tempdir) ||
-	die "$Name: could not create temporary file;";
-    } else {
-      ($fh, $stdin) = tempfile($template, UNLINK => 1) ||
-	die "$Name: could not create temporary file;";
-    }
-    open $fh, ">$stdin";
-    print $fh $_ foreach <STDIN>;
-
-    foreach (@filespec) {
-      $_ = $stdin if $_ eq '-';
-    }
-  }				# if $has_stdin
-
-  my $grog;
-  my $groff_options = "-T$Mode";
-  $groff_options = '-TX75-12 -Z' if $Mode eq 'x';
-  $groff_options = '-Tlatin1' if $Mode eq 'text';
-  if ($Mode eq 'pdf') {
-    my $ps2pdf;
-    my @path = File::Spec->path();
-    foreach (@path) {
-      my $file = File::Spec->catfile($_, 'ps2pdf');
-      if (-f $file && -x $file) {
-	$ps2pdf = "$file -";
-	last;
-      }
-    }
-    unless ($ps2pdf) {
-      foreach (@path) {
-	my $file = File::Spec->catfile($_, 'gs');
-	if (-f $file && -x $file) {
-	  $ps2pdf = $file . ' -q -dNOPAUSE -dBATCH -sDEVICE=pdfwrite ' .
-	    '-sOutputFile=- -c save pop -f -';
-	  last;
-	}
-      }
-    }
-    $grog = `grog -Tps @filespec`;
-    chomp $grog;
-    system("$grog | $ps2pdf");
-    exit $?;
-  } else {
-    $grog = `grog $groff_options @filespec`;
-    chomp $grog;
-    system($grog);
-    exit $?;
-  }
-}
-
-my $error_no_groffer;
-sub error_no_groffer {
-  return 1 if $error_no_groffer;
-  $error_no_groffer = 1;
-  print STDERR "$Name: groffer is not available.\n";
-}
-
-my $error_no_options;
-sub error_no_options {
-  return 1 if $error_no_options;
-  $error_no_groffer = 1;
-  print STDERR "$Name: groffer options are not allowed.\n";
-}
-
-sub usage_with_groffer {
-  print <<EOF;
-usage: $Name [option]... [--] [filespec]...
-
--h | --help     print usage information
--v | --version  print version information
-
-All other options are arbitrary options of `groffer'; the options
-override the behavior of this program.
-
-`filespec's are the same as in `groffer': either the names of
-existing, readable files or `-' for standard input or a search pattern
-for man pages.  No `filespec' assumes standard input automatically.
-EOF
-}
-
-sub usage_without_groffer {
-  print <<EOF;
-usage: $Name [option]... [--] [filespec]...
-
--h | --help     print usage information
--v | --version  print version information
-
-No other options are allowed because `groffer' is not available.
-
-The only `filespec's allowed are the names of existing, readable files
-or `-' for standard input.  No `filespec' assumes standard input
-automatically.
-EOF
-}

Index: groffer/perl/split_env.sh
===================================================================
RCS file: groffer/perl/split_env.sh
diff -N groffer/perl/split_env.sh
--- groffer/perl/split_env.sh	22 Jan 2013 00:29:41 -0000	1.4
+++ /dev/null	1 Jan 1970 00:00:00 -0000
@@ -1,48 +0,0 @@
-#! /bin/sh
-
-# groffer - display groff files
-
-# Source file position: <groff-source>/contrib/groffer/perl/split_env.sh
-# Installed position: <prefix>/lib/groff/groffer/split_env.sh
-
-# Copyright (C) 2006, 2009 Free Software Foundation, Inc.
-# Written by Bernd Warken <groff-bernd.warken-72@web.de>.
-
-# Last update: 5 Jan 2009
-
-# 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/>.
-
-########################################################################
-
-# This file is called from groffer.pl.  The environment variable
-# of the name in $1 will be split at output.  The corresponding variable
-# must be exported before the call of groffer.pl.
-
-if test $# = 0
-then
-    echo 'split_env.sh was called without an argument.' >&2;
-else
-    eval v='"$'"$1"'"';
-    if test _"$v"_ != __
-    then
-	eval set x $v;
-	shift;
-	for i in "$@";
-	  do
-	  echo $i;
-	done;
-    fi;
-fi;

Index: groffer/shell/ChangeLog.0
===================================================================
RCS file: groffer/shell/ChangeLog.0
diff -N groffer/shell/ChangeLog.0
--- groffer/shell/ChangeLog.0	22 Jan 2013 00:29:41 -0000	1.3
+++ /dev/null	1 Jan 1970 00:00:00 -0000
@@ -1,2122 +0,0 @@
-2006-10-10  Bernd Warken <groff-bernd.warken-72@web.de>
-
-	* ChangeLog.0: This file is the former ChangeLog file of the
-	`groffer' versions 0.* consisting of a shell version only.  Since
-	then the files have been moved to the subdirectory `shell' of the
-	`groffer' main directory.
-
-2006-10-05  Bernd Warken <groff-bernd.warken-72@web.de>
-	________________________________________________________________
-	* release of groffer 0.9.31
-
-	* groffer2.sh:
-	- _make_pdf(): Fix argument of `obj'.
-	- to_tmp(): Add option -r to soelim to omit the .lf request.  The
-	new global variable $_SOELIM_R stores the option if it is
-	available.  Use numbers for the names of the `file' and `so'
-	temporary files, such that the information for each filespec
-	argument is kept for debug.  New global variable $_FILE_NR.
-	- main_set_resources(): Remove `man' temporary files except for
-	debug
-	- man_get(): Change name in $_TMP_MANSPEC.
-	- man_is_man(): Change name in $_TMP_MANSPEC.  Remove file in
-	$_TMP_MANPEC if empty.
-	- _do_display() of main_display(): Add check on empty mode file.
-
-	* groffer.man: Filespec: Add information on the argument
-	handling of apropos.
-
-	Remove the space characters at the end of line in all files.
-
-2006-10-03  Bernd Warken <groff-bernd.warken-72@web.de>
-	________________________________________________________________
-	* release of groffer 0.9.30
-
-	* groffer2.sh:
-	- Correct spacing.
-        - main_do_fileargs(): Distribute special_filespec() in order to
-        get a better heading for `whatis'.
-
-2006-10-03  Bernd Warken <groff-bernd.warken-72@web.de>
-	________________________________________________________________
-	* release of groffer 0.9.29
-
-	* groffer2.sh:
-	- --to-stdtout: New option to display the generated mode file
-	without graphical display.
-	- _get_prog_args() of main_set_mode(): Make argument upper case.
-	- usage(): Add --to-stdout, remove -Q, reorder --source.
-
-	* groffer.man:
-	- Reorder the default viewers.
-	- Move `--source' to `groffer' options.
-	- Remove `-Q'.
-	- Add `--to-stdout'.
-	- Reconfigure the sections on filespec arguments.
-	- Remove information on wildcards.
-
-2006-10-01  Bernd Warken <groff-bernd.warken-72@web.de>
-	________________________________________________________________
-	* release of groffer 0.9.28
-
-	* groffer.sh:
-	- Change all directories to end with `/'.
-	- In the state before the run of `make', make the script runnable
-	from each directory using $0 and `pwd'.
-
-	* groffer2.sh:
-	- main_init(): Change the umask to 0077 to allow only access for
-	the file owner for the temporary files.  This is done for security
-	reasons.
-	- version(): Put the whole output under `<<EOF'.
-	- usage(): Add information on filespec arguments.
-	- main_do_fileargs(): Rewrite the handling of filespec
-	parameters.  Fix filespec man:name.section.
-
-2006-09-26  Bernd Warken <groff-bernd.warken-72@web.de>
-	________________________________________________________________
-	* release of groffer 0.9.27
-
-	* Makefile.sub: Add Emacs setting at the end of the file.
-
-	* TODO: Remove this file because it does not contain any actual
-	entries.
-
-	* groffer2.sh:
-	- main_set_mode(): Remove too early test of modes on X.  Fix pdf
-	mode.
-	- where_is_prog(): Fix this function to detect files in the
-	current directory.
-	- _get_prog_args() of main_set_mode(): Fix return;
-	- _get_first_prog() of main_set_mode(): Fix call of exit_test().
-	- cat_z(): Make it a single function and add file test.
-	- whatis_setup(): Rename whatis_header().  Fix display title to
-	`whatis'.
-	- apropos_setup(): Fix display title to `apropos'.
-	- Globals: Fix this section in the description of several
-	functions.
-	- apropos_filespec(): Fix variable $s and the corresponding sed
-	call.
-	- man_setup(): Add $EXTENSION.
-	- _do_man_so() of to_tmp(): Fix variables.
-	- $_ALL_EXIT: Remove unused variable.
-	- $_TITLE_ELT: Remove unused variable.
-	- man_set_resources(): Fix setting of $_DISPLAY_ARGS.
-	- main_display(): Fix description.  Remove $md_options.  Let
-	$MANOPT override system variables.
-
-2006-09-16  Bernd Warken <groff-bernd.warken-72@web.de>
-	________________________________________________________________
-	* release of groffer 0.9.26
-
-	### Simplification of main_set_mode()
-
-	* groffer2.sh:
-	- _get_first_prog() of main_set_mode(): Rewrite this function
-	such that it does not have an output, but set the variables
-	$_DISPLAY_PROG and $_DISPLAY_ARGS.
-	- _check_prog_on_list() of main_set_mode(): Rename and rewrite
-	_check_X_prog().  Suitable for being called for $_VIEWER_<mode>_X
-	and $_VIEWER_<mode>_TTY.  No output, but set the variables
-	$_DISPLAY_PROG and $_DISPLAY_ARGS.
-	- _obj_set_vars() of main_set_mode(): Remove this function.  It is
-	no longer necessary because its variables are set by the other
-	functions.
-	- _get_prog_args() of main_set_mode(): New function that
-	simplifies the loop in main_set_mode() and handles both
-	$_VIEWER_<mode>_X and $_VIEWER_<mode>_TTY.
-	- _process_mode() of main_set_mode(): Remove this function.
-	- main_set_mode(): Remove case for calling _process_mode().  In
-	the loop, use _get_prog_args() for simplification.
-	- main_parse_args(): Make --<mode>-viewer equivalent to
-	--<mode>-viewer-tty to make _process_mode() unnecessary.
-	- $_VIEWER_BACKGROUND: Start with `no'.
-
-	### Extend the documentation
-
-	* groffer2.sh:
-	- Environment Variables: Add information on the naming of
-	variables in functions.
-	- $_ADDOPTS_POST, $_ADDOPTS_X: Remove these unused variables.
-	- apropos_setup(), apropos_setup (), base_name(), dir_name(),
-	echo1(), echo2(), func_check(), func_pop(), func_push(),
-	is_greater_than(), list_append(), list_from_split(),
-	_manpath_add_sys() of manpath_add_lang_sys(), rm_tree(),
-	special_filespec(), special_setup(), tmp_create(), to_tmp_line(),
-	usage(), version(), where_is_prog(), main_set_mode():
-	Fix and extend the description.  Many other function descriptions
-	were just fixed without being mentioned.
-	- landmark 7: man_*(): Add information on the search of `man'
-	pages.
-
-	* groffer.man:
-	- GNU `man' option overview: Add --location, --no-location, and
-	--where.
-	- GNU `man' options: Add the GNU `man' long options that are
-	accepted by `groffer', but just ignored.
-	- MAN PAGE SEARCHING: Correct and extend this section.
-
-	* TODO:
-	- Remove entry on function headers.
-	- Remove entry on GNU `man' options.
-	- Remove entry on search algorithm for `man' pages.
-
-	### Other fixes
-
-	* groffer2.sh:
-	- man_get(): On `man' page search with given name and section
-	handle also files with extension when no files without extension
-	are found.
-
-2006-09-11  Bernd Warken <groff-bernd.warken-72@web.de>
-	________________________________________________________________
-	* release of groffer 0.9.25
-
-	### Version information
-
-	* groffer2.sh:
-	- version(): Add groffer to the version information; replace the
-	call of `groff --version'.
-
-	### Configuration Files
-
-	* groffer.sh: Fix the configuration handling by removing all
-	quotes.  Arguments are ended by the end of the line.
-
-	* groffer.man: Fix the section on the configuration files.
-
-	### Options
-
-	* groffer2.sh:
-	- $_OPTS_GROFF_SHORT_NA: Add `-k' as new groff option.
-	- main_pars_args(): Add X options `--ft', `--bordercolor',
-	`--borderwidth'.
-	- usage(): Add `--debug-filenames'.  Remove `*-viewer-tty'.
-	Correct first line after call of version().
-	- main_parse_MANOPT(): Fix `-h', `-t', and `-u' as options without
-	argument.
-
-	* groffer.man:
-	- Add documentation to `--fn', `--ft', `--bordercolor',
-	`--borderwidth'.
-	- Remove the `--*-viewer-tty' options.  These options are still
-	supported by the groffer program, but they aren't needed any
-	more.
-
-	### soelim: Allow manpath and compressed files in .so requests, as
-	### man does.
-
-	* groffer2.sh:
-	- $_FILESPEC_IS_MAN: New variable for storing if a filespec is for
-	searching a man page.
-	- to_tmp(): Rewrite. For existing file as filespec argument, add
-	call of `soelim' with the corresponding `-I dir' before the call
-	of `grog'.  For man paged, uncompress and store the files from .so
-	requests; replace the requests with the stored file names.
-	- _do_man_so() of to_tmp(): New function to handle the file of a
-	.so request.
-	- man_get(): For man pages without extension, add special search
-	strategy.
-
-	* README: Add the .so handling to the Compatiblity section.
-
-	### Print file names debug
-
-	* groffer2.sh:
-	- $_OPT_LOCATION: Replace this variable by
-	$_DEBUG_PRINT_FILENAMES.
-	- register_file(): Move file name printing and call to basename to
-	register_title().
-	- _do_man_so() of to_tmp(): Add file name printing for man pages.
-
-	### modes
-
-	* groffer2.sh:
-	- $_DEFAULT_MODES: New set of default modes in the sequence 'pdf',
-	'html', 'ps', 'x', 'dvi', and 'tty'.  That is done because the `x'
-	mode viewers `gxditview' and `xditview' are very bad programs.
-	- _make_pdf() of main_display(): If pdf format can not be
-	generated use Postscript mode (ps) instead for display.
-	- $_PDF_DID_NOT_WORK, $_PDF_HAS_PS2PDF, $_PDF_HAS_GS: New
-	variables for pdf mode to avoid several runs.
-	- $_VIEWER_TTY_TTY, $_VIEWER_TTY_X: Add these variables for the
-	viewers in tty mode.
-	- main_display(): Rewrite tty mode by using where_is_prog() to add
-	options to `less' from the command line.
-
-	* groffer.man:
-	- Add this information.
-	- Adjust the viewers in `SEE ALSO'.
-
-	### Check viewer option for programs running in X Window
-
-	* groffer2.sh:
-	- _check_X_prog() of main_set_mode(): New function for checking if
-	a program of a command line argument is in the list for X for this
-	mode.
-	- _get_first_prog() of main_set_mode(): Use where_is_prog();
-	change the output to the same 3-element list as _check_X_prog().
-	- _obj_set_vars() of main_set_mode(): New function for setting
-	some variables in several modes.  Argument is the 3-element list
-	from _check_X_prog() or _get_first_prog().
-	- _process_mode() of main_set_mode(): Remove part with
-	list_has_not_prog().  This is better done by _check_X_prog().
-	- main_set_mode(): Use _check_X_prog() in different modes.
-	Correct several modes.  Add reset of $_VIEWER_BACKGROUND at the
-	beginning of the loop of default modes.
-
-	### Allow man pages with space characters
-
-	* groffer2.sh:
-	- man_is_man(): Fix grep calls.
-	- list_from_file(): New function that reads the lines of a file as
-	list elements.
-	- man_get(): Fix `case' applications by double-quoting all
-	variables.  Use list_from_file() instead of setting with `cat'.
-	Add further tests.
-	- _do_man_so() of to_tmp(): Use list_from_file() instead of
-	setting with `cat'.
-
-	### Allow program names with space
-
-	* groffer2.sh:
-	- is_prog(), is_not_program(): Change to exactly one argument with
-	possible spaces and arguments.	Fix all calls.
-	- where_is_prog(): Change to exactly one argument.  Change
-	variable prefix to `wip'.  Rewrite it to support programs with
-	spaces and arguments.  Return a list with 3 elements: the
-	program's directory, the program name, and the given arguments.
-	- main_display(): Correct tty mode.
-
-	### Further fixes
-
-	* groffer2.sh:
-	- main_setup(): Fix func_check.
-	- clean_up(): Add variable to avoid several prints.
-	- where_is_prog(): Remove possible arguments from program
-	argument.
-	- obj_from_output(): As return value take the return value of the
-	called function.
-	- is_not_empty(): Rename of is_non_emtpy().
-	- $_VIEWER_BACKGROUND: Rename $_VIEWER_TERMINAL and reverse its
-	values.
-	- list_has_prog(), list_has_not_prog(): Remove these functions,
-	they are no longer needed.
-
-	* groffer.man:
-	- Add `--print' in OPTION OVERVIEW.
-	- Correct many entries with the non-breaking `\%' construct.
-
-2006-07-28  Bernd Warken <groff-bernd.warken-72@web.de>
-	________________________________________________________________
-	* release of groffer 0.9.24
-
-	### Extent long option abbreviation to abbreviations before each `-'.
-
-	* groffer2.sh:
-	- list_from_cmdline_with_minus(): New function, the same as
-	list_from_cmdline() with multiple abbreviations around `-'.
-	- _search_abbrev(): Subfunction of list_from_cmdline_with_minus().
-	- main_parse_args(): Use list_from_cmdline_with_minus() for
-	getting the double abbreviation, but keep main_parse_MANOPT()
-	to list_from_cmdline() for simple abbreviation of long options.
-	- For the debug test at the beginning, add the double abbreviation
-	functionality.
-
-	* README_SH, groffer.man: Document the multiple set of
-	abbreviations by `-'.
-
-	### Fix handling of `--apropos*' and `--whatis'
-
-	* groffer2.sh:
-	- apropos_filespec(): Fix handling of `/' and `.' in sed; add `\&'
-	at the beginning of each non-macro groff line in sed.
-	- main_parse_args(): Set $_MAN_OPT to `yes' if --whatis is called.
-	- main_do_fileargs(): Fix dealing with `apropos' for several
-	cases.
-	- apropos_*(), special_*(), whatis_*(): Add two different return
-	values.
-	- $_SPECIAL_SETUP: New variable to test whether apropos_setup() or
-	whatis_header() had been run.
-	- Add language locale to --whatis, the `whatis' program does not
-	support this.
-
-	### Handle several macro packages
-
-	* groffer2.sh:
-	- $_MACROS: New variable to store the actual macro package.
-	- $_MACRO_PACKAGES: New variable for the full macro packages of
-	groff (man, mdoc, me, mm, mom, ms).
-	- to_tmp(): Add test for different macro packages.  Ignore files
-	with a different one.
-	- main_do_fileargs(): Add different macro check before doing man
-	pages.
-
-	### Rewrite the man page search
-
-	* groffer2.sh:
-	- $_MAN_SEC_CHARS, $_MAN_SEC_LIST: New variables from $_MAN_SEC.
-	Add these to man_setup().
-	- man_get(): New function that finally gets the man page or man
-	pages for a filespec.  Avoid double files.
-	- man_is_man(): New function that checks whether a name goes as
-	man page.
-	- manpath_add_lang_sys(): Fix handling of language addition for
-	short language names.
-	- main_parse_args(): Move handling of `-' to main_do_fileargs().
-	- do_filearg(), man_do_filespec(), man_register_file(),
-	man_search_section(): Remove these functions.
-	- main_do_fileargs(): Rewrite this function together with
-	the removed functions.
-	- list_uniq(): New function to remove the multiple elements from a
-	list.
-
-	### Version handling.
-
-	* version.sh: New file for $_PROGRAM_VERSION, $_LAST_UPDATE, and
-	$_GROFF_VERSION_PRESET.
-
-	* groffer.sh:
-	- Add running of version.sh with `.'.
-	- Remove $_PROGRAM_VERSION and $_LAST_UPDATE.
-	- Run groffer2.sh with `.' instead of `exec'.  This allows to have
-	groffer2.sh without executive access permission.
-	- Determine $_BEFORE_MAKE by @VERSION@, use this variable on more
-	places.
-
-	* groffer2.sh:
-	- Remove executive access permission.
-	- version(): Write a version information without calling groff.
-
-	* Makefile.sub:
-	- Add version.sh.  Use $(INSTALL_DATA) instead of
-	$(INSTALL_SCRIPT) for version.sh and groffer2.sh.
-	- Add $(DESTDIR) to some elements of `sed' call in `groffer:'.
-
-	### viewers for different modes
-
-	* groffer2.sh:
-	- $_VIEWER_HTML_X: Add `epiphany' as browser.
-	- $_VIEWER_PDF_X: Add `kpdf' and `evince' as pdf viewer for X.
-	Make `kpdf', `acroread', `evince', and `xpdf' the first automatic
-	pdf viewers for X because they support searching.  Add `gpdf'.
-	- $_VIEWER_PS_X: Add `kpdf' and `evince' as ps viewer for X; make
-	`kpdf' the first automatic ps viewer for X because it supports
-	searching even for Postscript.
-
-	### pdf mode
-
-	* groffer2.sh:
-	- _make_pdf() of main_display(): add `ps2pdf' as secondary
-	transformer.
-	- main_set_resources(): Allow setting of resolution for `xpdf'
-	only if option -z is not set for `xpdf'.
-
-	### Revise $_VIEWER_*
-
-	* groffer2.sh:
-	- $_VIEWER_<mode>_TTY: Add this variable to each mode even if it
-	is only empty.
-	- $_VIEWER_<mode>_X: Rename $_VIEWER_<mode> to this for each
-	mode.
-
-	### Other fixes
-
-	* groffer2.sh:
-	- is_empty_file(): New function.
-	- obj_from_output(): Quote arguments by building a list.
-	- path_list(): Output path list with unique elements.
-	- where_is_prog(): Rename where_is().  Handle all file names
-	having a slash somewhere instead of only those that start with a
-	slash.
-	- $_REG_TITLE_LIST: Replace $_REGISTERED_TITLE and make it a
-	list.
-	- $_OPT_TITLE: Make it a list with at most 1 element.
-	- Remove double quotes in case patterns.
-	- _func_test(): For the function test at the beginning, add this
-	function for output check with $() construct.
-	- usage(): Add --shell.
-	- $_VIEWER_HTML_X: Add `firefox' and `mosaic'.
-	- list_get(): Remove this unused function.
-	- Fix func_check() calls in all functions.
-
-	* groffer.sh: Adjust groff version to 19.3.
-
-	* README: Add information list of the source files.
-
-2006-02-26  Claudio Fontana  <claudio@gnu.org>
-
-        * Makefile.sub: Add DESTDIR to install and uninstall targets
-        to support staged installations.
-
-2005-09-14  Bernd Warken <groff-bernd.warken-72@web.de>
-	________________________________________________________________
-	* release of groffer 0.9.23
-
-	### Increase the speed for the search of man pages
-
-	Run `find' on all man directories and ask this with `grep' instead
-	of scanning through many `ls'.
-
-	* groffer2.sh:
-	- $_TMP_MAN: New variable with the name of the file that stores
-	the `find' of the man path.
-	- $_TMP_MANSPEC: New variable with the name of the file that
-	stores the man page file names for each filespec.
-	- man_setup(): Do the `find' of the man path with $_TMP_MAN.
-	- man_do_filespec(): Add creation of $_TMP_MANSPEC.
-	- man_search_section(): Rewrite it to use $_TMP_MANSPEC.
-
-	* TODO: The demand on the increase of speed for man pages is now
-	removed.
-
-	### Increase speed by enhancement of debug
-
-	* groffer.sh: $_BEFORE_MAKE: New variable that stores whether the
-	@...@ constructs are still available or already transformed by
-	`make'.
-
-	* groffer2.sh:
-	- $_DEBUG_FUNC_CHECK: New debug variable that regulates the check
-	calls at the beginning and end of most functions done by the
-	functions func_<name>().  By default, this is enabled before the
-	run of `make', and disabled after.  $_DEBUG_STACKS and
-	$_DEBUG_USER_WITH_STACK enable this variable automatically.
-	- --debug-func: New option for setting $_DEBUG_FUNC_CHECK.
-	- usage(), main_parse_args(): Add information for --debug-func.
-	- func_<name>(): Disable these functions if $_DEBUG_FUNC_CHECK is
-	not `yes'.
-
-	* groffer.man:
-	- Add information on --debug-func.
-	- Move the sections on options for development to the end of
-	option processing.
-
-	### Fixes of man page search
-
-	- man_search_section(): Repair it such that extensions do not
-	occur in the directory name.
-	- manpath_set_from_path(): Rewrite it.  Add `.../MAN/...'
-	subdirectories additionally to `.../man/...'.
-	- manpath_add_lang_sys(): Rewrite it to overwrite _MAN_PATH by
-	systems parameter if any.  Then _MAN_PATH is prepended by the
-	language part.
-	- _manpath_add_sys(): New subfunction of manpath_add_lang_sys() to
-	handle the systems part.
-	- man_search_section: Fix it to handle section names that have
-	more than one character (an extension).
-	- $_MAN_PATH: Now stores man path as a list.  This is done in
-	man_setup() and manpath_set_from_path(), and used in
-	manpath_add_lang_sys().
-	- $_MAN_SYS: Now stores man systems parameter as a list.  This is
-	done in man_setup() and used in manpath_add_lang_sys().
-	- $_MAN_SEC_DONE, $_MAN_SYS_DONE, $_MAN_LANG_DONE: Remove these
-	variables.
-
-	### Reorder the beginning of groffer2.sh
-
-	* groffer2.sh:
-	- func_<name>(): Move these functions to the functions in
-	alphabetical order.
-	- main_init(): Move "Test for compression" to this function.
-	- Move the "System Test" and function landmark() to the beginning
-	"Test of rudimentary shell functionality".  Change landmarks 1 and
-	2 to new positions.
-
-	### Fix the mode when not in X
-
-	* groffer2.sh:
-	- main_parse_args(): Accept modes even when not in X, hoping for a
-	program given by option.  Add $_OPT_VIEWER_<MODE>_TTY.  Remove
-	$_VIEWER_TERMINAL.
-	- main_set_mode(): Add a section to set $_VIEWER_TERMINAL and move
-	the value of $_OPT_VIEWER_<MODE>_TTY to $_OPT_VIEWER_<MODE>.  When
-	not in X and no terminal programs are set remove $_OPT_MODE.  All
-	unknown programs are treated as terminal programs.
-	- usage(): Comment out options --<mode>-viewer-tty.  They exist
-	and are handled by `groffer', but they are no longer documented.
-	- $_OPT_VIEWER_<MODE>_TTY: New variables for option
-	--<mode>-viewer-tty.
-	- $_DEFAULT_MODE, $_VIEWER_<MODE>: Change it from , separation to
-	a list.  Rewrite _get_first_prog() of main_set_mode() to get
-	around with this.
-
-	* groffer.man: Remove information on --<mode>-viewer-tty.
-
-	### Debug
-
-	* groffer2.sh:
-	- $_DEBUG_PRINT_FILENAMES: New variable for printing the file
-	names that are displayed by `groffer'.
-	- --debug-filenames: The corresponding option.  It is used in
-	man_register_file(), register_file(), and main_parse_args().
-
-	* groffer.man: Add information on --debug-filenames.
-
-	### Other changements
-
-	* groffer2.sh:
-	- is_greater_than(): New function.  Use it where suitable.
-	- lists_combine(): New function to combine several lists to a
-	single list.
-	- list_from_split(): Rewrite it to output a list with quoted
-	elements.
-	- list_has_prog(), list_has_not_prog(): New functions to check the
-	list on an element that starts with a given word.
-	- obj_from_output(): Use this function at many places instead of
-	`var="$(...)"'; this makes the usage of exit_test() unnecessary.
-	- path_clean(): Fix assignment.
-	- path_list(): Rename path_split().
-	- tmp_create(): Add check of temporary file.
-	- usage(): Fix.
-
-	* README_SH:
-	- Fix section `Error handling'.
-	- Add section `Speed'.
-
-2005-08-22  Bernd Warken <groff-bernd.warken-72@web.de>
-	________________________________________________________________
-	* release of groffer 0.9.22
-
-	### `--whatis'
-
-	Produce a `groff' output and allow wild cards on filespec
-	parameters for `--whatis'.
-
-	* groffer2.sh:
-	- $_FILESPEC_ARG: New variable for storing the actual filespec
-	parameter.
-	- main_do_fileargs(): Set $_FILESPEC_ARG and add
-	what_is_filespec().
-        - main_parse_args(): Add --all to --whatis.
-	- to_tmp_line(): New function to write the arguments to the
-	temorary cat file.
-	- whatis_filename(): Rename of what_is().  Construct a better
-	printout using $_FILESPEC_ARG.  Repair the sed sequneces.
-	- whatis_filespec(): New function to print the filespec once
-	during the `whatis' process.
-	- whatis_header(): New funtion for printing the header of the
-	`whatis' output.
-
-	* groffer.man: Revise the documentation of --whatis.
-
-	### `--apropos*'
-
-	Produce `groff' for `--apropos*'.  Allow `--sections' for
-	`--apropos', ignore it  with `--apropos-*'.
-
-	* groffer2.sh:
-	- --apropos*: Make these options without argument.
-	- $_APROPOS_PROG: New variable for the program that is is used for
-	`apropos'.
-	- $_APROPOS_SECTIONS: New variable to determine the sections that
-	are filtered out of `apropos' output depending on `--apropos-*'.
-	- apropos_filespec(): Handling of apropos at the filespec level.
-	- apropos_run(): Remove it.
-	- apropos_setup(): New function.
-	- main_set_mode(): Remove handling of $_OPT_APROPOS*.
-
-	* groffer.man:
-	- Revise the documentation of `--apropos*'.
-	- Split section 'options for GNU man' into two sections `options
-	for man pages' and `long options taken over from GNU man'.
-	- Move `--apropos*', `--whatis', `--man', and `--no-man' to
-	section `options for man pages'.
-
-	### special display (apropos and whatis)
-
-	* groffer2.sh:
-	- special_setup(): New function that chooses the setup between
-	apropos and whatis.
-	- special_filespec(): New function that does the output at the
-	filespec level for apropos or whatis.
-
-	### handle `--sections' for man page searching
-
-	* groffer2.sh:
-	- man_do_filespec(): Use $_OPT_SECTIONS of --sections instead of
-	$_MAN_AUTO_SEC if non-empty.  If a section was given on the
-	filespec parameter $_OPT_SECTIONS is ignored.  This differs from
-	`man' which always uses the restricted sections of --sections.
-	This function works for both normal man page search and whatis.
-	- apropos_filespec(): Use --sections for --apropos, but not for
-	--apropos-* because these provide already their own sections.
-
-	### wildcards in filespec arguments
-
-	* groffer2.sh: Wildcards are now accepted.  In `--apropos*' and
-	`--whatis' they are interpreted as wildcard search elements; but
-	in normal display they are only handled as their own character.
-
-	### development; new option
-
-	* groffer2.sh:
-	- --print: New option that prints just its argument for parameter
-	check.
-	- usage(): Add new option.
-	- $_OPT_DO_NOTHING: New variable for do_nothing().  Handle it at
-	the end of main_parse_Args().
-
-	* groffer.man: Add information on --print.
-
-	### safe exit
-
-	* groffer2.sh:
-	- error(): Always exit with $_ERROR.
-	- exit_test(): New function to exit when first exit was hidden by
-	().  Call it after each $().
-
-	### automatic shell determination
-
-	* groffer.sh:
-	- If no option --shell is given perform a test of several shells
-	to automatically start some shell for groffer2.sh.  `ksh' is used
-	first because it can be safely terminated by Ctrl-C.
-	- This can be cancelled by providing --shell=''.
-	- Add test on `sed' program.
-
-	* groffer.man: Revise information on --shell.
-
-	### trap
-
-	* groffer2.sh:
-	- trap_set(): Remove argument.  Instead of $_ALL_EXIT use only
-	signal 0.
-	- trap_unset(): Rename trap_clean().  Instead of $_ALL_EXIT use
-	only signal 0.
-	- $_ALL_EXIT: Remove this variable.
-	- Replace all direct `trap' calls by trap_set().
-
-	* README_SH: New section `Bugs' on `trap'..
-
-	### user errors, error output without function stack
-
-	* groffer2.sh:
-	- error_user(): New function for user errors.
-	- error(): Remove call of clean_up() because the trap will do it
-	with the exit.  Remove the `kill' commands.  Create a temporary
-	file `.error' that can be tested by exit_test() for a better exit
-	test (especially for shell `ksh').
-	- $_DEBUG_USER_WITH_STACK: New variable to enable function stack
-	output in error_user().
-	- list_from_cmdline(), list_single_from_abbrev(), main_set_mode():
-	Use error_user().
-
-	### test modes on X and tty
-
-	* groffer2,sh:
-	- is_X(), is_not_X(): New functions for checking on X Window.
-	- $_VIEWER_HTML_TTY, $_VIEWER_HTML_X: New variables that split
-	$_VIEWER_HTML.  Add `galeon'.
-	- main_parse_args(): Allow mode change for graphical modes only
-	when in X Window.
-	- _do_display() of main_display(): Create a special run for
-	viewers that run on the terminal; `lynx' is the only one so far.
-
-	### add $GROFFER_MODE to command line
-
-	* groffer.sh:
-	- After the handling of the configuration files integrate
-	$GROFFER_OPT to the command line.
-	- This makes a `set' in the shell determination unnecessary.
-
-	* groffer2.sh:
-	- The debug test gets simpler because quotes are vanished without
-	$GROFFER_OPT.
-	- main_parse_MANOPT(): Prepend $mpm_list to the command line.
-	- main_parse_args(): `set' is unnecessary.
-
-	### debug; new options
-
-	* groffer2.sh:
-	- --debug-all, --debug-lm, --debug-params, --debug-shell,
-	--debug-stacks, --debug-tmpdir, --debug-user: New options.
-	- --debug: Enable all debug variables except $_DEBUG_STACKS and
-	$_DEBUG_LM.  By the new options the smallest abbreviation is now
-	`--debug'.
-	- $_DEBUG_STACKS: Rename $_DEBUG.
-	- $_DEBUG_PRINT_TMPDIR: New debug variable for printing the name
-	of the temporary directory in main_init().
-	- $_OPT_DEBUG: Remove this variable because debug is handled at
-	the early part of the script.
-	- clean_up(): Enlarge $_DEBUG_KEEP_FILES to not deleting the
-	temporary directory.
-	- usage(): Move all development options on a section of its own.
-	- Move the test of rudimentary shell functionality at the
-	beginning of the script.  Add test on `sed'.
-	- Follow this by the debug section.  The determination of all
-	--debug* options can be done without a function.
-
-	* groffer.man: Revise information on --debug and add new options.
-
-	### variables
-
-	* groffer.sh:
-	- $_ERROR: Move the definition of this variable here.
-	- $_GROFF_VERSION: New variable, is set over @...@ construct.
-	- $_OUTPUT_FILE_NAME: Move this variable to groffer2.sh.
-
-	* groffer2.sh:
-	- $_MAN_AUTO_SEC_LIST: Rename $_MAN_AUTO_SEC because it represents
-	a list.
-	- $_MAN_AUTO_SEC_CHARS: New read-only variable for storing
-	$_MAN_AUTO_SEC_LIST in [] construct.  Use it in man_do_filespec()
-	and whatis_filename().
-	- $_SPACE_CASE: New read-only variable with [] on space characters
-	with \ for `case' patterns.  Use it in several functions.
-	- $_SPACE_SED: New read-only variable with [] on space characters
-	for `sed'.  Use it in several functions.
-
-	### options and display
-
-	* groffer2.sh:
-	- list_from_cmdline(): Add test whether the same abbreviation is
-	part of long options with and without arguments.  Give handling of
-	`=' a `case' pattern of its own.
-	- main_display(): Remove unnecessary calls of `clean_up' in order
-	to use `mozilla' without problems.  In _do_display(): Fix -X by
-	providing a different process when $_DISPLAY_PROG is empty.
-	- main_set_mode(): Accept options for viewers as is, without check
-	for program.  Add test whether no program is given for a mode.
-	This avoids unnecessary empty $_DISPLAY_PROG in main_display().
-
-	### viewer programs that run on the terminal (tty); new options
-
-	* groffer2.sh:
-	- $_VIEWER_TERMINAL: New variable that stores whether a viewer was
-	supposed to run on tty.
-	- --dvi-viewer-tty, --html-viewer-tty, --pdf-viewer-tty,
-	--ps-viewer-tty, --tty-viewer-tty, --X-viewer-tty, --x-viewer-tty,
-	--www-viewer-tty: New options for viewers that run on a terminal.
-	- main_parse_args(), _do_display() of main_display(): Use the new
-	options and the new variable.
-	- usage(): Add the new options.
-
-	* groffer.man: Add information on options --*-viewer-tty.
-
-	### other fixes
-
-	* groffer2.sh:
-	- _do_display() of main_display(): Bear errors of `groff' run.
-	- is_not_file: Fix to have exactly one argument.
-	- is_not_prog(): Handle no arguments.
-	- list_has_not(): Fix.
-	- main_do_fileargs(): Remove $mdfa_exitcode.
-	- register_title(): Limit title to 4 elements.
-	- version(): Print the version information to standard output just
-	like `groff' does.
-	- --no-special: New option to disable former calls of `--all',
-	`--apropos*', and `whatis.
-	- --title: Make it an option with argument.
-
-2005-08-07  Keith Marshall  <keith.d.marshall@ntlworld.com>
-
-	* contrib/groffer/Makefile.sub (install): Reference groffer2.sh
-	as $(srcdir)/groffer2.sh, so it will install when building in a
-	different directory from the source.
-
-2005-08-02  Bernd Warken <groff-bernd.warken-72@web.de>
-	________________________________________________________________
-	* 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 that	it 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.
-
-2005-07-30  Bernd Warken <groff-bernd.warken-72@web.de>
-	________________________________________________________________
-	* release of groffer 0.9.20
-
-	### Split groffer.sh into two files groffer.sh and groffer2.sh.
-
-	* groffer.sh:
-	- Remove the second part of this script.  It is now in
-	groffer2.sh.
-	- $_GROFFER2_SH: New variable to point to the installed position
-	of `groffer2.sh'.  This position is presented using @libdir@.
-
-	* groffer2.sh: New script containing the second part of
-	groffer.sh. This script will be installed in the groffer library
-	directory @libdir@/groff/groffer, this might be
-	/usr/local/lib/groff/groffer/groffer2.sh for example.
-
-	* Makefile.sub:
-	- `groffer': Add replacement of @libdir@.
-	- `install_data': Add the installation of the groffer library
-	directory and groffer2.sh.
-	- `uninstall_sub': Delete the installed `groffer2.sh' and the
-	groffer library directory.
-
-	* README_SH:
-	- Remove the function list.
-	- Add argument options to the list of used commands.
-	- Documentation of the splitting of the script.
-	- Document the possible abbreviation of options.
-
-2005-07-07  Bernd Warken <groff-bernd.warken-72@web.de>
-	________________________________________________________________
-	* release of groffer 0.9.19
-
-	* groffer.sh: extensions
-	- `mode x': Mode for the equivalent options `--x', `--mode x',
-	`--X' `--mode X', and the default mode.  The default assumes a
-	resolution of 75 dpi.  The default device for a resolution of 75
-	dpi is `X75-12', the default device for a resolution of 100 dpi is
-	`X100'.  The default geometry for the resolution of 100 dpi is set
-	to the width 800 dpi.
-	- `mode X': New mode for option -X only.
-	- `-V': Extent the `groff' output of -V by `groffer' specific
-	information (in main_display()).
-	- register_file(): Replace title `-' by `stdin'.
-	- $_DEBUG_KEEP_FILES: If set to `yes' the files in the temporary
-	directory are not deleted before the end trap.
-
-	* groffer.sh: get `zsh' to work as well
-	- tmp_create(): Use `: >file' for generating an empty file.
-	- rmdir: Replace `rmdir' by `rm -f -r'.
-	- eval: Add `eval' to many commands with variable arguments.
-
-	* groffer.sh: repair `debug'
-	- Print all debug output to stderr.
-	- $_FUNC_STACK: Built function call stack even when $_DEBUG is not
-	set.  Now the arguments are not added.
-	- $_DEBUG: If set to `yes' print 3 call stack events: the function
-	that is added with its arguments is printed with `+++ '
-	(func_push()); the call stack after the addition is printed with
-	`>>> ' (func_push()); the call stack after the removing is printed
-	with `<<< ' (func_pop()).
-	- error(): Always print the function call stack on errors.
-
-	* groffer.sh: Corrections
-	- $_groffer_run: Rename to $_GROFFER_RUN.
-	- $unset: Rename to $_UNSET.
-	- Repair test of `unset'.
-	- Repair test for `--shell'.  The script is now rerun under the
-	shell specified in the option argument.  This can increase the
-	speed.
-
-	* README_SH: `zsh' now works.
-
-	* groffer.man:
-	- Reformulate the information for the `groffer' specific details
-	of option `-V'.
-	- Add information on the debug process.
-	- Add information on the default devices in `x mode'.
-	- Minor corrections.
-
-2005-07-01  Bernd Warken <groff-bernd.warken-72@web.de>
-	________________________________________________________________
-	* 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 choosing 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@'.
-
-2005-06-23  Bernd Warken <groff-bernd.warken-72@web.de>
-	________________________________________________________________
-	* release of groffer 0.9.17
-
-	* groffer.sh: get rid of `local' in functions (it is not POSIX)
-	- Replace local variables by variable names with a special prefix
-	that is an abbreviation of the corresponding function name (quasi-
-	local variables).
-	- Unset the quasi-local function variables before returning.
-	- _t_e_s_t_f_u_n_c_(): Remove tests for local and global
-	variables.
-	- Add quasi-local variables for saving the content of
-	single-character variables.
-	- Remove some unused local and global variables.
-	- Several variables were forgotten to make local.  They are now
-	made quasi-local.
-
-	* groffer.sh: other corrections
-	- $return_var: New function (after `eval') for an arbitrary
-	return value.
-	- obj*(): Add return modes.
-	- Rewrite tests for `true' and `false'.
-	- Add function names to error calls where it was forgotten.
-	- `for': Replace `for x in "$@"' by `for x'.
-	- `set': Replace `set -- ...' by `set x ...; shift'.
-	- `sed': Replace `\|.*|s|...|...|' by `s|...|...|'.
-
-	* README_SH:
-	- Add information on the removing of `local'.
-	- New section for non-POSIX shell restrictions.
-
-2005-06-20 Keith Marshall
-
-	* README-SH: Information of `Portable shells' in info autoconf.
-
-2005-06-19  Bernd Warken <groff-bernd.warken-72@web.de>
-	________________________________________________________________
-	* release of groffer 0.9.16
-
-	* groffer.sh: Place each `then', `else', and `do' on a line of its
-	own because some shells do not support the mixture mode.
-
-	* groffer.man: Add section `BUGS'.
-
-	* README_SH:
-	- Add compatibility information.
-	- Correct documentation for function arguments.
-
-2005-06-18  Keith Marshall
-
-	* groffer.sh: $_NULL_DEV: Replace /dev/null by $_NULL_DEV which is
-	either /dev/null or NUL if /dev/null does not exist.
-
-2005-06-17  Zvezdan Petkovic
-
-	* Makefile.sub: $(RM): Define it to `rm -f' because not all `make'
-	programs have it predefined.
-
-2005-06-16  Bernd Warken <groff-bernd.warken-72@web.de>
-	________________________________________________________________
-	* release of groffer 0.9.15
-
-	* Makefile.sub:
-	- Use `$(RM)'.
-	- Use `sed -f $(SH_DEPS_SED_SCRIPT)'.
-
-2005-05-20  Bernd Warken <groff-bernd.warken-72@web.de>
-	________________________________________________________________
-	* release of groffer 0.9.14
-
-	* groffer.man: correction of non-hyphenation
-
-2005-05-17  Bernd Warken <groff-bernd.warken-72@web.de>
-	________________________________________________________________
-	* release of groffer 0.9.13
-
-	* groffer.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
-
-2005-05-14  Keith Marshall
-
-	* groffer.sh:
-	- first line: Add space to `#! /bin/sh'.
-
-2004-11-15  Bernd Warken <groff-bernd.warken-72@web.de>
-	________________________________________________________________
-	* release of groffer 0.9.12
-
-	* groffer.sh:
-	- main_init(): Rewriting of the creation of the temporary
-	directory to ensure that it cannot be made writable apart from the
-	user.  If the directory already exists and cannot be removed then
-	append `X' to the directory name.
-	- is_non_empty_file(): fix it to use POSIX `test -s'.
-	- is_existing(): new function.
-	- POSIX `rm -f -r': use this in `clean_up()' and `main_init()'.
-	- `--macro-file': remove this unused long option.
-	- `-V', `--source', `--device': move these from groff options
-	to groffer options.
-	- `$_TMP_DIR_SUB': remove this unused variable.
-
-2004-06-15  Bernd Warken <groff-bernd.warken-72@web.de>
-	________________________________________________________________
-	* release of groffer 0.9.11
-
-	* groffer.sh:
-	- To the search of the `--apropos-*' options, add man pages with a
-	subsection in their apropos output.
-
-2004-06-02  Bernd Warken <groff-bernd.warken-72@web.de>
-	________________________________________________________________
-	* 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.
-
-2004-05-29  Bernd Warken <groff-bernd.warken-72@web.de>
-	________________________________________________________________
-	* release of groffer 0.9.9
-
-	* groffer.sh:
-	Fix first run section to allow the starting shell to go on if
-	`ash' is not available.
-
-	* groffer.man:
-	Remove unnecessary information on groffer version.
-
-2004-05-12  Bernd Warken <groff-bernd.warken-72@web.de>
-	________________________________________________________________
-	* release of groffer 0.9.8
-
-	* groffer.sh:
-	Fix problems of `test' by adding subs to arguments.
-
-	* groffer.man:
-	Write the file license as macros that are called in sections
-	AUTHOR and COPYING.
-
-	* .cvsignore:
-	Restore this file.
-
-2004-04-30  Bernd Warken <groff-bernd.warken-72@web.de>
-	________________________________________________________________
-	* release of groffer 0.9.7
-
-	* groffer.sh:
-	- obj(), obj_data(), obj_from_output(), obj_set(): New object
-	oriented functions to minimize complicated `eval' commands.
-	- list_*(): Corrections.
-	- usage(): Streamlining.
-
-	* groffer.man, README_SH:
-	Corrections.
-
-2004-04-27  Bernd Warken <groff-bernd.warken-72@web.de>
-	________________________________________________________________
-	* release of groffer 0.9.6
-
-	This version replaces the license of all files except ChangeLog of
-	the groffer source to the GNU General Public License (GPL) of the
-	version described in files COPYING and LICENSE in the groff top
-	source directory.
-
-	* groffer.man:
-	Changement from the GNU Free Documentation License (FDL) to
-	the GNU General Public License (GPL).
-
-	* README, README_SH, TODO:
-	Add license GNU General Public License (GPL).
-
-	* Makefile.sub, groffer.sh:
-	Keep the GNU General Public License (GPL), but refer to the
-	COPYING and LICENSE files.
-
-	* ChangeLog: Add a license in the style of Emacs ChangeLog file,
-	which is weaker than the GPL, but has its flavor.
-
-2004-04-24  Bernd Warken <groff-bernd.warken-72@web.de>
-	________________________________________________________________
-	* release of groffer 0.9.5
-
-	This version is a rewrite of groffer in many parts, but it is kept
-	in the old single script style.
-
-	Overview of new options:
-	--text, --mode text, --tty-viewer,
-	--X, --mode X, --X-viewer, --html, --mode html, --html-view,
-	--apropos-data, --apropos-devel, --apropos-progs
-
-	New file:
-	<groffer-source>/README_SH
-
-
-	******* Extension of the `apropos' handling
-
-        The output of man's `apropos' has grown immensely meanwhile, so it
-	has become inefficient.  Now `groffer' provides new options to get
-	the a selected information from this output.
-
-	* groffer.sh:
-        `--apropos-progs': new option for displaying only information
-        on programs (man page sections 1, 6, and 8)
-        `--apropos-data': new option for displaying only information
-        on documented data (man page sections 4, 5 and 7)
-        `--apropos-devel': new option for displaying only information
-        on development documentation (man page sections 2, 3 and 9)
-        `--apropos': still displays just the output of man's `apropos'
-	program.
-	- Specify all of these options as a single argument option; that
-	makes groffer's `--apropos' option slightly different because
-	the corresponding `man' option does not have arguments,	but takes
-	all file arguments as apropos targets.  So just ignore the `man'
-	options `-k' and `--apropos' in the parsing of $MANOPT.
-	- Exit after processing one `apropos' call.
-
-
-	******* Quasi object oriented function arguments
-
-	An object is the name of an environment variable.  The value of
-	this variable contains the object's content.  This allows to
-	specify function arguments and the calling syntax in a simpler way
-	by letting the first argument be a variable name, usable for input
-	or output.
-
-	Such an object type is `list', the string value of a shell
-	variable arranged in space-separated single-quoted elements, such
-	as $GROFFER_OPT internally.
-
-	* groffer.sh:
-	- Remove list_from_args(), list_element_from_arg()
-	list_from_lists(), list_length(), and list_prepend().
-	They can be replaced by list_append().
-	- All list*() functions are rearranged such that the first
-	argument is a list object, the name of a variable.
-
-
-	******* Simplification of configuration files
-
-	The new syntax of the groffer configuration files is
-	- all lines starting with a `-' character are interpreted as
-	command line options for all calls of groffer; they are collected
-	and prepended to the actual value of $GROFFER_OPT; optional
-	spaces at the beginning.of the line are omitted.
-	- all other lines are interpreted as a shell command and executed
-	in the current shell of the groffer call.
-
-	Precedence:
-	- The command line and the external environment variables such as
-	$GROFFER_OPT of the groffer call have the highest precedence.
-	- This is overwritten by the configuration file in the user's home
-	directory.
-	- The system configuration file in /etc has the lowest
-	precedence.
-
-	* groffer.sh:
-	The configuration files are now called after the determination of
-	the temporary files in main_init().
-
-
-	******* Script file name
-
-	The file name of the script is needed for the several calls during
-	the search for the optimal shell.
-
-	* groffer.sh:
-	- $_GROFFER_SH: replace $_this by $_GROFFER_SH and use $0 for
-	determining the file name of the script for the following calls,
-	instead of the cumbersome @BINDIR@ construction.
-	- Force the script to be called as an executable file, so $0 must
-	contain the program name.
-
-
-	******* Improved temporary file names
-
-	Just like groff, groffer mixes all file parameters into a single
-	output file.  Its name is now constructed as a comma-separated
-	list built from the file name arguments without a leading comma.
-	So a leading comma can be used for the internal temporary file
-	names.
-
-	* groffer.sh:
-	- $_OUTPUT_FILE_NAME: new global variable as basis for the output
-	file name; it is set in main_set_resources().
-        - tmp_create(): use `,name' for temporary files different from
-	output file because the output file name does not start with a
-	comma.  `$$' is not needed anymore.
-	- main_display(): simplification of $_modefile in _do_display()
-	and single display modes.
-	- Add extension `.html' to output file name in html mode.
-	- base_name(): correction for strange positions of `/'.
-
-
-	******* Mode fixes
-
-	* groffer.sh:
-	- Set the main default mode to `x' with groff's	X Window viewer
-	`gxditview'.
-	- Allow 'x' and 'X' in `--mode' for the X Window mode; the same
-	for `--x' and `X', `--x-viewer' and `--X-viewer'.
-	- Make groff's `-X' equivalent to `mode X'.
-	- Fix `--auto', `--mode auto',  and `--default-modes'.
-	- `html' mode: new mode equivalent to `www', add `konqueror' and
-	`lynx' as viewers.
-	- `pdf' mode: fix zoom options for pdf-viewer `xpdf' in
-	main_set_resources(); in main_display() fix the display structure.
-	- Set default X Window resolution to 75dpi.  This is not optimal,
-	but with a higher value the options and resources for some viewers
-	must be optimized.
-	`--text' and `--mode text': new option for text output without a
-	pager.
-	- `--tty-viewer': new option equivalent to `--pager'.
-	- Correct the pagers for `tty' mode.
-	- Fix `groff' mode in main_set_resources() and main_display().
-	- Harmonize `--mode arg' with the equivalent options `--arg'.
-
-
-	******* Fixes for command line options
-
-	* groffer.sh:
-	- list_from_cmdline(): fix the parsing of options with arguments.
-	- Rename $_OPT_TTY_DEVICE to $_OPT_TEXT_DEVICE.
-	- $_OPTS_X_*: new variables for the inhereted X Window variables.
-	- Improve the distribution of the command line options into
-	$_OPTS_GROFFER_*, $_OPTS_GROFF_*, $_OPTS_X_*, and $_OPTS_MAN_*.
-	- $_OPTS_MANOPT_*: new variables for the parsing of $MANOPT.
-	- Correct $_OPTS_CMDLINE_*.
-	- Remove some unused $_OPTS_*.
-	- `--iconic': new option from `-iconic' of the X Window toolkit.
-	- Correct `--rv' to an option without argument.
-	- Minor fixes of other  X Window toolkit options.
-
-
-	******* Other fixes
-
-	* groffer.sh:
-	- is_prog(): allow 0 arguments.
-	- is_not_writable(): new function.
-	- is_*(): fix trailing return codes.
-        - Replace most `test' calls by is_*() functions.
-	- man_setup(): due to bugs in `manpath', prefer
-	manpath_set_from_path() for the determination of the man page path.
-	- man_search_section(): correction of some `for' loops.
-	- Remove export of external non-groffer variables.
-
-
-	******* Documentation
-
-	* groffer.man:
-	- Reorder the option details according to the option origin as
-	groffer, groff, X, and man options.
-	- Add the programming changes information mentioned above.
-	- Support man pages with a dot in their name
-
-	* README_SH: new file
-	Move large parts of the documentation in `groffer.sh' into this
-	file.
-
-	* groffer.sh: usage():
-	- Change the output for `--help' to standard output.
-	- Restructure the information for this help output.
-
-
-	******* Removement of the author's email address
-
-	Because of the extreme spam attacks, the author removed all
-	occurencies of his email address in every file of the groffer
-	source.
-
-2003-01-22  Bernd Warken <groff-bernd.warken-72@web.de>
-	________________________________________________________________
-	* release of groffer 0.9.4
-
-	* groffer.sh: corrections for some restrictive shells
-	- Possible exit codes in actual `ash' are between 0 and 63.  To
-	handle even deeper restrictions, use 7 as maximal code instead
-	of 255 as replacement for error -1.
-	- Remove variables $_BAD2 and $_BAD3.
-	- Replace `trap' argument `EXIT' by 0 and write new fuctions
-	`trap_clean' and `trap_set' to handle the restrictions of `trap'
-	for some shells.
-	- Correct wrong $MANPATH to $_MAN_PATH in function
-	`man_do_filespec'.
-	- Test existence of directory before deleting it in the
-	`clean_up' definitions.
-	- Correct help output in `usage' (called by `--help').
-
-	* TODO:
-	Remove mention of `shoop' and `apropos'.
-
-2002-10-21  Bernd Warken <groff-bernd.warken-72@web.de>
-	________________________________________________________________
-	* release of groffer 0.9.3
-
-	* groffer.sh: new temporary subdirectory
-	- Generate temporary subdirectory for storing temporary files
-	with better names in future groffer versions (name:
-	"groffer$$" in usual temporary directory).
-	- Use `umask 000' for temporary files to allow cleaning up
-	for everyone after a system break.
-	- Change both clean_up() functions (for normal shell and
-	for main_display() subshell) to handle the new subdirectory.
-	- clean_up_secondary() and $_TMP_PREFIX are unnecessary now, so
-	they were removed.
-
-	* Makefile.sub: `sed' commands for "groffer:"
-	- Remove "@g@" entry (not used in "groffer.sh").
-	- Add global replace for "@BINDIR@" and "@VERSION@" for future
-	usage.
-
-	* TODO: think about...
-	- writing part of groffer in C/C++.
-	- handling several files with different macro packages.
-
-2002-10-17  Bernd Warken <groff-bernd.warken-72@web.de>
-	________________________________________________________________
-	* 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.
-
-2002-10-14  Bernd Warken <groff-bernd.warken-72@web.de>
-
-	* Makefile.sub:
-	add replacement "@BINDIR@" to "$(bindir)" for "groffer:"
-
-	* groffer.sh:
-	Define $_this as "@BINDIR@/${_PROGRAM_NAME}" to save the right
-	installation position of groffer for the special shell calling.
-
-	* groffer.man:
-	Remove double definition of filespec parameters.
-
-2002-10-13  Bernd Warken <groff-bernd.warken-72@web.de>
-	________________________________________________________________
-	* release of groffer 0.9.2
-
-	* groffer.sh: fixes
-	- Fix some 'sed' functions: two in func_stack_dump(), one in
-	  base_name(), add 'sed' command in list_from_cmdline().
-	- Finish main_parse_MANOPT() if $MANOPT is empty.
-	- Sort $_OPTS_GROFF_SHORT_NA like groff short options (but
-	  unchanged).
-	- Fix some comments.
-
-	* groffer.man: make it more readable (but no additions)
-	- A shortened section "SYNOPSIS" is followed by a simplified
-	  section "DESCRIPTION".
-	- The options from "SYNOPSIS" go to new section "OPTION
-	  OVERVIEW" with all groffer options in a single subsection.
-	- The details of all groffer options are described in section
-	  "GROFFER OPTIONS".
-	- New macro for file names ".File_name".
-	- "Option Parsing" is moved to section "COMPATIBILITY".
-	- Fix some "EXAMPLES".
-
-2002-09-30  Bernd Warken <groff-bernd.warken-72@web.de>
-	________________________________________________________________
-	* release of groffer 0.9.1
-
-	* TODO: remove done entries
-	- Remove request for different shells.
-	- Remove the 'sed' complaints.
-
-2002-07-15  Bernd Warken <groff-bernd.warken-72@web.de>
-
-	* groffer.sh: replace `sed' interface by direct `sed'
-	- This improves the performance of the shell programming parts
-	  and shortens the groffer script by about 5%.
-	- Remove functions: string_del_append(), string_del_leading(),
-	  string_del_trailing(), string_flatten(), string_get_before(),
-	  string_get_leading(), string_replace_all(), string_sed_s(),
-	  and their auxiliary functions.
-	- Replace all calls of these functions by direct `sed' commands.
-	- Define variables for special characters to ease `sed' calls.
-	- Remove `$APPEND'.
-	- Restrict list_from_string() to single character separators.
-	- Correct list_check() and base_name().
-	- Add comments to all calls of `sed'.
-
-	* groffer.sh: add run-time support for several shells
-	- New option `--shell': stop execution and rerun groffer under
-	  the shell specified in the argument of `--shell'.
-	- If no shell was specified at run-time, `ash' is tried first;
-	  if `ash' is not available continue with the shell with which
-	  groffer was called from the command line, or with the shell
-	  name in the first line of the script, actually `/bin/sh'.
-
-2002-07-12  Bernd Warken <groff-bernd.warken-72@web.de>
-	________________________________________________________________
-	* fixes for groffer 0.9.0
-
-	* groffer.sh: enhance version information
-	`groffer -v|--version' now print:
-	- groffer's version number and date
-	- the string `is part of '
-	- groff's version information (version number and copyright),
-	  but not groff's `called subprograms' information.
-
-	* groffer.sh: minor fixes
-	- Fix the argument parser to process argument `-' correctly.
-	- Some display programs have trouble with empty input; feed a
-	  line consisting of a single space character in this case for
-	  all display modes (not for source or groff modes).
-
-	* TODO:
-	fix entry `shoop' (not 'shopt').
-
-2002-06-28  Bernd Warken <groff-bernd.warken-72@web.de>
-	________________________________________________________________
-	* release of groffer 0.9.0
-
-	* groffer.sh: new mode `pdf'
-	- PDF (Portable Document Format):
-	  -> Transform groff `ps' output into pdf using `gs'.
-	  -> Pro: PDF viewers provide text searching (!).
-	  -> Con: the transformation is quite slow.
-	  -> Not suitable as an auto mode.
-	- New options `--pdf', `--pdf-viewer', `--mode pdf'.
-	- Standard pdf viewers `xpdf' and `acroread'.
-	- For `xpdf', choose zoom `z 3' for 100 dpi, `z 2' for 75 dpi.
-
-	* groffer.sh: support bzip2 decompression
-	- add test for `bzip2' with necessary options
-	- extend functions `catz()' and `save_stdin()'.
-
-	* TODO
-	remove entry on `bzip' decompression (done).
-
-	* groffer.man:
-	- Document new `pdf' features.
-	- Document new `bzip2' decompression.
-	- Fix documentation for `--auto-modes'.
-
-	* groffer.sh: minor fixes
-	- Improve device tests in `tty' and `dvi' modes.
-	- Internally, map mode `auto' to '' to facilitate tests.
-	- Fix auto mode sequence to: `ps,x,tty' as was intended.
-
-2002-06-25  Bernd Warken <groff-bernd.warken-72@web.de>
-
-	* groffer.sh:
-	Fix `source' mode.
-
-	* groffer.man:
-	Fix some indentations.
-
-2002-06-23  Bernd Warken <groff-bernd.warken-72@web.de>
-	________________________________________________________________
-	* release of groffer 0.8
-
-	* Makefile.sub: add copyright section
-
-	* groffer.man:
-	- Document the new options.
-	- Revise the documentation of the modes.
-	- Document the configuration files in new section `FILES'.
-	- Redesign section `EXAMPLES'.
-	- Remove documentation for `-W'.
-
-	* groffer.sh: new debugging features
-	- Disabled by default; enabled by environment variables.
-	- Add landmark() to catch typos with quotes.
-	- Add a function call stack for suitable functions; implemented
-	  as within the argument checker func_check().
-	- This implies the need to provide `return' with some clean-up
-	  facility; implemented as `eval "$_return_..."'.
-	- Add option `--debug' to enable debugging at run-time.
-	- Actually, the groffer script uses only shell builtins found
-	  in `ash' (a subset of POSIX) and POSIX `sed' as the only
-	  external shell utility.
-
-	* groffer.sh: customization of viewers
-	- In `groff' mode, the groffer viewing facilities are disabled.
-	- The postprocessor option `-P' costumizes the viewer only in
-	  some situations in the `groff' mode, so a new infrastructure
-	  for viewer customization is necessary.
-	- Allow to specify arguments to the viewer programs specified
-	  in `--*-viewer()'.
-	- Implement some of the essential X Toolkit resource options in
-	  groffer, but with use a leading double minus.
-	  -> `--bd': set border color.
-	  -> `--bg', `--background': set background color.
-	  -> `--bw': set border width.
-	  -> `--display': set X display.
-	  -> `--geometry': set size and position of viewer window.
-	  -> `--fg', `--foreground': set foreground color.
-	  -> `--ft', `--font': set font.
-	  -> `--resolution': set X resolution in dpi.
-	  -> `--title': set viewer window title.
-	  -> `--xrm': set X resource.
-	- Remove misnamed option `--xrdb'.
-
-	* groffer.sh: new mode structure
-	- New Postcript mode `ps' (`--ps'):
-	  -> default viewers: gv,ghostview,gs_x11,gs;
-	  -> `--ps-viewer' sets the Postscript viewer.
-	- New mode `www' (`--www') for displaying in a web browser:
-	  -> default browsers: mozilla,netscape,opera,amaya,arena;
-	  -> `--www-viewer' sets the web browser.
-	- New dvi mode (`--dvi'); default viewer `xdvi':
-	  -> default viewers: xdvi,dvilx;
-	  -> `--dvi-viewer' sets the dvi viewer.
-	- New mode `auto':
-	  -> active if no other mode is given or by new option `--auto';
-	  -> selects from a sequence of modes that are tested until one
-	    of them succeeds.
-	  -> the default mode sequence is actually `ps', `x', `tty'.
-	  -> `--default-modes' sets this mode sequence as a comma
-	     separated string of program names, optionally each one
-	     with arguments).
-	- New mode `groff':
-	  -> process input like groff, ignore viewing options.
-	  -> activated by new option `--groff'.
-	  -> automatically active with one of `-V', `-X', `-Z'.
-	- Revise `tty' mode:
-	  -> allow several text devices.
-	  ->
-	- Reorganize the mode management:
-	  -> new mode setting option `--mode'.
-	  -> logically separate source, groff, and display modes.
-	  -> intermediate output mode is now part of mode groff; remove
-	     any special features around `-Z'.
-	- Update usage() to reflect the new option structure.
-
-	* groffer.sh: add configuration files
-	- `/etc/groff/groffer.conf' system-wide configuration.
-	- `${HOME}/.groff/groffer.conf' user configuration.
-	- The configuration file are shell scripts for now; later
-	  implementations can identify this from the `#! /bin/sh' line.
-
-	* groffer.sh: new data structure `list':
-	- Implement a `list' data structure as a string consisting of
-	  single-quoted elements, separated by a space character;
-	  embedded single-quotes are escaped.
-
-	* groffer.sh: new option parser based on `list':
-	- Write new option parser based on `list', compatible to both
-	  POSIX getopts() and GNU getopt().
-	- Long options are now available on GNU and non-GNU systems.
-	- Get rid of POSIX getopts() and GNU getopt().
-	- the `-W--longopt' construct is now obsolete; remove it.
-	- add test/function for `unset'.
-	- Option strings are now implemented as `list's in order to
-	  allow unusual characters in options.
-	- Parse $MANOPT first; translate essential arguments into
-	  groffer options.
-
-	* groffer.man:
-	- determine prompt length for `.Shell_cmd'* dynamically.
-	- naming scheme for static strings and registers changed to
-	  `namespace:macro.variable'.
-
-
-2002-06-16  Werner Lemberg  <wl@gnu.org>
-
-	* groffer.sh:
-	Implement man option `--ascii' by `-mtty-char'.
-
-
-2002-05-31  Werner LEMBERG  <wl@gnu.org>
-
-        * groffer.man (@.Shell_cmd_width):
-	Increase to 4m (we use `sh#' as the prompt).
-
-
-2002-05-31  Bernd Warken <groff-bernd.warken-72@web.de>
-	________________________________________________________________
-	* release of groffer 0.7
-
-	* groffer.sh: remove incompatibilities with the `ash' shell:
-	- do not use `!command':
-          -> use `else'
-	  -> write `_not_' equivalents for some functions
-	- do not use `[^]' in `case':
-	  ->  restructure some functions.
-	- only single-character names for loop variables:
-	  -> spoils the paradigm of leading `_' for local variables.
-	- spurious trouble with `for i in ${var}':
-	  -> use `eval set -- ${var}' and `for i in "$@"'
-	- do not change or use $IFS:
-	  -> define new functions string_split() and `path_split()'.
-	  -> result must be processed by `eval set --'.
-	  -> solve conflicts with existing positional parameters.
-	- trouble with exporting external `$GROFF_*' variables:
-	  -> hope that they were exported in the calling shell.
-	- not smart about additional blanks:
-	  -> remove unnecessary white space.
-
-	* groffer.sh: improve run-time speed:
-	- `ash' more than doubles the speed of `bash'.
-	- speed-up `man_setup()'.
-
-
-2002-05-30  Werner Lemberg  <wl@gnu.org>
-
-	* groffer.man:
-	- remove some wrong `\:'.
-	- rename macro names that start with a `[' (clashes with refer).
-	- fix TP_header.
-
-
-2002-05-28  Bernd Warken <groff-bernd.warken-72@web.de>
-	________________________________________________________________
-	* release of groffer 0.6
-
-	This is almost a complete rewrite since groffer 0.5 .
-	________________________________________________________________
-	* Documentation
-
-	* groffer.man:
-   	- Apply the changes done in www.tmac (.URL and .MTO)
-	- Replace \fP by \f[].
-	- Redesign and rewrite most macros.
-	- Include the documentation for the new features.
-	- Greatly enlarge section ENVIRONMENT
-	- Add examples.
-
-	* TODO:
-	- Start a TODO file with several sections.
-
-	* ChangeLog:
-	Due to the many changes, shorten and rearrange the entries
-	since groffer 0.5 .
-	________________________________________________________________
-	* Shell compatibility
-
-	* groffer.sh:
-	- Due to possible conflicts in old BSD versions, `[]' was
-	  replaced by `test'; the `test' options `-a' and `-o' were
-	  replaced by multiple calls of `test'.
-	- Write interface to the `sed' command `s' to become
-	  independent of the delimiter character.  Rewrite all text
-	  manipulating function to use this new scheme.  The new
-	  functions are named `string_*'.
-	- `tr' is not needed any longer, replaced by `sed'.
-	- `grep' is not needed any longer, mostly replaced by `case'.
-	- Revision of test for `getopt'.
-	- Remove `set -a'; explicitly export variables.
-	- The only external programs used are POSIX `sed' and the
-	  fallback to `apropos'.  All other program calls were
-	  replaced by shell builtins and functions.
-
-	________________________________________________________________
-	* Cosmetics
-
-	* groffer.sh:
-	- Implement a prefix based naming scheme for local variables
-	  and functions (OOP-like).
-	- Introduce variables for white space (better readability with
-	  $IFS).
-	- Store the names of the processed filespecs into a variable
-	  instead of a temporary file.
-	- Error-prone shell constructions were replaced by functions
-	  with a simple interface.
-	- To avoid too long pipes, replace supercat() by do_fileargs();
-	  every input file is handled independently.
-
-	________________________________________________________________
-	* New features:
-	- Add support for more X devices (e.g. X75-12 and X100-12).
-	- Add long option `--intermediate_output' to `-Z'.
-	- Make the options for mode selection clobber each other.
-	- Add option `--mode' with an argument having the following
-	  values:
-	  `X': force displaying in X, same as options `-X';
-	  `tty': display with a pager on text terminal; same as `--tty';
-	  `source', `default', `auto', etc.
-	- Make the handling of the X mode like in groff (e.g. -X -Tps).
-	- Make resolution for gxditview behave like groff (default
-	  75 dpi).
-	- Add environment variable $GROFFER_OPT to preset groffer
-	  options.
-
-	________________________________________________________________
-	* implement most of the functionality of GNU `man'.
-
-	- Add all `man' long options to groffer.
-	- Add all `man' environment variables.
-	- Parse and use content of `$MANOPT'.
-	- The precedence of the options and environment variables
-	  is regulated like in GNU `man'.
-	- Force the option `--manpath' to have a colon-separated
-	  argument like GNU `man'.
-	- Support `man section name' calling convention.
-	- Remove all dependencies on `man -w'.
-
-	* groffer.sh:
-	- Add the new features above.
-	- Rewrite the search algorithm for man pages.
-	- Remove searching with `man -w' (problems with space
-	  characters in file names).
-	- Fix and complement usage().
-	- The filespec parsers gets a function of its own do_manpage().
-
-
-2002-01-08  Bernd Warken <groff-bernd.warken-72@web.de>
-
-	* groffer 0.5 (beta) released
-
-	* groffer.man:
-	- Fix hyphenation problems with macros describing options.
-	- Fix the handling of some `-' characters.
-	- Examples of shell commands now print in font CR instead of CB.
-	- Remove documentation for option `-X'.
-	- Add documentation for option `--dpi'.
-
-	* groffer.sh:
-	- New method for creating temporary files, based on process
-	  IDs.  This is reliable enough and suitable for GNU and POSIX.
-	- Run gxditview in a new shell instantiation for having a clean
-    	  handling of the temporary files when running in the
-	  background.
-	- Revision of the retrieving method for the window title.
-	- Empty input is now tolerated.
-	- Export the variables that are set before the call of `set -a'.
-	- Function usage() corrected and updated.
-	- Unnecessary stuff removed.
-	- Comments adjusted.
-	- Pass option `-X' to groff, i.e. force X output with 75 dpi.
-	- Implement option `--dpi' for setting the resolution for the X
-	  viewer, which had already been documented in earlier versions.
-
-2002-01-07  Bernd Warken <groff-bernd.warken-72@web.de> 
-
-	* groffer 0.4 (beta) released (as groff `contrib')
-
-	* groffer.man:
-	- New features documented.
-	- Macros stream-lined.
-	- Section EXAMPLES added.
-
-	* groffer.sh:
-	- System tests added/optimized.
-	- Speed/memory optimizations by defining some shell functions
-	  alternatively depending on the text results.
-	- Use `gzip' for decompression instead of `zcat'.
-	- Signal handling added for clean exiting by `trap'.
-	- Temporary files exist only as long as necessary.
-	- Setup of path for man-pages moved after the option parsing.
-	- Fixed a bug in determining the path for man-pages.
-	- Fixed a bug in the handling of non-groffer options.
-
-	* New features:
-	- New option --tty for forcing paging on text terminal.
-	- New option --no-man for disabling the man-page feature.
-	- Implement reserved POSIX -W feature to simulate long options.
-	- gxditview is now run as a background process.
-
-2002-01-05  Werner LEMBERG  <wl@gnu.org>
-
-        * Integrate groffer into groff's `contrib' tree.
-
-        * Makefile: Replaced by...
-        Makefile.sub: New file.
-
-        * groffer: Replaced by...
-        groffer.sh: New file.
-
-        * groffer.man (OptDef): Add missing backslashes.
-        Update copyright.
-
-2001-12-15  Bernd Warken <groff-bernd.warken-72@web.de>
-
-	* groffer 0.3 (alpha) released (still stand-alone package).
-
-	* GNU and POSIX are supported (POSIX without long options).
-
-	* New options : --man, --mandb, --title, --xrdb
-
-	* Support for command line arguments with embedded single space
-	characters (GNU only) .
-
-	* Several search methods for man-pages when no `man -w' is
-	available ($MANPATH, mandb, a default path).
-
-	* Language support for man-pages.
-
-	* Recognize the following filespecs as man-page parameters:
-	  man:name(section), man:name, name.section, name.
-
-2001-12-03  Bernd Warken <groff-bernd.warken-72@web.de>
-
-	* Stand-alone package for groffer 0.2 (alpha) created
-	Files: groffer, groffer.man, Makefile, TODO, ChangeLog
-
-2001-12-02  Bernd Warken <groff-bernd.warken-72@web.de>
-
-	* groffer 0.2 (alpha) program released.
-
-	* Name changed from `groffview' to `groffer'.
-
-	* Comments added.
-
-	* Name changed from `groffview' to `groffer'.
-
-	* Options harmonized with groff.
-	New options : -Q --source, -T --device, -X .
-	Other options known from groff are passed unchanged.
-
-	* 100 dpi as default, 75 dpi only in emergency situations.
-
-	* Bugs with temporary files fixed.
-
-	* Code restructured and comments added.
-
-2001-11-28  Bernd Warken <groff-bernd.warken-72@web.de>
-
-	***** groffview 0.1 (experimental) and groffview.man released
-	(predecessor of groffer, shell script)
-
-	* Options : -h --help, -v --version
-
-	* Search for man-pages based on $MANPATH
-
-	* development of `groffview' shell script started
-
-2001-11-28  Bernd Warken <groff-bernd.warken-72@web.de>
-
-	________________________________________________________________
-	License
-
-	Copyright (C) 2001,2002,2003,2004,2005,2006
-	Free Software Foundation, Inc.
-	Written by Bernd Warken <groff-bernd.warken-72@web.de>.
-
-	Copying and distribution of this file, with or without
-	modification, are permitted provided the copyright notice and this
-	notice are preserved.
-
-	This file is part of `groffer', which is part of the `groff'
-	project.
-
-
-	Emacs settings
-
-	Local Variables:
-	mode: change-log
-	End:

Index: groffer/shell/README_SH
===================================================================
RCS file: groffer/shell/README_SH
diff -N groffer/shell/README_SH
--- groffer/shell/README_SH	1 Feb 2013 08:12:27 -0000	1.7
+++ /dev/null	1 Jan 1970 00:00:00 -0000
@@ -1,297 +0,0 @@
-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 function in groffer2.sh has a description that starts with the
-function name and symbols for its arguments in parentheses `()'.  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 on 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.
-
-For shell compatibility, see also Autobook, chapter 22.
-
-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: 7 Feb 2011
-
-Copyright (C) 2003-2006, 2009, 2011
-  Free Software Foundation, Inc.
-Written by Bernd Warken <groff-bernd.warken-72@web.de>
-
-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:

Index: groffer/shell/groffer.man
===================================================================
RCS file: groffer/shell/groffer.man
diff -N groffer/shell/groffer.man
--- groffer/shell/groffer.man	1 Feb 2013 08:12:27 -0000	1.18
+++ /dev/null	1 Jan 1970 00:00:00 -0000
@@ -1,4124 +0,0 @@
-.TH GROFFER @MAN1EXT@ "@MDATE@" "Groff Version @VERSION@"
-.SH NAME
-groffer \- display groff files and man\~pages on X and tty
-.
-.SH "SYNOPSIS"
-.\" The .SH was moved to this place in order to appease `apropos'.
-.
-.\" --------------------------------------------------------------------
-.\" Legalese
-.\" --------------------------------------------------------------------
-.
-.de author
-This file was written by Bernd Warken <groff-bernd.warken-72@web.de>.
-..
-.de copyleft
-Copyright (C) 2001, 2002, 2004-2012
- Free Software Foundation, Inc.
-.
-.P
-This file is part of
-.IR \%groffer ,
-which is part of
-.IR \%groff ,
-a free software project.
-.
-You can redistribute it and/or modify it under the terms of the
-.nh
-.B GNU General Public License
-.hy
-as published by the
-.nh
-.BR "Free Software Foundation" ,
-.hy
-either version 3 of the License, or (at your option) any later version.
-.
-.P
-You should have received a copy of the \f[CR]GNU General Public
-License\f[] along with
-.IR groff ,
-see the files \%\f[CB]COPYING\f[] and \%\f[CB]LICENSE\f[] in the top
-directory of the
-.I groff
-source package.
-.
-Or read the
-.I man\~page
-.BR gpl (1).
-You can also visit
-.nh
-.B <http://www.gnu.org/licenses/>.
-.hy
-..
-.
-.\" --------------------------------------------------------------------
-.\" Setup
-.\" --------------------------------------------------------------------
-.
-.ds Ellipsis "\&.\|.\|.\&\"
-.
-.\" --------------------------------------------------------------------
-.\" Macro definitions
-.
-.\" --------------------------------------------------------------------
-.\" .CB  (<text>...)
-.\"
-.\" Print in constant-width bold font.
-.\"
-.de CB
-.  ft CB
-.  Text \\$*
-.  ft
-..
-.\" --------------------------------------------------------------------
-.\" .CI  (<text>...)
-.\"
-.\" Print in constant-width italic font.
-.\"
-.de CI
-.  ft CI
-.  Text \\$*
-.  ft
-..
-.\" --------------------------------------------------------------------
-.\" .CR  (<text>...)
-.\"
-.\" Print in constant-width roman font.
-.\"
-.de CR
-.  ft CR
-.  Text \\$*
-.  ft
-..
-.\" --------------------------------------------------------------------
-.\" .Error  (<text>...)
-.\"
-.\" Print error message to terminal and abort.
-.\"
-.de Error
-.  tm \\$*
-.  ab
-..
-.\" --------------------------------------------------------------------
-.\" .Env_var  (<env_var_name> [<punct>])
-.\"
-.\" Display an environment variable, with optional punctuation.
-.\"
-.de Env_var
-.  nh
-.  SM
-.  Text \f[CB]\\$1\f[]\\$2
-.  hy
-..
-.\" --------------------------------------------------------------------
-.\" .File_name  (<path_name>)
-.\"
-.\" Display a file or directory name in CB font.
-.\"
-.de File_name
-.  Header_CB \\$@
-..
-.\" --------------------------------------------------------------------
-.\" .Header_CB  (<path_name>)
-.\"
-.\" Display a line in CB font, for example after .TP
-.\"
-.de Header_CB
-.  nh
-.  Text \f[CB]\\$1\f[]\\$2
-.  hy
-..
-.\"  --------------------------------------------------------------------
-.\" .Text  (<text>...)
-.\"
-.\" Treat the arguments as text, no matter how they look.
-.\"
-.de Text
-.  if \\n[.$]=0 \
-.    return
-.  nh
-.  nop \)\\$*\)
-.  hy
-..
-.\" --------------------------------------------------------------------
-.\" .Topic  ([<indent>])
-.\"
-.\" A bulleted paragraph
-.\"
-.de Topic
-.  ie \\n[.$]=0 \
-.    ds @indent 2m\"
-.  el \
-.    ds @indent \\$1\"
-.  IP \[bu] \\*[@indent]
-.  rm @indent
-..
-
-.\" End of macro definitions
-.
-.
-.\" --------------------------------------------------------------------
-.\" SH "SYNOPSIS"
-.\" --------------------------------------------------------------------
-.
-.SY groffer
-.OP option \*[Ellipsis]
-.OP --
-.OP \%filespec \*[Ellipsis]
-.YS
-.
-.SY groffer
-.BR -h | --help
-.YS
-.
-.SY groffer
-.BR -v | --version
-.YS
-.
-.
-.\" --------------------------------------------------------------------
-.SH DESCRIPTION
-.\" --------------------------------------------------------------------
-.
-The
-.B \%groffer
-program is the easiest way to use
-.BR \%groff (@MAN1EXT@).
-It can display arbitrary documents written in the
-.I \%groff
-language, see
-.BR \%groff (@MAN7EXT@),
-or other
-.I \%roff
-languages, see
-.BR \%roff (@MAN7EXT@),
-that are compatible to the original
-.I \%troff
-language.
-.
-It finds and runs all necessary
-.I groff
-preprocessors, such as
-.BR @g@chem .
-.
-.
-.P
-The
-.B \%groffer
-program also includes many of the features for finding and displaying
-the \%\f[CR]Unix\f[] manual pages
-.nh
-.RI ( man\~pages ),
-.hy
-such that it can be used as a replacement for a
-.BR \%man (1)
-program.
-.
-Moreover, compressed files that can be handled by
-.BR \%gzip (1)
-or
-.BR \%bzip2 (1)
-are decompressed on-the-fly.
-.
-.
-.P
-The normal usage is quite simple by supplying a file name or name of a
-.I \%man\~page
-without further options.
-.
-But the option handling has many possibilities for creating special
-behaviors.
-.
-This can be done either in configuration files, with the shell
-environment variable
-.Env_var \%$GROFFER_OPT ,
-or on the command line.
-.
-.
-.P
-The output can be generated and viewed in several different ways
-available for
-.IR \%groff .
-.
-This includes the
-.I \%groff
-native \%\f[CR]X\~Window\f[] viewer
-.BR \%gxditview (@MAN1EXT@),
-each
-.IR \%Postcript ,
-.IR \%pdf ,
-or
-.I \%dvi
-display program, a web browser by generating
-.I \%html
-in
-.IR \%www\~mode ,
-or several
-.I \%text\~modes
-in text terminals.
-.
-.
-.P
-Most of the options that must be named when running
-.B \%groff
-directly are determined automatically for
-.BR \%groffer ,
-due to the internal usage of the
-.BR \%grog (@MAN1EXT@)
-program.
-.
-But all parts can also be controlled manually by arguments.
-.
-.
-.P
-Several file names can be specified on the command line arguments.
-.
-They are transformed into a single document in the normal way of
-.BR \%groff .
-.
-.
-.P
-Option handling is done in \f[CR]GNU\f[] style.
-.
-Options and file names can be mixed freely.
-.
-The option
-.RB ` \-\- '
-closes the option handling, all following arguments are treated as
-file names.
-.
-Long options can be abbreviated in several ways.
-.
-.
-.\" --------------------------------------------------------------------
-.SH "OPTION OVERVIEW"
-.\" --------------------------------------------------------------------
-.
-.TP
-.I breaking options
-.RS
-.P
-.SY
-.OP -h\~\fR|\fB\~--help
-.OP -v\~\fR|\fB\~--version
-.YS
-.RE
-.
-.
-.TP
-.I \%groffer mode options
-.RS
-.P
-.SY
-.OP --auto
-.OP --default
-.OP --default\-modes mode1,mode2,\*[Ellipsis]
-.OP --dvi
-.OP --dvi\-viewer prog
-.OP --groff
-.OP --html
-.OP --html\-viewer prog
-.OP --mode display_mode
-.OP --pdf
-.OP --pdf\-viewer prog
-.OP --ps
-.OP --ps\-viewer prog
-.OP --source
-.OP --text
-.OP --to\-stdout
-.OP --tty
-.OP --tty\-viewer prog
-.OP --www
-.OP --www\-viewer prog
-.OP --x\~\fR|\fB\~--X
-.OP --x\-viewer\~\fR|\fB\~--X\-viewer prog
-.YS
-.RE
-.
-.
-.TP
-.I options related to \%groff
-.RS
-.P
-.SY
-.OP -T\~\fR|\fB\~--device device
-.OP -Z\~\fR|\fB\~--intermediate\-output\~\fR|\fB\~--ditroff
-.YS
-.P
-All further
-.B \%groff
-short options are accepted.
-.RE
-.
-.
-.TP
-.I options for man\~pages
-.RS
-.P
-.SY
-.OP --apropos
-.OP --apropos\-data
-.OP --apropos\-devel
-.OP --apropos\-progs
-.OP --man
-.OP --no\-man
-.OP --no\-special
-.OP --whatis
-.YS
-.RE
-.
-.
-.TP
-.I long options taken over from GNU man
-.RS
-.P
-.SY
-.OP --all
-.OP --ascii
-.OP --ditroff
-.OP --extension suffix
-.OP --locale language
-.OP --local\-file
-.OP --location\~\fR|\fB\~--where
-.OP --manpath dir1:dir2:\*[Ellipsis]
-.OP --no\-location
-.OP --pager program
-.OP --sections sec1:sec2:\*[Ellipsis]
-.OP --systems sys1,sys2,\*[Ellipsis]
-.OP --troff\-device device
-.YS
-.P
-Further long options of \f[CR]GNU\f[]
-.B man
-are accepted as well.
-.RE
-.
-.
-.TP
-.I X Window Toolkit options
-.RS
-.P
-.SY
-.OP --bd\~\fR|\fB\~--bordercolor pixels
-.OP --bg\~\fR|\fB\~--background color
-.OP --bw\~\fR|\fB\~--borderwidth pixels
-.OP --display X-display
-.OP --fg\~\fR|\fB\~--foreground color
-.OP --fn\~\fR|\fB\~--ft\~\fR|\fB\~--font font_name
-.OP --geometry size_pos
-.OP --resolution value
-.OP --rv
-.OP --title string
-.OP --xrm X\-resource
-.YS
-.RE
-.
-.
-.TP
-.I options for development
-.RS
-.P
-.SY
-.OP --debug
-.OP --debug\-all
-.OP --debug\-filenames
-.OP --debug\-func
-.OP --debug\-grog
-.OP --debug\-keep
-.OP --debug\-lm
-.OP --debug\-params
-.OP --debug\-shell
-.OP --debug\-stacks
-.OP --debug\-tmpdir
-.OP --debug\-user
-.OP --do\-nothing
-.OP --print text
-.OP --shell prog
-.OP -V
-.YS
-.RE
-.
-.
-.TP
-.I \%filespec arguments
-.RS
-.P
-The
-.I \%filespec
-parameters are all arguments that are neither an option nor an option
-argument.
-.
-They usually mean a file name or a
-.I man page
-searching scheme.
-.
-.
-.P
-In the following, the term
-.I section_extension
-is used.
-.
-It means a word that consists of a
-.I man section
-that is optionally followed by an
-.IR extension .
-.
-The name of a
-.I man section
-is a single character from
-.BR \%[1-9on] ,
-the
-.I extension
-is some word.
-.
-The
-.I extension
-is mostly lacking.
-.
-.
-.P
-No
-.I \%filespec
-parameters means standard input.
-.
-.
-.TP 10m
-.B -
-stands for standard input (can occur several times).
-.
-.
-.TP
-.I filename
-the path name of an existing file.
-.
-.
-.TP
-.BI man: name ( section_extension )
-.TQ
-.BI man: name . section_extension
-.TQ
-.IB name ( section_extension )
-.TQ
-.IB name . section_extension
-.TQ
-.I "section_extension name"
-search the \%man\~page
-.I \%name
-in the section with optional extension
-.IR section_extension .
-.
-.
-.TP
-.BI man: name
-\%man\~page in the lowest
-.I \%man\~section
-that has
-.IR \%name .
-.
-.
-.TP
-.I name
-if
-.I \%name
-is not an existing file search for the man\~page
-.I \%name
-in the lowest man\~section.
-.
-.RE
-.
-.
-.\" --------------------------------------------------------------------
-.SH "OPTION DETAILS"
-.\" --------------------------------------------------------------------
-.
-The
-.B \%groffer
-program can usually be run with very few options.
-.
-But for special purposes, it supports many options.
-.
-These can be classified in 5 option classes.
-.
-.
-.P
-All short options of
-.B \%groffer
-are compatible with the short options of
-.BR \%groff (@MAN1EXT@).
-.
-All long options of
-.B \%groffer
-are compatible with the long options of
-.BR \%man (1).
-.
-.
-.P
-Arguments for long option names can be abbreviated in several ways.
-.
-First, the argument is checked whether it can be prolonged as is.
-.
-Furthermore, each minus sign
-.B -
-is considered as a starting point for a new abbreviation.
-.
-This leads to a set of multiple abbreviations for a single argument.
-.
-For example,
-.B --de\-n\-f
-can be used as an abbreviation for
-.BR --debug\-not\-func ,
-but
-.B --de\-n
-works as well.
-.
-If the abbreviation of the argument leads to several resulting options
-an error is raised.
-.
-.
-.P
-These abbreviations are only allowed in the environment variable
-.Env_var \%$GROFFER_OPT ,
-but not in the configuration files.
-.
-In configuration, all long options must be exact.
-.
-.
-.\" --------------------------------------------------------------------
-.SS "groffer breaking Options"
-.\" --------------------------------------------------------------------
-.
-As soon as one of these options is found on the command line it is
-executed, printed to standard output, and the running
-.B \%groffer
-is terminated thereafter.
-.
-All other arguments are ignored.
-.
-.
-.TP
-.B -h\~\fR|\fB\~--help
-Print help information with a short explanation of options to
-standard output.
-.
-.
-.TP
-.B -v\~\fR|\fB\~--version
-Print version information to standard output.
-.
-.
-.\" --------------------------------------------------------------------
-.SS "groffer Mode Options"
-.\" --------------------------------------------------------------------
-.
-The display mode and the viewer programs are determined by these
-options.
-.
-If none of these mode and viewer options is specified
-.B \%groffer
-tries to find a suitable display mode automatically.
-.
-The default modes are
-.IR "mode pdf" ,
-.IR "mode ps" ,
-.IR "mode html" ,
-.IR "mode x" ,
-and
-.I "mode dvi"
-in \%\f[CR]X\~Window\f[] with different viewers and
-.I mode tty
-with device
-.I latin1
-under
-.B less
-on a terminal; other modes are tested if the programs for the main
-default mode do not exist.
-.
-.
-.P
-In \%\f[CR]X\~Window\f[],
-many programs create their own window when called.
-.B \%groffer
-can run these viewers as an independent program in the background.
-.
-As this does not work in text mode on a terminal (tty) there must be a
-way to know which viewers are \%\f[CR]X\~Window\f[] graphical
-programs.
-.
-The
-.B \%groffer
-script has a small set of information on some viewer names.
-.
-If a viewer argument of the command\-line chooses an element that is
-kept as \%\f[CR]X\~Window\f[] program in this list it is treated as a
-viewer that can run in the background.
-.
-All other, unknown viewer calls are not run in the background.
-.
-.
-.P
-For each mode, you are free to choose whatever viewer you want.
-.
-That need not be some graphical viewer suitable for this mode.
-.
-There is a chance to view the output source; for example, the
-combination of the options
-.B --mode=ps
-and
-.B --ps\-viewer=less
-shows the content of the
-.I Postscript
-output, the source code, with the pager
-.BR less .
-.
-.
-.TP
-.B --auto
-Equivalent to
-.BR --mode=auto .
-.
-.
-.TP
-.B --default
-Reset all configuration from previously processed command line options
-to the default values.
-.
-This is useful to wipe out all former options of the configuration, in
-.Env_var \%$GROFFER_OPT ,
-and restart option processing using only the rest of the command line.
-.
-.
-.TP
-.BI --default\-modes \ mode1,mode2,\*[Ellipsis]
-Set the sequence of modes for
-.I \%auto\~mode
-to the comma separated list given in the argument.
-.
-See
-.B --mode
-for details on modes.  Display in the default manner; actually, this
-means to try the modes
-.IR x ,
-.IR ps ,
-and
-.I \%tty
-in this sequence.
-.
-.
-.
-.TP
-.B --dvi
-Equivalent to
-.BR --mode=\%dvi .
-.
-.
-.TP
-.BI --dvi\-viewer \ prog
-Choose a viewer program for
-.IR \%dvi\~mode .
-.
-This can be a file name or a program to be searched in
-.Env_var $PATH .
-.
-Known \%\f[CR]X\~Window\f[]
-.I \%dvi
-viewers include
-.BR \%xdvi (1)
-and
-.BR \%dvilx (1).
-.
-In each case, arguments can be provided additionally.
-.
-.
-.TP
-.B --groff
-Equivalent to
-.BR --mode=groff .
-.
-.
-.TP
-.B --html
-Equivalent to
-.BR --mode=html .
-.
-.
-.TP
-.B --html\-viewer
-Choose a web browser program for viewing in
-.IR \%html\~mode .
-.
-It can be the path name of an executable file or a program in
-.Env_var $PATH .
-.
-In each case, arguments can be provided additionally.
-.
-.
-.TP
-.BI --mode \ value
-.
-Set the display mode.
-.
-The following mode values are recognized:
-.
-.RS
-.
-.TP
-.Header_CB auto
-Select the automatic determination of the display mode.
-.
-The sequence of modes that are tried can be set with the
-.B --default\-modes
-option.
-.
-Useful for restoring the
-.I \%default\~mode
-when a different mode was specified before.
-.
-.
-.TP
-.Header_CB dvi
-Display formatted input in a
-.I \%dvi
-viewer program.
-.
-By default, the formatted input is displayed with the
-.BR \%xdvi (1)
-program.
-.
-.
-.TP
-.Header_CB groff
-After the file determination, switch
-.B \%groffer
-to process the input like
-.BR \%groff (@MAN1EXT@)
-would do.
-.
-This disables the
-.I \%groffer
-viewing features.
-.
-.
-.TP
-.Header_CB html
-Translate the input into html format and display the result in a web
-browser program.
-.
-By default, the existence of a sequence of standard web browsers is
-tested, starting with
-.BR \%konqueror (1)
-and
-.BR \%mozilla (1).
-The text html viewer is
-.BR \%lynx (1).
-.
-.
-.TP
-.Header_CB pdf
-Display formatted input in a
-.I \%PDF
-(Portable Document Format) viewer
-program.
-.
-By default, the input is formatted by
-.B \%groff
-using the Postscript device, then it is transformed into the PDF file
-format using
-.BR \%gs (1),
-or
-.BR ps2pdf (1).
-If that's not possible, the
-.I Postscript mode (ps)
-is used instead.
-.
-Finally it is displayed using different viewer programs.
-.
-.I \%pdf
-has a big advantage because the text is displayed graphically and
-is searchable as well.
-.
-.
-.TP
-.Header_CB ps
-Display formatted input in a Postscript viewer program.
-.
-By default, the formatted input is displayed in one of many viewer
-programs.
-.
-.
-.TP
-.Header_CB text
-Format in a
-.I \%groff\~text\~mode
-and write the result to standard output without a pager or viewer
-program.
-.
-The text device,
-.I \%latin1
-by default, can be chosen with option
-.BR -T .
-.
-.
-.TP
-.Header_CB tty
-Format in a
-.I \%groff\~text\~mode
-and write the result to standard output using a text pager program,
-even when in \%\f[CR]X\~Window\f[].
-.
-.
-.TP
-.Header_CB www
-Equivalent to
-.BR --mode=html .
-.
-.
-.TP
-.Header_CB x
-Display the formatted input in a native
-.I roff
-viewer.
-.
-By default, the formatted input is displayed with the
-.BR \%gxditview (@MAN1EXT@)
-program being distributed together with
-.BR \%groff .
-But the standard \%\f[CR]X\~Window\f[] tool
-.BR \%xditview (1)
-can also be chosen with the option
-.BR --x\-viewer .
-The default resolution is
-.BR 75dpi ,
-but
-.B 100dpi
-are also possible.
-.
-The default
-.I groff
-device
-for the resolution of
-.B 75dpi
-is
-.BR X75\-12 ,
-for
-.B 100dpi
-it is
-.BR X100 .
-.
-The corresponding
-.I "groff intermediate output"
-for the actual device is generated and the result is displayed.
-.
-For a resolution of
-.BR 100dpi ,
-the default width of the geometry of the display program is chosen to
-.BR 850dpi .
-.
-.
-.TP
-.Header_CB X
-Equivalent to
-.BR --mode=x .
-.
-.
-.P
-The following modes do not use the
-.I \%groffer
-viewing features.
-.
-They are only interesting for advanced applications.
-.
-.
-.TP
-.Header_CB groff
-Generate device output with plain
-.I \%groff
-without using the special viewing features of
-.IR \%groffer .
-If no device was specified by option
-.B -T
-the
-.I \%groff
-default
-.B \%ps
-is assumed.
-.
-.
-.TP
-.Header_CB source
-Output the roff source code of the input files without further
-processing.
-.
-.
-.RE
-.
-.
-.TP
-.B --pdf
-Equivalent to
-.BR --mode=pdf .
-.
-.
-.TP
-.BI --pdf\-viewer \ prog
-Choose a viewer program for
-.IR \%pdf\~mode .
-.
-This can be a file name or a program to be searched in
-.Env_var $PATH ;
-arguments can be provided additionally.
-.
-.
-.TP
-.B --ps
-Equivalent to
-.BR --mode=ps .
-.
-.
-.TP
-.BI --ps\-viewer \ prog
-Choose a viewer program for
-.IR \%ps\~mode .
-.
-This can be a file name or a program to be searched in
-.Env_var $PATH .
-.
-Common Postscript viewers include
-.BR \%gv (1),
-.BR \%ghostview (1),
-and
-.BR \%gs (1),
-.
-In each case, arguments can be provided additionally.
-.
-.
-.TP
-.B --source
-Equivalent to
-.BR --mode=source .
-.
-.
-.TP
-.B --text
-Equivalent to
-.BR --mode=text .
-.
-.
-.TP
-.B --to\-stdout
-The file for the chosen mode is generated and its content is printed
-to standard output.
-.
-It will not be displayed in graphical mode.
-.
-.
-.TP
-.B --tty
-Equivalent to
-.BR --mode=tty .
-.
-.
-.TP
-.BI --tty\-viewer \ prog
-Choose a text pager for mode
-.IR tty .
-The standard pager is
-.BR less (1).
-This option is equivalent to
-.I man
-option
-.BR --pager=\fIprog\fP .
-The option argument can be a file name or a program to be searched in
-.Env_var $PATH ;
-arguments can be provided additionally.
-.
-.
-.TP
-.B --www
-Equivalent to
-.BR --mode=html .
-.
-.
-.TP
-.BI --www\-viewer \ prog
-Equivalent to
-.BR --html\-viewer .
-.
-.
-.TP
-.B --X\~\fR|\fB\~--x
-Equivalent to
-.BR --mode=x .
-.
-.
-.TP
-.BI --X\-viewer\~\fR|\fB\~--x\-viewer \ prog
-Choose a viewer program for
-.IR \%x\~mode .
-Suitable viewer programs are
-.BR \%gxditview (@MAN1EXT@)
-which is the default and
-.BR \%xditview (1).
-The argument can be any executable file or a program in
-.Env_var $PATH ;
-arguments can be provided additionally.
-.
-.
-.TP
-.B --
-Signals the end of option processing; all remaining arguments are
-interpreted as
-.I \%filespec
-parameters.
-.
-.
-.P
-Besides these,
-.B \%groffer
-accepts all short options that are valid for the
-.BR \%groff (@MAN1EXT@)
-program.
-.
-All
-.RB \%non- groffer
-options are sent unmodified via
-.B \%grog
-to
-.BR \%groff .
-.
-So postprocessors, macro packages, compatibility with
-.I classical
-.IR \%troff ,
-and much more can be manually specified.
-.
-.
-.\" --------------------------------------------------------------------
-.SS "Options related to groff"
-.\" --------------------------------------------------------------------
-.
-All short options of
-.B \%groffer
-are compatible with the short options of
-.BR \%groff (@MAN1EXT@).
-.
-The following of
-.B \%groff
-options have either an additional special meaning within
-.B \%groffer
-or make sense for normal usage.
-.
-.
-.P
-Because of the special outputting behavior of the
-.B \%groff
-option
-.B -Z
-.B \%groffer
-was designed to be switched into
-.IR \%groff\~mode ;
-the
-.I \%groffer
-viewing features are disabled there.
-.
-The other
-.B \%groff
-options do not switch the mode, but allow to customize the formatting
-process.
-.
-.
-.TP
-.B --a
-This generates an ascii approximation of output in the
-.IR \%text\~modes .
-.
-That could be important when the text pager has problems with control
-sequences in
-.IR "tty mode" .
-.
-.
-.TP
-.BI --m \ file
-Add
-.I \%file
-as a
-.I \%groff
-macro file.
-.
-This is useful in case it cannot be recognized automatically.
-.
-.
-.TP
-.BI --P \ opt_or_arg
-Send the argument
-.I \%opt_or_arg
-as an option or option argument to the actual
-.B \%groff
-postprocessor.
-.
-.
-.TP
-.B --T \fIdevname\fR\~\fR|\fB\~--device \fIdevname\fR
-.
-This option determines
-.BR \%groff 's
-output device.
-.
-The most important devices are the text output devices for referring
-to the different character sets, such as
-.BR \%ascii ,
-.BR \%utf8 ,
-.BR \%latin1 ,
-and others.
-.
-Each of these arguments switches
-.B \%groffer
-into a
-.I \%text\~mode
-using this device, to
-.I \%mode\~tty
-if the actual mode is not a
-.IR \%text\~mode .
-.
-The following
-.I \%devname
-arguments are mapped to the corresponding
-.B \%groffer
-.B --mode=\fIdevname\fR
-option:
-.BR \%dvi ,
-.BR \%html ,
-and
-.BR \%ps .
-All
-.B \%X*
-arguments are mapped to
-.IR \%mode\~x .
-Each other
-.I \%devname
-argument switches to
-.I \%mode\~groff
-using this device.
-.
-.
-.TP
-.B --X
-is equivalent to
-.BR "groff \-X" .
-It displays the
-.I groff intermediate output
-with
-.BR gxditview .
-As the quality is relatively bad this option is deprecated; use
-.B --X
-instead because the
-.I \%x\~mode
-uses an
-.IR X *
-device for a better display.
-.
-.
-.TP
-.B -Z\~\fR|\fB\~--intermediate-output\~\fR|\fB\~--ditroff
-Switch into
-.I \%groff\~mode
-and format the input with the
-.I \%groff intermediate output
-without postprocessing; see
-.BR \%groff_out (@MAN5EXT@).
-This is equivalent to option
-.B --ditroff
-of
-.IR \%man ,
-which can be used as well.
-.
-.
-.P
-All other
-.B \%groff
-options are supported by
-.BR \%groffer ,
-but they are just transparently transferred to
-.B \%groff
-without any intervention.
-.
-The options that are not explicitly handled by
-.B \%groffer
-are transparently passed to
-.BR \%groff .
-.
-Therefore these transparent options are not documented here, but in
-.BR \%groff (@MAN1EXT@).
-Due to the automatism in
-.BR \%groffer ,
-none of these
-.B \%groff
-options should be needed, except for advanced usage.
-.
-.
-.\" --------------------------------------------------------------------
-.SS "Options for man\~pages"
-.\" --------------------------------------------------------------------
-.
-.TP
-.B --apropos
-Start the
-.BR \%apropos (1)
-command or facility of
-.BR \%man (1)
-for searching the
-.I \%filespec
-arguments within all
-.I \%man\~page
-descriptions.
-.
-Each
-.I \%filespec
-argument is taken for search as it is;
-.I section
-specific parts are not handled, such that
-.B 7 groff
-searches for the two arguments
-.B 7
-and
-.BR groff ,
-with a large result; for the
-.I \%filespec
-.B groff.7
-nothing will be found.
-.
-The
-.I language
-locale is handled only when the called programs do support this; the
-GNU
-.B apropos
-and
-.B man \-k
-do not.
-.
-The display differs from the
-.B \%apropos
-program by the following concepts:
-.RS
-.Topic
-Construct a
-.I \%groff
-frame similar to a
-.I \%man\~page
-to the output of
-.BR \%apropos ,
-.Topic
-each
-.I \%filespec
-argument is searched on its own.
-.Topic
-The restriction by
-.B --sections
-is handled as well,
-.Topic
-wildcard characters are allowed and handled without a further option.
-.RE
-.
-.
-.TP
-.B --apropos\-data
-Show only the
-.B \%apropos
-descriptions for data documents, these are the
-.BR \%man (7)
-.IR sections\~4 ", " 5 ", and " 7 .
-.
-Direct
-.I section
-declarations are ignored, wildcards are accepted.
-.
-.
-.TP
-.B --apropos\-devel
-Show only the
-.B \%apropos
-descriptions for development documents, these are the
-.BR man (7)
-.IR sections\~2 ", " 3 ", and " 9 .
-.
-Direct
-.I section
-declarations are ignored, wildcards are accepted.
-.
-.
-.TP
-.B --apropos\-progs
-Show only the
-.B \%apropos
-descriptions for documents on programs, these are the
-.BR \%man (7)
-.IR sections\~1 ", " 6 ", and " 8 .
-.
-Direct
-.I section
-declarations are ignored, wildcards are accepted.
-.
-.
-.TP
-.B --whatis
-For each
-.I \%filespec
-argument search all
-.I \%man\~pages
-and display their description \[em] or say that it is not a
-.IR \%man\~page .
-This is written from anew, so it differs from
-.IR man 's
-.B whatis
-output by the following concepts
-.RS
-.Topic
-each retrieved file name is added,
-.Topic
-local files are handled as well,
-.Topic
-the \fIlanguage\fP and \fIsystem\fP locale is supported,
-.Topic
-the display is framed by a
-.I groff
-output format similar to a
-.IR \%man\~page ,
-.Topic
-wildcard characters are allowed without a further option.
-.RE
-.
-.
-.P
-The following options were added to
-.B \%groffer
-for choosing whether the file name arguments are interpreted as names
-for local files or as a search pattern for
-.IR \%man\~pages .
-.
-The default is looking up for local files.
-.
-.
-.TP
-.B --man
-Check the non-option command line arguments
-.nh
-.RI ( filespecs )
-.hy
-first on being
-.IR \%man\~pages ,
-then whether they represent an existing file.
-.
-By default, a
-.I \%filespec
-is first tested whether it is an existing file.
-.
-.
-.TP
-.B --no-man\~\fR|\fB\~--local-file
-Do not check for
-.IR \%man\~pages .
-.
-.B --local-file
-is the corresponding
-.B man
-option.
-.
-.
-.TP
-.B --no-special
-Disable former calls of
-.BR --all ,
-.BR --apropos* ,
-and
-.BR --whatis .
-.
-.
-.\" --------------------------------------------------------------------
-.SS "Long options taken over from GNU man"
-.\" --------------------------------------------------------------------
-.
-The long options of
-.B \%groffer
-were synchronized with the long options of \f[CR]GNU\f[]
-.BR man .
-.
-All long options of \f[CR]GNU\f[]
-.B man
-are recognized, but not all of these options are important to
-.BR \%groffer ,
-so most of them are just ignored.
-.
-These ignored
-.B man
-options are
-.BR --catman ,
-.BR --troff ,
-and
-.BR --update .
-.
-.
-.P
-In the following, the
-.B man
-options that have a special meaning for
-.B \%groffer
-are documented.
-.
-.
-.P
-If your system has \f[CR]GNU\f[]
-.B man
-installed the full set of long and short options of the \f[CR]GNU\f[]
-.B man
-program can be passed via the environment variable
-.Env_var \%$MANOPT ;
-see
-.BR \%man (1).
-.
-.
-.TP
-.B --all
-In searching
-.IR \%man\~pages ,
-retrieve all suitable documents instead of only one.
-.
-.
-.TP
-.B -7\~\fR|\fB\~--ascii
-In
-.IR \%text\~modes ,
-display ASCII translation of special characters for critical environment.
-.
-This is equivalent to
-.BR "groff \%-mtty_char" ;
-see
-.BR groff_tmac (@MAN5EXT@).
-.
-.
-.TP
-.B --ditroff
-Produce
-.IR "groff intermediate output" .
-This is equivalent to
-.B \%groffer
-.BR -Z .
-.
-.
-.TP
-.BI --extension \ suffix
-Restrict
-.I \%man\~page
-search to file names that have
-.I \%suffix
-appended to their section element.
-.
-For example, in the file name
-.I \%/usr/share/man/man3/terminfo.3ncurses.gz
-the
-.I \%man\~page
-extension is
-.IR \%ncurses .
-.
-.
-.TP
-.BI --locale \ language
-.
-Set the language for
-.IR \%man\~pages .
-.
-This has the same effect, but overwrites
-.Env_var $LANG .
-.
-.
-.TP
-.B --location
-Print the location of the retrieved files to standard error.
-.
-.
-.TP
-.B --no-location
-Do not display the location of retrieved files; this resets a former
-call to
-.BR --location .
-.
-This was added by
-.BR \%groffer .
-.
-.
-.TP
-.BI --manpath \ 'dir1:dir2:\*[Ellipsis]'
-Use the specified search path for retrieving
-.I \%man\~pages
-instead of the program defaults.
-.
-If the argument is set to the empty string "" the search for
-.I \%man\~page
-is disabled.
-.
-.
-.TP
-.B --pager
-Set the pager program in
-.IR \%tty\~mode ;
-default is
-.BR \%less .
-This is equivalent to
-.BR --tty\-viewer .
-.
-.
-.TP
-.BI --sections \ sec1:sec2:\*[Ellipsis]
-Restrict searching for
-.I \%man\~pages
-to the given
-.IR sections ,
-a colon-separated list.
-.
-.
-.TP
-.BI --systems \ sys1,sys2,\*[Ellipsis]
-Search for
-.I \%man\~pages
-for the given operating systems; the argument
-.I \%systems
-is a comma-separated list.
-.
-.
-.TP
-.B --where
-Equivalent to
-.BR --location .
-.
-.
-.\" --------------------------------------------------------------------
-.SS "X\~\%Window\~\%Toolkit Options"
-.\" --------------------------------------------------------------------
-.
-The following long options were adapted from the corresponding
-\%\f[CR]X\~Window\~Toolkit\f[] options.
-.
-.B \%groffer
-will pass them to the actual viewer program if it is an
-\%\f[CR]X\~Window\f[] program.
-.
-Otherwise these options are ignored.
-.
-.
-.P
-Unfortunately these options use the old style of a single minus for
-long options.
-.
-For
-.B \%groffer
-that was changed to the standard with using a double minus for long
-options, for example,
-.B \%groffer
-uses the option
-.B --font
-for the \%\f[CR]X\~Window\f[] option
-.BR -font .
-.
-.
-.P
-See
-.BR X (7)
-and the documentation on the \%\f[CR]X\~Window\~Toolkit\f[] options
-for more details on these options and their arguments.
-.
-.
-.TP
-.BI --background \ color
-Set the background color of the viewer window.
-.
-.
-.TP
-.BI --bd \ pixels
-This is equivalent to
-.BR --bordercolor .
-.
-.
-.TP
-.BI --bg \ color
-This is equivalent to
-.BR --background .
-.
-.
-.TP
-.BI --bw \ pixels
-This is equivalent to
-.BR --borderwidth .
-.
-.
-.TP
-.BI --bordercolor \ pixels
-Specifies the color of the border surrounding the viewer window.
-.
-.
-.TP
-.BI --borderwidth \ pixels
-Specifies the width in pixels of the border surrounding the viewer
-window.
-.
-.
-.TP
-.BI --display \ X-display
-Set the \%\f[CR]X\~Window\f[] display on which the viewer program
-shall be started, see the \%\f[CR]X\~Window\f[] documentation for the
-syntax of the argument.
-.
-.
-.TP
-.BI --foreground \ color
-Set the foreground color of the viewer window.
-.
-.
-.TP
-.BI --fg \ color
-This is equivalent to
-.BR -foreground .
-.
-.
-.TP
-.BI --fn \ font_name
-This is equivalent to
-.BR --font .
-.
-.
-.TP
-.BI --font \ font_name
-Set the font used by the viewer window.
-.
-The argument is an \%\f[CR]X\~Window\f[] font name.
-.
-.
-.TP
-.BI --ft \ font_name
-This is equivalent to
-.BR --font .
-.
-.
-.TP
-.BI --geometry \ size_pos
-Set the geometry of the display window, that means its size and its
-starting position.
-.
-See
-.BR \%X (7)
-for the syntax of the argument.
-.
-.
-.TP
-.BI --resolution \ value
-Set \%\f[CR]X\~Window\f[] resolution in dpi (dots per inch) in some
-viewer programs.
-.
-The only supported dpi values are
-.B 75
-and
-.BR 100 .
-.
-Actually, the default resolution for
-.B \%groffer
-is set to
-.BR 75dpi .
-The resolution also sets the default device in
-.IR "mode x" .
-.
-.
-.TP
-.B --rv
-Reverse foreground and background color of the viewer window.
-.
-.
-.TP
-.BI --title "\ 'some text'"
-Set the title for the viewer window.
-.
-.
-.TP
-.BI --xrm \ 'resource'
-Set \f[CR]\%X\~Window\f[] resource.
-.
-.
-.\" --------------------------------------------------------------------
-.SS "Options for Development"
-.\" --------------------------------------------------------------------
-.
-.TP
-.B --debug
-Enable eight debugging informations.
-.
-The temporary files are kept and not deleted, the name of the
-temporary directory and the shell name for
-.File_name groffer2.sh
-are printed, the displayed file names are printed, the
-.B grog
-output is printed, the parameters are printed at several steps of
-development, and a function stack is output with function
-\f[CR]error_user()\f[] as well.
-.
-Neither the function call stack at the opening and closing of each
-function call nor the landmark information to determine how far the
-program is running are printed.
-.
-These seem to be the most useful parts among all debugging options.
-.
-.
-.TP
-.B --debug\-all
-Enable all ten debugging informations including the function call
-stack and the landmark information.
-.
-.
-.TP
-.B --debug\-filenames
-Print the names of the files and
-.I \%man\~pages
-that are displayed by
-.BR \&groffer .
-.
-.
-.TP
-.B --debug\-func
-Enable the basic debugging information for checking the functions on
-the beginning and end of each call.
-.
-The options
-.B --debug\-stacks
-and
-.B --debug\-user
-enable this option automatically.
-.
-This option is important for the development, but it decreases the
-speed of
-.B groffer
-by large amounts.
-.
-.
-.TP
-.B --debug\-grog
-Print the output of all
-.B grog
-commands.
-.
-.
-.TP
-.B --debug\-keep
-Enable two debugging informations, the printing of the name of the
-temporary directory and the keeping of the temporary files.
-.
-.
-.TP
-.B --debug\-lm
-Enable one debugging information, the landmark information.
-.
-.
-.TP
-.B --debug\-params
-Enable one debugging information, the parameters at several steps.
-.
-.
-.TP
-.B --debug\-shell
-Enable one debugging information, the shell name for
-.File_name groffer2.sh .
-.
-.
-.TP
-.B --debug\-stacks
-Enable one debugging information, the function call stack.
-.
-.
-.TP
-.B --debug\-tmpdir
-Enable one debugging information, the name of the temporary directory.
-.
-.
-.TP
-.B --debug\-user
-Enable one debugging information, the function stack with
-\f[CR]error_user()\f[].
-.
-.
-.TP
-.B --do-nothing
-This is like
-.BR --version ,
-but without the output; no viewer is started.
-.
-This makes only sense in development.
-.
-.
-.TP
-.B --print=\fItext\fR
-Just print the argument to standard error.
-.
-This is good for parameter check.
-.
-.
-.TP
-.B --shell \fIshell_program\fR
-Specify the shell under which the
-.File_name \%groffer2.sh
-script should be run.
-.
-This option overwrites the automatic shell determination of the
-program.
-.
-If the argument
-.I shell_program
-is empty a former shell option and the automatic shell determination
-is cancelled and the default shell is restored.
-.
-Some shells run considerably faster than the standard shell.
-.
-.
-.TP
-.B -V
-This is an advanced option for debugging only.
-.
-Instead of displaying the formatted input, a lot of
-.I \%groffer
-specific information is printed to standard output:
-.
-.RS
-.Topic
-the output file name in the temporary directory,
-.
-.Topic
-the display mode of the actual
-.B \%groffer
-run,
-.
-.Topic
-the display program for viewing the output with its arguments,
-.
-.Topic
-the active parameters from the config files, the arguments in
-.Env_var \%$GROFFER_OPT ,
-and the arguments of the command line,
-.
-.Topic
-the pipeline that would be run by the
-.B \%groff
-program, but without executing it.
-.RE
-.
-.
-.P
-Other useful debugging options are the
-.B \%groff
-option
-.B -Z
-and
-.BR --mode=groff .
-.
-.
-.\" --------------------------------------------------------------------
-.SS "Filespec Arguments"
-.\" --------------------------------------------------------------------
-.
-A
-.I \%filespec
-parameter is an argument that is not an option or option argument.
-.
-In
-.BR \%groffer ,
-.I \%filespec
-parameters are a file name or a template for searching
-.IR \%man\~pages .
-.
-These input sources are collected and composed into a single output
-file such as
-.B \%groff
-does.
-.
-.
-.P
-The strange \%\f[CR]POSIX\f[] behavior to regard all arguments behind
-the first non-option argument as
-.I \%filespec
-arguments is ignored.
-.
-The \f[CR]GNU\f[] behavior to recognize options even when mixed with
-.I \%filespec
-arguments is used throughout.
-.
-But, as usual, the double minus argument
-.B --
-ends the option handling and interprets all following arguments as
-.I \%filespec
-arguments; so the \%\f[CR]POSIX\f[] behavior can be easily adopted.
-.
-.
-.P
-The options
-.B --apropos*
-have a special handling of
-.I filespec
-arguments.
-.
-Each argument is taken as a search scheme of its own.
-.
-Also a regexp (regular expression) can be used in the filespec.
-.
-For example,
-.B groffer --apropos '^gro.f$'
-searches
-.B groff
-in the
-.I man\~page
-name, while
-.B groffer --apropos groff
-searches
-.B groff
-somewhere in the name or description of the
-.IR man\~pages .
-.
-.
-.P
-All other parts of
-.IR groffer ,
-such as the normal display or the output with
-.B --whatis
-have a different scheme for
-.IR filespecs .
-No regular expressions are used for the arguments.
-.
-The
-.I filespec
-arguments are handled by the following scheme.
-.
-.
-.P
-It is necessary to know that on each system the
-.I \%man\~pages
-are sorted according to their content into several sections.
-.
-The
-.I classical man sections
-have a single-character name, either a digit from
-.B 1
-to
-.B 9
-or one of the characters
-.B n
-or
-.BR o .
-.
-.
-.P
-This can optionally be followed by a string, the so-called
-.IR extension .
-The
-.I extension
-allows to store several
-.I man\~pages
-with the same name in the same
-.IR section .
-But the
-.I extension
-is only rarely used, usually it is omitted.
-.
-Then the
-.I extensions
-are searched automatically by alphabet.
-.
-.
-.P
-In the following, we use the name
-.I section_extension
-for a word that consists of a single character
-.I section
-name or a
-.I section
-character that is followed by an
-.IR extension .
-.
-Each
-.I \%filespec
-parameter can have one of the following forms in decreasing sequence.
-.
-.
-.Topic
-No
-.I \%filespec
-parameters means that
-.B \%groffer
-waits for standard input.
-.
-The minus option
-.B -
-always stands for standard input; it can occur several times.
-.
-If you want to look up a
-.I \%man\~page
-called
-.B -
-use the argument
-.BR man:\- .
-.
-.
-.Topic
-Next a
-.I \%filespec
-is tested whether it is the path name of an existing file.
-.
-Otherwise it is assumed to be a searching pattern for a
-.IR \%man\~page .
-.
-.
-.Topic
-.BI \%man: name ( section_extension ) ,
-.BI \%man: name . section_extension,
-.IB \%name ( section_extension ) ,
-or
-.IB \%name . section_extension
-search the \%man\~page
-.I \%name
-in \%man\~section and possibly extension of
-.IR \%section_extension .
-.
-.
-.Topic
-Now
-.BI \%man: name
-searches for a
-.I \%man\~page
-in the lowest
-.I \%man\~section
-that has a document called
-.IR \%name .
-.
-.
-.Topic
-.I \%section_extension\~name
-is a pattern of 2 arguments that originates from a strange argument
-parsing of the
-.B man
-program.
-.
-Again, this searches the man page
-.I name
-with
-.IR \%section_extension ,
-a combination of a
-.I section
-character optionally followed by an
-.IR extension .
-.
-.
-.Topic
-We are left with the argument
-.I \%name
-which is not an existing file.
-.
-So this searches for the
-.I \%man\~page
-called
-.I \%name
-in the lowest
-.I \%man\~section
-that has a document for this name.
-.
-.
-.P
-Several file name arguments can be supplied.
-.
-They are mixed by
-.B \%groff
-into a single document.
-.
-Note that the set of option arguments must fit to all of these file
-arguments.
-.
-So they should have at least the same style of the
-.I \%groff
-language.
-.
-.
-.\" --------------------------------------------------------------------
-.SH "OUTPUT MODES"
-.\" --------------------------------------------------------------------
-.
-By default, the
-.B \%groffer
-program collects all input into a single file, formats it with the
-.B \%groff
-program for a certain device, and then chooses a suitable viewer
-program.
-.
-The device and viewer process in
-.B \%groffer
-is called a
-.IR \%mode .
-.
-The mode and viewer of a running
-.B \%groffer
-program is selected automatically, but the user can also choose it
-with options.
-.
-.
-The modes are selected by option the arguments of
-.BR --mode=\fIanymode .
-Additionally, each of this argument can be specified as an option of
-its own, such as
-.BR anymode .
-Most of these modes have a viewer program, which can be chosen by an
-option that is constructed like
-.BR --\fIanymode\fR\-viewer .
-.
-.
-.P
-Several different modes are offered, graphical modes for
-\f[CR]\%X\~Window\f[],
-.IR \%text\~modes ,
-and some direct
-.I \%groff\~modes
-for debugging and development.
-.
-.
-.P
-By default,
-.B \%groffer
-first tries whether
-.I \%x\~mode
-is possible, then
-.IR \%ps\~mode ,
-and finally
-.IR \%tty\~mode .
-.
-This mode testing sequence for
-.I \%auto\~mode
-can be changed by specifying a comma separated list of modes with the
-option
-.B --default\-modes.
-.
-.
-.P
-The searching for
-.I \%man\~pages
-and the decompression of the input are active in every mode.
-.
-.
-.\" --------------------------------------------------------------------
-.SS "Graphical Display Modes"
-.\" --------------------------------------------------------------------
-.
-The graphical display modes work mostly in the \%\f[CR]X\~Window\f[]
-environment (or similar implementations within other windowing
-environments).
-.
-The environment variable
-.Env_var \%$DISPLAY
-and the option
-.B --display
-are used for specifying the \%\f[CR]X\~Window\f[] display to be used.
-.
-If this environment variable is empty
-.B \%groffer
-assumes that no \%\f[CR]X\~Window\f[] is running and changes to a
-.IR \%text\~mode .
-.
-You can change this automatic behavior by the option
-.BR --default\-modes .
-.
-.
-.P
-Known viewers for the graphical display modes and their standard
-\%\f[CR]X\~Window\f[] viewer programs are
-.
-.Topic
-in a PDF viewer
-.nh
-.RI ( \%pdf\~mode )
-.hy
-.
-.Topic
-in a web browser
-.nh
-.RI ( html
-or
-.IR \%www\~mode )
-.hy
-.RE
-.
-.Topic
-in a Postscript viewer
-.nh
-.RI ( \%ps\~mode )
-.hy
-.
-.Topic
-\%\f[CR]X\~Window\f[]
-.I roff
-viewers such as
-.BR \%gxditview (@MAN1EXT@)
-or
-.BR \%xditview (1)
-(in
-.IR \%x\~mode )
-.
-.Topic
-in a dvi viewer program
-.nh
-.RI ( \%dvi\~mode )
-.hy
-.
-.
-.P
-The
-.I \%pdf\~mode
-has a major advantage \[em] it is the only graphical display mode that
-allows to search for text within the viewer; this can be a really
-important feature.
-.
-Unfortunately, it takes some time to transform the input into the PDF
-format, so it was not chosen as the major mode.
-.
-.
-.P
-These graphical viewers can be customized by options of the
-\%\f[CR]X\~Window\~Toolkit\f[].
-.
-But the
-.B \%groffer
-options use a leading double minus instead of the single minus used by
-the \%\f[CR]X\~Window\~Toolkit\f[].
-.
-.
-.\" --------------------------------------------------------------------
-.SS "Text modes"
-.\" --------------------------------------------------------------------
-.
-There are two modes for text output,
-.I \%mode\~text
-for plain output without a pager and
-.I \%mode\~tty
-for a text output on a text terminal using some pager program.
-.
-.
-.P
-If the variable
-.Env_var \%$DISPLAY
-is not set or empty,
-.B \%groffer
-assumes that it should use
-.IR \%tty\~\%mode .
-.
-.
-.P
-In the actual implementation, the
-.I groff
-output device
-.I \%latin1
-is chosen for
-.IR \%text\~modes .
-.
-This can be changed by specifying option
-.B -T
-or
-.BR \%--device .
-.
-.
-.P
-The pager to be used can be specified by one of the options
-.B --pager
-and
-.BR --tty\-viewer ,
-or by the environment variable
-.Env_var \%$PAGER .
-If all of this is not used the
-.BR \%less (1)
-program with the option
-.B -r
-for correctly displaying control sequences is used as the default
-pager.
-.
-.
-.\" --------------------------------------------------------------------
-.SS "Special Modes for Debugging and Development"
-.\" --------------------------------------------------------------------
-.
-These modes use the
-.I \%groffer
-file determination and decompression.
-.
-This is combined into a single input file that is fed directly into
-.B \%groff
-with different strategy without the
-.I \%groffer
-viewing facilities.
-.
-These modes are regarded as advanced, they are useful for debugging
-and development purposes.
-.
-.
-.P
-The
-.I \%source\~mode
-with option
-.B --source
-just displays the decompressed input.
-.
-.
-.P
-Otion
-.B --to\-stdout
-does not display in a graphical mode.
-.
-It just generates the file for the chosen mode and then prints its
-content to standard output.
-.
-.
-.P
-The
-.I \%groff\~mode
-passes the input to
-.B \%groff
-using only some suitable options provided to
-.BR \%groffer .
-.
-This enables the user to save the generated output into a file or pipe
-it into another program.
-.
-.
-.P
-In
-.IR \%groff\~\%mode ,
-the option
-.B -Z
-disables post-processing, thus producing the
-.nh
-.I groff intermediate
-.IR output .
-.hy
-.
-In this mode, the input is formatted, but not postprocessed; see
-.BR \%groff_out (@MAN5EXT@)
-for details.
-.
-.
-.P
-All
-.B \%groff
-short options are supported by
-.BR \%groffer .
-.
-.
-.\" --------------------------------------------------------------------
-.SH "MAN PAGE SEARCHING"
-.\" --------------------------------------------------------------------
-.
-The default behavior of
-.B \%groffer
-is to first test whether a file parameter represents a local file; if
-it is not an existing file name, it is assumed to represent the name
-of a
-.IR \%man\~page .
-The following options can be used to determine whether the arguments
-should be handled as file name or
-.I \%man\~page
-arguments.
-.
-.TP
-.B --man
-forces to interpret all file parameters as
-.I \%filespecs
-for searching
-.IR \%man\~pages .
-.
-.TP
-.B --no\-man
-.TQ
-.B --local\-file
-disable the
-.I man
-searching; so only local files are displayed.
-.
-.
-.P
-If neither a local file nor a
-.I \%man\~page
-was retrieved for some file parameter a warning is issued on standard
-error, but processing is continued.
-.
-.
-.\" --------------------------------------------------------------------
-.SS "Search Algorithm"
-.\" --------------------------------------------------------------------
-.
-Let us now assume that a
-.I \%man\~page
-should be searched.
-.
-The
-.B \%groffer
-program provides a search facility for
-.IR \%man\~pages .
-.
-All long options, all environment variables, and most of the
-functionality of the \f[CR]GNU\fP
-.BR \%man (1)
-program were implemented.
-.
-The search algorithm shall determine which file is displayed for a given
-.IR \%man\~page .
-The process can be modified by options and environment variables.
-.
-.
-.P
-The only
-.I man
-action that is omitted in
-.B \%groffer
-are the preformatted
-.IR \%man\~pages ,
-also called
-.IR cat\~pages .
-.
-With the excellent performance of the actual computers, the
-preformatted
-.I \%man\~pages
-aren't necessary any longer.
-.
-Additionally,
-.B \%groffer
-is a
-.I roff
-program; it wants to read
-.I roff
-source files and format them itself.
-.
-.
-.P
-The algorithm for retrieving the file for a
-.I \%man\~page
-needs first a set of directories.
-.
-This set starts with the so-called
-.I man\~path
-that is modified later on by adding names of
-.I operating system
-and
-.IR language .
-.
-This arising set is used for adding the section directories which
-contain the
-.I \%man\~page
-files.
-.
-.
-.P
-The
-.I man\~path
-is a list of directories that are separated by colon.
-.
-It is generated by the following methods.
-.
-.Topic
-The environment variable
-.Env_var \%$MANPATH
-can be set.
-.
-.Topic
-It can be read from the arguments of the environment variable
-.Env_var \%$MANOPT .
-.
-.Topic
-The
-.I man\~path
-can be manually specified by using the option
-.BR --manpath .
-An empty argument disables the
-.I \%man\~page
-searching.
-.
-.Topic
-When no
-.I man\~path
-was set the
-.BR \%manpath (1)
-program is tried to determine one.
-.
-.Topic
-If this does not work a reasonable default path from
-.Env_var $PATH
-is determined.
-.
-.
-.P
-We now have a starting set of directories.
-.
-The first way to change this set is by adding names of
-.I operating
-.IR systems .
-.
-This assumes that
-.I \%man\~pages
-for several
-.I operating systems
-are installed.
-.
-This is not always true.
-.
-The names of such
-.I operating systems
-can be provided by 3 methods.
-.
-.Topic
-The environment variable
-.Env_var \%$SYSTEM
-has the lowest precedence.
-.
-.Topic
-This can be overridden by an option in
-.Env_var \%$MANOPT .
-.
-.Topic
-This again is overridden by the command line option
-.BR --systems .
-.
-.
-.P
-Several names of
-.I operating systems
-can be given by appending their names, separated by a comma.
-.
-.
-.P
-The
-.I man\~path
-is changed by appending each
-.I system
-name as subdirectory at the end of each directory of the set.
-.
-No directory of the
-.I man\~path
-set is kept.
-.
-But if no
-.I system
-name is specified the
-.I man\~path
-is left unchanged.
-.
-.
-.P
-After this, the actual set of directories can be changed by
-.I language
-information.
-.
-This assumes that there exist
-.I man\~pages
-in different languages.
-.
-The wanted
-.I language
-can be chosen by several methods.
-.
-.Topic
-Environment variable
-.Env_var $LANG .
-.
-.Topic
-This is overridden by
-.Env_var \%$LC_MESSAGES .
-.
-.Topic
-This is overridden by
-.Env_var $LC_ALL .
-.
-.Topic
-This can be overridden by providing an option in
-.Env_var \%$MANOPT .
-.
-.Topic
-All these environment variables are overridden by the command line
-option
-.BR --locale .
-.
-.
-.P
-The
-.I default language
-can be specified by specifying one of the pseudo-language parameters
-\f[CR]C\fP or \f[CR]\%POSIX\fP.
-.
-This is like deleting a formerly given
-.I language
-information.
-.
-The
-.I \%man\~pages
-in the
-.I default language
-are usually in English.
-.
-.
-.P
-Of course, the
-.I language
-name is determined by
-.BR man .
-In \f[CR]GNU\fP
-.BR man ,
-it is specified in the \%\f[CR]POSIX\~1003.1\fP based format:
-.P
-.nh
-\f[I]<language>\f[][\f[CB]_\f[]\f[I]<territory>\f[][\f[CB].\fP\
-\f[I]<character-set>\f[][\f[CB],\fP\f[I]<version>\fP]]],
-.hy
-.P
-but the two-letter code in
-.nh
-.I <language>
-.hy
-is sufficient for most purposes.
-.
-If for a complicated
-.I language
-formulation no
-.I \%man\~pages
-are found
-.B \%groffer
-searches the country part consisting of these first two characters as
-well.
-.
-.
-.P
-The actual directory set is copied thrice.
-.
-The
-.I language
-name is appended as subdirectory to each directory in the first copy
-of the actual directory set (this is only done when a language
-information is given).
-.
-Then the 2-letter abbreviation of the
-.I language
-name is appended as subdirectories to the second copy of the directory
-set (this is only done when the given language name has more than 2
-letters).
-.
-The third copy of the directory set is kept unchanged (if no
-.I language
-information is given this is the kept directory set).
-.
-These maximally 3 copies are appended to get the new directory set.
-.
-.
-.P
-We now have a complete set of directories to work with.
-.
-In each of these directories, the
-.I man
-files are separated in
-.IR sections .
-.
-The name of a
-.I section
-is represented by a single character, a digit between
-.I 1
-and
-.IR 9 ,
-or the character
-.I o
-or
-.IR n ,
-in this order.
-.
-.
-.P
-For each available
-.IR section ,
-a subdirectory
-.File_name man \fI<section>\fP
-exists containing all
-.I man
-files for this
-.IR section ,
-where
-.I <section>
-is a single character as described before.
-.
-Each
-.I man
-file in a
-.I section
-directory has the form
-.IR \%\f[CB]man\fP<section>\f[CB]/\fP<name>\f[CB].\fP<section>\
-[<extension>][\f[CB].\fP<compression>] ,
-where
-.I \%<extension>
-and
-.I \%<compression>
-are optional.
-.
-.I \%<name>
-is the name of the
-.I \%man\~page
-that is also specified as filespec argument on the command line.
-.
-.
-.P
-The
-.I extension
-is an addition to the section.
-.
-This postfix acts like a subsection.
-.
-An
-.I extension
-occurs only in the file name, not in name of the
-.I section
-subdirectory.
-.
-It can be specified on the command line.
-.
-.
-.P
-On the other hand, the
-.I compression
-is just an information on how the file is compressed.
-.
-This is not important for the user, such that it cannot be specified
-on the command line.
-.
-.
-.P
-There are 4 methods to specify a
-.I section
-on the command line:
-.
-.Topic
-Environment variable
-.Env_var \%$MANSECT
-.
-.Topic
-Command line option
-.B --sections
-.
-.Topic
-Appendix to the
-.I name
-argument in the form
-.I <name>.<section>
-.
-.Topic
-Preargument before the
-.I name
-argument in the form
-.I <section> <name>
-.
-.
-.P
-It is also possible to specify several
-.I sections
-by appending the single characters separated by colons.
-.
-One can imagine that this means to restrict the
-.I \%man\~page
-search to only some
-.IR sections .
-.
-The multiple
-.I sections
-are only possible for
-.Env_var \%$MANSECT
-and
-.BR --sections .
-.
-.
-.P
-If no
-.I section
-is specified all
-.I sections
-are searched one after the other in the given order, starting with
-.IR section\~1 ,
-until a suitable file is found.
-.
-.
-.P
-There are 4 methods to specify an
-.I extension
-on the command line.
-.
-But it is not necessary to provide the whole extension name, some
-abbreviation is good enough in most cases.
-.
-.Topic
-Environment variable
-.Env_var \%$EXTENSION
-.
-.Topic
-Command line option
-.B --extension
-.
-.Topic
-Appendix to the
-.I <name>.<section>
-argument in the form
-.I <name>.<section><extension>
-.
-.Topic
-Preargument before the
-.I name
-argument in the form
-.I <section><extension> <name>
-.
-.
-.P
-For further details on
-.I \%man\~page
-searching, see
-.BR \%man (1).
-.
-.
-.\" --------------------------------------------------------------------
-.SS "Examples of man files"
-.\" --------------------------------------------------------------------
-.
-.TP
-.File_name /usr/share/man/man1/groff.1
-This is an uncompressed file for the
-.I \%man\~page
-\f[CR]groff\fP in
-.IR section\~1 .
-.
-It can be called by
-.EX
-\fIsh#\fR groffer\~groff
-.EE
-No
-.I section
-is specified here, so all
-.I sections
-should be searched, but as
-.I section\~1
-is searched first this file will be found first.
-.
-The file name is composed of the following components.
-.File_name /usr/share/man
-must be part of the
-.IR \%man\~path ;
-the subdirectory
-.File_name man1/
-and the part
-.File_name .1
-stand for the
-.IR section ;
-.File_name groff
-is the name of the
-.IR \%man\~page .
-.
-.
-.TP
-.File_name /usr/local/share/man/man7/groff.7.gz
-The file name is composed of the following components.
-.File_name /usr/local/share/man
-must be part of the
-.IR \%man\~path ;
-the subdirectory
-.File_name man7/
-and the part
-.File_name .7
-stand for the
-.IR section ;
-.File_name groff
-is the name of the
-.IR \%man\~page ;
-the final part
-.File_name .gz
-stands for a compression with
-.BR gzip (1).
-As the
-.I section
-is not the first one it must be specified as well.
-.
-This can be done by one of the following commands.
-.EX
-\fIsh#\fR\~groffer\~groff.7
-\fIsh#\fR\~groffer\~7\~groff
-\fIsh#\fR\~groffer\~\-\-sections=7\~groff
-.EE
-.
-.TP
-.File_name /usr/local/man/man1/ctags.1emacs21.bz2
-Here
-.File_name /usr/local/man
-must be in
-.IR \%man\~path ;
-the subdirectory
-.File_name man1/
-and the file name part
-.File_name .1
-stand for
-.IR section\~1 ;
-the name of the
-.I \%man\~page
-is
-.File_name ctags ;
-the section has an extension
-.File_name emacs21 ;
-and the file is compressed as
-.File_name .bz2
-with
-.BR bzip2 (1).
-The file can be viewed with one of the following commands
-.EX
-\fIsh#\fR\~groffer\~ctags.1e
-\fIsh#\fR\~groffer\~1e\~ctags
-\fIsh#\fR\~groffer\~\-\-extension=e\~\-\-sections=1\~ctags
-.EE
-where \f[CR]e\fP works as an abbreviation for the extension
-\f[CR]emacs21\fP.
-.
-.
-.TP
-.File_name /usr/man/linux/de/man7/man.7.Z
-The directory
-.File_name /usr/man
-is now part of the
-.IR \%man\~path ;
-then there is a subdirectory for an
-.I operating system
-name
-.File_name linux/ ;
-next comes  a subdirectory
-.File_name de/
-for the German
-.IR language ;
-the
-.I section
-names
-.File_name man7
-and
-.File_name .7
-are known so far;
-.File_name man
-is the name of the
-.IR \%man\~page ;
-and
-.File_name .Z
-signifies the compression that can be handled by
-.BR gzip (1).
-We want now show how to provide several values for some options.
-.
-That is possible for
-.I sections
-and
-.I operating system
-names.
-.
-So we use as
-.I sections\~5
-and
-.I 7
-and as
-.I system
-names
-.I linux
-and
-.IR aix .
-The command is then
-.sp
-.EX
-\fIsh#\fR groffer\~\-\-locale=de\~\-\-sections=5:7\~\-\-systems=linux,aix\~man
-\fIsh#\fR LANG=de\~MANSECT=5:7\~SYSTEM=linux,aix\~groffer\~man
-.EE
-.
-.
-.\" --------------------------------------------------------------------
-.SH DECOMPRESSION
-.\" --------------------------------------------------------------------
-.
-The program has a decompression facility.
-.
-If standard input or a file that was retrieved from the command line
-parameters is compressed with a format that is supported by either
-.BR \%gzip (1)
-or
-.BR \%bzip2 (1)
-it is decompressed on-the-fly.
-.
-This includes the \f[CR]GNU\fP
-.BR \%.gz ,
-.BR \%.bz2 ,
-and the traditional
-.B \%.Z
-compression.
-.
-The program displays the concatenation of all decompressed input in
-the sequence that was specified on the command line.
-.
-.
-.\" --------------------------------------------------------------------
-.SH "ENVIRONMENT"
-.\" --------------------------------------------------------------------
-.
-The
-.B \%groffer
-program supports many system variables, most of them by courtesy of
-other programs.
-.
-All environment variables of
-.BR \%groff (@MAN1EXT@)
-and \f[CR]GNU\fP
-.BR \%man (1)
-and some standard system variables are honored.
-.
-.
-.\" --------------------------------------------------------------------
-.SS "Native groffer Variables"
-.\" --------------------------------------------------------------------
-.
-.TP
-.Env_var \%$GROFFER_OPT
-Store options for a run of
-.BR \%groffer .
-.
-The options specified in this variable are overridden by the options
-given on the command line.
-.
-The content of this variable is run through the shell builtin `eval';
-so arguments containing white-space or special shell characters should
-be quoted.
-.
-Do not forget to export this variable, otherwise it does not exist
-during the run of
-.BR groffer .
-.
-.
-.\" --------------------------------------------------------------------
-.SS "System Variables"
-.\" --------------------------------------------------------------------
-.
-The
-.B \%groffer
-program is a shell script that is run through
-.File_name /bin/sh ,
-which can be internally linked to programs like
-.BR \%bash (1).
-The corresponding system environment is automatically effective.
-.
-The following variables have a special meaning for
-.BR \%groffer .
-.
-.
-.TP
-.Env_var \%$DISPLAY
-If this variable is set this indicates that the \%\f[CR]X\~Window\fP
-system is running.
-.
-Testing this variable decides on whether graphical or text output is
-generated.
-.
-This variable should not be changed by the user carelessly, but it can
-be used to start the graphical
-.B \%groffer
-on a remote \%\f[CR]X\~Window\fP terminal.
-.
-For example, depending on your system,
-.B \%groffer
-can be started on the second monitor by the command
-.sp
-.EX
-\fIsh#\fR DISPLAY=:0.1\~groffer\~what.ever &
-.EE
-.
-.
-.TP
-.Env_var \%$LC_ALL
-.TQ
-.Env_var \%$LC_MESSAGES
-.TQ
-.Env_var $LANG
-If one of these variables is set (in the above sequence), its content
-is interpreted as the locale, the language to be used, especially when
-retrieving
-.IR \%man\~pages .
-.
-A locale name is typically of the form
-.nh
-.IR language [\c
-.B _\c
-.IR territory [\c
-.B .\c
-.IR codeset [\c
-.B @\c
-.IR modifier ]]],
-.hy
-where
-.I \%language
-is an ISO 639 language code,
-.I \%territory
-is an ISO 3166 country code, and
-.I \%codeset
-is a character set or encoding identifier like ISO-8859-1 or UTF-8;
-see
-.BR \%setlocale (3).
-.
-The locale values \f[CR]C\fP and \%\f[CR]POSIX\fP
-stand for the default, i.e. the
-.I \%man\~page
-directories without a language prefix.
-.
-This is the same behavior as when all 3\~variables are unset.
-.
-.
-.TP
-.Env_var \%$PAGER
-This variable can be used to set the pager for the tty output.
-.
-For example, to disable the use of a pager completely set this
-variable to the
-.BR \%cat (1)
-program
-.sp
-.EX
-\fIsh#\fR PAGER=cat\~groffer\~anything
-.EE
-.sp
-.
-.TP
-.Env_var $PATH
-All programs within the
-.B \%groffer
-shell script are called without a fixed path.
-.
-Thus this environment variable determines the set of programs used
-within the run of
-.BR \%groffer .
-.
-.
-.\" --------------------------------------------------------------------
-.SS "Groff Variables"
-.\" --------------------------------------------------------------------
-.
-The
-.B \%groffer
-program internally calls
-.BR \%groff ,
-so all environment variables documented in
-.BR \%groff (@MAN1EXT@)
-are internally used within
-.B \%groffer
-as well.
-.
-The following variable has a direct meaning for the
-.B \%groffer
-program.
-.
-.TP
-.Env_var \%$GROFF_TMPDIR
-If the value of this variable is an existing, writable directory,
-.B \%groffer
-uses it for storing its temporary files, just as
-.B groff
-does.
-.
-See the
-.BR \%groff (@MAN1EXT@)
-man page for more details on the location of temporary files.
-.
-.
-.\" --------------------------------------------------------------------
-.SS "Man Variables"
-.\" --------------------------------------------------------------------
-.
-Parts of the functionality of the
-.B man
-program were implemented in
-.BR \%groffer ;
-support for all environment variables documented in
-.BR \%man (1)
-was added to
-.BR \%groffer ,
-but the meaning was slightly modified due to the different approach in
-.BR \%groffer ;
-but the user interface is the same.
-.
-The
-.B man
-environment variables can be overwritten by options provided with
-.Env_var \%$MANOPT ,
-which in turn is overwritten by the command line.
-.
-.
-.TP
-.Env_var \%$EXTENSION
-Restrict the search for
-.I \%man\~pages
-to files having this extension.
-.
-This is overridden by option
-.BR --extension ;
-see there for details.
-.
-.
-.TP
-.Env_var \%$MANOPT
-This variable contains options as a preset for
-.BR \%man (1).
-As not all of these are relevant for
-.B \%groffer
-only the essential parts of its value are extracted.
-.
-The options specified in this variable overwrite the values of the
-other environment variables that are specific to
-.IR man .
-.
-All options specified in this variable are overridden by the options
-given on the command line.
-.
-.
-.TP
-.Env_var \%$MANPATH
-If set, this variable contains the directories in which the
-.I \%man\~page
-trees are stored.
-.
-This is overridden by option
-.BR \%--manpath .
-.
-.
-.TP
-.Env_var \%$MANSECT
-If this is a colon separated list of section names, the search for
-.I \%man\~pages
-is restricted to those manual sections in that order.
-.
-This is overridden by option
-.BR --sections .
-.
-.
-.TP
-.Env_var \%$SYSTEM
-If this is set to a comma separated list of names these are interpreted
-as
-.I \%man\~page
-trees for different operating systems.
-.
-This variable can be overwritten by option
-.BR --systems ;
-see there for details.
-.
-.
-.P
-The environment variable
-.Env_var \%$MANROFFSEQ
-is ignored by
-.B \%groffer
-because the necessary preprocessors are determined automatically.
-.
-.
-.\" --------------------------------------------------------------------
-.SH "CONFIGURATION FILES"
-.\" --------------------------------------------------------------------
-.
-The
-.B \%groffer
-program can be preconfigured by two configuration files.
-.
-.
-.TP
-.File_name \%/etc/groff/groffer.conf
-System-wide configuration file for
-.BR \%groffer .
-.
-.
-.TP
-.File_name \%$HOME/.groff/groffer.conf
-User-specific configuration file for
-.BR \%groffer ,
-where
-.Env_var \%$HOME
-denotes the user's home directory.
-.
-This file is called after the system-wide configuration file to enable
-overriding by the user.
-.
-.
-.P
-Both files are handled for the configuration, but the configuration
-file in
-.File_name /etc
-comes first; it is overwritten by the configuration file in the home
-directory; both configuration files are overwritten by the environment
-variable
-.Env_var \%$GROFFER_OPT ;
-everything is overwritten by the command line arguments.
-.
-.
-.P
-In the configuration files, arbitrary spaces are allowed at the
-beginning of each line, they are just ignored.
-.
-Apart from that, the lines of the configuration lines either start
-with a minus character, all other lines are interpreted as shell
-commands.
-.
-.
-.P
-The lines with the beginning minus are interpreted as
-.B groffer
-options.
-.
-This easily allows to set general
-.B \%groffer
-options that should be used with any call of
-.BR \%groffer .
-.
-.
-.P
-If a lines starts with a double minus it represents a
-.B \%groffer
-long option; everything behind the first equal sign
-.RB ` = '
-or space character up to the end of the line is interpreted as its
-argument.
-.
-A line starting with a single minus represents a short options cluster
-with or without a final argument.
-.
-It is not necessary to use quotes in these lines; quotes are just
-ignored.
-.
-.
-.P
-The lines starting with a minus are changed into a prepend to the
-existing value of
-.Env_var \%$GROFFER_OPT .
-.
-So the configuration files will be transferred into a shell script
-that is called within
-.BR \%groffer .
-.
-.
-.P
-It makes sense to use these configuration files for the following
-tasks:
-.
-.Topic
-Preset command line options, such as choosing a
-.I \%mode
-or a viewer.
-.
-These are written into lines starting with a single or double minus
-sign, followed by the option name.
-.
-.Topic
-Preset environment variables recognized by
-.BR \%groffer ;
-but do not forget to export them.
-.
-.Topic
-You can also write a shell function for calling, for example a viewer
-program for some
-.IR \%mode .
-Such a function can be fed into a corresponding
-.B --\f[I]mode\fP\-viewer
-option.
-.
-.Topic
-Enter
-.B --shell
-to specify a shell for the run of
-.File_name groffer2.sh .
-Some shells run much faster than the standard shell.
-.
-.
-.P
-As an example, consider the following configuration file that can be
-used either in
-.File_name \%/etc/groff/groffer.conf
-or
-.File_name \%~/.groff/groffer.conf .
-.
-.
-.P
-.ft CR
-.nh
-.nf
-# groffer configuration file
-#
-# groffer options that are used in each call of groffer
-\-\-shell=ksh
-\-\-foreground=DarkBlue
-\-\-resolution=100
-\-\-x\-viewer=gxditview \-geometry 900x1200
-#
-# some shell commands
-if test "$DISPLAY" = ""; then
-  export DISPLAY='localhost:0.0'
-fi
-date >>~/mygroffer.log
-.fi
-.hy
-.ft
-.
-.
-.P
-The lines starting with
-.B #
-are just ignored, so they act as command lines.
-.
-This configuration sets four
-.B \%groffer
-options (the lines starting with `\-') and runs two shell commands (the
-rest of the script).
-.
-This has the following effects:
-.
-.
-.Topic
-Use
-.B ksh
-as the shell to run the
-.B \%groffer
-script; if it works it should be faster than the usual
-.BR sh .
-.
-.
-.Topic
-Use a text color of
-.B \%DarkBlue
-in all viewers that support this, such as
-.BR \%gxditview .
-.
-.
-.Topic
-Use a resolution of
-.B 100dpi
-in all viewers that support this, such as
-.BR \%gxditview .
-.
-By this, the default device in
-.I x mode
-is set to
-.BR X100 .
-.
-.
-.Topic
-Force
-.BR \%gxditview (@MAN1EXT@)
-as the
-.I \%x-mode
-viewer using the geometry option for setting the width to
-.B 900px
-and the height to
-.BR 1200px .
-This geometry is suitable for a resolution of
-.BR 100dpi .
-.
-.
-.Topic
-If the environment variable
-.Env_var \%$DISPLAY
-is empty set it to
-.IR localhost:0.0 .
-.
-That allows to start
-.B \%groffer
-in the standard \%\f[CR]X\~Window\fP display, even when the program
-is called from a text console.
-.
-.
-.Topic
-Just for fun, the date of each
-.B \%groffer
-start is written to the file
-.File_name mygroffer.log
-in the home directory.
-.
-.
-.\" --------------------------------------------------------------------
-.SH "EXAMPLES"
-.\" --------------------------------------------------------------------
-.
-The usage of
-.B \%groffer
-is very easy.
-.
-Usually, it is just called with a file name or
-.IR \%man\~page .
-.
-The following examples, however, show that
-.B \%groffer
-has much more fancy capabilities.
-.
-.sp
-.EX
-\fIsh#\fR\~groffer\~/usr/local/share/doc/groff/meintro.ms.gz
-.EE
-.sp
-Decompress, format and display the compressed file
-.File_name meintro.ms.gz
-in the directory
-.File_name /usr/local/share/doc/groff ,
-using the standard viewer
-.B \%gxditview
-as graphical viewer when in \%\f[CR]X\~Window\fP, or the
-.BR \%less (1)
-pager program when not in \%\f[CR]X\~Window\fP.
-.
-.sp
-.EX
-\fIsh#\fR\~groffer\~groff
-.EE
-.sp
-If the file
-.File_name \%./groff
-exists use it as input.
-.
-Otherwise interpret the argument as a search for the
-.I \%man\~page
-named
-.B \%groff
-in the smallest possible
-.IR \%man\~section ,
-being section 1 in this case.
-.
-.sp
-.EX
-\fIsh#\fR\~groffer\~man:groff
-.EE
-.sp
-search for the
-.I \%man\~page
-of
-.B \%groff
-even when the file
-.File_name ./groff
-exists.
-.
-.sp
-.EX
-\fIsh#\fR\~groffer\~groff.7
-\fIsh#\fR\~groffer\~7\~groff
-.EE
-.sp
-search the
-.I \%man\~page
-of
-.B \%groff
-in
-.I \%man\~section
-.BR 7 .
-This section search works only for a digit or a single character from
-a small set.
-.
-.sp
-.EX
-\fIsh#\fR\~groffer\~fb.modes
-.EE
-.sp
-If the file
-.File_name ./fb.modes
-does not exist interpret this as a search for the
-.I \%man\~page
-of
-.BR fb.modes .
-As the extension
-.I \%modes
-is not a single character in classical section style the argument is
-not split to a search for
-.BR fb .
-.
-.sp
-.EX
-\fIsh#\fR\~groffer\~groff\~\[cq]troff(1)\[cq]\~man:roff
-.EE
-.sp
-The arguments that are not existing files are looked-up as the
-following
-.IR \%man\~pages :
-.B \%groff
-(automatic search, should be found in \fIman\fP\~section\~1),
-.B \%troff
-(in section\~1),
-and
-.B \%roff
-(in the section with the lowest number, being\~7 in this case).
-.
-The quotes around
-.nh
-.I \[cq]troff(1)\[cq]
-.hy
-are necessary because the parentheses are special shell characters;
-escaping them with a backslash character
-.I \[rs](
-and
-.I \[rs])
-would be possible, too.
-.
-The formatted files are concatenated and displayed in one piece.
-.
-.sp
-.EX
-\fIsh#\fR\~LANG=de\~groffer\~--man\~--www\~--www-viewer=galeon\~ls
-.EE
-.sp
-Retrieve the German
-.I \%man\~page
-(language
-.IR de )
-for the
-.B ls
-program, decompress it, format it to
-.I \%html
-format
-.nh
-.RI ( \%www\~mode )
-.hy
-and view the result in the web browser
-.BR \%galeon .
-The option
-.B --man
-guarantees that the
-.I \%man\~page
-is retrieved, even when a local file
-.File_name \%ls
-exists in the actual directory.
-.
-.
-.sp
-.EX
-\fIsh#\fR\~groffer\~--source\~'man:roff(7)'
-.EE
-.sp
-Get the
-.I \%man\~page
-called
-.I \%roff
-in \fIman\fP\~section 7, decompress it, and print its unformatted
-content, its source code.
-.
-.
-.sp
-.EX
-\fIsh#\fR\~groffer\~--de-p\~--in\~--ap
-.EE
-.sp
-This is a set of abbreviated arguments, it is determined as
-.br
-.sp
-.EX
-\fIsh#\fR\~groffer\~--debug-params\~--intermediate-output\~--apropos
-.EE
-.sp
-.
-.sp
-.EX
-\fIsh#\fR\~cat\~file.gz\~|\~groffer\~-Z\~-mfoo
-.EE
-.sp
-.
-The file
-.File_name file.gz
-is sent to standard input, this is decompressed, and then this is
-transported to the
-.I \%groff intermediate output mode
-without post-processing
-.RB ( groff
-option
-.BR -Z ),
-using macro package
-.I \%foo
-.RB ( groff
-option
-.BR -m ).
-.
-.
-.sp
-.EX
-\fIsh#\fR\~echo\~'\[rs]f[CB]WOW!'\~|
-> groffer --x --bg red --fg yellow --geometry 200x100 -
-.EX
-.sp
-.
-Display the word \f[CB]WOW!\fP in a small window in constant-width
-bold font, using color yellow on red background.
-.
-.
-.\" --------------------------------------------------------------------
-.SH "COMPATIBILITY"
-.\" --------------------------------------------------------------------
-.
-The
-.B \%groffer
-program consists of two shell scripts.
-.
-.
-.P
-The starting script is the file
-.File_name \%groffer
-that is installed in a
-.File_name bin
-directory.
-.
-It is generated from the source file
-.File_name \%groffer.sh .
-.
-It is just a short starting script without any functions such that it
-can run on very poor shells.
-.
-.
-.P
-The main part of the
-.B \%groffer
-program is the file
-.File_name groffer2.sh
-that is installed in the
-.I groff
-library directory.
-.
-This script can be run under a different shell by using the
-.B \%groffer
-option
-.BR --shell .
-.
-.
-.P
-Both scripts are compatible with both
-\f[CR]GNU\fP and \%\f[CR]POSIX\fP.
-.
-\%\f[CR]POSIX\fP compatibility refers to
-\%\f[CR]IEEE\~P1003.2/D11.2\fP of September 1991, a very early
-version of the \%\f[CR]POSIX\fP standard that is still freely
-available on the Internet at
-.UR http://\:www.funet.fi/\:pub/\:doc/\:posix/\:p1003.2/\:d11.2/\:all
-\%POSIX\~P1003.2\~draft\~11.2
-.UE .
-.
-.
-.P
-Only a restricted set of shell language elements and shell builtins is
-used to achieve even compatibility with some Bourne shells that are
-not fully \%\f[CR]POSIX\fP compatible.
-.
-The
-.B \%groffer
-shell scripts were tested on many shells, including the following
-Bourne shells:
-.BR \%ash (1),
-.BR \%bash (1),
-.BR \%dash (1),
-.BR \%ksh (1),
-.BR \%pdksh (1),
-.BR \%posh (1),
-and
-.BR \%zsh (1).
-So it should work on most actual free and commercial operating
-systems.
-.
-.
-.P
-The shell for the run of
-.File_name groffer2.sh
-can be chosen by the option
-.BR --shell
-on the command line or the environment variable
-.Env_var $GROFF_OPT .
-If you want to add it to one of the
-.B \%groffer
-configuration files you must write a line starting with
-.BR --shell .
-.
-.
-.P
-The
-.B \%groffer
-program provides its own parser for command line arguments that is
-compatible to both \%\f[CR]POSIX\fP
-.BR \%getopts (1)
-and \%\f[CR]GNU\fP
-.BR \%getopt (1).
-It can handle option arguments and file names containing white space
-and a large set of special characters.
-.
-The following standard types of options are supported.
-.
-.
-.Topic
-The option consisting of a single minus
-.B -
-refers to standard input.
-.
-.
-.Topic
-A single minus followed by characters refers to a single character
-option or a combination thereof; for example, the
-.B \%groffer
-short option combination
-.B -Qmfoo
-is equivalent to
-.BR -Q\~\-m\~foo .
-.
-.
-.Topic
-Long options are options with names longer than one character; they
-are always preceded by a double minus.
-.
-An option argument can either go to the next command line argument or
-be appended with an equal sign to the argument; for example,
-.B --long=arg
-is equivalent to
-.BR --long\~arg .
-.
-.
-.Topic
-An argument of
-.B --
-ends option parsing; all further command line arguments are
-interpreted as
-.I \%filespec
-parameters, i.e. file names or constructs for searching
-.IR \%man\~pages ).
-.
-.
-.Topic
-All command line arguments that are neither options nor option
-arguments are interpreted as
-.I \%filespec
-parameters and stored until option parsing has finished.
-.
-For example, the command line
-.sp
-.EX
-\fIsh#\fR\~groffer file1 -a -o arg file2
-.EE
-.sp
-is equivalent to
-.sp
-.EX
-\fIsh#\fR\~groffer -a -o arg -- file1 file2
-.EE
-.sp
-.
-.P
-The free mixing of options and
-.I \%filespec
-parameters follows the GNU principle.
-.
-That does not fulfill the strange option behavior of \%\f[CR]POSIX\fP
-that ends option processing as soon as the first non-option argument
-has been reached.
-.
-The end of option processing can be forced by the option
-.RB ` \-\- '
-anyway.
-.
-.
-.\" --------------------------------------------------------------------
-.SH "BUGS"
-.\" --------------------------------------------------------------------
-.
-Report bugs to the
-.MT bug-groff@gnu.org
-bug-groff mailing list 
-.ME .
-.
-Include a complete, self-contained example that will allow the bug to
-be reproduced, and say which version of
-.B \%groffer
-you are using.
-.
-.
-.P
-You can also use the
-.MT groff@gnu.org
-groff mailing list
-.ME ,
-but you must first subscribe to this list.
-.
-You can do that by visiting the
-.UR http://\:lists.gnu.org/\:mailman/\:listinfo/\:groff
-groff mailing list web page
-.UE .
-.
-.
-.P
-See
-.BR \%groff (@MAN1EXT@)
-for information on availability.
-.
-.
-.\" --------------------------------------------------------------------
-.SH "SEE ALSO"
-.\" --------------------------------------------------------------------
-.
-.P
-.BR \%groff (@MAN1EXT@),
-.BR \%@g@troff (@MAN1EXT@)
-.RS
-Details on the options and environment variables available in
-.BR \%groff ;
-all of them can be used with
-.BR \%groffer .
-.RE
-.
-.
-.TP
-.BR \%groff (@MAN7EXT@)
-Documentation of the
-.I \%groff
-language.
-.
-.
-.TP
-.BR \%grog (@MAN1EXT@)
-Internally,
-.B \%groffer
-tries to guess the
-.B \%groff
-command line options from the input using this program.
-.
-.
-.TP
-.BR groff_out (@MAN5EXT@)
-Documentation on the
-.I \%groff intermediate output
-.nh
-.RI ( ditroff
-output).
-.hy
-.
-.
-.TP
-.BR groff_tmac (@MAN5EXT@)
-Documentation on the
-.I \%groff
-macro files.
-.
-.
-.TP
-.BR \%man (1)
-The standard program to display
-.IR \%man\~pages .
-.
-The information there is only useful if it is the
-.I \%man\~page
-for GNU
-.BR man .
-Then it documents the options and environment variables that are
-supported by
-.BR \%groffer .
-.
-.
-.P
-.BR \%ash (1),
-.BR \%bash (1),
-.BR \%dash (1),
-.BR \%ksh (1),
-.BR \%pdksh (1),
-.BR \%posh (1),
-.BR \%sh (1),
-.BR \%zsh (1)
-.RS
-Bourne shells that were tested with
-.BR \%groffer .
-.RE
-.
-.
-.P
-.BR \%gxditview (@MAN1EXT@),
-.BR \%xditview (1x)
-.RS
-Viewers for
-.BR \%groffer 's
-.IR \%x\~mode .
-.RE
-.
-.
-.P
-.BR \%kpdf (1),
-.BR \%kghostview (1),
-.BR \%evince (1),
-.BR \%ggv (1),
-.BR \%gv (1),
-.BR \%ghostview (1),
-.BR \%gs (1)
-.RS
-Viewers for
-.BR \%groffer 's
-.IR \%ps\~mode .
-.RE
-.
-.
-.P
-.BR \%kpdf (1),
-.BR \%acroread (1),
-.BR \%evince (1),
-.BR \%xpdf (1),
-.BR \%gpdf (1),
-.BR \%kghostview (1),
-.BR \%ggv (1)
-.RS
-Viewers for
-.BR \%groffer 's
-.IR \%pdf\~mode .
-.RE
-.
-.
-.P
-.BR \%kdvi (1),
-.BR \%xdvi (1),
-.BR \%dvilx (1)
-.RS
-Viewers for
-.BR \%groffer 's
-.IR \%dvi\~mode .
-.RE
-.
-.
-.P
-.BR \%konqueror (1),
-.BR \%epiphany (1),
-.BR \%firefox (1),
-.BR \%mozilla (1),
-.BR \%netscape (1),
-.BR \%lynx (1)
-.RS
-Web-browsers for
-.BR \%groffer 's
-.I \%html
-or
-.IR \%www\~mode .
-.RE
-.
-.
-.TP
-.BR \%less (1)
-Standard pager program for the
-.IR \%tty\~mode .
-.
-.
-.P
-.BR \%gzip (1),
-.BR \%bzip2 (1)
-.RS
-The decompression programs supported by
-.BR \%groffer .
-.RE
-.
-.
-.\" --------------------------------------------------------------------
-.SH "AUTHOR"
-.\" --------------------------------------------------------------------
-.author
-.
-.
-.\" --------------------------------------------------------------------
-.SH "COPYING"
-.\" --------------------------------------------------------------------
-.copyleft
-.
-.
-.\" --------------------------------------------------------------------
-.\" Emacs settings
-.\" --------------------------------------------------------------------
-.
-.\" Local Variables:
-.\" mode: nroff
-.\" End:

Index: groffer/shell/groffer.sh
===================================================================
RCS file: groffer/shell/groffer.sh
diff -N groffer/shell/groffer.sh
--- groffer/shell/groffer.sh	22 Jan 2013 00:29:41 -0000	1.5
+++ /dev/null	1 Jan 1970 00:00:00 -0000
@@ -1,384 +0,0 @@
-#! /bin/sh
-
-# groffer - display groff files
-
-# Source file position: <groff-source>/contrib/groffer/groffer.sh
-# Installed position: <prefix>/bin/groffer
-
-# Copyright (C) 2001, 2002, 2003, 2004, 2005, 2006, 2009
-# Free Software Foundation, Inc.
-# Written by Bernd Warken <groff-bernd.warken-72@web.de>.
-
-# Last update: 5 Jan 2009
-
-# 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/>.
-
-########################################################################
-
-export GROFFER_OPT;		# option environment for groffer
-
-export _CONF_FILE_ETC;		# configuration file in /etc
-export _CONF_FILE_HOME;		# configuration file in $HOME
-export _CONF_FILES;		# configuration files
-_CONF_FILE_ETC='/etc/groff/groffer.conf';
-_CONF_FILE_HOME="${HOME}/.groff/groffer.conf";
-_CONF_FILES="${_CONF_FILE_ETC} ${_CONF_FILE_HOME}";
-
-# characters
-
-export _AT;
-export _SP;
-export _SQ;
-export _TAB;
-
-_AT='@';
-_SP=' ';
-_SQ="'";
-_TAB='	';
-
-export _ERROR;
-_ERROR='7';			# for syntax errors; no `-1' in `ash'
-
-# @...@ constructs
-
-export _BEFORE_MAKE;
-if test _@VERSION@_ = _${_AT}VERSION${_AT}_
-then
-  # script before `make'
-  _BEFORE_MAKE='yes';
-else
-  _BEFORE_MAKE='no';
-fi;
-
-export _AT_BINDIR_AT;
-export _AT_G_AT;
-export _AT_LIBDIR_AT;
-export _GROFFER_LIBDIR;
-case "${_BEFORE_MAKE}" in
-yes)
-  self="$0";
-  case "${self}" in
-  /*) :; ;;
-  *)
-    curdir="$(pwd)";
-    case "${curdir}" in
-    */)
-      self="${curdir}${self}";
-      ;;
-    *)
-      self="${curdir}/${self}";
-      ;;
-    esac;
-    ;;
-  esac;
-  groffer_shell_dir="$(dirname ${self})";
-  case "${groffer_shell_dir}" in
-  */) :; ;;
-  *) groffer_shell_dir="${groffer_shell_dir}/";
-  esac;
-  groffer_top_dir="${groffer_shell_dir}../";
-  _AT_G_AT='';
-  _AT_BINDIR_AT="${groffer_shell_dir}";
-  _AT_LIBDIR_AT="${groffer_shell_dir}";
-  _GROFFER_LIBDIR="${_AT_LIBDIR_AT}";
-  _VERSION_SH="${groffer_top_dir}version.sh";
-  ;;
-no)
-  _AT_G_AT='@g@';
-  _AT_BINDIR_AT='@BINDIR@';
-  case "${_AT_BINDIR_AT}" in
-  */) :; ;;
-  *) _AT_BINDIR_AT="${_AT_BINDIR_AT}/";
-  esac;
-  _AT_LIBDIR_AT='@libdir@';
-  case "${_AT_LIBDIR_AT}" in
-  */) :; ;;
-  *) _AT_LIBDIR_AT="${_AT_LIBDIR_AT}/";
-  esac;
-  _GROFFER_LIBDIR="${_AT_LIBDIR_AT}"'groff/groffer/';
-  _VERSION_SH="${_GROFFER_LIBDIR}"'version.sh';
-  ;;
-esac;
-
-if test -f "${_VERSION_SH}"
-then
-  . "${_VERSION_SH}";
-fi;
-
-export _GROFF_VERSION;
-case "${_BEFORE_MAKE}" in
-yes)
-  _GROFF_VERSION="${_GROFF_VERSION_PRESET}";
-  ;;
-no)
-  _GROFF_VERSION='@VERSION@';
-  ;;
-esac;
-
-export _GROFFER2_SH;		# file name of the script that follows up
-_GROFFER2_SH="${_GROFFER_LIBDIR}"'groffer2.sh';
-
-export _GROFFER_SH;		# file name of this shell script
-case "$0" in
-*groffer*)
-  _GROFFER_SH="$0";
-  ;;
-*)
-  echo 'The groffer script should be started directly.' >&2
-  exit 1;
-  ;;
-esac;
-
-export _NULL_DEV;
-if test -c /dev/null
-then
-  _NULL_DEV="/dev/null";
-else
-  _NULL_DEV="NUL";
-fi;
-
-
-# Test of the `$()' construct.
-if test _"$(echo "$(echo 'test')")"_ \
-     != _test_
-then
-  echo 'The "$()" construct did not work.' >&2;
-  exit "${_ERROR}";
-fi;
-
-# Test of sed program
-if test _"$(echo red | sed 's/r/s/')"_ != _sed_
-then
-  echo 'The sed program did not work.' >&2;
-  exit "${_ERROR}";
-fi;
-
-# for some systems it is necessary to set some unset variables to `C'
-# according to Autobook, ch. 22
-for var in LANG LC_ALL LC_MESSAGES LC_CTYPES LANGUAGES
-do
-  if eval test _"\${$var+set}"_ = _set_
-  then
-    eval ${var}='C';
-    eval export ${var};
-  fi;
-done;
-
-
-########################### configuration
-
-# read and transform the configuration files, execute the arising commands
-for f in "${_CONF_FILE_HOME}" "${_CONF_FILE_ETC}"
-do
-  if test -f "$f"
-  then
-    o="";			# $o means groffer option
-    # use "" quotes because of ksh and posh
-    eval "$(cat "$f" | sed -n '
-# Ignore comments
-/^['"${_SP}${_TAB}"']*#/d
-# Delete leading and final space
-s/^['"${_SP}${_TAB}"']*//
-s/['"${_SP}${_TAB}"']*$//
-# Print all lines with shell commands, those not starting with -
-/^[^-]/p
-# Remove all single and double quotes
-s/['"${_SQ}"'"]//g
-# Replace empty arguments
-s/^\(-[^ ]*\)=$/o="${o} \1 '"${_SQ}${_SQ}"'"/p
-# Replace division between option and argument by single space
-s/[='"${_SP}${_TAB}"']['"${_SP}${_TAB}"']*/'"${_SP}"'/
-# Handle lines without spaces
-s/^\(-[^'"${_SP}"']*\)$/o="${o} \1"/p
-# Encircle the remaining arguments with single quotes
-s/^\(-[^ ]*\) \(.*\)$/o="${o} \1 '"${_SQ}"'\2'"${_SQ}"'"/p
-')"
-
-    # Remove leading space
-    o="$(echo "$o" | sed 's/^ *//')";
-    if test _"${o}"_ != __
-    then
-      if test _"{GROFFER_OPT}"_ = __
-      then
-        GROFFER_OPT="${o}";
-      else
-        GROFFER_OPT="${o} ${GROFFER_OPT}";
-      fi;
-    fi;
-  fi;
-done;
-
-# integrate $GROFFER_OPT into the command line; it isn't needed any more
-if test _"${GROFFER_OPT}"_ != __
-then
-  eval set x "${GROFFER_OPT}" '"$@"';
-  shift;
-  GROFFER_OPT='';
-fi;
-
-
-########################### Determine the shell
-
-export _SHELL;
-
-supports_func=no;
-foo() { echo bar; } 2>${_NULL_DEV};
-if test _"$(foo)"_ = _bar_
-then
-  supports_func=yes;
-fi;
-
-# use "``" instead of "$()" for using the case ")" construct
-# do not use "" quotes because of ksh
-_SHELL=`
-  # $x means list.
-  # $s means shell.
-  # The command line arguments are taken over.
-  # Shifting herein does not have an effect outside.
-  export x;
-  case " $*" in
-  *\ --sh*)			# abbreviation for --shell
-    x='';
-    s='';
-    # determine all --shell arguments, store them in $x in reverse order
-    while test $# != 0
-    do
-      case "$1" in
-      --shell|--sh|--she|--shel)
-        if test "$#" -ge 2
-        then
-          s="$2";
-          shift;
-        fi;
-        ;;
-      --shell=*|--sh=*|--she=*|--shel=*)
-        # delete up to first "=" character
-        s="$(echo x"$1" | sed 's/^x[^=]*=//')";
-        ;;
-      *)
-        shift;
-        continue;
-      esac;
-      if test _"${x}"_ = __
-      then
-        x="'${s}'";
-      else
-        x="'${s}' ${x}";
-      fi;
-      shift;
-    done;
-
-    # from all possible shells in $x determine the first being a shell
-    # or being empty
-    s="$(
-      # "" quotes because of posh
-      eval set x "${x}";
-      shift;
-      if test $# != 0
-      then
-        for i
-        do
-          if test _"$i"_ = __
-          then
-            if test _"${supports_func}"_ = _yes_
-            then
-              # use the empty argument as the default shell
-              echo 'standard shell';
-              break;
-            else
-              echo groffer: standard shell does not support functions. >&2;
-              continue;
-            fi;
-          else
-            # test $i on being a shell program;
-            # use this kind of quoting for posh
-            if test _"$(eval "$i -c 'echo ok'" 2>${_NULL_DEV})"_ = _ok_ >&2
-            then
-              # test whether shell supports functions
-              if eval "$i -c 'foo () { exit 0; }; foo'" 2>${_NULL_DEV}
-              then
-                # shell with function support found
-                cat <<EOF
-${i}
-EOF
-                break;
-              else
-                # if not being a shell with function support go on searching
-                echo groffer: argument $i is not a shell \
-with function support. >&2
-                continue;
-              fi;
-            else
-              # if not being a shell go on searching
-              echo groffer: argument $i is not a shell. >&2
-              continue;
-            fi;
-          fi;
-        done;
-      fi;
-    )";
-    if test _"${s}"_ != __
-    then
-      cat <<EOF
-${s}
-EOF
-    fi;
-    ;;
-  esac;
-`
-
-########################### test fast shells for automatic run
-
-if test _"${_SHELL}"_ = __
-then
-  # shell sorted by speed, bash is very slow
-  for s in ksh ash dash pdksh zsh posh sh bash
-  do
-    # test on shell with function support
-    if eval "$s -c 'foo () { exit 0; }; foo'" 2>${_NULL_DEV}
-    then
-      _SHELL="$s";
-      break;
-    fi;
-  done;
-fi;
-
-
-########################### start groffer2.sh
-
-if test _"${_SHELL}"_ = _'standard shell'_
-then
-  _SHELL='';
-fi;
-
-if test _"${_SHELL}"_ = __
-then
-  # no shell found, so start groffer2.sh normally
-  if test _${supports_func}_ = _yes_
-  then
-    eval . "'${_GROFFER2_SH}'" '"$@"';
-    exit;
-  else
-    echo groffer: standard shell does not support functions; no shell works.\
-Get some free working shell such as bash. >&2
-    exit "${_ERROR}";
-  fi;
-else
-  # start groffer2.sh with the found $_SHELL
-  # do not quote $_SHELL to allow arguments
-  eval exec "${_SHELL} '${_GROFFER2_SH}'" '"$@"';
-  exit;
-fi;

Index: groffer/shell/groffer2.sh
===================================================================
RCS file: groffer/shell/groffer2.sh
diff -N groffer/shell/groffer2.sh
--- groffer/shell/groffer2.sh	22 Jan 2013 00:29:42 -0000	1.7
+++ /dev/null	1 Jan 1970 00:00:00 -0000
@@ -1,7312 +0,0 @@
-#! /bin/sh
-
-# groffer - display groff files
-
-# Source file position: <groff-source>/contrib/groffer/shell/groffer2.sh
-# Installed position: <prefix>/lib/groff/groffer/groffer2.sh
-
-# This file should not be run independently.  It is called by
-# `groffer.sh' in the source or by the installed `groffer' program.
-
-# Copyright (C) 2001, 2002, 2003, 2004, 2005, 2006, 2009
-# Free Software Foundation, Inc.
-# Written by Bernd Warken <groff-bernd.warken-72@web.de>.
-
-# Last update: 5 Jan 2009
-
-# 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/>.
-
-
-########################################################################
-#             Test of rudimentary shell functionality
-########################################################################
-
-# Zsh is not Bourne compatible without the following:
-if test -n "$ZSH_VERSION"; then
-  emulate sh
-  NULLCMD=:
-fi
-
-
-########################################################################
-# Test of `unset'
-#
-export _UNSET;
-export _foo;
-_foo=bar;
-_res="$(unset _foo 2>&1)";
-if unset _foo >${_NULL_DEV} 2>&1 && \
-   test _"${_res}"_ = __ && test _"${_foo}"_ = __
-then
-  _UNSET='unset';
-  eval "${_UNSET}" _foo;
-  eval "${_UNSET}" _res;
-else
-  _UNSET=':';
-fi;
-
-
-########################################################################
-# Test of `test'.
-#
-if test a = a && test a != b && test -f "${_GROFFER_SH}"
-then
-  :;
-else
-  echo '"test" did not work.' >&2;
-  exit "${_ERROR}";
-fi;
-
-
-########################################################################
-# Test of `echo' and the `$()' construct.
-#
-if echo '' >${_NULL_DEV}
-then
-  :;
-else
-  echo '"echo" did not work.' >&2;
-  exit "${_ERROR}";
-fi;
-if test _"$(t1="$(echo te)" &&
-            t2="$(echo '')" &&
-            t3="$(echo 'st')" &&
-            echo "${t1}${t2}${t3}")"_ \
-     != _test_
-then
-  echo 'The "$()" construct did not work' >&2;
-  exit "${_ERROR}";
-fi;
-
-
-########################################################################
-# Test of sed program; test in groffer.sh is not valid here.
-#
-if test _"$(echo xTesTx \
-           | sed -n 's/^.\([Tt]e*x*sTT*\).*$/\1/p' \
-           | sed 's|T|t|g')"_ != _test_
-then
-  echo 'The sed program did not work.' >&2;
-  exit "${_ERROR}";
-fi;
-
-
-########################################################################
-# Test of `cat'.
-#
-if test _"$(echo test | cat)"_ != _test_
-then
-  error 'Test of "cat" command failed.';
-fi;
-
-
-########################################################################
-# Test of function definitions.
-#
-_t_e_s_t_f_u_n_c_()
-{
-  return 0;
-}
-
-_test_func()
-{
-  echo test;
-}
-
-if _t_e_s_t_f_u_n_c_ 2>${_NULL_DEV} && \
-   test _"$(_test_func 2>${_NULL_DEV})"_ = _test_
-then
-  :;
-else
-  echo 'Shell '"${_SHELL}"' does not support function definitions.' >&2;
-  exit "${_ERROR}";
-fi;
-
-
-########################################################################
-# landmark (<text>)
-#
-# Print <text> to standard error as a debugging aid.
-#
-# Globals: $_DEBUG_LM
-#
-landmark()
-{
-  if test _"${_DEBUG_LM}"_ = _yes_
-  then
-    echo "LM: $*" >&2;
-  fi;
-} # landmark()
-
-
-########################################################################
-# test for compression.
-#
-export _HAS_COMPRESSION;
-export _HAS_BZIP;
-if test _"$(echo 'test' | gzip -c -d -f - 2>${_NULL_DEV})"_ = _test_
-then
-  _HAS_COMPRESSION='yes';
-  if echo 'test' | bzip2 -c 2>${_NULL_DEV} | bzip2 -t 2>${_NULL_DEV} \
-     && test _"$(echo 'test' | bzip2 -c 2>${_NULL_DEV} \
-                             | bzip2 -d -c 2>${_NULL_DEV})"_ \
-             = _test_
-  then
-    _HAS_BZIP='yes';
-  else
-    _HAS_BZIP='no';
-  fi;
-else
-  _HAS_COMPRESSION='no';
-  _HAS_BZIP='no';
-fi;
-
-
-########################################################################
-#                    debug - diagnostic messages
-########################################################################
-
-export _DEBUG_FUNC_CHECK;
-if test _"${_BEFORE_MAKE}"_ = _yes_
-then
-  _DEBUG_FUNC_CHECK='yes';
-else
-  _DEBUG_FUNC_CHECK='no';
-fi;
-_DEBUG_FUNC_CHECK='no';	# disable function checking
-#_DEBUG_FUNC_CHECK='yes';	# enable function checking
-
-export _DEBUG_STACKS;
-_DEBUG_STACKS='no';		# disable stack output in each function
-#_DEBUG_STACKS='yes';		# enable stack output in each function
-
-export _DEBUG_USER_WITH_STACK;
-_DEBUG_USER_WITH_STACK='no';	# disable stack dump in error_user()
-#_DEBUG_USER_WITH_STACK='yes';	# enable stack dump in error_user()
-
-export _DEBUG_LM;
-_DEBUG_LM='no';			# disable landmark messages
-#_DEBUG_LM='yes';		# enable landmark messages
-
-export _DEBUG_GROG;
-_DEBUG_GROG='no';		# disable grog output
-#_DEBUG_GROG='yes';		# enable grog output
-
-export _DEBUG_KEEP_FILES;
-_DEBUG_KEEP_FILES='no'		# disable file keeping in temporary dir
-#_DEBUG_KEEP_FILES='yes'	# enable file keeping in temporary dir
-
-export _DEBUG_PRINT_PARAMS;
-_DEBUG_PRINT_PARAMS='no';	# disable printing of all parameters
-#_DEBUG_PRINT_PARAMS='yes';	# enable printing of all parameters
-
-export _DEBUG_PRINT_SHELL;
-_DEBUG_PRINT_SHELL='no';	# disable printing of the shell name
-#_DEBUG_PRINT_SHELL='yes';	# enable printing of the shell name
-
-export _DEBUG_PRINT_TMPDIR;
-_DEBUG_PRINT_TMPDIR='no';	# disable printing of the temporary dir
-#_DEBUG_PRINT_TMPDIR='yes';	# enable printing of the temporary dir
-
-export _DEBUG_PRINT_FILENAMES;
-_DEBUG_PRINT_FILENAMES='no';	# disable printing of the found file names
-#_DEBUG_PRINT_FILENAMES='yes';	# enable printing of the found file names
-
-# determine all --debug* options
-case " $*" in
-*\ --deb*|*\ --d*-*)
-  # --debug-* options
-  d=' --debug-all --debug-filenames --debug-func --debug-grog '\
-'--debug-not-func --debug-keep --debug-lm --debug-params '\
-'--debug-shell --debug-stacks --debug-tmpdir --debug-user ';
-  # non-debug options with scheme --d*-*
-  n=' --do-nothing --default-modes --dvi-viewer --dvi-viewer-tty ';
-  for i
-  do
-    case "$i" in
-    --deb|--debu|--debug)
-      _DEBUG_FUNC_CHECK='yes';
-      # _DEBUG_STACKS='yes';
-      _DEBUG_USER_WITH_STACK='yes';
-      # _DEBUG_LM='yes';
-      _DEBUG_GROG='yes';
-      _DEBUG_KEEP_FILES='yes';
-      _DEBUG_PRINT_PARAMS='yes';
-      _DEBUG_PRINT_SHELL='yes';
-      _DEBUG_PRINT_TMPDIR='yes';
-      _DEBUG_PRINT_FILENAMES='yes';
-      continue;
-      ;;
-    --d*-*)
-      # before `-'
-      b="$(echo x"$i" | sed 's/^x--\([^-]*\)-.*$/\1/')";
-      # after `-'
-      a="$(echo x"$i" | sed 's/^x--[^-]*-\(.*\)$/\1/')";
-      ;;
-    *)
-      continue;
-      ;;
-    esac;
-    case "$n" in
-    *\ --$b*-$a*)
-      continue;
-      ;;
-    esac;
-    case "$d" in
-    *\ --$b*-$a*)
-      case "$a" in
-      f|s)			# double --debug-* options
-        continue;
-        ;;
-      esac;
-      # extract whole word of double abbreviation
-      s="$(cat <<EOF | sed -n 's/^.* \(--'"$b"'[^ -]*-'"$a"'[^ ]*\) .*/\1/p'
-$d
-EOF
-)"
-      case "$s" in
-      '') continue; ;;
-      --debug-all)
-        _DEBUG_FUNC_CHECK='yes';
-        _DEBUG_STACKS='yes';
-        _DEBUG_USER_WITH_STACK='yes';
-        _DEBUG_GROG='yes';
-        _DEBUG_LM='yes';
-        _DEBUG_KEEP_FILES='yes';
-        _DEBUG_PRINT_PARAMS='yes';
-        _DEBUG_PRINT_SHELL='yes';
-        _DEBUG_PRINT_TMPDIR='yes';
-        _DEBUG_PRINT_FILENAMES='yes';
-        _DEBUG_PRINT_FILENAMES='yes';
-        ;;
-      --debug-filenames)
-        _DEBUG_PRINT_FILENAMES='yes';
-        ;;
-      --debug-func)
-        _DEBUG_FUNC_CHECK='yes';
-	;;
-      --debug-not-func)
-        _DEBUG_FUNC_CHECK='no';
-        _DEBUG_STACKS='no';
-        _DEBUG_USER_WITH_STACK='no';
-	;;
-      --debug-grog)
-        _DEBUG_GROG='yes';
-	;;
-      --debug-keep)
-        _DEBUG_PRINT_TMPDIR='yes';
-        _DEBUG_KEEP_FILES='yes';
-        ;;
-      --debug-lm)
-        _DEBUG_LM='yes';
-        ;;
-      --debug-params)
-        _DEBUG_PRINT_PARAMS='yes';
-        ;;
-      --debug-shell)
-        _DEBUG_PRINT_SHELL='yes';
-        ;;
-      --debug-stacks)
-        _DEBUG_STACKS='yes';
-        ;;
-      --debug-tmpdir)
-        _DEBUG_PRINT_TMPDIR='yes';
-        ;;
-      --debug-user)
-        _DEBUG_USER_WITH_STACK='yes';
-        ;;
-      esac;
-      ;;
-    esac;
-  done
-  ;;
-esac;
-
-if test _"${_DEBUG_STACKS}"_ = _yes_ || \
-   test _"${_DEBUG_USER_WITH_STACK}"_ = _yes_
-then
-  _DEBUG_FUNC_CHECK='yes';
-fi
-
-if test _"${_DEBUG_PRINT_PARAMS}"_ = _yes_
-then
-  echo "parameters: $@" >&2;
-fi;
-
-if test _"${_DEBUG_PRINT_SHELL}"_ = _yes_
-then
-  if test _"${_SHELL}"_ = __
-  then
-    if test _"${POSIXLY_CORRECT}"_ = _y_
-    then
-      echo 'shell: bash as /bin/sh (none specified)' >&2;
-    else
-      echo 'shell: /bin/sh (none specified)' >&2;
-    fi;
-  else
-    echo "shell: ${_SHELL}" >&2;
-  fi;
-fi;
-
-
-########################################################################
-#                       Environment Variables
-########################################################################
-
-landmark "1: environment variables";
-
-# Environment variables that exist only for this file start with an
-# underscore letter.  Global variables to this file are written in
-# upper case letters, e.g. $_GLOBAL_VARIABLE; temporary variables
-# start with an underline and use only lower case letters and
-# underlines, e.g.  $_local_variable.
-
-#   [A-Z]*     system variables,      e.g. $MANPATH
-#   _[A-Z_]*   global file variables, e.g. $_MAN_PATH
-#   _[a-z_]*   temporary variables,   e.g. $_manpath
-
-# Due to incompatibilities of the `ash' shell, the name of loop
-# variables in `for' must be a single character.
-#   [a-z]      local loop variables,   e.g. $i
-
-# In functions, other writings are used for variables.  As some shells
-# do not support the `local' command a unique prefix in lower case is
-# constructed for each function, most are the abbreviation of the
-# function name.  All variable names start with this prefix.
-#   ${prefix}_[a-z_]*	variable name in a function, e.g. $msm_modes
-
-
-########################################################################
-# read-only variables (global to this file)
-########################################################################
-
-# function return values; `0' means ok; other values are error codes
-export _BAD;
-export _GOOD;
-export _NO;
-export _OK;
-export _YES;
-
-_GOOD='0';			# return ok
-_BAD='1';			# return negatively, error code `1'
-# $_ERROR was already defined as `7' in groffer.sh.
-
-_NO="${_BAD}";
-_YES="${_GOOD}";
-_OK="${_GOOD}";
-
-# quasi-functions, call with `eval', e.g `eval "${return_ok}"'
-export return_ok;
-export return_good;
-export return_bad;
-export return_yes;
-export return_no;
-export return_error;
-export return_var;
-return_ok="func_pop; return ${_OK}";
-return_good="func_pop; return ${_GOOD}";
-return_bad="func_pop; return ${_BAD}";
-return_yes="func_pop; return ${_YES}";
-return_no="func_pop; return ${_NO}";
-return_error="func_pop; return ${_ERROR}";
-return_var="func_pop; return";	# add number, e.g. `eval "${return_var} $n'
-
-
-export _DEFAULT_MODES;
-_DEFAULT_MODES="'pdf' 'html' 'ps' 'x' 'dvi' 'tty'";
-export _DEFAULT_RESOLUTION;
-_DEFAULT_RESOLUTION='75';
-
-export _DEFAULT_TTY_DEVICE;
-_DEFAULT_TTY_DEVICE='latin1';
-
-# _VIEWER_* viewer programs for different modes constructed as lists
-export _VIEWER_DVI_TTY;		# viewer program for dvi mode in tty
-export _VIEWER_DVI_X;		# viewer program for dvi mode in X
-export _VIEWER_HTML_TTY;	# viewer program for html mode in tty
-export _VIEWER_HTML_X;		# viewer program for html mode in X
-export _VIEWER_PDF_TTY;		# viewer program for pdf mode in tty
-export _VIEWER_PDF_X;		# viewer program for pdf mode in X
-export _VIEWER_PS_TTY;		# viewer program for ps mode in tty
-export _VIEWER_PS_X;		# viewer program for ps mode in X
-export _VIEWER_TTY_TTY;		# viewer program for X/x mode in tty
-export _VIEWER_TTY_X;		# viewer program for X/x mode in X
-export _VIEWER_X_TTY;		# viewer program for X/x mode in tty
-export _VIEWER_X_X;		# viewer program for X/x mode in X
-_VIEWER_DVI_TTY="";
-_VIEWER_DVI_X="'kdvi' 'xdvi' 'dvilx'";
-_VIEWER_HTML_TTY="'lynx' 'w3m'";
-_VIEWER_HTML_X="'konqueror' 'epiphany' 'mozilla-firefox' 'firefox' 'mozilla' \
-'netscape' 'galeon' 'opera' 'amaya' 'arena' 'mosaic'";
-_VIEWER_PDF_TTY="";
-_VIEWER_PDF_X="'kpdf' 'acroread' 'evince' 'xpdf -z 150' 'gpdf' \
-'kghostview --scale 1.45' 'ggv'";
-_VIEWER_PS_TTY="";
-_VIEWER_PS_X="'kpdf' 'kghostview --scale 1.45' 'evince' 'ggv' 'gv' \
-'ghostview' 'gs_x11,gs'";
-_VIEWER_TTY_TTY="'less -r -R' 'more' 'pager'";
-_VIEWER_TTY_X="'xless'";
-_VIEWER_X_TTY="";
-_VIEWER_X_X="'gxditview' 'xditview'";
-
-# Search automatically in standard sections `1' to `8', and in the
-# traditional sections `9', `n', and `o'.  On many systems, there
-# exist even more sections, mostly containing a set of man pages
-# special to a specific program package.  These aren't searched for
-# automatically, but must be specified on the command line.
-export _MAN_AUTO_SEC_LIST;
-_MAN_AUTO_SEC_LIST="'1' '2' '3' '4' '5' '6' '7' '8' '9' 'n' 'o'";
-export _MAN_AUTO_SEC_CHARS;
-_MAN_AUTO_SEC_CHARS='[123456789no]';
-
-export _SPACE_SED;
-_SPACE_SED='['"${_SP}${_TAB}"']';
-
-export _SPACE_CASE;
-_SPACE_CASE='[\'"${_SP}"'\'"${_TAB}"']';
-
-export _PROCESS_ID;		# for shutting down the program
-_PROCESS_ID="$$";
-
-export _START_DIR;		# directory at start time of the script
-_START_DIR="$(pwd)";
-
-
-############ the command line options of the involved programs
-#
-# The naming scheme for the options environment names is
-# $_OPTS_<prog>_<length>[_<argspec>]
-#
-# <prog>:    program name GROFFER, GROFF, or CMDLINE (for all
-#            command line options)
-# <length>:  LONG (long options) or SHORT (single character options)
-# <argspec>: ARG for options with argument, NA for no argument;
-#            without _<argspec> both the ones with and without arg.
-#
-# Each option that takes an argument must be specified with a
-# trailing : (colon).
-
-# exports
-export _OPTS_GROFFER_SHORT_NA;
-export _OPTS_GROFFER_SHORT_ARG;
-export _OPTS_GROFFER_LONG_NA;
-export _OPTS_GROFFER_LONG_ARG;
-export _OPTS_GROFF_SHORT_NA;
-export _OPTS_GROFF_SHORT_ARG;
-export _OPTS_GROFF_LONG_NA;
-export _OPTS_GROFF_LONG_ARG;
-export _OPTS_X_SHORT_ARG;
-export _OPTS_X_SHORT_NA;
-export _OPTS_X_LONG_ARG;
-export _OPTS_X_LONG_NA;
-export _OPTS_MAN_SHORT_ARG;
-export _OPTS_MAN_SHORT_NA;
-export _OPTS_MAN_LONG_ARG;
-export _OPTS_MAN_LONG_NA;
-export _OPTS_MANOPT_SHORT_ARG;
-export _OPTS_MANOPT_SHORT_NA;
-export _OPTS_MANOPT_LONG_ARG;
-export _OPTS_MANOPT_LONG_NA;
-export _OPTS_CMDLINE_SHORT_NA;
-export _OPTS_CMDLINE_SHORT_ARG;
-export _OPTS_CMDLINE_LONG_NA;
-export _OPTS_CMDLINE_LONG_ARG;
-
-###### groffer native options
-
-_OPTS_GROFFER_SHORT_NA="'h' 'Q' 'v' 'V' 'X' 'Z'";
-_OPTS_GROFFER_SHORT_ARG="'T'";
-
-_OPTS_GROFFER_LONG_NA="'auto' \
-'apropos' 'apropos-data' 'apropos-devel' 'apropos-progs' \
-'debug' 'debug-all' 'debug-filenames' \
-'debug-func' 'debug-not-func' 'debug-grog' 'debug-keep' 'debug-lm' \
-'debug-params' 'debug-shell' 'debug-stacks' 'debug-tmpdir' 'debug-user' \
-'default' 'do-nothing' 'dvi' 'groff' 'help' 'intermediate-output' 'html' \
-'man' 'no-location' 'no-man' 'no-special' 'pdf' 'ps' 'rv' 'source' \
-'text' 'to-stdout' 'text-device' 'tty' 'tty-device' \
-'version' 'whatis' 'www' 'x' 'X'";
-
-_OPTS_GROFFER_LONG_ARG="\
-'default-modes' 'device' 'dvi-viewer' 'dvi-viewer-tty' 'extension' 'fg' \
-'fn' 'font' 'foreground' 'html-viewer' 'html-viewer-tty' 'mode' \
-'pdf-viewer' 'pdf-viewer-tty' 'print' 'ps-viewer' 'ps-viewer-tty' 'shell' \
-'title' 'tty-viewer' 'tty-viewer-tty' 'www-viewer' 'www-viewer-tty' \
-'x-viewer' 'x-viewer-tty' 'X-viewer' 'X-viewer-tty'";
-
-##### groffer options inhereted from groff
-
-_OPTS_GROFF_SHORT_NA="'a' 'b' 'c' 'C' 'e' 'E' 'g' 'G' 'i' 'k' 'l' 'N' 'p' \
-'R' 's' 'S' 't' 'U' 'z'";
-_OPTS_GROFF_SHORT_ARG="'d' 'f' 'F' 'I' 'K' 'L' 'm' 'M' 'n' 'o' 'P' 'r' \
-'w' 'W'";
-_OPTS_GROFF_LONG_NA="";
-_OPTS_GROFF_LONG_ARG="";
-
-##### groffer options inhereted from the X Window toolkit
-
-_OPTS_X_SHORT_NA="";
-_OPTS_X_SHORT_ARG="";
-
-_OPTS_X_LONG_NA="'iconic' 'rv'";
-
-_OPTS_X_LONG_ARG="'background' 'bd' 'bg' 'bordercolor' 'borderwidth' \
-'bw' 'display' 'fg' 'fn' 'font' 'foreground' 'ft' 'geometry' \
-'resolution' 'title' 'xrm'";
-
-###### groffer options inherited from man
-
-_OPTS_MAN_SHORT_NA="";
-_OPTS_MAN_SHORT_ARG="";
-
-_OPTS_MAN_LONG_NA="'all' 'ascii' 'catman' 'ditroff' \
-'local-file' 'location' 'troff' 'update' 'where'";
-
-_OPTS_MAN_LONG_ARG="'locale' 'manpath' \
-'pager' 'preprocessor' 'prompt' 'sections' 'systems' 'troff-device'";
-
-###### additional options for parsing $MANOPT only
-
-_OPTS_MANOPT_SHORT_NA="'7' 'a' 'c' 'd' 'D' 'f' 'h' 'k' 'l' 't' 'u' \
-'V' 'w' 'Z'";
-_OPTS_MANOPT_SHORT_ARG="'e' 'L' 'm' 'M' 'p' 'P' 'r' 'S' 'T'";
-
-_OPTS_MANOPT_LONG_NA="${_OPTS_MAN_LONG_NA} \
-'apropos' 'debug' 'default' 'help' 'html' 'ignore-case' 'location-cat' \
-'match-case' 'troff' 'update' 'version' 'whatis' 'where' 'where-cat'";
-
-_OPTS_MANOPT_LONG_ARG="${_OPTS_MAN_LONG_NA} \
-'config_file' 'encoding' 'extension' 'locale'";
-
-###### collections of command line options
-
-_OPTS_CMDLINE_SHORT_NA="${_OPTS_GROFFER_SHORT_NA} \
-${_OPTS_GROFF_SHORT_NA} ${_OPTS_X_SHORT_NA} ${_OPTS_MAN_SHORT_NA}";
-_OPTS_CMDLINE_SHORT_ARG="${_OPTS_GROFFER_SHORT_ARG} \
-${_OPTS_GROFF_SHORT_ARG} ${_OPTS_X_SHORT_ARG} ${_OPTS_MAN_SHORT_ARG}";
-
-_OPTS_CMDLINE_LONG_NA="${_OPTS_GROFFER_LONG_NA} \
-${_OPTS_GROFF_LONG_NA} ${_OPTS_X_LONG_NA} ${_OPTS_MAN_LONG_NA}";
-_OPTS_CMDLINE_LONG_ARG="${_OPTS_GROFFER_LONG_ARG} \
-${_OPTS_GROFF_LONG_ARG} ${_OPTS_MAN_LONG_ARG} ${_OPTS_X_LONG_ARG}";
-
-
-########################################################################
-# read-write variables (global to this file)
-########################################################################
-
-export _ALL_PARAMS;		# All options and file name parameters
-export _ADDOPTS_GROFF;		# Transp. options for groff (`eval').
-export _APROPOS_PROG;		# Program to run apropos.
-export _APROPOS_SECTIONS;	# Sections for different --apropos-*.
-export _DISPLAY_MODE;		# Display mode.
-export _DISPLAY_PROG;		# Viewer program to be used for display.
-export _DISPLAY_ARGS;		# X resources for the viewer program.
-export _FILE_NR;		# number for temporary `,file,*'
-export _FILEARGS;		# Stores filespec parameters.
-export _FILESPEC_ARG;		# Stores the actual filespec parameter.
-export _FILESPEC_IS_MAN;	# filespec is for searching a man page
-export _FUNC_STACK;		# Store debugging information.
-export _MACRO_PACKAGES;		# groff's macro packages.
-export _MACRO_PKG;		# Macro package for each found file.
-export _NO_FILESPECS;		# Yes, if there are no filespec arguments.
-export _OUTPUT_FILE_NAME;	# output generated, see main_set_res..()
-export _REG_TITLE_LIST;		# Processed file names.
-export _SOELIM_R;		# option -r for soelim
-export _SPECIAL_FILESPEC;	# Filespec ran for apropos or whatis.
-export _SPECIAL_SETUP;		# Test on setup for apropos or whatis.
-export _VIEWER_BACKGROUND;	# viewer shall be run in the background or not
-# _MAN_* finally used configuration of man searching
-export _MAN_ALL;		# search all man pages per filespec
-export _MAN_ENABLE;		# enable search for man pages
-export _MAN_EXT;		# extension for man pages
-export _MAN_FORCE;		# force file parameter to be man pages
-export _MAN_IS_SETUP;		# setup man variables only once
-export _MAN_LANG;		# language for man pages
-export _MAN_LANG2;		# language for man pages
-export _MAN_PATH;		# search path for man pages as a list
-export _MAN_SEC;		# sections for man pages; sep. `:'
-export _MAN_SEC_CHARS;		# sections for man pages as [] construct
-export _MAN_SEC_LIST;		# sections for man pages as a list
-export _MAN_SYS;		# system names for man pages as a list
-# _MANOPT_* as parsed from $MANOPT
-export _MANOPT_ALL;		# $MANOPT --all
-export _MANOPT_EXTENSION;	# $MANOPT --extension
-export _MANOPT_LANG;		# $MANOPT --locale
-export _MANOPT_PATH;		# $MANOPT --manpath
-export _MANOPT_PAGER;		# $MANOPT --pager
-export _MANOPT_SEC;		# $MANOPT --sections
-export _MANOPT_SYS;		# $MANOPT --systems
-# variables for mode pdf
-export _PDF_DID_NOT_WORK;
-export _PDF_HAS_GS;
-export _PDF_HAS_PS2PDF;
-# _OPT_* as parsed from groffer command line
-export _OPT_ALL;		# display all suitable man pages
-export _OPT_APROPOS;		# call `apropos' program
-export _OPT_BD;			# set border color in some modes
-export _OPT_BG;			# set background color in some modes
-export _OPT_BW;			# set border width in some modes
-export _OPT_DEFAULT_MODES;	# `,'-list of modes when no mode given
-export _OPT_DEVICE;		# device option
-export _OPT_DO_NOTHING;		# do nothing in main_display()
-export _OPT_DISPLAY;		# set X display
-export _OPT_EXTENSION;		# set extension for man page search
-export _OPT_FG;			# set foreground color in some modes
-export _OPT_FN;			# set font in some modes
-export _OPT_GEOMETRY;		# set size and position of viewer in X
-export _OPT_ICONIC;		# -iconic option for X viewers
-export _OPT_LANG;		# set language for man pages
-export _OPT_MODE;		# values: X, tty, Q, Z, ""
-export _OPT_MANPATH;		# manual setting of path for man-pages
-export _OPT_PAGER;		# specify paging program for tty mode
-export _OPT_RESOLUTION;		# set X resolution in dpi
-export _OPT_RV;			# reverse fore- and background colors
-export _OPT_SECTIONS;		# sections for man page search
-export _OPT_STDOUT;		# print mode file to standard output
-export _OPT_SYSTEMS;		# man pages of different OS's
-export _OPT_TITLE;		# title for gxditview window
-export _OPT_TEXT_DEVICE;	# set device for tty mode
-export _OPT_V;			# groff option -V
-export _OPT_VIEWER_DVI;		# viewer program for dvi mode
-export _OPT_VIEWER_HTML;	# viewer program for html mode
-export _OPT_VIEWER_PDF;		# viewer program for pdf mode
-export _OPT_VIEWER_PS;		# viewer program for ps mode
-export _OPT_VIEWER_X;		# viewer program for x mode
-export _OPT_WHATIS;		# print the man description
-export _OPT_XRM;		# specify X resource
-export _OPT_Z;			# groff option -Z
-# _TMP_* temporary directory and files
-export _TMP_DIR;		# groffer directory for temporary files
-export _TMP_CAT;		# stores concatenation of everything
-export _TMP_MAN;		# stores find of man path
-export _TMP_MANSPEC;		# filters man pages with filespec
-export _TMP_STDIN;		# stores stdin, if any
-
-# these variables are preset in section `Preset' after the rudim. test
-
-
-########################################################################
-# Preset and reset of read-write global variables
-########################################################################
-
-# For variables that can be reset by option `--default', see reset().
-
-_FILE_NR=0;
-_FILEARGS='';
-_MACRO_PACKAGES="'-man' '-mdoc' '-me' '-mm' '-mom' '-ms'";
-_SPECIAL_FILESPEC='no';
-_SPECIAL_SETUP='no';
-
-# _TMP_* temporary files
-_TMP_DIR='';
-_TMP_CAT='';
-_TMP_MAN='';
-_TMP_CONF='';
-_TMP_STDIN='';
-
-# variables for mode pdf
-_PDF_DID_NOT_WORK='no';
-_PDF_HAS_GS='no';
-_PDF_HAS_PS2PDF='no';
-
-# option -r for soelim
-if : | soelim -r 2>${_NULL_DEV} >${_NULL_DEV}
-then
-  _SOELIM_R='-r';
-else
-  _SOELIM_R='';
-fi;
-
-########################################################################
-# reset ()
-#
-# Reset the variables that can be affected by options to their default.
-#
-reset()
-{
-  if test "$#" -ne 0
-  then
-    error "reset() does not have arguments.";
-  fi;
-
-  _ADDOPTS_GROFF='';
-  _APROPOS_PROG='';
-  _APROPOS_SECTIONS='';
-  _DISPLAY_ARGS='';
-  _DISPLAY_MODE='';
-  _DISPLAY_PROG='';
-  _MACRO_PKG='';
-  _NO_FILESPECS='';
-  _REG_TITLE_LIST='';
-
-  # _MAN_* finally used configuration of man searching
-  _MAN_ALL='no';
-  _MAN_ENABLE='yes';		# do search for man-pages
-  _MAN_EXT='';
-  _MAN_FORCE='no';		# first local file, then search man page
-  _MAN_IS_SETUP='no';
-  _MAN_LANG='';
-  _MAN_LANG2='';
-  _MAN_PATH='';
-  _MAN_SEC='';
-  _MAN_SEC_CHARS='';
-  _MAN_SEC_LIST='';
-  _MAN_SYS='';
-
-  # _MANOPT_* as parsed from $MANOPT
-  _MANOPT_ALL='no';
-  _MANOPT_EXTENSION='';
-  _MANOPT_LANG='';
-  _MANOPT_PATH='';
-  _MANOPT_PAGER='';
-  _MANOPT_SEC='';
-  _MANOPT_SYS='';
-
-  # _OPT_* as parsed from groffer command line
-  _OPT_ALL='no';
-  _OPT_APROPOS='no';
-  _OPT_BD='';
-  _OPT_BG='';
-  _OPT_BW='';
-  _OPT_DEFAULT_MODES='';
-  _OPT_DEVICE='';
-  _OPT_DISPLAY='';
-  _OPT_DO_NOTHING='no';
-  _OPT_EXTENSION='';
-  _OPT_FG='';
-  _OPT_FN='';
-  _OPT_GEOMETRY='';
-  _OPT_ICONIC='no';
-  _OPT_LANG='';
-  _OPT_MODE='';
-  _OPT_MANPATH='';
-  _OPT_PAGER='';
-  _OPT_RESOLUTION='';
-  _OPT_RV='no';
-  _OPT_SECTIONS='';
-  _OPT_SYSTEMS='';
-  _OPT_STDOUT='no';
-  _OPT_TITLE='';
-  _OPT_TEXT_DEVICE='';
-  _OPT_V='no';
-  _OPT_VIEWER_DVI='';
-  _OPT_VIEWER_PDF='';
-  _OPT_VIEWER_PS='';
-  _OPT_VIEWER_HTML='';
-  _OPT_VIEWER_X='';
-  _OPT_WHATIS='no';
-  _OPT_XRM='';
-  _OPT_Z='no';
-  _VIEWER_BACKGROUND='no';
-}
-
-reset;
-
-
-########################################################################
-#              Preliminary functions for error handling
-########################################################################
-
-landmark "2: preliminary functions";
-
-# These functions do not have a func-check frame.  Basically they could be
-# moved to the functions in alphabetical order.
-
-##############
-# echo1 (<text>*)
-#
-# Output to stdout with final line break.
-#
-# Arguments : arbitrary text including `-'.
-#
-echo1()
-{
-  cat <<EOF
-$@
-EOF
-} # echo1()
-
-
-##############
-# echo2 (<text>*)
-#
-# Output to stderr with final line break.
-#
-# Arguments : arbitrary text including `-'.
-#
-echo2()
-{
-  cat >&2 <<EOF
-$@
-EOF
-} # echo2()
-
-
-
-
-##############
-# clean_up ()
-#
-# Clean up at exit.
-#
-cu_already='no';
-clean_up()
-{
-  cd "${_START_DIR}" >"${_NULL_DEV}" 2>&1;
-  if test _${_DEBUG_KEEP_FILES}_ = _yes_
-  then
-    if test _"$cu_already"_ = _yes_
-    then
-      eval "${return_ok}";
-    fi;
-    cu_already=yes;
-    echo2 "Kept temporary directory ${_TMP_DIR}."
-  else
-    if test _"${_TMP_DIR}"_ != __
-    then
-      if test -e "${_TMP_DIR}"
-      then
-        rm -f -r "${_TMP_DIR}" >${_NULL_DEV} 2>&1;
-      fi;
-    fi;
-  fi;
-  eval "${return_ok}";
-} # clean_up()
-
-
-#############
-# diag (text>*)
-#
-# Output a diagnostic message to stderr.
-#
-diag()
-{
-  echo2 '>>>>>'"$*";
-} # diag()
-
-
-#############
-# error (<text>*)
-#
-# Print an error message to standard error, print the function stack,
-# exit with an error condition.  The argument should contain the name
-# of the function from which it was called.  This is for system errors.
-#
-error()
-{
-  case "$#" in
-    1) echo2 'groffer error: '"$1"; ;;
-    *) echo2 'groffer error: wrong number of arguments in error().'; ;;
-  esac;
-  func_stack_dump;
-  if test _"${_TMP_DIR}"_ != __ && test -d "${_TMP_DIR}"
-  then
-    : >"${_TMP_DIR}"/,error;
-  fi;
-  exit "${_ERROR}";
-} # error()
-
-
-#############
-# error_user (<text>*)
-#
-# Print an error message to standard error; exit with an error condition.
-# The error is supposed to be produced by the user.  So the funtion stack
-# is omitted.
-#
-error_user()
-{
-  case "$#" in
-    1)
-      echo2 'groffer error: '"$1";
-       ;;
-    *)
-      echo2 'groffer error: wrong number of arguments in error_user().';
-      ;;
-  esac;
-  if test _"${_DEBUG_USER_WITH_STACK}"_ = _yes_
-  then
-    func_stack_dump;
-  fi;
-  if test _"${_TMP_DIR}"_ != __ && test -d "${_TMP_DIR}"
-  then
-    : >"${_TMP_DIR}"/,error;
-  fi;
-  exit "${_ERROR}";
-} # error_user()
-
-
-
-#############
-# exit_test ()
-#
-# Test whether the former command ended with error().  Exit again.
-#
-# Globals: $_ERROR
-#
-exit_test()
-{
-  if test "$?" = "${_ERROR}"
-  then
-    exit ${_ERROR};
-  fi;
-  if test _"${_TMP_DIR}"_ != __ && test -f "${_TMP_DIR}"/,error
-  then
-    exit ${_ERROR};
-  fi;
-} # exit_test()
-
-
-########################################################################
-#       Definition of normal Functions in alphabetical order
-########################################################################
-
-landmark "3: functions";
-
-########################################################################
-# apropos_filespec ()
-#
-# Compose temporary file for filspec.
-#
-# Globals:  in: $_OPT_APROPOS, $_SPECIAL_SETUP, $_FILESPEC_ARG,
-#               $_APROPOS_PROG, $_APROPOS_SECTIONS, $_OPT_SECTIONS
-#          out: $_SPECIAL_FILESPEC
-#
-# Variable prefix: af
-#
-apropos_filespec()
-{
-
-  func_check apropos_filespec '=' 0 "$@";
-  if obj _OPT_APROPOS is_yes
-  then
-    if obj _SPECIAL_SETUP is_not_yes
-    then
-      error 'apropos_filespec(): apropos_setup() must be run first.';
-    fi;
-    _SPECIAL_FILESPEC='yes';
-    if obj _NO_FILESPECS is_yes
-    then
-      to_tmp_line '.SH no filespec';
-      eval "${_APROPOS_PROG}" | sed 's/^/\\\&/' >>"${_TMP_CAT}";
-      eval "${return_ok}";
-    fi;
-    eval to_tmp_line \
-      "'.SH $(echo1 "${_FILESPEC_ARG}" | sed 's/[^\\]-/\\-/g')'";
-    exit_test;
-    if obj _APROPOS_SECTIONS is_empty
-    then
-      if obj _OPT_SECTIONS is_empty
-      then
-        s='^.*(..*).*$';
-      else
-        s='^.*(['"$(echo1 "${_OPT_SECTIONS}" | sed 's/://g')"']';
-      fi;
-    else
-      s='^.*(['"${_APROPOS_SECTIONS}"']';
-    fi;
-### apropos_filespec()
-    af_filespec="$(echo1 "${_FILESPEC_ARG}" | sed '
-s,/,\\/,g
-s/\./\\./g
-')";
-    eval "${_APROPOS_PROG}" "'${_FILESPEC_ARG}'" | \
-      sed -n '
-/^'"${af_filespec}"': /s/^\(.*\)$/\\\&\1/p
-/'"$s"'/p
-' | \
-      sort |\
-      sed '
-s/^\(.*(..*).*\)  *-  *\(.*\)$/\.br\n\.TP 15\n\.BR \"\1\"\n\\\&\2/
-' >>"${_TMP_CAT}";
-    eval ${_UNSET} af_filespec;
-    eval "${return_ok}";
-  else
-    eval "${return_bad}";
-  fi;
-} # apropos_filespec()
-
-
-########################################################################
-# apropos_setup ()
-#
-# Setup for the --apropos* options, just 2 global variables are set.
-#
-# Globals:  in: $_OPT_APROPOS
-#          out: $_SPECIAL_SETUP, $_APROPOS_PROG
-#
-apropos_setup()
-{
-  func_check apropos_setup '=' 0 "$@";
-  if obj _OPT_APROPOS is_yes
-  then
-    if is_prog apropos
-    then
-      _APROPOS_PROG='apropos';
-    elif is_prog man
-    then
-      if man --apropos man >${_NULL_DEV} 2>${_NULL_DEV}
-      then
-        _APROPOS_PROG='man --apropos';
-      elif man -k man >${_NULL_DEV} 2>${_NULL_DEV}
-      then
-        _APROPOS_PROG='man -k';
-      fi;
-    fi;
-    if obj _APROPOS_PROG is_empty
-    then
-      error 'apropos_setup(): no apropos program available.';
-    fi;
-    to_tmp_line '.TH GROFFER APROPOS';
-    _SPECIAL_SETUP='yes';
-    if obj _OPT_TITLE is_empty
-    then
-      _OPT_TITLE='apropos';
-    fi;
-    eval "${return_ok}";
-  else
-    eval "${return_bad}";
-  fi;
-} # apropos_setup()
-
-
-########################################################################
-# base_name (<path>)
-#
-# Get the file name part of <path>, i.e. delete everything up to last
-# `/' from the beginning of <path>.  Remove final slashes, too, to get
-# a non-empty output.  The output is constructed according the shell
-# program `basename'.
-#
-# Arguments : 1
-# Output    : the file name part (without slashes)
-#
-# Variable prefix: bn
-#
-base_name()
-{
-  func_check base_name = 1 "$@";
-  bn_name="$1";
-  case "${bn_name}" in
-    */)
-      # delete all final slashes
-      bn_name="$(echo1 "${bn_name}" | sed 's|//*$||')";
-      exit_test;
-      ;;
-  esac;
-  case "${bn_name}" in
-    '')
-      eval ${_UNSET} bn_name;
-      eval "${return_bad}";
-      ;;
-    /)
-      # this is like `basename' does
-      echo1 '/';
-      ;;
-    */*)
-      # delete everything before and including the last slash `/'.
-      echo1 "${bn_name}" | sed 's|^.*//*\([^/]*\)$|\1|';
-      ;;
-    *)
-      obj bn_name echo1;
-      ;;
-  esac;
-  eval ${_UNSET} bn_name;
-  eval "${return_ok}";
-} # base_name()
-
-
-########################################################################
-# cat_z (<file>)
-#
-# Decompress if possible or just print <file> to standard output.
-# gzip, bzip2, and .Z decompression is supported.
-#
-# Arguments: 1, a file name.
-# Output: the content of <file>, possibly decompressed.
-#
-cat_z()
-{
-  func_check cat_z = 1 "$@";
-  case "$1" in
-  '')
-    error 'cat_z(): empty file name.';
-    ;;
-  '-')
-    error 'cat_z(): for standard input use save_stdin().';
-    ;;
-  esac;
-  if is_file "$1"
-  then
-    :;
-  else
-    error 'cat_z(): argument $1 is not a file.';
-  fi;
-  if test -s "$1"
-  then
-    :;
-  else
-    eval "${return_ok}";
-  fi;
-  if obj _HAS_COMPRESSION is_yes
-  then
-    if obj _HAS_BZIP is_yes
-    then
-      # test whether being compressed with bz2
-      if bzip2 -t "$1" 2>${_NULL_DEV}
-      then
-        bzip2 -c -d "$1" 2>${_NULL_DEV};
-        eval "${return_ok}";
-      fi;
-    fi;
-    # if not compressed gzip acts like `cat'
-    gzip -c -d -f "$1" 2>${_NULL_DEV};
-  else
-    cat "$1";
-  fi;
-  eval "${return_ok}";
-} # cat_z()
-
-
-########################################################################
-# clean_up ()
-#
-# Do the final cleaning up before exiting; used by the trap calls.
-#
-# defined above
-
-
-########################################################################
-# diag (<text>*)
-#
-# Print marked message to standard error; useful for debugging.
-#
-# defined above
-
-
-########################################################################
-landmark '4: dir_name()*';
-########################################################################
-
-#######################################################################
-# dir_name (<name>)
-#
-# Get the directory name of <name>.  The output is constructed
-# according to the shell program `dirname'.
-#
-# Arguments : 1
-# Output    : the directory part of <name>
-#
-# Variable prefix: dn
-#
-dir_name()
-{
-  func_check dir_name = 1 "$@";
-  obj_from_output dn_name dir_name_chop "$1";
-  case "${dn_name}" in
-  ''|.)
-    echo1 '.';
-    ;;
-  /)
-    echo1 '/';
-    ;;
-  */*)
-    echo1 "$(echo1 "${dn_name}" | sed 's#/*[^/][^/]*$##')";
-    ;;
-  *)
-    echo1 "${dn_name}";
-    ;;
-  esac;
-  eval "${return_ok}";
-} # dir_name()
-
-
-#######################################################################
-# dir_name_append (<dir> <name>)
-#
-# Append `name' to `dir' with clean handling of `/'.
-#
-# Arguments : 2
-# Output    : the generated new directory name <dir>/<name>
-#
-dir_name_append()
-{
-  func_check dir_name_append = 2 "$@";
-  if is_empty "$1"
-  then
-    echo1 "$2";
-  elif is_empty "$2"
-  then
-    echo1 "$1";
-  else
-    dir_name_chop "$1"/"$2";
-  fi;
-  eval "${return_ok}";
-} # dir_name_append()
-
-
-########################################################################
-# dir_name_chop (<name>)
-#
-# Remove unnecessary slashes from directory name.
-#
-# Argument: 1, a directory name.
-# Output:   path without double, or trailing slashes.
-#
-# Variable prefix: dc
-#
-dir_name_chop()
-{
-  func_check dir_name_chop = 1 "$@";
-  # replace all multiple slashes by a single slash `/'.
-  dc_res="$(echo1 "$1" | sed 's|///*|/|g')";
-  exit_test;
-  case "${dc_res}" in
-  ?*/)
-    # remove trailing slash '/';
-    echo1 "${dc_res}" | sed 's|/$||';
-    ;;
-  *)
-    obj dc_res echo1
-    ;;
-  esac;
-  eval ${_UNSET} dc_res;
-  eval "${return_ok}";
-} # dir_name_chop()
-
-
-########################################################################
-# do_nothing ()
-#
-# Dummy function that does nothing.
-#
-do_nothing()
-{
-  eval return "${_OK}";
-} # do_nothing()
-
-
-########################################################################
-# echo1 (<text>*)
-#
-# Print to standard output with final line break.
-#
-# defined above
-
-
-########################################################################
-# echo2 (<text>*)
-#
-# Print to standard error with final line break.
-#
-# defined above
-
-
-
-########################################################################
-# error (<text>*)
-#
-# Print error message and exit with error code.
-#
-# defined above
-
-
-########################################################################
-# exit_test ()
-#
-# Test whether the former command ended with error().  Exit again.
-#
-# defined above
-
-
-if test _"${_DEBUG_FUNC_CHECK}"_ = _yes_
-then
-
-  #############
-  # func_check (<func_name> <rel_op> <nr_args> "$@")
-  #
-  # This is called at the first line of each function.  It checks the
-  # number of arguments of function <func_name> and registers the
-  # function call to _FUNC_STACK.
-  #
-  # Arguments: >=3
-  #   <func_name>: name of the calling function.
-  #   <rel_op>:    a relational operator: = != < > <= >=
-  #   <nr_args>:   number of arguments to be checked against <operator>
-  #   "$@":        the arguments of the calling function.
-  #
-  # Variable prefix: fc
-  #
-  func_check()
-  {
-    if test "$#" -lt 3
-    then
-      error 'func_check() needs at least 3 arguments.';
-    fi;
-    fc_fname="$1";
-    case "$3" in
-    1)
-      fc_nargs="$3";
-      fc_s='';
-      ;;
-    0|[2-9])
-      fc_nargs="$3";
-      fc_s='s';
-      ;;
-    *)
-      error "func_check(): third argument must be a digit.";
-      ;;
-    esac;
-### func_check()
-    case "$2" in
-    '='|'-eq')
-      fc_op='-eq';
-      fc_comp='exactly';
-      ;;
-    '>='|'-ge')
-      fc_op='-ge';
-      fc_comp='at least';
-      ;;
-    '<='|'-le')
-      fc_op='-le';
-      fc_comp='at most';
-      ;;
-    '<'|'-lt')
-      fc_op='-lt';
-      fc_comp='less than';
-      ;;
-    '>'|'-gt')
-      fc_op='-gt';
-      fc_comp='more than';
-      ;;
-    '!='|'-ne')
-      fc_op='-ne';
-      fc_comp='not';
-      ;;
-### func_check()
-    *)
-      error \
-        'func_check(): second argument is not a relational operator.';
-      ;;
-    esac;
-    shift;
-    shift;
-    shift;
-    if test "$#" "${fc_op}" "${fc_nargs}"
-    then
-      do_nothing;
-    else
-      error "func_check(): \
-${fc_fname}"'() needs '"${fc_comp} ${fc_nargs}"' argument'"${fc_s}"'.';
-    fi;
-    func_push "${fc_fname}";
-    if test _"${_DEBUG_STACKS}"_ = _yes_
-    then
-      echo2 '+++ '"${fc_fname} $@";
-      echo2 '>>> '"${_FUNC_STACK}";
-    fi;
-    eval ${_UNSET} fc_comp;
-    eval ${_UNSET} fc_fname;
-    eval ${_UNSET} fc_nargs;
-    eval ${_UNSET} fc_op;
-    eval ${_UNSET} fc_s;
-  } # func_check()
-
-
-  #############
-  # func_pop ()
-  #
-  # Retrieve the top element from the function stack.  This is called
-  # by every return variable in each function.
-  #
-  # The stack elements are separated by `!'; the popped element is
-  # identical to the original element, except that all `!' characters
-  # were removed.
-  #
-  # Arguments: 1
-  #
-  func_pop()
-  {
-    if test "$#" -ne 0
-    then
-      error 'func_pop() does not have arguments.';
-    fi;
-    case "${_FUNC_STACK}" in
-    '')
-      if test _"${_DEBUG_STACKS}"_ = _yes_
-      then
-        error 'func_pop(): stack is empty.';
-      fi;
-      ;;
-    *!*)
-      # split at first bang `!'.
-      _FUNC_STACK="$(echo1 "${_FUNC_STACK}" | sed 's/^[^!]*!//')";
-      exit_test;
-      ;;
-    *)
-      _FUNC_STACK='';
-      ;;
-    esac;
-    if test _"${_DEBUG_STACKS}"_ = _yes_
-    then
-      echo2 '<<< '"${_FUNC_STACK}";
-    fi;
-  } # func_pop()
-
-
-  #############
-  # func_push (<element>)
-  #
-  # Store another element to the function stack.  This is called by
-  # func_check() at the beginning of each function.
-  #
-  # The stack elements are separated by `!'; if <element> contains a `!'
-  # it is removed first.
-  #
-  # Arguments: 1
-  #
-  # Variable prefix: fp
-  #
-  func_push()
-  {
-    if test "$#" -ne 1
-    then
-      error 'func_push() needs 1 argument.';
-    fi;
-    case "$1" in
-    *'!'*)
-      # remove all bangs `!'.
-      fp_element="$(echo1 "$1" | sed 's/!//g')";
-      exit_test;
-      ;;
-    *)
-      fp_element="$1";
-      ;;
-    esac;
-    if test _"${_FUNC_STACK}"_ = __
-    then
-      _FUNC_STACK="${fp_element}";
-    else
-      _FUNC_STACK="${fp_element}!${_FUNC_STACK}";
-    fi;
-    eval ${_UNSET} fp_element;
-  } # func_push()
-
-
-  #############
-  # func_stack_dump ()
-  #
-  # Print the content of the function stack.  Ignore the arguments.
-  #
-  func_stack_dump()
-  {
-    diag 'call stack(): '"${_FUNC_STACK}";
-  } # func_stack_dump()
-
-else				# $_DEBUG_FUNC_CHECK is not `yes'
-
-  func_check() { return; }
-  func_pop() { return; }
-  func_push() { return; }
-  func_stack_dump() { return; }
-
-fi;				# test of $_DEBUG_FUNC_CHECK
-
-
-########################################################################
-# get_first_essential (<arg>*)
-#
-# Retrieve first non-empty argument.
-#
-# Return  : `1' if all arguments are empty, `0' if found.
-# Output  : the retrieved non-empty argument.
-#
-# Variable prefix: gfe
-#
-get_first_essential()
-{
-  func_check get_first_essential '>=' 0 "$@";
-  if is_equal "$#" 0
-  then
-    eval "${return_ok}";
-  fi;
-  for i
-  do
-    gfe_var="$i";
-    if obj gfe_var is_not_empty
-    then
-      obj gfe_var echo1;
-      eval ${_UNSET} gfe_var;
-      eval "${return_ok}";
-    fi;
-  done;
-  eval ${_UNSET} gfe_var;
-  eval "${return_bad}";
-} # get_first_essential()
-
-
-########################################################################
-landmark '5: is_*()';
-########################################################################
-
-########################################################################
-# is_dir (<name>)
-#
-# Test whether `name' is a readable directory.
-#
-# Arguments : 1
-# Return    : `0' if arg1 is a directory, `1' otherwise.
-#
-is_dir()
-{
-  func_check is_dir '=' 1 "$@";
-  if is_not_empty "$1" && test -d "$1" && test -r "$1"
-  then
-    eval "${return_yes}";
-  fi;
-  eval "${return_no}";
-} # is_dir()
-
-
-########################################################################
-# is_empty (<string>)
-#
-# Test whether <string> is empty.
-#
-# Arguments : <=1
-# Return    : `0' if arg1 is empty or does not exist, `1' otherwise.
-#
-is_empty()
-{
-  func_check is_empty '=' 1 "$@";
-  if test _"$1"_ = __
-  then
-    eval "${return_yes}";
-  fi;
-  eval "${return_no}";
-} # is_empty()
-
-
-########################################################################
-# is_empty_file (<file_name>)
-#
-# Test whether <file_name> is an empty existing file.
-#
-# Arguments : <=1
-# Return    :
-#   `0' if arg1 is an empty existing file
-#   `1' otherwise
-#
-is_empty_file()
-{
-  func_check is_empty_file '=' 1 "$@";
-  if is_file "$1"
-  then
-    if test -s "$1"
-    then
-      eval "${return_no}";
-    else
-      eval "${return_yes}";
-    fi;
-  fi;
-  eval "${return_no}";
-} # is_empty_file()
-
-
-########################################################################
-# is_equal (<string1> <string2>)
-#
-# Test whether <string1> is equal to <string2>.
-#
-# Arguments : 2
-# Return    : `0' both arguments are equal strings, `1' otherwise.
-#
-is_equal()
-{
-  func_check is_equal '=' 2 "$@";
-  if test _"$1"_ = _"$2"_
-  then
-    eval "${return_yes}";
-  fi;
-  eval "${return_no}";
-} # is_equal()
-
-
-########################################################################
-# is_existing (<name>)
-#
-# Test whether <name> is an existing file or directory.  Solaris 2.5 does
-# not have `test -e'.
-#
-# Arguments : 1
-# Return    : `0' if arg1 exists, `1' otherwise.
-#
-is_existing()
-{
-  func_check is_existing '=' 1 "$@";
-  if is_empty "$1"
-  then
-    eval "${return_no}";
-  fi;
-  if test -f "$1" || test -d "$1" || test -c "$1"
-  then
-    eval "${return_yes}";
-  fi;
-  eval "${return_no}";
-} # is_existing()
-
-
-########################################################################
-# is_file (<name>)
-#
-# Test whether <name> is a readable file.
-#
-# Arguments : 1
-# Return    : `0' if arg1 is a readable file, `1' otherwise.
-#
-is_file()
-{
-  func_check is_file '=' 1 "$@";
-  if is_not_empty "$1" && test -f "$1" && test -r "$1"
-  then
-    eval "${return_yes}";
-  fi;
-  eval "${return_no}";
-} # is_file()
-
-
-########################################################################
-# is_greater_than (<integer1> <integer2>)
-#
-# Test whether <integer1> is greater than <integer2>.
-#
-# Arguments : 2
-# Return    : `0' if <integer1> is a greater integer than <integer2>,
-#             `1' otherwise.
-#
-is_greater_than()
-{
-  func_check is_greater_than '=' 2 "$@";
-  if is_integer "$1" && is_integer "$2" && test "$1" -gt "$2"
-  then
-    eval "${return_yes}";
-  fi;
-  eval "${return_no}";
-} # is_greater_than()
-
-
-########################################################################
-# is_integer (<string>)
-#
-# Test whether `string' is an integer.
-#
-# Arguments : 1
-# Return    : `0' if argument is an integer, `1' otherwise.
-#
-is_integer()
-{
-  func_check is_integer '=' 1 "$@";
-  if is_equal "$(echo1 "$1" | sed -n '
-s/^[0-9][0-9]*$/ok/p
-s/^[-+][0-9][0-9]*$/ok/p
-')" 'ok'
-  then
-    eval "${return_yes}";
-  fi;
-  eval "${return_no}";
-} # is_integer()
-
-
-########################################################################
-# is_not_empty_file (<file_name>)
-#
-# Test whether <file_name> is a non-empty existing file.
-#
-# Arguments : <=1
-# Return    :
-#   `0' if arg1 is a non-empty existing file
-#   `1' otherwise
-#
-is_not_empty_file()
-{
-  func_check is_not_empty_file '=' 1 "$@";
-  if is_file "$1" && test -s "$1"
-  then
-    eval "${return_yes}";
-  fi;
-  eval "${return_no}";
-} # is_not_empty_file()
-
-
-########################################################################
-# is_not_dir (<name>)
-#
-# Test whether <name> is not a readable directory.
-#
-# Arguments : 1
-# Return    : `0' if arg1 is a directory, `1' otherwise.
-#
-is_not_dir()
-{
-  func_check is_not_dir '=' 1 "$@";
-  if is_dir "$1"
-  then
-    eval "${return_no}";
-  fi;
-  eval "${return_yes}";
-} # is_not_dir()
-
-
-########################################################################
-# is_not_empty (<string>)
-#
-# Test whether <string> is not empty.
-#
-# Arguments : <=1
-# Return    : `0' if arg1 exists and is not empty, `1' otherwise.
-#
-is_not_empty()
-{
-  func_check is_not_empty '=' 1 "$@";
-  if is_empty "$1"
-  then
-    eval "${return_no}";
-  fi;
-  eval "${return_yes}";
-} # is_not_empty()
-
-
-########################################################################
-# is_not_equal (<string1> <string2>)
-#
-# Test whether <string1> differs from <string2>.
-#
-# Arguments : 2
-#
-is_not_equal()
-{
-  func_check is_not_equal '=' 2 "$@";
-  if is_equal "$1" "$2"
-  then
-    eval "${return_no}";
-  fi
-  eval "${return_yes}";
-} # is_not_equal()
-
-
-########################################################################
-# is_not_file (<filename>)
-#
-# Test whether <filename> is a not readable file.
-#
-# Arguments : 1 (empty allowed)
-#
-is_not_file()
-{
-  func_check is_not_file '=' 1 "$@";
-  if is_file "$1"
-  then
-    eval "${return_no}";
-  fi;
-  eval "${return_yes}";
-} # is_not_file()
-
-
-########################################################################
-# is_not_prog (<program>)
-#
-# Verify that <program> is not a command in $PATH.
-#
-# Arguments : 1,  <program> can have spaces and arguments.
-#
-is_not_prog()
-{
-  func_check is_not_prog '=' 1 "$@";
-  if where_is_prog "$1" >${_NULL_DEV}
-  then
-    eval "${return_no}";
-  fi;
-  eval "${return_yes}";
-} # is_not_prog()
-
-
-########################################################################
-# is_not_writable (<name>)
-#
-# Test whether <name> is not a writable file or directory.
-#
-# Arguments : >=1 (empty allowed), more args are ignored
-#
-is_not_writable()
-{
-  func_check is_not_writable '>=' 1 "$@";
-  if is_writable "$1"
-  then
-    eval "${return_no}";
-  fi;
-  eval "${return_yes}";
-} # is_not_writable()
-
-
-########################################################################
-# is_not_X ()
-#
-# Test whether the script is not running in X Window by checking $DISPLAY.
-#
-is_not_X()
-{
-  func_check is_not_X '=' 0 "$@";
-  if obj DISPLAY is_empty
-  then
-    eval "${return_yes}";
-  fi;
-  eval "${return_no}";
-} # is_not_X()
-
-
-########################################################################
-# is_not_yes (<string>)
-#
-# Test whether <string> is not `yes'.
-#
-# Arguments : 1
-#
-is_not_yes()
-{
-  func_check is_not_yes = 1 "$@";
-  if is_yes "$1"
-  then
-    eval "${return_no}";
-  fi;
-  eval "${return_yes}";
-} # is_not_yes()
-
-
-########################################################################
-# is_prog (<name>)
-#
-# Determine whether <name> is a program in $PATH.
-#
-# Arguments : 1,  <program> can have spaces and arguments.
-#
-is_prog()
-{
-  func_check is_prog '=' 1 "$@";
-  if where_is_prog "$1" >${_NULL_DEV}
-  then
-    eval "${return_yes}";
-  fi;
-  eval "${return_no}";
-} # is_prog()
-
-
-########################################################################
-# is_writable (<name>)
-#
-# Test whether <name> is a writable file or directory.
-#
-# Arguments : >=1 (empty allowed), more args are ignored
-#
-is_writable()
-{
-  func_check is_writable '>=' 1 "$@";
-  if is_empty "$1"
-  then
-    eval "${return_no}";
-  fi;
-  if test -r "$1"
-  then
-    if test -w "$1"
-    then
-      eval "${return_yes}";
-    fi;
-  fi;
-  eval "${return_no}";
-} # is_writable()
-
-
-########################################################################
-# is_X ()
-#
-# Test whether the script is running in X Window by checking $DISPLAY.
-#
-is_X()
-{
-  func_check is_X '=' 0 "$@";
-  if obj DISPLAY is_not_empty
-  then
-    eval "${return_yes}";
-  fi;
-  eval "${return_no}";
-} # is_X()
-
-
-########################################################################
-# is_yes (<string>)
-#
-# Test whether <string> has value `yes'.
-#
-# Return    : `0' if arg1 is `yes', `1' otherwise.
-#
-is_yes()
-{
-  func_check is_yes '=' 1 "$@";
-  if is_equal "$1" 'yes'
-  then
-    eval "${return_yes}";
-  fi;
-  eval "${return_no}";
-} # is_yes()
-
-
-########################################################################
-# landmark ()
-#
-# Print debugging information on standard error if $_DEBUG_LM is `yes'.
-#
-# Globals: $_DEBUG_LM
-#
-# Defined in section `Debugging functions'.
-
-
-########################################################################
-# leave ([<code>])
-#
-# Clean exit without an error or with error <code>.
-#
-leave()
-{
-  clean_up;
-  if test $# = 0
-  then
-    exit "${_OK}";
-  else
-    exit "$1";
-  fi;
-} # leave()
-
-
-########################################################################
-landmark '6: list_*()';
-########################################################################
-#
-# `list' is an object class that represents an array or list.  Its
-# data consists of space-separated single-quoted elements.  So a list
-# has the form "'first' 'second' '...' 'last'".  See list_append() for
-# more details on the list structure.  The array elements of `list'
-# can be get by `eval set x "$list"; shift`.
-
-
-########################################################################
-# list_append (<list> <element>...)
-#
-# Add one or more elements to an existing list.  <list> may also be
-# empty.
-#
-# Arguments: >=2
-#   <list>: a variable name for a list of single-quoted elements
-#   <element>:  some sequence of characters.
-# Output: none, but $<list> is set to
-#   if <list> is empty:  "'<element>' '...'"
-#   otherwise:           "$list '<element>' ..."
-#
-# Variable prefix: la
-#
-list_append()
-{
-  func_check list_append '>=' 2 "$@";
-  la_name="$1";
-  eval la_list='"${'"$1"'}"';
-  shift;
-  for s
-  do
-    la_s="$s";
-    case "${la_s}" in
-    *\'*)
-      # escape each single quote by replacing each
-      # "'" (squote) by "'\''" (squote bslash squote squote);
-      # note that the backslash must be doubled in the following `sed'
-      la_element="$(echo1 "${la_s}" | sed 's/'"${_SQ}"'/&\\&&/g')";
-      exit_test;
-      ;;
-    '')
-      la_element="";
-      ;;
-    *)
-      la_element="${la_s}";
-      ;;
-    esac;
-### list_append()
-    if obj la_list is_empty
-    then
-      la_list="'${la_element}'";
-    else
-      la_list="${la_list} '${la_element}'";
-    fi;
-  done;
-  eval "${la_name}"='"${la_list}"';
-  eval ${_UNSET} la_element;
-  eval ${_UNSET} la_list;
-  eval ${_UNSET} la_name;
-  eval ${_UNSET} la_s;
-  eval "${return_ok}";
-} # list_append()
-
-
-########################################################################
-# list_from_cmdline (<pre_name_of_opt_lists> [<cmdline_arg>...])
-#
-# Transform command line arguments into a normalized form.
-#
-# Options, option arguments, and file parameters are identified and
-# output each as a single-quoted argument of its own.  Options and
-# file parameters are separated by a '--' argument.
-#
-# Arguments: >=1
-#   <pre_name>: common part of a set of 4 environment variable names:
-#     $<pre_name>_SHORT_NA:  list of short options without an arg.
-#     $<pre_name>_SHORT_ARG: list of short options that have an arg.
-#     $<pre_name>_LONG_NA:   list of long options without an arg.
-#     $<pre_name>_LONG_ARG:  list of long options that have an arg.
-#   <cmdline_arg>...: the arguments from a command line, such as "$@",
-#                     the content of a variable, or direct arguments.
-#
-# Output: ['-[-]opt' ['optarg']]... '--' ['filename']...
-#
-# Example:
-#   list_from_cmdline PRE -a f1 -bcarg --lon=larg f2 low larg2
-#     PRE_SHORT_NA="'a' 'b'"
-#     PRE_SHORT_ARG="'c' 'd'"
-#     PRE_LONG_NA="'help' 'version'"
-#     PRE_LONG_ARG="'longer' 'lower'"
-# This will result in printing:
-#   '-a' '-b' '-c' 'arg' '--longer' 'larg' '--lower' 'larg2' '--' 'f1' 'f2'
-#
-#   Use this function in the following way:
-#     eval set x "$(list_from_cmdline PRE_NAME "$@")";
-#     shift;
-#     while test "$1" != '--'; do
-#       case "$1" in
-#       ...
-#       esac;
-#       shift;
-#     done;
-#     shift;         #skip '--'
-#     # all positional parameters ("$@") left are file name parameters.
-#
-# Variable prefix: lfc
-#
-list_from_cmdline()
-{
-  func_check list_from_cmdline '>=' 1 "$@";
-  # short options, no argument
-  obj_from_output lfc_short_n obj_data "$1"_SHORT_NA;
-  # short options, with argument
-  obj_from_output lfc_short_a obj_data "$1"_SHORT_ARG;
-  # long options, no argument
-  obj_from_output lfc_long_n obj_data "$1"_LONG_NA;
-  # long options, with argument
-  obj_from_output lfc_long_a obj_data "$1"_LONG_ARG;
-  if obj lfc_short_n is_empty
-  then
-    error 'list_from_cmdline(): no $'"$1"'_SHORT_NA options.';
-  fi;
-  if obj lfc_short_a is_empty
-  then
-    error 'list_from_cmdline(): no $'"$1"'_SHORT_ARG options.';
-  fi;
-  if obj lfc_long_n is_empty
-  then
-    error 'list_from_cmdline(): no $'"$1"'_LONG_NA options.';
-  fi;
-  if obj lfc_long_a is_empty
-  then
-    error 'list_from_cmdline(): no $'"$1"'_LONG_ARG options.';
-  fi;
-  shift;
-
-  if is_equal "$#" 0
-  then
-    echo1 "'--'"
-    eval ${_UNSET} lfc_fparams;
-    eval ${_UNSET} lfc_short_a;
-    eval ${_UNSET} lfc_short_n;
-### list_from_cmdline()
-    eval ${_UNSET} lfc_long_a;
-    eval ${_UNSET} lfc_long_n;
-    eval ${_UNSET} lfc_result;
-    eval "${return_ok}";
-  fi;
-
-  lfc_fparams='';
-  lfc_result='';
-  while is_greater_than "$#" 0
-  do
-    lfc_arg="$1";
-    shift;
-    case "${lfc_arg}" in
-    --) break; ;;
-    --*=*)
-      # delete leading '--';
-      lfc_with_equal="$(echo1 "${lfc_arg}" | sed 's/^--//')";
-      # extract option by deleting from the first '=' to the end
-      lfc_abbrev="$(echo1 "${lfc_with_equal}" | \
-                    sed 's/^\([^=]*\)=.*$/\1/')";
-      obj_from_output lfc_opt \
-        list_single_from_abbrev lfc_long_a "${lfc_abbrev}";
-      if obj lfc_opt is_empty
-      then
-        error_user "--${lfc_abbrev} is not an option.";
-      else
-        # get the option argument by deleting up to first `='
-        lfc_optarg="$(echo1 "${lfc_with_equal}" | sed 's/^[^=]*=//')";
-        exit_test;
-        list_append lfc_result "--${lfc_opt}" "${lfc_optarg}";
-        continue;
-      fi;
-### list_from_cmdline()
-      ;;
-    --*)
-      # delete leading '--';
-      lfc_abbrev="$(echo1 "${lfc_arg}" | sed 's/^--//')";
-      if list_has lfc_long_n "${lfc_abbrev}"
-      then
-        lfc_opt="${lfc_abbrev}";
-      else
-        obj_from_output lfc_opt \
-          list_single_from_abbrev lfc_long_n "${lfc_abbrev}";
-        if obj lfc_opt is_not_empty && is_not_equal "$#" 0
-        then
-          obj_from_output a \
-            list_single_from_abbrev lfc_long_a "${lfc_abbrev}";
-          if obj a is_not_empty
-          then
-            error_user "The abbreviation ${lfc_arg} \
-has multiple options: --${lfc_opt} and --${a}.";
-          fi;
-        fi;
-      fi; # if list_has lfc_long_n "${lfc_abbrev}"
-      if obj lfc_opt is_not_empty
-      then
-        # long option, no argument
-        list_append lfc_result "--${lfc_opt}";
-        continue;
-      fi;
-      obj_from_output lfc_opt \
-        list_single_from_abbrev lfc_long_a "${lfc_abbrev}";
-      if obj lfc_opt is_not_empty
-      then
-### list_from_cmdline()
-        # long option with argument
-        if is_equal "$#" 0
-        then
-          error_user "no argument for option --${lfc_opt}."
-        fi;
-        list_append lfc_result "--${lfc_opt}" "$1";
-        shift;
-        continue;
-      fi; # if obj lfc_opt is_not_empty
-      error_user "${lfc_arg} is not an option.";
-      ;;
-    -?*)			# short option (cluster)
-      # delete leading `-';
-      lfc_rest="$(echo1 "${lfc_arg}" | sed 's/^-//')";
-      exit_test;
-      while obj lfc_rest is_not_empty
-      do
-        # get next short option from cluster (first char of $lfc_rest)
-        lfc_optchar="$(echo1 "${lfc_rest}" | sed 's/^\(.\).*$/\1/')";
-        # remove first character from ${lfc_rest};
-        lfc_rest="$(echo1 "${lfc_rest}" | sed 's/^.//')";
-        exit_test;
-        if list_has lfc_short_n "${lfc_optchar}"
-        then
-          list_append lfc_result "-${lfc_optchar}";
-          continue;
-        elif list_has lfc_short_a "${lfc_optchar}"
-        then
-          if obj lfc_rest is_empty
-          then
-            if is_greater_than "$#" 0
-            then
-### list_from_cmdline()
-              list_append lfc_result "-${lfc_optchar}" "$1";
-              shift;
-              continue;
-            else
-              error_user "no argument for option -${lfc_optchar}.";
-            fi;
-          else			# rest is the argument
-            list_append lfc_result "-${lfc_optchar}" "${lfc_rest}";
-            lfc_rest='';
-            continue;
-          fi; # if obj lfc_rest is_empty
-        else
-          error_user "unknown option -${lfc_optchar}.";
-        fi; # if list_has lfc_short_n "${lfc_optchar}"
-      done; # while obj lfc_rest is_not_empty
-      ;;
-    *)
-      # Here, $lfc_arg is not an option, so a file parameter.
-      list_append lfc_fparams "${lfc_arg}";
-
-      # Ignore the strange POSIX option handling to end option
-      # parsing after the first file name argument.  To reuse it, do
-      # a `break' here if $POSIXLY_CORRECT of `bash' is not empty.
-      # When `bash' is called as `sh' $POSIXLY_CORRECT is set
-      # automatically to `y'.
-      ;;
-    esac; # case "${lfc_arg}" in
-  done; # while is_greater_than "$#" 0
-  list_append lfc_result '--';
-  if obj lfc_fparams is_not_empty
-  then
-    lfc_result="${lfc_result} ${lfc_fparams}";
-  fi;
-### list_from_cmdline()
-  if is_greater_than "$#" 0
-  then
-    list_append lfc_result "$@";
-  fi;
-  obj lfc_result echo1;
-  eval ${_UNSET} lfc_abbrev;
-  eval ${_UNSET} lfc_fparams;
-  eval ${_UNSET} lfc_short_a;
-  eval ${_UNSET} lfc_short_n;
-  eval ${_UNSET} lfc_long_a;
-  eval ${_UNSET} lfc_long_n;
-  eval ${_UNSET} lfc_result;
-  eval ${_UNSET} lfc_arg;
-  eval ${_UNSET} lfc_opt;
-  eval ${_UNSET} lfc_opt_arg;
-  eval ${_UNSET} lfc_opt_char;
-  eval ${_UNSET} lfc_with_equal;
-  eval ${_UNSET} lfc_rest;
-  eval "${return_ok}";
-} # list_from_cmdline()
-
-
-########################################################################
-# list_from_cmdline_with_minus (<pre_name_of_opt_lists> [<cmdline_arg>...])
-#
-# Transform command line arguments into a normalized form with a double
-# abbreviation before and after an internal `-' sign.
-#
-# Options, option arguments, and file parameters are identified and
-# output each as a single-quoted argument of its own.  Options and
-# file parameters are separated by a `--' argument.
-#
-# Arguments: >=1
-#   <pre_name>: common part of a set of 4 environment variable names:
-#     $<pre_name>_SHORT_NA:  list of short options without an arg.
-#     $<pre_name>_SHORT_ARG: list of short options that have an arg.
-#     $<pre_name>_LONG_NA:   list of long options without an arg.
-#     $<pre_name>_LONG_ARG:  list of long options that have an arg.
-#   <cmdline_arg>...: the arguments from a command line, such as "$@",
-#                     the content of a variable, or direct arguments.
-#
-# Output: ['-[-]opt' ['optarg']]... '--' ['filename']...
-#
-# Example:
-#   list_from_cmdline PRE -a f1 -bcarg --lon=larg --h-n f2 low larg2
-#     PRE_SHORT_NA="'a' 'b'"
-#     PRE_SHORT_ARG="'c' 'd'"
-#     PRE_LONG_NA="'help' 'version' 'hi-non-arg'"
-#     PRE_LONG_ARG="'long-arg' 'low-arg'"
-# This will result in printing:
-#   '-a' '-b' '-c' 'arg' '--long-arg' 'larg' '--hi-non-arg' \
-#     '--low-arg' 'larg2' '--' 'f1' 'f2'
-#
-# Use this function in the following way:
-#   eval set x "$(list_from_cmdline_with_minus PRE_NAME "$@")";
-#   shift;
-#   while test "$1" != '--'; do
-#     case "$1" in
-#     ...
-#     esac;
-#     shift;
-#   done;
-#   shift;         #skip '--'
-#   # all positional parameters ("$@") left are file name parameters.
-#
-# Variable prefix: lfcwm
-#
-list_from_cmdline_with_minus()
-{
-  func_check list_from_cmdline_with_minus '>=' 1 "$@";
-  # short options, no argument
-  obj_from_output lfcwm_short_n obj_data "$1"_SHORT_NA;
-  # short options, with argument
-  obj_from_output lfcwm_short_a obj_data "$1"_SHORT_ARG;
-  # long options, no argument
-  obj_from_output lfcwm_long_n obj_data "$1"_LONG_NA;
-  # long options, with argument
-  obj_from_output lfcwm_long_a obj_data "$1"_LONG_ARG;
-  if obj lfcwm_short_n is_empty
-  then
-    error 'list_from_cmdline(): no $'"$1"'_SHORT_NA options.';
-  fi;
-  if obj lfcwm_short_a is_empty
-  then
-    error 'list_from_cmdline(): no $'"$1"'_SHORT_ARG options.';
-  fi;
-  if obj lfcwm_long_n is_empty
-  then
-    error 'list_from_cmdline(): no $'"$1"'_LONG_NA options.';
-  fi;
-  if obj lfcwm_long_a is_empty
-  then
-    error 'list_from_cmdline(): no $'"$1"'_LONG_ARG options.';
-  fi;
-  shift;
-
-  if is_equal "$#" 0
-  then
-    echo1 "'--'";
-    eval ${_UNSET} lfcwm_short_a;
-    eval ${_UNSET} lfcwm_short_n;
-### list_from_cmdline_with_minus()
-    eval ${_UNSET} lfcwm_long_a;
-    eval ${_UNSET} lfcwm_long_n;
-    eval "${return_ok}";
-  fi;
-  obj_from_output lfcwm_long_both lists_combine lfcwm_long_a lfcwm_long_n;
-  lfcwm_fparams='';
-  lfcwm_result='';
-  while is_greater_than "$#" 0	# command line arguments
-  do
-    lfcwm_arg="$1";
-    shift;
-    lfcwm_optarg='';
-    case "${lfcwm_arg}" in
-    --)
-      break;
-      ;;
-    --*=*)
-      # delete leading '--';
-      lfcwm_with_equal="$(echo1 "${lfcwm_arg}" | sed 's/^--//')";
-      # extract option by deleting from the first '=' to the end
-      lfcwm_abbrev="$(echo1 "${lfcwm_with_equal}" | \
-                    sed 's/^\([^=]*\)=.*$/\1/')";
-      # extract option argument by deleting up to the first '='
-      lfcwm_optarg="$(echo1 "${lfcwm_with_equal}" | \
-                    sed 's/^[^=]*=\(.*\)$/\1/')";
-### list_from_cmdline_with_minus()
-      if list_has lfcwm_long_a "${lfcwm_abbrev}"
-      then
-        lfcwm_opt="${lfcwm_abbrev}";
-      else
-        obj_from_output lfcwm_opt \
-          _search_abbrev lfcwm_long_a "${lfcwm_abbrev}";
-      fi;
-      list_append lfcwm_result "--${lfcwm_opt}" "${lfcwm_optarg}";
-      continue;
-      ;;
-    --*)
-      # delete leading '--';
-      lfcwm_abbrev="$(echo1 "${lfcwm_arg}" | sed 's/^--//')";
-      if list_has lfcwm_long_both "${lfcwm_abbrev}"
-      then
-        lfcwm_opt="${lfcwm_abbrev}";
-      else
-        obj_from_output lfcwm_opt \
-          _search_abbrev lfcwm_long_both "${lfcwm_abbrev}";
-      fi;
-### list_from_cmdline_with_minus()
-      if list_has lfcwm_long_a "${lfcwm_opt}"
-      then
-        if is_equal "$#" 0
-        then
-          error_user "Option ${lfcwm_opt} needs an argument.";
-        fi;
-        lfcwm_optarg="$1";
-        shift;
-        list_append lfcwm_result "--${lfcwm_opt}" "${lfcwm_optarg}";
-      else
-        list_append lfcwm_result "--${lfcwm_opt}";
-      fi;
-      continue;
-      ;;
-    -?*)			# short option (cluster)
-      # delete leading '-';
-      lfcwm_rest="$(echo1 "${lfcwm_arg}" | sed 's/^-//')";
-      while obj lfcwm_rest is_not_empty
-      do
-        # get next short option from cluster (first char of $lfcwm_rest)
-        lfcwm_optchar="$(echo1 "${lfcwm_rest}" | sed 's/^\(.\).*$/\1/')";
-        # remove first character from ${lfcwm_rest};
-        lfcwm_rest="$(echo1 "${lfcwm_rest}" | sed 's/^.//')";
-        if list_has lfcwm_short_n "${lfcwm_optchar}"
-        then
-          list_append lfcwm_result "-${lfcwm_optchar}";
-          continue;
-        elif list_has lfcwm_short_a "${lfcwm_optchar}"
-        then
-          if obj lfcwm_rest is_empty
-          then
-            if is_greater_than "$#" 0
-            then
-### list_from_cmdline_with_minus()
-              list_append lfcwm_result "-${lfcwm_optchar}" "$1";
-              shift;
-              continue;
-            else
-              error_user "no argument for option -${lfcwm_optchar}.";
-            fi;
-          else			# rest is the argument
-            list_append lfcwm_result "-${lfcwm_optchar}" "${lfcwm_rest}";
-            lfcwm_rest='';
-            continue;
-          fi; # if obj lfcwm_rest is_empty
-        else
-          error_user "unknown option -${lfcwm_optchar}.";
-        fi; # if list_has lfcwm_short_n "${lfcwm_optchar}"
-      done; # while obj lfcwm_rest is_not_empty
-      ;;
-    *)
-      # Here, $lfcwm_arg is not an option, so a file parameter.
-      list_append lfcwm_fparams "${lfcwm_arg}";
-
-      # Ignore the strange POSIX option handling to end option
-      # parsing after the first file name argument.  To reuse it, do
-      # a `break' here if $POSIXLY_CORRECT of `bash' is not empty.
-      # When `bash' is called as `sh' $POSIXLY_CORRECT is set
-      # automatically to `y'.
-      ;;
-    esac;
-  done;
-
-  list_append lfcwm_result '--';
-  if obj lfcwm_fparams is_not_empty
-  then
-    lfcwm_result="${lfcwm_result} ${lfcwm_fparams}";
-  fi;
-### list_from_cmdline_with_minus()
-  if is_greater_than "$#" 0
-  then
-    list_append lfcwm_result "$@";
-  fi;
-  obj lfcwm_result echo1;
-  eval ${_UNSET} lfcwm_abbrev;
-  eval ${_UNSET} lfcwm_fparams;
-  eval ${_UNSET} lfcwm_short_a;
-  eval ${_UNSET} lfcwm_short_n;
-  eval ${_UNSET} lfcwm_long_a;
-  eval ${_UNSET} lfcwm_long_both;
-  eval ${_UNSET} lfcwm_long_n;
-  eval ${_UNSET} lfcwm_result;
-  eval ${_UNSET} lfcwm_arg;
-  eval ${_UNSET} lfcwm_opt;
-  eval ${_UNSET} lfcwm_optarg;
-  eval ${_UNSET} lfcwm_optchar;
-  eval ${_UNSET} lfcwm_with_equal;
-  eval ${_UNSET} lfcwm_rest;
-  eval "${return_ok}";
-} # list_from_cmdline_with_minus()
-
-
-# _search_abbrev (<list> <abbrev>)
-#
-# Check whether <list> has an element constructed from the abbreviation
-# <abbrev>.  All `-' in <abbrev> are replaced by `-*'.  This construction
-# is searched first with `<construction>[^-]*'.  If there is more than a
-# single element an error is created.  If none is found `<construction>*'
-# is searched.  Again an error is created for several results.
-# This function was constructed from the former function
-# list_single_from_abbrev().
-#
-# This is a local function of list_from_cmdline_with_minus().
-#
-# Arguments: 2
-#   <list>:   a variable name for a list of single-quoted elements
-#   <abbrev>: some sequence of characters.
-#
-# Output: the found element (always not empty), error when none found.
-#
-# Variable prefix: _sa
-#
-_search_abbrev()
-{
-  func_check _search_abbrev '=' 2 "$@";
-  eval _sa_list='"${'$1'}"';
-  if obj _sa_list is_empty
-  then
-    error "_search_abbrev(): list is empty.";
-  fi;
-
-  _sa_abbrev="$2";
-  if obj _sa_abbrev is_empty
-  then
-    error "_search_abbrev(): abbreviation argument is empty.";
-  fi;
-
-  _sa_case="$(echo1 "${_sa_abbrev}" | sed 's/-/\*-/g')";
-  _sa_opt='';
-  case " ${_sa_list}" in
-  *\ \'${_sa_case}*)		# list has the abbreviation
-    _sa_m1='';
-    _sa_m2='';
-    _sa_nm='';
-    eval set x "${_sa_list}";
-    shift;
-    for i			# over the option list
-    do
-      _sa_i="$i";
-### _search_abbrev() of list_from_cmdline_with_minus()
-      case "${_sa_i}" in
-      ${_sa_case}*-*)
-        if obj _sa_m1 is_empty
-        then
-          _sa_m1="${_sa_i}";
-          continue;
-        fi;
-        _sa_m2="${_sa_i}";
-        continue;
-        ;;
-      ${_sa_case}*)
-        if obj _sa_nm is_empty
-        then
-          _sa_nm="${_sa_i}";
-          continue;
-        fi;
-        error_user "The abbreviation --${_sa_abbrev} has multiple options "\
-"--${_sa_nm} and --${_sa_i}.";
-        ;;
-      esac;
-    done;
-    if obj _sa_nm is_empty
-    then
-      if obj _sa_m2 is_not_empty
-      then
-        error_user "The abbreviation --${_sa_abbrev} has multiple options "\
-"--${_sa_m1} and --${_sa_m2}.";
-      fi;
-### _search_abbrev() of list_from_cmdline_with_minus()
-      if obj _sa_m1 is_not_empty
-      then
-        _sa_opt="${_sa_m1}";
-      fi;
-    else
-      _sa_opt="${_sa_nm}";
-    fi;
-    ;;
-  esac;
-  if obj _sa_opt is_empty
-  then
-    error_user "--${_sa_abbrev} is not an option.";
-  fi;
-  obj _sa_opt echo1;
-  eval "${_UNSET}" _sa_abbrev;
-  eval "${_UNSET}" _sa_case;
-  eval "${_UNSET}" _sa_i;
-  eval "${_UNSET}" _sa_list;
-  eval "${_UNSET}" _sa_m1;
-  eval "${_UNSET}" _sa_m2;
-  eval "${_UNSET}" _sa_nm;
-  eval "${_UNSET}" _sa_opt;
-  eval "${return_ok}";
-} # _search_abbrev() of list_from_cmdline_with_minus()
-
-
-########################################################################
-# list_from_file (<list_name> <file_name>)
-#
-# Extrect the lines from <file_name> and store them as elements to list
-# <list_name>.
-#
-# Arguments: 2
-#   <list_name>: a variable name for output, a list of single-quoted elts
-#   <file_name>: the name of an existing file
-#
-# Variable prefix: lff
-#
-list_from_file()
-{
-  func_check list_from_file '=' 2 "$@";
-  if is_not_file "$2"
-  then
-    eval "${return_bad}";
-  fi;
-  lff_n="$(wc -l "$2" | eval sed "'s/^[ ${_TAB}]*\([0-9]\+\).*$/\1/'")";
-  eval "$1"="''";
-  if obj lff_n is_equal 0
-  then
-    eval "${return_good}";
-  fi;
-  lff_i=0;
-  while obj lff_i is_not_equal "${lff_n}"
-  do
-    lff_i="$(expr "${lff_i}" + 1)";
-    list_append "$1" "$(eval sed -n "'${lff_i}p
-${lff_i}q'" "'$2'")";
-  done;
-  eval "${_UNSET}" lff_i;
-  eval "${_UNSET}" lff_n;
-  eval "${return_good}";
-} # list_from_file()
-
-
-########################################################################
-# list_from_split (<string> <separator_char>)
-#
-# Split <string> by <separator_char> into a list, omitting the separator.
-#
-# Arguments: 2: a <string> that is to be split into parts divided by
-#               character <separator_char>
-# Output: the resulting list string
-#
-# Variable prefix: lfs
-#
-list_from_split()
-{
-  func_check list_from_split = 2 "$@";
-  if is_empty "$1"
-  then
-    eval "${return_ok}";
-  fi;
-  case "$2" in
-  ?)
-    lfs_splitter="$2";
-    ;;
-  '\:')
-    lfs_splitter=':';
-    ;;
-  *)
-    error "list_from_split(): split argument $2 must be a single character.";
-    ;;
-  esac;
-  lfs_list='';
-  lfs_rest="$1";
-  while :
-  do
-    case "${lfs_rest}" in
-    *${lfs_splitter}*)
-      case "${lfs_splitter}" in
-      /)
-        lfs_elt="$(echo1 ${lfs_rest} | sed \
-          's|^\([^'"${lfs_splitter}"']*\)'"${lfs_splitter}"'.*|\1|')";
-        lfs_rest="$(echo1 ${lfs_rest} | sed \
-          's|^[^'"${lfs_splitter}"']*'"${lfs_splitter}"'\(.*\)$|\1|')";
-        ;;
-      *)
-### list_from_split()
-        lfs_elt="$(echo1 ${lfs_rest} | sed \
-          's/^\([^'"${lfs_splitter}"']*\)'"${lfs_splitter}"'.*/\1/')";
-        lfs_rest="$(echo1 ${lfs_rest} | sed \
-          's/^[^'"${lfs_splitter}"']*'"${lfs_splitter}"'\(.*\)$/\1/')";
-        ;;
-      esac;
-      list_append lfs_list "${lfs_elt}"
-      continue;
-      ;;
-    *)
-      list_append lfs_list "${lfs_rest}"
-      break
-      ;;
-    esac;
-  done
-  echo1 "${lfs_list}";
-
-  eval ${_UNSET} lfs_elt;
-  eval ${_UNSET} lfs_list;
-  eval ${_UNSET} lfs_rest;
-  eval ${_UNSET} lfs_splitter;
-  eval "${return_ok}";
-} # list_from_split()
-
-
-########################################################################
-# list_has (<list-name> <element>)
-#
-# Test whether the list <list-name> has the element <element>.
-#
-# Arguments: 2
-#   <list_name>: a variable name for a list of single-quoted elements
-#   <element>:  some sequence of characters.
-#
-# Variable prefix: lh
-#
-list_has()
-{
-  func_check list_has = 2 "$@";
-  eval lh_list='"${'$1'}"';
-  if obj lh_list is_empty
-  then
-    eval "${_UNSET}" lh_list;
-    eval "${return_no}";
-  fi;
-  case "$2" in
-    \'*\')  lh_element=" $2 "; ;;
-    *)      lh_element=" '$2' "; ;;
-  esac;
-  if string_contains " ${lh_list} " "${lh_element}"
-  then
-    eval "${_UNSET}" lh_list;
-    eval "${_UNSET}" lh_element;
-    eval "${return_yes}";
-  else
-    eval "${_UNSET}" lh_list;
-    eval "${_UNSET}" lh_element;
-    eval "${return_no}";
-  fi;
-} # list_has()
-
-
-########################################################################
-# list_has_abbrev (<list_var> <abbrev>)
-#
-# Test whether the list of <list_var> has an element starting with
-# <abbrev>.
-#
-# Arguments: 2
-#   <list_var>: a variable name for a list of single-quoted elements
-#   <abbrev>:   some sequence of characters.
-#
-# Variable prefix: lha
-#
-list_has_abbrev()
-{
-  func_check list_has_abbrev '=' 2 "$@";
-  eval lha_list='"${'$1'}"';
-  if obj lha_list is_empty
-  then
-    eval "${_UNSET}" lha_list;
-    eval "${return_no}";
-  fi;
-  case "$2" in
-  \'*)
-    lha_element="$(echo1 "$2" | sed 's/'"${_SQ}"'$//')";
-    ;;
-  *)
-    lha_element="'$2";
-    ;;
-  esac;
-  if string_contains " ${lha_list}" " ${lha_element}"
-  then
-    eval "${_UNSET}" lha_list;
-    eval "${_UNSET}" lha_element;
-    eval "${return_yes}";
-  else
-    eval "${_UNSET}" lha_list;
-    eval "${_UNSET}" lha_element;
-    eval "${return_no}";
-  fi;
-  eval "${return_ok}";
-} # list_has_abbrev()
-
-
-########################################################################
-# list_has_not (<list> <element>)
-#
-# Test whether <list> has no <element>.
-#
-# Arguments: 2
-#   <list>:    a space-separated list of single-quoted elements.
-#   <element>: some sequence of characters.
-#
-# Variable prefix: lhn
-#
-list_has_not()
-{
-  func_check list_has_not = 2 "$@";
-  eval lhn_list='"${'$1'}"';
-  if obj lhn_list is_empty
-  then
-    eval "${_UNSET}" lhn_list;
-    eval "${return_yes}";
-  fi;
-  case "$2" in
-    \'*\') lhn_element=" $2 "; ;;
-    *)     lhn_element=" '$2' "; ;;
-  esac;
-  if string_contains " ${lhn_list} " "${lhn_element}"
-  then
-    eval "${_UNSET}" lhn_list;
-    eval "${_UNSET}" lhn_element;
-    eval "${return_no}";
-  else
-    eval "${_UNSET}" lhn_list;
-    eval "${_UNSET}" lhn_element;
-    eval "${return_yes}";
-  fi;
-} # list_has_not()
-
-
-########################################################################
-# list_single_from_abbrev (<list-var> <abbrev>)
-#
-# Check whether the list has an element starting with <abbrev>.  If
-# there are more than a single element an error is raised.
-#
-# Arguments: 2
-#   <list-var>: a variable name for a list of single-quoted elements
-#   <abbrev>:   some sequence of characters.
-#
-# Output: the found element.
-#
-# Variable prefix: lsfa
-#
-list_single_from_abbrev()
-{
-  func_check list_single_from_abbrev '=' 2 "$@";
-  eval lsfa_list='"${'$1'}"';
-  if obj lsfa_list is_empty
-  then
-    eval "${_UNSET}" lsfa_list;
-    eval "${return_no}";
-  fi;
-  lsfa_abbrev="$2";
-  if list_has lsfa_list "${lsfa_abbrev}"
-  then
-    obj lsfa_abbrev echo1;
-    eval "${_UNSET}" lsfa_abbrev;
-    eval "${_UNSET}" lsfa_list;
-    eval "${return_yes}";
-  fi;
-  if list_has_abbrev lsfa_list "${lsfa_abbrev}"
-  then
-    lsfa_element='';
-    eval set x "${lsfa_list}";
-    shift;
-### list_single_from_abbrev()
-    for i
-    do
-      case "$i" in
-      ${lsfa_abbrev}*)
-        if obj lsfa_element is_not_empty
-        then
-          error_user "The abbreviation --${lsfa_abbrev} \
-has multiple options: --${lsfa_element} and --${i}.";
-        fi;
-        lsfa_element="$i";
-        ;;
-      esac;
-    done;
-    obj lsfa_element echo1;
-    eval "${_UNSET}" lsfa_abbrev;
-    eval "${_UNSET}" lsfa_element;
-    eval "${_UNSET}" lsfa_list;
-    eval "${return_yes}";
-  else
-    eval "${_UNSET}" lsfa_abbrev;
-    eval "${_UNSET}" lsfa_element;
-    eval "${_UNSET}" lsfa_list;
-    eval "${return_no}";
-  fi;
-} # list_single_from_abbrev()
-
-
-########################################################################
-# list_uniq (<list>)
-#
-# Generate a list with only unique elements.
-#
-# Output: the corrected list
-#
-# Variable prefix: lu
-#
-list_uniq()
-{
-  func_check list_uniq '=' 1 "$@";
-  if is_empty "$1"
-  then
-    eval "${return_ok}";
-  fi;
-  eval a='"${'"$1"'}"';
-  if obj a is_empty
-  then
-    eval "${return_ok}";
-  fi;
-  eval set x "$a";
-  shift;
-  lu_list='';
-  for i
-  do
-    lu_i="$i";
-    if list_has lu_list "${lu_i}"
-    then
-      continue;
-    else
-      list_append lu_list ${lu_i};
-    fi;
-  done;
-  obj lu_list echo1;
-  eval "${_UNSET}" lu_i;
-  eval "${_UNSET}" lu_list;
-  eval "${return_ok}";
-} # list_uniq()
-
-
-########################################################################
-# lists_combine (<list1> <list2> ...)
-#
-# Combine several lists to a single list.  All arguments are list names.
-#
-# Output: the combined list
-#
-# Variable prefix: lc
-#
-lists_combine()
-{
-  func_check lists_combine '>=' 2 "$@";
-  lc_list='';
-  for i
-  do
-    eval lc_arg='"${'"$i"'}"';
-    case "${lc_arg}" in
-    '') :; ;;
-    "'"*"'")
-      if obj lc_list is_empty
-      then
-        lc_list="${lc_arg}";
-      else
-        lc_list="${lc_list} ${lc_arg}";
-      fi;
-      ;;
-    *)
-      error 'lists_combine(): $'"$i"' is not a list.';
-      ;;
-    esac;
-  done;
-  obj lc_list echo1;
-  eval "${_UNSET}" lc_arg;
-  eval "${_UNSET}" lc_list;
-  eval "${return_ok}";
-} # lists_combine()
-
-
-########################################################################
-landmark '7: man_*()';
-########################################################################
-
-########################################################################
-# Information on the search of man pages in groffer
-
-# The search of man pages is based on a set of directories.  That
-# starts with the so-called man path.  This is determined in function
-# man_setup() either by the command-line option --manpath, by $MANOPT,
-# or by $MANPATH.  There is also a program `manpath'.  If all of this
-# does not work a man path is created from $PATH with function
-# manpath_set_from_path().  We now have a set of existing directories
-# for the search of man pages; usually they end with `/man'.
-
-# The directory set of the man path can be changed in 2 ways.  If
-# operating system names are given in $SYSTEM or by --systems on the
-# command-line all man path directory will be appended by these names.
-# The appended system names replace the original man path; but if no
-# system name is set, the original man path is kept.  In `groffer',
-# this is done by the function manpath_add_lang_sys() in man_setup().
-
-# The next addition for directories is the language.  It is specified
-# by --locale or by one of the environment variables $LC_ALL,
-# $LC_MESSAGES, and $LANG.  The language name of `C' or `POSIX' means
-# the return to the default language (usually English); this deletes
-# former language specifications.  The language name and its
-# abbreviation with 2 characters is appended to the man page
-# directories.  But these new arising directories are added to the man
-# page, they do not replace it such as the system names did.  This is
-# done by function manpath_add_lang_sys() in man_setup() as well.
-
-# Now we have the basic set of directories for the search of man pages
-# for given filespec arguments.  The real directories with the man
-# page source files are gotten by appending `man<section>' to each
-# directory, where section is a single character of the form
-# `[1-9on]'.
-
-# There you find files named according to the form
-# <name>.<section>[<extension>][<compression>], where `[]' means
-# optional this time.  <name> is the name of the man page; <section>
-# is the single character from the last paragraphe; the optional
-# <extension> consists of some letters denoting special aspects for
-# the section; and the optional <compression> is something like `.gz',
-# `.Z', or `.bz2', meaning that the file is compressed.
-
-# If name, section. and extension are specified on the command-line
-# the file of the form <name>.<section><extension> with or without
-# <compression> are handled.  The first one found according to the
-# directory set for the section is shown.
-
-# If just name and section are specified on the command-line then
-# first <name>.<section> with or without <compression> are searched.
-# If no matching file was found, <name>.<section><extension> with or
-# without <compression> are searched for all possible extensions.
-
-# If only name is specified on the command-line then the section
-# directories are searched by and by, starting with section `1', until
-# a file is matched.
-
-# The function man_is_man() determines all suitable man files for a
-# command-line argument, while man_get() searches the single matching
-# file for display.
-
-
-########################################################################
-# man_get (<man-name> [<section> [<extension>]])
-#
-# Write a man page to the temporary file.
-#
-# Globals in: $_TMP_MANSPEC, $_MAN_SEC_CHARS, $_MAN_EXT, $_MAN_ALL
-#
-# Arguments: 1, 2, or 3
-#
-# Variable prefix: mg
-#
-man_get()
-{
-  func_check man_get '>=' 1 "$@";
-  if obj _TMP_MANSPEC is_empty
-  then
-    error 'man_get(): man_is_man() must be run first on '"$*".;
-  fi;
-  mg_name="$1";
-  mg_sec="$2";
-  if is_empty "$2"
-  then
-    mg_sec="${_MAN_SEC_CHARS}";	# take care it is not a single section
-  fi;
-  mg_ext="$3";
-  if is_empty "$3"
-  then
-    mg_ext="${_MAN_EXT}";
-  fi;
-  if obj _TMP_MANSPEC is_not_equal "${_TMP_DIR}/,man:$1:${mg_sec}${mg_ext}"
-  then
-    error 'man_get(): $_TMP_MANSPEC does not suit to the arguments '"$*".;
-  fi;
-### man_get()
-
-  if obj _MAN_ALL is_yes
-  then
-    list_from_file mg_list "${_TMP_MANSPEC}";
-    eval set x ${mg_list};
-    shift;
-    mg_ok='no';
-    mg_list='';
-    for f
-    do
-      mg_f="$f";
-      if list_has mg_list "${mg_f}"
-      then
-        continue;
-      else
-        list_append mg_list "${mg_f}";
-      fi;
-### man_get()
-      if obj mg_f is_file
-      then
-        to_tmp "${mg_f}" && mg_ok='yes';
-      fi;
-    done;
-    if obj mg_ok is_yes
-    then
-      register_title man:"${mg_name}";
-    fi;
-    eval ${_UNSET} mg_ext;
-    eval ${_UNSET} mg_f;
-    eval ${_UNSET} mg_list;
-    eval ${_UNSET} mg_name;
-    eval ${_UNSET} mg_sec;
-    eval "${return_ok}";
-  else				# $_MAN_ALL is not 'yes'
-    if is_empty "$2"
-    then			# no section from command line
-      if obj _MAN_SEC_LIST is_empty
-      then
-        m="${_MAN_AUTO_SEC_LIST}"; # list of all sections
-      else
-        m="${_MAN_SEC_LIST}";	# from --sections
-      fi;
-### man_get()
-      for s in $(eval set x $m; shift; echo1 "$@")
-      do
-        mg_s="$s";
-        list_from_file mg_list "${_TMP_MANSPEC}";
-        eval set x ${mg_list};
-        shift;
-        if obj mg_ext is_empty
-        then
-          for f
-          do
-            mg_f="$f";
-            case "${mg_f}" in
-*/man"${mg_s}"/"${mg_name}"."${mg_s}"|*/man"${mg_s}"/"${mg_name}"."${mg_s}".*)
-              if obj mg_f is_file
-              then
-                to_tmp "${mg_f}" && register_title "${mg_name}(${mg_s})";
-                eval ${_UNSET} mg_ext;
-                eval ${_UNSET} mg_f;
-                eval ${_UNSET} mg_list;
-                eval ${_UNSET} mg_name;
-                eval ${_UNSET} mg_s;
-                eval ${_UNSET} mg_sec;
-                eval "${return_ok}";
-              fi;
-              ;;
-             esac;		# "$mg_f"
-          done;			# for f
-        fi;			# mg_ext is_empty
-### man_get()
-        for f
-        do
-          mg_f="$f";
-          case "${mg_f}" in
-          */man"${mg_s}"/"${mg_name}"."${mg_s}""${mg_ext}"*)
-            if obj mg_f is_file
-            then
-              to_tmp "${mg_f}" && register_title "${mg_name}(${mg_s})";
-              eval ${_UNSET} mg_ext;
-              eval ${_UNSET} mg_f;
-              eval ${_UNSET} mg_list;
-              eval ${_UNSET} mg_name;
-              eval ${_UNSET} mg_s;
-              eval ${_UNSET} mg_sec;
-              eval "${return_ok}";
-            fi;
-            ;;
-           esac;		# "$mg_f"
-        done;			# for f
-      done;			# for s
-    else			# $mg_sec is not empty, do with section
-      list_from_file mg_list "${_TMP_MANSPEC}";
-      eval set x ${mg_list};
-      shift;
-      if obj mg_ext is_empty
-      then
-        for f
-        do
-          mg_f="$f";
-### man_get()
-          case "${mg_f}" in
-*/man"${mg_sec}"/"${mg_name}"."${mg_sec}"|\
-*/man"${mg_sec}"/"${mg_name}"."${mg_sec}".*)
-            if obj mg_f is_file
-            then
-              obj mg_f to_tmp && \
-                register_title "${mg_name}(${mg_sec})";
-              eval ${_UNSET} mg_ext;
-              eval ${_UNSET} mg_f;
-              eval ${_UNSET} mg_list;
-              eval ${_UNSET} mg_name;
-              eval ${_UNSET} mg_s;
-              eval ${_UNSET} mg_sec;
-              eval "${return_ok}";
-            fi;
-            ;;
-          esac;
-        done;			# for f
-        for f
-        do
-          mg_f="$f";
-### man_get()
-          case "${mg_f}" in
-*/man"${mg_sec}"/"${mg_name}"."${mg_sec}"*)
-            if obj mg_f is_file
-            then
-              obj mg_f to_tmp && \
-                register_title "${mg_name}(${mg_sec})";
-              eval ${_UNSET} mg_ext;
-              eval ${_UNSET} mg_f;
-              eval ${_UNSET} mg_list;
-              eval ${_UNSET} mg_name;
-              eval ${_UNSET} mg_s;
-              eval ${_UNSET} mg_sec;
-              eval "${return_ok}";
-            fi;
-            ;;
-          esac;
-        done;			# for f
-      else			# mg_ext is not empty
-        for f
-        do
-          mg_f="$f";
-### man_get()
-          case "${mg_f}" in
-*/man"${mg_sec}"/"${mg_name}"."${mg_sec}""${mg_ext}"|\
-*/man"${mg_sec}"/"${mg_name}"."${mg_sec}""${mg_ext}".*)
-            if obj mg_f is_file
-            then
-              obj mg_f to_tmp && \
-                register_title "${mg_name}(${mg_sec}${mg_ext})";
-              eval ${_UNSET} mg_ext;
-              eval ${_UNSET} mg_f;
-              eval ${_UNSET} mg_list;
-              eval ${_UNSET} mg_name;
-              eval ${_UNSET} mg_s;
-              eval ${_UNSET} mg_sec;
-              eval "${return_ok}";
-            fi;
-            ;;
-          esac;
-        done;			# for f
-        for f
-        do
-          mg_f="$f";
-### man_get()
-          case "${mg_f}" in
-          */man"${mg_sec}"/"${mg_name}"."${mg_sec}""${mg_ext}"*)
-            if obj mg_f is_file
-            then
-              obj mg_f to_tmp && \
-                register_title "${mg_name}(${mg_sec}${mg_ext})";
-              eval ${_UNSET} mg_ext;
-              eval ${_UNSET} mg_f;
-              eval ${_UNSET} mg_list;
-              eval ${_UNSET} mg_name;
-              eval ${_UNSET} mg_s;
-              eval ${_UNSET} mg_sec;
-              eval "${return_ok}";
-            fi;
-            ;;
-          esac;
-        done;			# for f
-      fi;
-    fi;				# $mg_sec
-  fi;				# $_MAN_ALL
-
-  eval ${_UNSET} mg_ext;
-  eval ${_UNSET} mg_f;
-  eval ${_UNSET} mg_list;
-  eval ${_UNSET} mg_name;
-  eval ${_UNSET} mg_sec;
-  eval ${_UNSET} mg_s;
-  eval "${return_ok}";
-} # man_get()
-
-
-########################################################################
-# man_is_man (<man-name> [<section> [<extension>]])
-#
-# Test whether <man-name> exists as man page.
-#
-# Globals: in: $_TMP_MAN, $_MAN_SEC_CHARS, $_TMP_DIR, $_MAN_EXT,
-#              $_MAN_AUTO_SEC_CHARS
-#         out: $_TMP_MANSPEC
-#
-# Arguments: 1, 2, or 3
-#
-# Variable prefix: mim
-#
-man_is_man()
-{
-  func_check man_is_man '>=' 1 "$@";
-  if is_empty "$1"
-  then
-    _TMP_MANSPEC='';
-    eval "${return_no}";
-  fi;
-  if obj _TMP_DIR is_empty
-  then
-    error 'man_is_man(): main_init() must be run first.';
-  fi;
-  if obj _MAN_IS_SETUP is_not_yes
-  then
-    error 'man_is_man(): man_setup() must be run first.';
-  fi;
-  mim_sec="$2";
-  if is_empty "$2"
-  then
-    mim_sec="${_MAN_SEC_CHARS}";
-  fi;
-  if is_empty "$3"
-  then
-    mim_ext="${_MAN_EXT}";
-  else
-    mim_ext="$3";
-  fi;
-  _TMP_MANSPEC="${_TMP_DIR}/,man:$1:${mim_sec}${mim_ext}";
-### man_is_man()
-  if obj _TMP_MANSPEC is_not_file
-  then
-    if obj mim_sec is_empty
-    then
-      m="${_MAN_AUTO_SEC_CHARS}";
-      eval grep "'/man$m/$1\.$m${mim_ext}'" \
-           "${_TMP_MAN}" > "${_TMP_MANSPEC}";
-    else
-      eval grep "'/man${mim_sec}/$1\.${mim_sec}${mim_ext}'" \
-           "${_TMP_MAN}" > "${_TMP_MANSPEC}";
-    fi;
-  fi;
-  eval ${_UNSET} mim_ext;
-  eval ${_UNSET} mim_sec;
-  if obj _TMP_MANSPEC is_empty_file
-  then
-    rm_file_with_debug "${_TMP_MANSPEC}";
-    eval "${return_no}";
-  else
-    eval "${return_yes}";
-  fi;
-} # man_is_man()
-
-
-########################################################################
-# man_setup ()
-#
-# Setup the variables $_MAN_* needed for man page searching.
-#
-# Globals:
-#   in:     $_OPT_*, $_MANOPT_*, $LANG, $LC_MESSAGES, $LC_ALL,
-#           $MANPATH, $MANSEC, $PAGER, $SYSTEM, $MANOPT.
-#   out:    $_MAN_PATH, $_MAN_LANG, $_MAN_SYS, $_MAN_LANG, $_MAN_LANG2,
-#           $_MAN_SEC, $_MAN_ALL, $_TMP_MAN
-#   in/out: $_MAN_ENABLE
-#
-# The precedence for the variables related to `man' is that of GNU
-# `man', i.e.
-#
-# $LANG; overridden by
-# $LC_MESSAGES; overridden by
-# $LC_ALL; this has the same precedence as
-# $MANPATH, $MANSEC, $PAGER, $SYSTEM; overridden by
-# $MANOPT; overridden by
-# the groffer command line options.
-#
-# $MANROFFSEQ is ignored because grog determines the preprocessors.
-#
-# Variable prefix: ms
-#
-man_setup()
-{
-  func_check man_setup '=' 0 "$@";
-
-  if obj _MAN_IS_SETUP is_yes
-  then
-    eval "${return_ok}";
-  fi;
-  _MAN_IS_SETUP='yes';
-
-  if obj _MAN_ENABLE is_not_yes
-  then
-    eval "${return_ok}";
-  fi;
-
-  # determine basic path for man pages
-  obj_from_output ms_path \
-    get_first_essential "${_OPT_MANPATH}" "${_MANOPT_PATH}" "${MANPATH}";
-  if obj ms_path is_empty && is_prog 'manpath'
-  then
-    obj_from_output ms_path manpath 2>${_NULL_DEV}; # not always available
-  fi;
-  if obj ms_path is_empty
-  then
-    manpath_set_from_path;
-  else
-    obj_from_output _MAN_PATH path_list "${ms_path}";
-  fi;
-  if obj _MAN_PATH is_empty
-  then
-    _MAN_ENABLE="no";
-    echo2 "man_setup(): man path is empty";
-    eval ${_UNSET} ms_path;
-    eval "${return_ok}";
-  fi;
-  obj_from_output _MAN_PATH list_uniq _MAN_PATH;
-### man_setup()
-
-  if obj _MAN_ALL is_not_yes
-  then
-    if obj _OPT_ALL is_yes || obj _MANOPT_ALL is_yes
-    then
-      _MAN_ALL='yes';
-    else
-      _MAN_ALL='no';
-    fi;
-  fi;
-
-  ms_sys="$(get_first_essential \
-              "${_OPT_SYSTEMS}" "${_MANOPT_SYS}" "${SYSTEM}")";
-  if obj ms_sys is_not_empty
-  then
-    obj_from_output _MAN_SYS list_from_split "${ms_sys}" ',';
-  fi;
-
-  obj_from_output ms_lang get_first_essential \
-           "${_OPT_LANG}" "${LC_ALL}" "${LC_MESSAGES}" "${LANG}";
-  case "${ms_lang}" in
-    C|POSIX)
-      _MAN_LANG="";
-      _MAN_LANG2="";
-      ;;
-    ?)
-      _MAN_LANG="${ms_lang}";
-      _MAN_LANG2="";
-      ;;
-    ??)
-      _MAN_LANG="${ms_lang}";
-      _MAN_LANG2="${ms_lang}";
-      ;;
-### man_setup()
-    *)
-      _MAN_LANG="${ms_lang}";
-      # get first two characters of $ms_lang
-      _MAN_LANG2="$(echo1 "${ms_lang}" | sed 's/^\(..\).*$/\1/')";
-      exit_test;
-      ;;
-  esac;
-  # from now on, use only $_MAN_LANG*, forget about $_OPT_LANG, $LC_*.
-
-  manpath_add_lang_sys;
-  obj_from_output _MAN_PATH list_uniq _MAN_PATH;
-
-  obj_from_output _MAN_SEC get_first_essential \
-    "${_OPT_SECTIONS}" "${_MANOPT_SEC}" "${MANSEC}";
-  _MAN_SEC_LIST="";
-  _MAN_SEC_CHARS="";
-  case "${_MAN_SEC}" in
-  *:*)
-    eval set x "$(list_from_split "${_MAN_SEC}" :)";
-    shift;
-    for s
-    do
-      if list_has _MAN_AUTO_SEC_LIST "$s"
-      then
-        list_append _MAN_SEC_LIST "$s";
-        _MAN_SEC_CHARS="${_MAN_SEC_CHARS}$s";
-      fi;
-    done
-    if obj _MAN_SEC_CHARS is_not_empty
-    then
-      _MAN_SEC_CHARS="[${_MAN_SEC_CHARS}]";
-    fi;
-    ;;
-  *)
-    if list_has _MAN_AUTO_SEC_LIST "${_MAN_SEC}"
-    then
-      list_append _MAN_SEC_LIST "${_MAN_SEC}";
-      _MAN_SEC_CHARS="[${_MAN_SEC}]";
-    fi;
-    ;;
-  esac;
-
-### man_setup()
-  obj_from_output _MAN_EXT get_first_essential \
-    "${_OPT_EXTENSION}" "${_MANOPT_EXTENSION}" "${EXTENSION}";
-
-  _TMP_MAN="$(tmp_create man)";
-
-  eval set x "${_MAN_PATH}";
-  shift;
-  if is_not_equal "$#" 0
-  then
-    for i
-    do
-      for j in "$i"/man*
-      do
-        if obj j is_dir
-	then
-          find "$j" >>"${_TMP_MAN}";
-        fi;
-      done
-    done;
-  fi;
-
-  eval ${_UNSET} ms_lang;
-  eval ${_UNSET} ms_list;
-  eval ${_UNSET} ms_path;
-  eval ${_UNSET} ms_sys;
-  eval "${return_ok}";
-} # man_setup()
-
-
-########################################################################
-landmark '8: manpath_*()';
-########################################################################
-
-########################################################################
-# manpath_add_lang_sys ()
-#
-# Add language and operating system specific directories to man path.
-#
-# Arguments : 0
-# Output    : none
-# Globals:
-#   in:     $_MAN_SYS: a list of names of operating systems.
-#           $_MAN_LANG and $_MAN_LANG2: each a single name
-#   in/out: $_MAN_PATH: list of directories which shall have the `man?'
-#             subdirectories.
-#
-# Variable prefix: mals
-#
-manpath_add_lang_sys()
-{
-  func_check manpath_add_lang_sys '=' 0 "$@";
-  if obj _MAN_PATH is_empty
-  then
-    eval "${return_ok}";
-  fi;
-  if obj _MAN_SYS is_empty
-  then
-    mals_mp="${_MAN_PATH}";
-  else
-    mals_mp='';
-    eval set x "${_MAN_SYS}";
-    shift;
-    for s
-    do
-      _manpath_add_sys "$s";
-    done;
-  fi;
-
-  if obj mals_mp is_not_empty
-  then
-    mals_lang_path='';
-    if is_equal "$_MAN_LANG" "$_MAN_LANG2"
-    then
-      mals_man_lang2='';
-    else
-      mals_man_lang2="${_MAN_LANG2}";
-    fi;
-    for i in "${_MAN_LANG}" "${mals_man_lang2}"
-    do
-      if obj i is_empty
-      then
-        continue;
-      fi;
-### manpath_add_lang_sys()
-      mals_lang="$i";
-      eval set x "${mals_mp}";
-      shift;
-      for p
-      do
-        obj_from_output mals_dir dir_name_append "${p}" "${mals_lang}";
-        if obj mals_dir is_dir
-        then
-          list_append mals_lang_path "${mals_dir}";
-        fi;
-      done;
-    done;
-    obj_from_output mals_mp lists_combine mals_lang_path mals_mp;
-  fi;
-
-  _MAN_PATH="${mals_mp}";
-  eval ${_UNSET} mals_dir;
-  eval ${_UNSET} mals_lang;
-  eval ${_UNSET} mals_lang_path;
-  eval ${_UNSET} mals_man_lang2;
-  eval ${_UNSET} mals_mp;
-  eval "${return_ok}";
-} # manpath_add_lang_sys()
-
-
-# _manpath_add_sys (<system>)
-#
-# Append the existing subdirectories <system> of man path directories to
-# the list $mals_mp.
-#
-# Local function to manpath_add_lang_sys().
-#
-# Argument: 1, a operating system name (for appending to a man path
-#              directory)
-#
-# Globals in:     $_MAN_PATH
-# Globals in/out: $mals_mp
-#
-# Variable prefix: _mas
-#
-_manpath_add_sys()
-{
-  func_check _manpath_add_sys '=' 1 "$@";
-  case "$1" in
-  '')
-    :;
-    ;;
-  man)
-    obj_from_output mals_mp lists_combine mals_mp _MAN_PATH;
-    ;;
-  *)
-    _mas_sys="$1";
-    eval set x "${_MAN_PATH}";
-    shift;
-    for p
-    do
-      obj_from_output _mas_dir dir_name_append "${p}" "${_mas_sys}";
-      if obj _mas_dir is_dir
-      then
-        list_append mals_mp "${_mas_dir}";
-      fi;
-    done;
-    ;;
-  esac;
-  eval ${_UNSET} _mas_dir;
-  eval ${_UNSET} _mas_sys;
-  eval "${return_ok}";
-} # _manpath_add_sys() of manpath_add_lang_sys()
-
-
-########################################################################
-# manpath_set_from_path ()
-#
-# Determine basic search path for man pages from $PATH.
-#
-# Return:    `0' if a valid man path was retrieved.
-# Output:    none
-# Globals:
-#   in:  $PATH
-#   out: $_MAN_PATH
-#
-# Variable prefix: msfp
-#
-manpath_set_from_path()
-{
-  func_check manpath_set_from_path '=' 0 "$@";
-
-  msfp_manpath='';
-
-  # get a basic man path from $PATH
-  if obj PATH is_not_empty
-  then
-    # delete the final `/bin' part
-    p="$(echo1 "${PATH}" | sed 's|//*bin/*:|:|g')";
-    obj_from_output msfp_list path_list "$p";
-    # append some default directories
-    for b in /usr/local /usr/local /usr /usr \
-           /usr/X11R6 /usr/openwin \
-           /opt /opt/gnome /opt/kde
-    do
-      msfp_base="$b";
-      if list_has_not msfp_list "${msfp_base}" && obj msfp_base is_dir
-      then
-        list_append msfp_list "${msfp_base}";
-      fi;
-    done;
-    eval set x "${msfp_list}";
-    shift;
-    for d
-    do
-      # including empty for former `/bin'.
-      msfp_base="$d";
-      for e in /share/man /share/MAN /man /MAN
-      do
-        msfp_mandir="${msfp_base}$e";
-        if obj msfp_mandir is_dir
-        then
-          list_append msfp_manpath "${msfp_mandir}";
-        fi;
-      done;
-    done;
-  fi;
-
-  _MAN_PATH="${msfp_manpath}";
-  eval ${_UNSET} msfp_base;
-  eval ${_UNSET} msfp_list;
-  eval ${_UNSET} msfp_mandir;
-  eval ${_UNSET} msfp_manpath;
-  eval "${return_ok}";
-} # manpath_set_from_path()
-
-
-########################################################################
-landmark '9: obj_*()';
-########################################################################
-
-########################################################################
-# obj (<object> <call_name> <arg>...)
-#
-# This works like a method (object function) call for an object.
-# Run "<call_name> $<object> <arg> ...".
-#
-# The first argument represents an object name whose data is given as
-# first argument to <call_name>().
-#
-# Argument: >=2
-#           <object>: variable name
-#           <call_name>: a program or function name
-#
-# Variable prefix: o
-#
-obj()
-{
-  func_check obj '>=' 2 "$@";
-  eval o_arg1='"${'$1'}"';
-  if is_empty "$2"
-  then
-    error "obj(): function name is empty."
-  else
-    o_func="$2";
-  fi;
-  shift;
-  shift;
-  eval "${o_func}"' "${o_arg1}" "$@"';
-  n="$?";
-  eval ${_UNSET} o_arg1;
-  eval ${_UNSET} o_func;
-  eval "${return_var} $n";
-} # obj()
-
-
-########################################################################
-# obj_data (<object>)
-#
-# Print the data of <object>, i.e. the content of $<object>.
-# For possible later extensions.
-#
-# Arguments: 1
-#            <object>: a variable name
-# Output:    the data of <object>
-#
-# Variable prefix: od
-#
-obj_data()
-{
-  func_check obj_data '=' 1 "$@";
-  if is_empty "$1"
-  then
-    error "obj_data(): object name is empty."
-  fi;
-  eval od_res='"${'"$1"'}"';
-  obj od_res echo1;
-  eval ${_UNSET} od_res;
-  eval "${return_ok}";
-} # obj_data()
-
-
-########################################################################
-# obj_from_output (<object> <call_name> <arg>...)
-#
-# Run '$<object>="$(<call_name> <arg>...)"' to set the result of a
-# function call to a global variable.  Variables are not stored.
-#
-# Arguments: >=2
-#            <object>: a variable name
-#            <call_name>: the name of a function or program
-#            <arg>: optional argument to <call_name>
-# Output:    none
-#
-# Variable prefix: ofo
-#
-obj_from_output()
-{
-  func_check obj_from_output '>=' 2 "$@";
-  if is_empty "$1"
-  then
-    error "obj_from_output(): variable name is empty.";
-  fi;
-  if is_empty "$2"
-  then
-    error "obj_from_output(): function name is empty."
-  fi;
-  ofo_result_name="$1";
-  shift;
-  ofo_return=0;
-  if is_equal "$#" 0
-  then
-    eval "${ofo_result_name}"'=""';
-  else
-    ofo_list='';
-    for i
-    do
-      list_append ofo_list "$i";
-    done;
-    eval "${ofo_result_name}"'="$('"${ofo_list}"')"';
-    ofo_return="$?";
-    exit_test;
-  fi;
-  r="${ofo_return}";
-  eval ${_UNSET} ofo_list;
-  eval ${_UNSET} ofo_return;
-  eval ${_UNSET} ofo_result_name;
-  eval "${return_var} $r";
-} # obj_from_output()
-
-
-########################################################################
-# obj_set (<object> <data>)
-#
-# Set the data of <object>, i.e. call "$<object>=<data>".
-#
-# Arguments: 2
-#            <object>: a variable name
-#            <data>: a string
-# Output::   none
-#
-obj_set()
-{
-  func_check obj_set '=' 2 "$@";
-  if is_empty "$1"
-  then
-    error "obj_set(): object name is empty."
-  fi;
-  eval "$1"='"$2"';
-  eval "${return_ok}";
-} # obj_set()
-
-
-########################################################################
-# path_chop (<path>)
-#
-# Remove unnecessary colons from path.
-#
-# Argument: 1, a colon separated path.
-# Output:   path without leading, double, or trailing colons.
-#
-path_chop()
-{
-  func_check path_chop = 1 "$@";
-
-  # replace multiple colons by a single colon `:'
-  # remove leading and trailing colons
-  echo1 "$1" | sed '
-s/^:*//
-s/:::*/:/g
-s/:*$//
-';
-  eval "${return_ok}";
-} # path_chop()
-
-
-########################################################################
-# path_clean (<path>)
-#
-# Remove non-existing directories from a colon-separated list.
-#
-# Argument: 1, a colon separated path.
-# Output:   colon-separated list of existing directories.
-#
-# Variable prefix: pc
-#
-path_clean()
-{
-  func_check path_clean = 1 "$@";
-  if is_not_equal "$#" 1
-  then
-    error 'path_clean() needs 1 argument.';
-  fi;
-  pc_arg="$1";
-  eval set x "$(path_list "${pc_arg}")";
-  exit_test;
-  shift;
-  pc_res="";
-  for i
-  do
-    pc_i="$i";
-    if obj pc_i is_not_empty \
-       && obj pc_res path_not_contains "${pc_i}" \
-       && obj pc_i is_dir
-    then
-      case "${pc_i}" in
-      ?*/)
-        pc_res="${pc_res}:$(dir_name_chop "${pc_i}")";
-        exit_test;
-        ;;
-      *)
-        pc_res="${pc_res}:${pc_i}";
-        ;;
-      esac;
-    fi;
-  done;
-  path_chop "${pc_res}";
-  eval ${_UNSET} pc_arg;
-  eval ${_UNSET} pc_i;
-  eval ${_UNSET} pc_res;
-  eval "${return_ok}";
-} # path_clean()
-
-
-########################################################################
-# path_contains (<path> <dir>)
-#
-# Test whether <dir> is contained in <path>, a list separated by `:'.
-#
-# Arguments : 2
-# Return    : `0' if arg2 is substring of arg1, `1' otherwise.
-#
-path_contains()
-{
-  func_check path_contains = 2 "$@";
-  case ":$1:" in
-    *:${2}:*)
-      eval "${return_yes}";
-      ;;
-    *)
-      eval "${return_no}";
-      ;;
-  esac;
-  eval "${return_ok}";
-} # path_contains()
-
-
-########################################################################
-# path_not_contains (<path> <dir>)
-#
-# Test whether <dir> is not contained in colon separated <path>.
-#
-# Arguments : 2
-#
-path_not_contains()
-{
-  func_check path_not_contains = 2 "$@";
-  if path_contains "$1" "$2"
-  then
-    eval "${return_no}";
-  else
-    eval "${return_yes}";
-  fi;
-  eval "${return_ok}";
-} # path_not_contains()
-
-
-########################################################################
-# path_list (<path>)
-#
-# From a `:' separated path generate a list with unique elements.
-#
-# Arguments: 1: a colon-separated path
-# Output:    the resulting list, process it with `eval set'
-#
-# Variable prefix: pl
-#
-path_list()
-{
-  func_check path_list = 1 "$@";
-  eval set x "$(list_from_split "$1" '\:')";
-  shift;
-  pl_list='';
-  for e
-  do
-    pl_elt="$e";
-    if list_has pl_list "${pl_elt}"
-    then
-      continue;
-    else
-      list_append pl_list "${pl_elt}";
-    fi;
-  done;
-  obj pl_list echo1;
-  eval ${_UNSET} pl_elt;
-  eval ${_UNSET} pl_list;
-  eval "${return_ok}";
-} # path_list()
-
-
-########################################################################
-landmark '10: register_*()';
-########################################################################
-
-########################################################################
-# register_file (<filename>)
-#
-# Write a found file and register the title element.
-#
-# Arguments: 1: a file name
-# Output: none
-#
-register_file()
-{
-  func_check register_file = 1 "$@";
-  if is_empty "$1"
-  then
-    error 'register_file(): file name is empty';
-  fi;
-  if is_equal "$1" '-'
-  then
-    to_tmp "${_TMP_STDIN}" && register_title 'stdin';
-  else
-    to_tmp "$1" && register_title "$1";
-    exit_test;
-  fi;
-  eval "${return_ok}";
-} # register_file()
-
-
-########################################################################
-# register_title (<filespec>)
-#
-# Create title element from <filespec> and append to $_REG_TITLE_LIST.
-# Basename is created.
-#
-# Globals: $_REG_TITLE_LIST (rw)
-#
-# Variable prefix: rt
-#
-register_title()
-{
-  func_check register_title '=' 1 "$@";
-  if is_empty "$1"
-  then
-    eval "${return_ok}";
-  fi;
-
-  if obj _DEBUG_PRINT_FILENAMES is_yes
-  then
-    if is_equal "$1" 'stdin'
-    then
-      echo2 "file: standard input";
-    else
-      if obj _FILESPEC_IS_MAN is_yes
-      then
-        echo2 "file title: $1";
-      else
-        echo2 "file: $1";
-      fi;
-    fi;
-  fi;
-
-  case "${_REG_TITLE_LIST}" in
-  *\ *\ *\ *)
-    eval "${return_ok}";
-    ;;
-  esac;
-
-  # remove directory part
-  obj_from_output rt_title base_name "$1";
-  # replace space characters by `_'
-  rt_title="$(echo1 "${rt_title}" | sed 's/[ 	]/_/g')";
-  # remove extension `.bz2'
-  rt_title="$(echo1 "${rt_title}" | sed 's/\.bz2$//')";
-  # remove extension `.gz'
-  rt_title="$(echo1 "${rt_title}" | sed 's/\.gz$//')";
-  # remove extension `.Z'
-  rt_title="$(echo1 "${rt_title}" | sed 's/\.Z$//')";
-
-  if obj rt_title is_empty
-  then
-    eval ${_UNSET} rt_title;
-    eval "${return_ok}";
-  fi;
-  list_append _REG_TITLE_LIST "${rt_title}";
-  eval ${_UNSET} rt_title;
-  eval "${return_ok}";
-} # register_title()
-
-
-########################################################################
-# reset ()
-#
-# Reset the variables that can be affected by options to their default.
-#
-#
-# Defined in section `Preset' after the rudimentary shell tests.
-
-
-########################################################################
-# rm_file (<file_name>)
-#
-# Remove file.
-#
-rm_file()
-{
-  func_check rm_file '=' 1 "$@";
-  if is_file "$1"
-  then
-    rm -f "$1" >${_NULL_DEV} 2>&1;
-  fi;
-  if is_existing "$1"
-  then
-    eval "${return_bad}";
-  else
-    eval "${return_good}";
-  fi;
-} # rm_file()
-
-
-########################################################################
-# rm_file_with_debug (<file_name>)
-#
-# Remove file if $_DEBUG_KEEP_FILES allows it.
-#
-# Globals: $_DEBUG_KEEP_FILES
-#
-rm_file_with_debug()
-{
-  func_check rm_file_with_debug '=' 1 "$@";
-  if obj _DEBUG_KEEP_FILES is_not_yes
-  then
-    if is_file "$1"
-    then
-      rm -f "$1" >${_NULL_DEV} 2>&1;
-    fi;
-  fi;
-  if is_existing "$1"
-  then
-    eval "${return_bad}";
-  else
-    eval "${return_good}";
-  fi;
-} # rm_file_with_debug()
-
-
-########################################################################
-# rm_tree (<dir_name>)
-#
-# Remove a file or a complete directory tree.
-#
-# Globals: $_DEBUG_KEEP_FILES
-#
-rm_tree()
-{
-  func_check rm_tree '=' 1 "$@";
-  if is_existing "$1"
-  then
-    rm -f -r "$1" >${_NULL_DEV} 2>&1;
-  fi;
-  if is_existing "$1"
-  then
-    eval "${return_bad}";
-  else
-    eval "${return_good}";
-  fi;
-} # rm_tree()
-
-
-########################################################################
-# save_stdin ()
-#
-# Store standard input to temporary file (with decompression).
-#
-# Variable prefix: ss
-#
-if obj _HAS_COMPRESSION is_yes
-then
-  save_stdin()
-  {
-    func_check save_stdin '=' 0 "$@";
-    ss_f="${_TMP_DIR}"/INPUT;
-    cat >"${ss_f}";
-    cat_z "${ss_f}" >"${_TMP_STDIN}";
-    rm_file "${ss_f}";
-    eval ${_UNSET} ss_f;
-    eval "${return_ok}";
-  } # save_stdin()
-else				# no compression
-  save_stdin()
-  {
-    func_check save_stdin '=' 0 "$@";
-    cat >"${_TMP_STDIN}";
-    eval "${return_ok}";
-  } # save_stdin()
-fi;
-
-
-########################################################################
-# special_filespec ()
-#
-# Handle special modes like whatis and apropos.  Run their filespec
-# functions if suitable.
-#
-# Globals:  in: $_OPT_APROPOS, $_OPT_WHATIS, $_SPECIAL_SETUP
-#          out: $_SPECIAL_FILESPEC (internal)
-#
-special_filespec()
-{
-  func_check special_filespec '=' 0 "$@";
-  if obj _OPT_APROPOS is_not_yes && obj _OPT_WHATIS is_not_yes
-  then
-    eval "${return_bad}";
-  fi;
-  if obj _OPT_APROPOS is_yes && obj _OPT_WHATIS is_yes
-  then
-    error \
-      'special_filespec(): $_OPT_APROPOS and $_OPT_WHATIS are both "yes"';
-  fi;
-  if obj _SPECIAL_SETUP is_not_yes
-  then
-    error 'special_filespec(): setup for apropos or whatis must be run first.';
-  fi;
-  if apropos_filespec || whatis_filespec;
-  then
-    eval "${return_ok}";
-  else
-    eval "${return_bad}";
-  fi;
-} # special_filespec()
-
-
-########################################################################
-# special_setup ()
-#
-# Handle special modes like whatis and apropos.  Run their setup
-# functions if suitable.
-#
-special_setup()
-{
-  func_check special_setup '=' 0 "$@";
-  if obj _OPT_APROPOS is_yes && obj _OPT_WHATIS is_yes
-  then
-    error \
-      'special_setup(): $_OPT_APROPOS and $_OPT_WHATIS are both "yes"';
-  fi;
-  if apropos_setup || whatis_setup
-  then
-    eval "${return_ok}";
-  else
-    eval "${return_bad}";
-  fi;
-} # special_setup()
-
-
-########################################################################
-landmark '11: stack_*()';
-########################################################################
-
-########################################################################
-# string_contains (<string> <part>)
-#
-# Test whether <part> is contained in <string>.
-#
-# Arguments : 2 text arguments.
-# Return    : `0' if arg2 is substring of arg1, `1' otherwise.
-#
-string_contains()
-{
-  func_check string_contains '=' 2 "$@";
-  case "$1" in
-    *${2}*)
-      eval "${return_yes}";
-      ;;
-    *)
-      eval "${return_no}";
-      ;;
-  esac;
-  eval "${return_ok}";
-} # string_contains()
-
-
-########################################################################
-# string_not_contains (<string> <part>)
-#
-# Test whether <part> is not substring of <string>.
-#
-# Arguments : 2 text arguments.
-# Return    : `0' if arg2 is substring of arg1, `1' otherwise.
-#
-string_not_contains()
-{
-  func_check string_not_contains '=' 2 "$@";
-  if string_contains "$1" "$2"
-  then
-    eval "${return_no}";
-  else
-    eval "${return_yes}";
-  fi;
-  eval "${return_ok}";
-} # string_not_contains()
-
-
-########################################################################
-landmark '12: tmp_*()';
-########################################################################
-
-########################################################################
-# tmp_cat ()
-#
-# Output the temporary cat file (the concatenation of all input).
-#
-tmp_cat()
-{
-  func_check tmp_cat '=' 0 "$@";
-  cat "${_TMP_CAT}";
-  eval "${return_var}" "$?";
-} # tmp_cat()
-
-
-########################################################################
-# tmp_create (<suffix>?)
-#
-# Create temporary file.  The generated name is `,' followed by
-# <suffix>.
-#
-# Argument: 0 or 1
-#
-# Globals: $_TMP_DIR
-#
-# Output : name of created file
-#
-# Variable prefix: tc
-#
-tmp_create()
-{
-  func_check tmp_create '<=' 1 "$@";
-  if obj _TMP_DIR is_empty || obj _TMP_DIR is_not_dir
-  then
-    error 'tmp_create(): there is no temporary directory.';
-  else
-    # the output file does not have `,' as first character, so these are
-    # different names from the output file.
-    tc_tmp="${_TMP_DIR}/,$1";
-    obj tc_tmp rm_file;
-    : >"${tc_tmp}"
-    obj tc_tmp echo1;
-  fi;
-  eval ${_UNSET} tc_tmp;
-  eval "${return_ok}";
-} # tmp_create()
-
-
-########################################################################
-# to_tmp (<filename>)
-#
-# Print file (decompressed) to the temporary cat file.
-#
-# Variable prefix: tt
-#
-to_tmp()
-{
-  func_check to_tmp '=' 1 "$@";
-  if obj _TMP_CAT is_empty
-  then
-    error 'to_tmp(): $_TMP_CAT is not yet set';
-  fi;
-  tt_1="$1";
-  tt_so_nr=0;			# number for temporary `,so,*,*'
-  if is_file "${tt_1}"
-  then
-    tt_dir="$(dir_name "${tt_1}")";
-    if obj _OPT_WHATIS is_yes
-    then
-      whatis_filename "${tt_1}" >>"${_TMP_CAT}";
-    else
-      _FILE_NR="$(expr ${_FILE_NR} + 1)";
-      tt_file="${_TMP_DIR}/,file${_FILE_NR}";
-      if obj _FILESPEC_IS_MAN is_yes
-      then
-        if obj _DEBUG_PRINT_FILENAMES is_yes
-        then
-          echo2 "file: ${tt_1}";
-        fi;
-        tt_tmp="${_TMP_DIR}/,tmp";
-        cat_z "${tt_1}" >"${tt_file}";
-        grep '^\.[ 	]*so[ 	]' "${tt_file}" |
-	  sed 's/^\.[ 	]*so[ 	]*//' >"${tt_tmp}";
-        list_from_file tt_list "${tt_tmp}";
-        eval set x ${tt_list};
-        shift;
-        for i
-        do
-          tt_i="$i";
-          tt_so_nr="$(expr ${tt_so_nr} + 1)";
-          tt_sofile="${_TMP_DIR}/,so${_FILE_NR}_${tt_so_nr}";
-          tt_sofiles="${tt_sofiles} ${tt_sofile}";
-          _do_man_so "${tt_i}";
-        done;
-        rm_file "${tt_tmp}";
-        mv "${tt_file}" "${tt_tmp}";
-        cat "${tt_tmp}" | soelim -I "${tt_dir}" ${_SOELIM_R} >"${tt_file}";
-        for f in ${tt_sofiles}
-        do
-          rm_file_with_debug $f;
-        done;
-        rm_file "${tt_tmp}";
-      else			# $_FILESPEC_IS_MAN ist not yes
-        cat_z "${tt_1}" | soelim -I "${tt_dir}" ${_SOELIM_R} >"${tt_file}";
-      fi;
-### to_tmp()
-      obj_from_output tt_grog grog "${tt_file}";
-      if is_not_equal "$?" 0
-      then
-        exit "${_ERROR}";
-      fi;
-      echo2 "grog output: ${tt_grog}";
-      case " ${tt_grog} " in
-      *\ -m*)
-        eval set x "$(echo1 " ${tt_grog} " | sed '
-s/'"${_TAB}"'/ /g
-s/  */ /g
-s/ -m / -m/g
-s/ -mm\([^ ]\)/ -m\1/g
-')";
-        shift;
-        for i
-        do
-          tt_i="$i";
-          case "${tt_i}" in
-          -m*)
-            if list_has _MACRO_PACKAGES "${tt_i}"
-            then
-              case "${_MACRO_PKG}" in
-              '')
-                _MACRO_PKG="${tt_i}";
-                ;;
-              ${tt_i})
-                :;
-                ;;
-              -m*)
-                echo2 "Ignore ${tt_1} because it needs ${tt_i} instead "\
-"of ${_MACRO_PKG}."
-                rm_file_with_debug "${tt_file}";
-                eval ${_UNSET} tt_1;
-                eval ${_UNSET} tt_dir;
-                eval ${_UNSET} tt_file;
-                eval ${_UNSET} tt_grog;
-                eval ${_UNSET} tt_i;
-                eval ${_UNSET} tt_so_nr;
-                eval ${_UNSET} tt_sofile;
-                eval ${_UNSET} tt_sofiles;
-                eval ${_UNSET} tt_sofound;
-                eval ${_UNSET} tt_list;
-                eval ${_UNSET} tt_tmp;
-                eval "${return_bad}";
-                ;;
-### to_tmp()
-              *)
-                error \
-'to_tmp(): $_MACRO_PKG does not start with -m: '"${_MACRO_PKG}";
-                ;;
-              esac;
-            fi;
-            ;;
-          esac;
-        done;
-        ;;
-      esac;
-      cat "${tt_file}" >>"${_TMP_CAT}";
-      rm_file_with_debug "${tt_file}";
-    fi;
-  else
-    error "to_tmp(): could not read file \`${tt_1}'.";
-  fi;
-  eval ${_UNSET} tt_1;
-  eval ${_UNSET} tt_dir;
-  eval ${_UNSET} tt_file;
-  eval ${_UNSET} tt_grog;
-  eval ${_UNSET} tt_i;
-  eval ${_UNSET} tt_so_nr;
-  eval ${_UNSET} tt_sofile;
-  eval ${_UNSET} tt_sofiles;
-  eval ${_UNSET} tt_sofound;
-  eval ${_UNSET} tt_list;
-  eval ${_UNSET} tt_tmp;
-  eval "${return_ok}";
-} # to_tmp()
-
-
-#############
-# _do_man_so (<so_arg>)
-#
-# Handle single .so file name for man pages.
-#
-# Local function to to_tmp().
-#
-# Globals from to_tmp(): $tt_tmp, $tt_sofile, $tt_file
-# Globals: $_TMP_MAN
-#
-# Variable prefix: dms
-#
-_do_man_so() {
-  func_check _do_man_so '=' 1 "$@";
-  _dms_so="$1";			# evt. with `\ '
-  _dms_soname="$(echo $1 | sed 's/\\[ 	]/ /g')"; # without `\ '
-  case "${_dms_soname}" in
-  /*)				# absolute path
-    if test -f "${_dms_soname}"
-    then
-      eval "${return_ok}";
-    fi;
-    if test -f "${_dms_soname}"'.gz'
-    then
-      _dms_sofound="${_dms_soname}"'.gz';
-    elif test -f "${_dms_soname}"'.Z'
-    then
-      _dms_sofound="${_dms_soname}"'.Z';
-    elif test -f "${_dms_soname}"'.bz2'
-    then
-      _dms_sofound="${_dms_soname}"'.bz2';
-    else
-      eval ${_UNSET} _dms_so;
-      eval ${_UNSET} _dms_soname;
-      eval "${return_ok}";
-    fi;
-    ;;
-### _do_man_so() of to_tmp()
-  *)				# relative to man path
-    eval grep "'/${_dms_soname}\$'" "${_TMP_MAN}" >"${tt_tmp}";
-    if is_empty_file "${tt_tmp}"
-    then
-      eval grep "'/${_dms_soname}.gz\$'" "${_TMP_MAN}" >"${tt_tmp}";
-      if is_empty_file "${tt_tmp}"
-      then
-        eval grep "'/${_dms_soname}.Z\$'" "${_TMP_MAN}" >"${tt_tmp}";
-        if is_empty_file "${tt_tmp}"
-        then
-          eval grep "'/${_dms_soname}.bz2\$'" "${_TMP_MAN}" >"${tt_tmp}";
-        fi;
-      fi;
-    fi;
-    if is_empty_file "${tt_tmp}"
-    then
-      eval "${return_ok}";
-    fi;
-    _dms_done='no';
-    list_from_file _dms_list "${tt_tmp}";
-    eval set x ${_dms_list};
-    shift;
-    for i
-    do
-      _dms_sofound="$i";
-      if obj _dms_sofound is_empty
-      then
-        continue;
-      fi;
-      _dms_done='yes';
-      break;
-    done;
-### _do_man_so() of to_tmp()
-    if obj _dms_done is_not_yes
-    then
-      eval ${_UNSET} _dms_done;
-      eval ${_UNSET} _dms_sofound;
-      eval "${return_ok}";
-    fi;
-    ;;
-  esac;
-  if obj _DEBUG_PRINT_FILENAMES is_yes
-  then
-    echo2 "file from .so: ${_dms_so}";
-  fi;
-  cat_z "${_dms_sofound}" >"${tt_sofile}";
-  _dms_esc="$(echo ${_dms_so} | sed 's/\\/\\\\/g')";
-  cat "${tt_file}" | eval sed \
-"'s#^\\.[ 	]*so[ 	]*\(${_dms_so}\|${_dms_esc}\|${_dms_soname}\)[ 	]*\$'"\
-"'#.so ${tt_sofile}#'" \
-    >"${tt_tmp}";
-  rm_file "${tt_file}";
-  mv "${tt_tmp}" "${tt_file}";
-  eval ${_UNSET} _dms_done;
-  eval ${_UNSET} _dms_esc;
-  eval ${_UNSET} _dms_so;
-  eval ${_UNSET} _dms_sofound;
-  eval ${_UNSET} _dms_soname;
-  eval "${return_ok}";
-} # _do_man_so() of to_tmp()
-
-
-########################################################################
-# to_tmp_line (<text>...)
-#
-# Print single line with <text> to the temporary cat file.
-#
-to_tmp_line()
-{
-  func_check to_tmp_line '>=' 1 "$@";
-  if obj _TMP_CAT is_empty
-  then
-    error 'to_tmp_line(): $_TMP_CAT is not yet set';
-  fi;
-  echo1 "$*" >>"${_TMP_CAT}";
-  eval "${return_ok}";
-} # to_tmp_line()
-
-
-########################################################################
-# trap_set
-#
-# Call function on signal 0.
-#
-trap_set()
-{
-  func_check trap_set '=' 0 "$@";
-  trap 'clean_up' 0 2>${_NULL_DEV} || :;
-  eval "${return_ok}";
-} # trap_set()
-
-
-########################################################################
-# trap_unset ()
-#
-# Disable trap on signal 0.
-#
-trap_unset()
-{
-  func_check trap_unset '=' 0 "$@";
-  trap '' 0 2>${_NULL_DEV} || :;
-  eval "${return_ok}";
-} # trap_unset()
-
-
-########################################################################
-# usage ()
-#
-# Print usage information to standard output; for groffer option --help.
-#
-usage()
-{
-  func_check usage = 0 "$@";
-  echo;
-  version;
-  cat <<EOF
-
-Usage: groffer [option]... [filespec]...
-
-Display roff files, standard input, and/or Unix manual pages with a X
-Window viewer or in several text modes.  All input is decompressed
-on-the-fly with all formats that gzip can handle.
-
-"filespec" is one of
-  "filename"       name of a readable file
-  "-"              for standard input
-  "man:name(n)"    man page "name" in section "n"
-  "man:name.n"     man page "name" in section "n"
-  "man:name"       man page "name" in first section found
-  "name(n)"        man page "name" in section "n"
-  "name.n"         man page "name" in section "n"
-  "n name"         man page "name" in section "n"
-  "name"           man page "name" in first section found
-where `section' is a single character out of [1-9on], optionally followed
-by some more letters that are called the `extension'.
-
--h --help         print this usage message.
--T --device=name  pass to groff using output device "name".
--v --version      print version information.
--V                display the groff execution pipe instead of formatting.
--X                display with "gxditview" using groff -X.
--Z --ditroff --intermediate-output
-                  generate groff intermediate output without
-                  post-processing and viewing, like groff -Z.
-All other short options are interpreted as "groff" formatting options.
-
-The most important groffer long options are
-
---apropos=name    start man's "apropos" program for "name".
---apropos-data=name
-                  "apropos" for "name" in man's data sections 4, 5, 7.
---apropos-devel=name
-                  "apropos" for "name" in development sections 2, 3, 9.
---apropos-progs=name
-                  "apropos" for "name" in man's program sections 1, 6, 8.
---auto            choose mode automatically from the default mode list.
---default         reset all options to the default value.
---default-modes=mode1,mode2,...
-                  set sequence of automatically tried modes.
---dvi             display in a viewer for TeX device independent format.
---dvi-viewer=prog choose the viewer program for dvi mode.
---groff           process like groff, disable viewing features.
---help            display this helping output.
---html            display in a web browser.
---html-viewer=program
-                  choose a web browser for html mode.
---man             check file parameters first whether they are man pages.
---mode=auto|dvi|groff|html|pdf|ps|source|text|tty|www|x|X
-                  choose display mode.
---no-man          disable man-page facility.
---no-special      disable --all, --apropos*, and --whatis
---pager=program   preset the paging program for tty mode.
---pdf             display in a PDF viewer.
---pdf-viewer=prog choose the viewer program for pdf mode.
---ps              display in a Postscript viewer.
---ps-viewer=prog  choose the viewer program for ps mode.
---shell=program   specify a shell under which to run groffer2.sh.
---source          output as roff source.
---text            output in a text device without a pager.
---to-stdout       output the content of the mode file without display.
---tty             display with a pager on text terminal even when in X.
---tty-viewer=prog select a pager for tty mode; same as --pager.
---whatis          display the file name and description of man pages
---www             same as --html.
---www-viewer=prog same as --html-viewer
---x --X           display with "gxditview" using an X* device.
---x-viewer=prog   choose viewer program for x mode (X mode).
---X-viewer=prog   same as "--xviewer".
-
-The usual X Windows toolkit options transformed into GNU long options:
---background=color, --bd=size, --bg=color, --bordercolor=color,
---borderwidth=size, --bw=size, --display=Xdisplay, --fg=color,
---fn=font, --font=font, --foreground=color, --geometry=geom, --iconic,
---resolution=dpi, --rv, --title=text, --xrm=resource
-
-Long options of GNU "man":
---all, --ascii, --ditroff, --extension=suffix, --locale=language,
---local-file=name, --location, --manpath=dir1:dir2:...,
---sections=s1:s2:..., --systems=s1,s2,..., --where, ...
-
-Development options that are not useful for normal usage:
---debug, --debug-all, --debug-filenames, --debug-func,
---debug-not-func, --debug-grog, --debug-keep, --debug-lm,
---debug-params, --debug-shell, --debug-stacks, --debug-tmpdir,
---debug-user, --do-nothing, --print=text, --shell=prog
-
-EOF
-
-  eval "${return_ok}";
-} # usage()
-
-
-########################################################################
-# version ()
-#
-# Print version information to standard output.
-# For groffer option --version.
-#
-version()
-{
-  func_check version = 0 "$@";
-  y="$(echo "${_LAST_UPDATE}" | sed 's/^.* //')";
-  cat <<EOF
-groffer ${_PROGRAM_VERSION} of ${_LAST_UPDATE} (shell version)
-is part of groff version ${_GROFF_VERSION}.
-Copyright (C) $y Free Software Foundation, Inc.
-GNU groff and groffer come with ABSOLUTELY NO WARRANTY.
-You may redistribute copies of groff and its subprograms
-under the terms of the GNU General Public License.
-EOF
-  eval "${return_ok}";
-} # version()
-
-
-########################################################################
-# warning (<string>)
-#
-# Print warning to stderr.
-#
-warning()
-{
-  echo2 "warning: $*";
-} # warning()
-
-
-########################################################################
-# whatis_filename (<filename>)
-#
-# Interpret <filename> as a man page and display its `whatis'
-# information as a fragment written in the groff language.
-#
-# Globals:  in: $_OPT_WHATIS, $_SPECIAL_SETUP, $_SPECIAL_FILESPEC,
-#               $_FILESPEC_ARG
-#
-# Variable prefix: wf
-#
-whatis_filename()
-{
-  func_check whatis_filename = 1 "$@";
-  if obj _OPT_WHATIS is_not_yes
-  then
-    error 'whatis_filename(): $_OPT_WHATIS is not yes.';
-  fi;
-  if obj _SPECIAL_SETUP is_not_yes
-  then
-    error \
-      'whatis_filename(): setup for whatis whatis_setup() must be run first.';
-  fi;
-  if obj _SPECIAL_FILESPEC is_not_yes
-  then
-    error 'whatis_filename(): whatis_filespec() must be run first.';
-  fi;
-  wf_arg="$1";
-  if obj wf_arg is_not_file
-  then
-    error "whatis_filename(): argument is not a readable file."
-  fi;
-  wf_dot='^\.'"${_SPACE_SED}"'*';
-### whatis_filename()
-  if obj _FILESPEC_ARG is_equal '-'
-  then
-    wf_arg='stdin';
-  fi;
-  cat <<EOF
-\f[CR]${wf_arg}\f[]:
-.br
-EOF
-
-  # get the parts of the file name
-  wf_name="$(base_name $1)";
-  wf_section="$(echo1 $1 | sed -n '
-s|^.*/man\('"${_MAN_AUTO_SEC_CHARS}"'\).*$|\1|p
-')";
-  if obj wf_section is_not_empty
-  then
-    case "${wf_name}" in
-    *.${wf_section}*)
-      s='yes';
-      ;;
-    *)
-      s='';
-      wf_section='';
-      ;;
-### whatis_filename()
-    esac
-    if obj s is_yes
-    then
-      wf_name="$(echo1 ${wf_name} | sed '
-s/^\(.*\)\.'${wf_section}'.*$/\1/
-')";
-    fi;
-  fi;
-
-  # traditional man style; grep the line containing `.TH' macro, if any
-  wf_res="$(cat_z "$1" | sed '
-/'"${wf_dot}"'TH /p
-d
-')";
-  exit_test;
-  if obj wf_res is_not_empty
-  then				# traditional man style
-    # get the first line after the first `.SH' macro, by
-    # - delete up to first .SH;
-    # - print all lines before the next .SH;
-    # - quit.
-    wf_res="$(cat_z "$1" | sed -n '
-1,/'"${wf_dot}"'SH/d
-/'"${wf_dot}"'SH/q
-p
-')";
-
-    if obj wf_section is_not_empty
-    then
-      case "${wf_res}" in
-      ${wf_name}${_SPACE_CASE}*-${_SPACE_CASE}*)
-        s='yes';
-        ;;
-### whatis_filename()
-      *)
-        s='';
-        ;;
-      esac;
-      if obj s is_yes
-      then
-        wf_res="$(obj wf_res echo1 | sed '
-s/^'"${wf_name}${_SPACE_SED}"'[^-]*-'"${_SPACE_SED}"'*\(.*\)$/'"${wf_name}"' ('"${wf_section}"') \\[em] \1/
-')";
-      fi;
-    fi;
-    obj wf_res echo1;
-    echo;
-    eval ${_UNSET} wf_arg;
-    eval ${_UNSET} wf_dot;
-    eval ${_UNSET} wf_name;
-    eval ${_UNSET} wf_res;
-    eval ${_UNSET} wf_section;
-    eval "${return_ok}";
-  fi;
-
-  # mdoc style (BSD doc); grep the line containing `.Nd' macro, if any
-  wf_res="$(cat_z "$1" | sed -n '/'"${wf_dot}"'Nd /s///p')";
-  exit_test;
-  if obj wf_res is_not_empty
-  then				# BSD doc style
-    if obj wf_section is_not_empty
-    then
-      wf_res="$(obj wf_res echo1 | sed -n '
-s/^\(.*\)$/'"${wf_name}"' ('"${wf_section}"') \\[em] \1/p
-')";
-    fi;
-### whatis_filename()
-    obj wf_res echo1;
-    echo;
-    eval ${_UNSET} wf_arg;
-    eval ${_UNSET} wf_dot;
-    eval ${_UNSET} wf_name;
-    eval ${_UNSET} wf_res;
-    eval ${_UNSET} wf_section;
-    eval "${return_ok}";
-  fi;
-  echo1 'is not a man page';
-  echo;
-  eval ${_UNSET} wf_arg;
-  eval ${_UNSET} wf_dot;
-  eval ${_UNSET} wf_name;
-  eval ${_UNSET} wf_res;
-  eval ${_UNSET} wf_section;
-  eval "${return_bad}";
-} # whatis_filename()
-
-
-
-########################################################################
-# whatis_filespec ()
-#
-# Print the filespec name as .SH to the temporary cat file.
-#
-# Globals:  in: $_OPT_WHATIS, $_SPECIAL_SETUP
-#          out: $_SPECIAL_FILESPEC
-#
-whatis_filespec()
-{
-  func_check whatis_filespec '=' 0 "$@";
-  if obj _OPT_WHATIS is_yes
-  then
-    if obj _SPECIAL_SETUP is_not_yes
-    then
-      error 'whatis_filespec(): whatis_setup() must be run first.';
-    fi;
-    _SPECIAL_FILESPEC='yes';
-    eval to_tmp_line \
-      "'.SH $(echo1 "${_FILESPEC_ARG}" | sed 's/[^\\]-/\\-/g')'";
-    exit_test;
-    eval "${return_ok}";
-  else
-    eval "${return_bad}";
-  fi;
-} # whatis_filespec()
-
-
-########################################################################
-# whatis_setup ()
-#
-# Print the whatis header to the temporary cat file; this is the setup
-# for whatis.
-#
-# Globals:  in: $_OPT_WHATIS
-#          out: $_SPECIAL_SETUP
-#
-whatis_setup()
-{
-  func_check whatis_setup '=' 0 "$@";
-  if obj _OPT_WHATIS is_yes
-  then
-    to_tmp_line '.TH GROFFER WHATIS';
-    _SPECIAL_SETUP='yes';
-    if obj _OPT_TITLE is_empty
-    then
-      _OPT_TITLE='whatis';
-    fi;
-    eval "${return_ok}";
-  else
-    eval "${return_bad}";
-  fi;
-} # whatis_setup()
-
-
-########################################################################
-# where_is_prog (<program>)
-#
-# Output path of a program and the given arguments if in $PATH.
-#
-# Arguments : 1, <program> can have spaces and arguments.
-# Output    : list of 2 elements: prog name (with directory) and arguments
-# Return    : `0' if arg1 is a program in $PATH, `1' otherwise.
-#
-# Variable prefix: wip
-#
-where_is_prog()
-{
-  func_check where_is_prog '=' 1 "$@";
-  if is_empty "$1"
-  then
-    eval "${return_bad}";
-  fi;
-
-  # Remove disturbing multiple spaces and tabs
-  wip_1="$(echo1 "$1" | sed 's/[ 	][ 	]*/ /g' | \
-           sed 's/\(\\\)* / /g' | sed 's/^ //' | sed 's/ $//')";
-  wip_noarg="$(echo1 "${wip_1}" | sed 's/ -.*$//')";
-  exit_test;
-
-  if obj wip_noarg is_empty
-  then
-    eval ${_UNSET} wip_1;
-    eval ${_UNSET} wip_noarg;
-    eval "${return_bad}";
-  fi;
-
-  case "${wip_1}" in
-  *\ -*)
-    wip_args="$(echo1 "${wip_1}" |
-                eval sed "'s#^${wip_noarg} ##'")";
-    exit_test;
-    ;;
-  *)
-    wip_args='';
-    ;;
-  esac;
-
-  wip_result='';
-### where_is_prog()
-
-  if test -f "${wip_noarg}" && test -x "${wip_noarg}"
-  then
-    list_append wip_result "${wip_noarg}" "${wip_args}";
-    exit_test;
-    obj wip_result echo1;
-    exit_test;
-    eval ${_UNSET} wip_1;
-    eval ${_UNSET} wip_args;
-    eval ${_UNSET} wip_noarg;
-    eval ${_UNSET} wip_result;
-    eval "${return_ok}";
-  fi;
-
-  # test whether $wip_noarg has directory, so it is not tested with $PATH
-  case "${wip_noarg}" in
-  */*)
-    # now $wip_noarg (with /) is not an executable file
-
-    # test name with space
-    obj_from_output wip_name base_name "${wip_noarg}";
-    obj_from_output wip_dir dir_name "${wip_noarg}";
-    case "${wip_name}" in
-    *\ *)
-      wip_base="$(echo1 "${wip_name}" | sed 's/ .*$//')";
-      exit_test;
-      obj_from_output wip_file dir_name_append "${wip_dir}" "${wip_base}";
-      exit_test;
-### where_is_prog()
-      if test -f "${wip_file}" && test -x "${wip_file}"
-      then
-        wip_baseargs="$(echo1 "${wip_name}" |
-                        eval sed "'s#^${wip_base} ##'")";
-        exit_test;
-        if obj wip_args is_empty
-        then
-          wip_args="${wip_baseargs}";
-        else
-          wip_args="${wip_baseargs} ${wip_args}";
-        fi;
-
-        list_append wip_result "${wip_file}" "${wip_args}";
-        exit_test;
-        obj wip_result echo1;
-        exit_test;
-        eval ${_UNSET} wip_1;
-        eval ${_UNSET} wip_args;
-        eval ${_UNSET} wip_base;
-        eval ${_UNSET} wip_baseargs;
-        eval ${_UNSET} wip_dir;
-        eval ${_UNSET} wip_file;
-        eval ${_UNSET} wip_name;
-        eval ${_UNSET} wip_noarg;
-        eval ${_UNSET} wip_result;
-        eval "${return_ok}";
-      fi; # test ${wip_file}
-      ;;
-    esac; # end of test name with space
-
-### where_is_prog()
-    eval ${_UNSET} wip_1;
-    eval ${_UNSET} wip_args;
-    eval ${_UNSET} wip_base;
-    eval ${_UNSET} wip_dir;
-    eval ${_UNSET} wip_name;
-    eval ${_UNSET} wip_noarg;
-    eval ${_UNSET} wip_result;
-    eval "${return_bad}";
-    ;;
-  esac; # test of $wip_noarg on path with directory
-
-
-  # now $wip_noarg does not have a /, so it is checked with $PATH.
-
-  eval set x "$(path_list "${PATH}")";
-  exit_test;
-  shift;
-
-  # test path with $win_noarg, evt. with spaces
-  for d
-  do
-    wip_dir="$d";
-    obj_from_output wip_file dir_name_append "${wip_dir}" "${wip_noarg}";
-### where_is_prog()
-
-    # test $win_file on executable file
-    if test -f "${wip_file}" && test -x "${wip_file}"
-    then
-      list_append wip_result "${wip_file}" "${wip_args}";
-      exit_test;
-      obj wip_result echo1;
-      exit_test;
-      eval ${_UNSET} wip_1;
-      eval ${_UNSET} wip_dir;
-      eval ${_UNSET} wip_file;
-      eval ${_UNSET} wip_noarg;
-      eval ${_UNSET} wip_result;
-      eval "${return_ok}";
-    fi; # test $win_file on executable file
-  done; # test path with $win_prog with spaces
-
-  case "${wip_noarg}" in
-  *\ *)
-    # test on path with base name without space
-    wip_base="$(echo1 "${wip_noarg}" | sed 's/^\([^ ]*\) .*$/\1/')";
-    exit_test;
-    for d
-    do
-      wip_dir="$d";
-      obj_from_output wip_file dir_name_append "${wip_dir}" "${wip_base}";
-      exit_test;
-### where_is_prog()
-
-      # test $win_file on executable file
-      if test -f "${wip_file}" && test -x "${wip_file}"
-      then
-        wip_baseargs="$(echo1 "${wip_noarg}" |
-                        sed 's/[^ ]* \(.*\)$/\1/')";
-        exit_test;
-        if obj wip_args is_empty
-        then
-          wip_args="${wip_baseargs}";
-        else
-          wip_args="${wip_args} ${wip_baseargs}";
-        fi;
-        list_append wip_result "${wip_file}" "${wip_args}";
-        exit_test;
-        obj wip_result echo1;
-        exit_test;
-        eval ${_UNSET} wip_1;
-        eval ${_UNSET} wip_args;
-        eval ${_UNSET} wip_base;
-        eval ${_UNSET} wip_baseargs;
-        eval ${_UNSET} wip_dir;
-        eval ${_UNSET} wip_file;
-        eval ${_UNSET} wip_name;
-        eval ${_UNSET} wip_noarg;
-        eval ${_UNSET} wip_result;
-        eval "${return_ok}";
-      fi; # test of $wip_file on executable file
-    done; # test path with base name without space
-### where_is_prog()
-    ;;
-  esac; # test of $wip_noarg on space
-
-  eval ${_UNSET} wip_1;
-  eval ${_UNSET} wip_args;
-  eval ${_UNSET} wip_base;
-  eval ${_UNSET} wip_baseargs;
-  eval ${_UNSET} wip_dir;
-  eval ${_UNSET} wip_file;
-  eval ${_UNSET} wip_name;
-  eval ${_UNSET} wip_noarg;
-  eval ${_UNSET} wip_result;
-  eval "${return_bad}";
-} # where_is_prog()
-
-
-########################################################################
-#                        main* Functions
-########################################################################
-
-# The main area contains the following parts:
-# - main_init(): initialize temporary files and set exit trap
-# - main_parse_MANOPT(): parse $MANOPT
-# - main_parse_args(): argument parsing
-# - main_set_mode (): determine the display mode
-# - main_do_fileargs(): process filespec arguments
-# - main_set_resources(): setup X resources
-# - main_display(): do the displaying
-# - main(): the main function that calls all main_*()
-
-
-#######################################################################
-# main_init ()
-#
-# Set exit trap and create temporary directory and some temporary files.
-#
-# Globals: $_TMP_DIR, $_TMP_CAT, $_TMP_STDIN
-#
-# Variable prefix: mi
-#
-main_init()
-{
-  func_check main_init = 0 "$@";
-  # call clean_up() on shell termination.
-  trap_set;
-
-  # create temporary directory
-  umask 0077;
-  _TMP_DIR='';
-  for d in "${GROFF_TMPDIR}" "${TMPDIR}" "${TMP}" "${TEMP}" \
-           "${TEMPDIR}" "${HOME}"'/tmp' '/tmp' "${HOME}" '.'
-  do
-    mi_dir="$d";
-    if obj mi_dir is_empty || obj mi_dir is_not_dir || \
-       obj mi_dir is_not_writable
-    then
-      continue;
-    fi;
-
-    case "${mi_dir}" in
-    */)
-      _TMP_DIR="${mi_dir}";
-      ;;
-    *)
-      _TMP_DIR="${mi_dir}"'/';
-      ;;
-    esac;
-    _TMP_DIR="${_TMP_DIR}groffer${_PROCESS_ID}";
-    if obj _TMP_DIR rm_tree
-    then
-      :
-    else
-      mi_tdir_="${_TMP_DIR}"_;
-      mi_n=1;
-      mi_tdir_n="${mi_tdir_}${mi_n}";
-### main_init()
-      while obj mi_tdir_n is_existing
-      do
-        if obj mi_tdir_n rm_tree
-        then
-          # directory could not be removed
-          mi_n="$(expr "${mi_n}" + 1)";
-          mi_tdir_n="${mi_tdir_}${mi_n}";
-          continue;
-        fi;
-      done;
-      _TMP_DIR="${mi_tdir_n}";
-    fi;
-    eval mkdir "${_TMP_DIR}";
-    if is_not_equal "$?" 0
-    then
-      obj _TMP_DIR rm_tree;
-      _TMP_DIR='';
-      continue;
-    fi;
-    if obj _TMP_DIR is_dir && obj _TMP_DIR is_writable
-    then
-      # $_TMP_DIR can now be used as temporary directory
-      break;
-    fi;
-    obj _TMP_DIR rm_tree;
-    _TMP_DIR='';
-    continue;
-  done;
-  if obj _TMP_DIR is_empty
-  then
-    error "main_init(): \
-Couldn't create a directory for storing temporary files.";
-  fi;
-### main_init()
-  if obj _DEBUG_PRINT_TMPDIR is_yes
-  then
-    echo2 "temporary directory: ${_TMP_DIR}";
-  fi;
-
-  obj_from_output _TMP_CAT tmp_create groffer_cat;
-  obj_from_output _TMP_STDIN tmp_create groffer_input;
-
-  eval ${_UNSET} mi_dir;
-  eval ${_UNSET} mi_n;
-  eval ${_UNSET} mi_tdir_;
-  eval ${_UNSET} mi_tdir_n;
-  eval "${return_ok}";
-} # main_init()
-
-
-########################################################################
-# main_parse_MANOPT ()
-#
-# Parse $MANOPT to retrieve man options, but only if it is a non-empty
-# string; found man arguments can be overwritten by the command line.
-#
-# Globals:
-#   in: $MANOPT, $_OPTS_MANOPT_*
-#   out: $_MANOPT_*
-#
-# Variable prefix: mpm
-#
-main_parse_MANOPT()
-{
-  func_check main_parse_MANOPT = 0 "$@";
-
-  if obj MANOPT is_not_empty
-  then
-    # Delete leading and final spaces
-    MANOPT="$(echo1 "${MANOPT}" | sed '
-s/^'"${_SPACE_SED}"'*//
-s/'"${_SPACE_SED}"'*$//
-')";
-    exit_test;
-  fi;
-  if obj MANOPT is_empty
-  then
-    eval "${return_ok}";
-  fi;
-
-  mpm_list='';
-  # add arguments in $MANOPT by mapping them to groffer options
-  eval set x "$(list_from_cmdline _OPTS_MANOPT "${MANOPT}")";
-  exit_test;
-  shift;
-  until test "$#" -le 0 || is_equal "$1" '--'
-  do
-    mpm_opt="$1";
-    shift;
-    case "${mpm_opt}" in
-    -7|--ascii)
-      list_append mpm_list '--ascii';
-      ;;
-    -a|--all)
-      list_append mpm_list '--all';
-      ;;
-### main_parse_MANOPT()
-    -c|--catman)
-      do_nothing;
-      shift;
-      ;;
-    -d|--debug)
-      do_nothing;
-      ;;
-    -D|--default)
-      # undo all man options so far
-      mpm_list='';
-      ;;
-    -e|--extension)
-      list_append mpm_list '--extension';
-      shift;
-      ;;
-    -f|--whatis)
-      list_append mpm_list '--whatis';
-      shift;
-      ;;
-    -h|--help)
-      do_nothing;
-      ;;
-    -k|--apropos)
-      # groffer's --apropos takes an argument, but man's does not, so
-      do_nothing;
-      ;;
-    -l|--local-file)
-      do_nothing;
-      ;;
-    -L|--locale)
-      list_append mpm_list '--locale' "$1";
-      shift;
-      ;;
-### main_parse_MANOPT()
-    -m|--systems)
-      list_append mpm_list '--systems' "$1";
-      shift;
-      ;;
-    -M|--manpath)
-      list_append mpm_list '--manpath' "$1";
-      shift;
-      ;;
-    -p|--preprocessor)
-      do_nothing;
-      shift;
-      ;;
-    -P|--pager)
-      list_append mpm_list '--pager' "$1";
-      shift;
-      ;;
-    -r|--prompt)
-      do_nothing;
-      shift;
-      ;;
-    -S|--sections)
-      list_append mpm_list '--sections' "$1";
-      shift;
-      ;;
-    -t|--troff)
-      do_nothing;
-      ;;
-    -T|--device)
-      list_append mpm_list '-T' "$1";
-      shift;
-      ;;
-### main_parse_MANOPT()
-    -u|--update)
-      do_nothing;
-      ;;
-    -V|--version)
-      do_nothing;
-      ;;
-    -w|--where|--location)
-      list_append mpm_list '--location';
-      ;;
-    -Z|--ditroff)
-      do_nothing;
-      ;;
-    # ignore all other options
-    esac;
-  done;
-
-  # prepend $mpm_list to the command line
-  if obj mpm_list is_not_empty
-  then
-    eval set x "${mpm_list}" '"$@"';
-    shift;
-  fi;
-
-  eval ${_UNSET} mpm_list;
-  eval ${_UNSET} mpm_opt;
-  eval "${return_ok}";
-} # main_parse_MANOPT()
-
-
-########################################################################
-# main_parse_args (<command_line_args>*)
-#
-# Parse arguments; process options and filespec parameters.
-#
-# Arguments: pass the command line arguments unaltered.
-# Globals:
-#   in:  $_OPTS_*
-#   out: $_OPT_*, $_ADDOPTS, $_FILEARGS
-#
-# Variable prefix: mpa
-#
-main_parse_args()
-{
-  func_check main_parse_args '>=' 0 "$@";
-  obj_from_output _ALL_PARAMS list_from_cmdline_with_minus _OPTS_CMDLINE "$@";
-  if obj _DEBUG_PRINT_PARAMS is_yes
-  then
-    echo2 "parameters: ${_ALL_PARAMS}";
-  fi;
-  eval set x "${_ALL_PARAMS}";
-  shift;
-
-  # By the call of `eval', unnecessary quoting was removed.  So the
-  # positional shell parameters ($1, $2, ...) are now guaranteed to
-  # represent an option or an argument to the previous option, if any;
-  # then a `--' argument for separating options and
-  # parameters; followed by the filespec parameters if any.
-
-  # Note, the existence of arguments to options has already been checked.
-  # So a check for `$#' or `--' should not be done for arguments.
-
-  until test "$#" -le 0 || is_equal "$1" '--'
-  do
-    mpa_opt="$1";		# $mpa_opt is fed into the option handler
-    shift;
-    case "${mpa_opt}" in
-    -h|--help)
-      usage;
-      leave;
-      ;;
-    -Q|--source)		# output source code (`Quellcode').
-      _OPT_MODE='source';
-      ;;
-### main_parse_args()
-    -T|--device|--troff-device) # device; arg
-      _OPT_DEVICE="$1";
-      _check_device_with_mode;
-      shift;
-      ;;
-    -v|--version)
-      version;
-      leave;
-      ;;
-    -V)
-      _OPT_V='yes';
-      ;;
-    -Z|--ditroff|--intermediate-output) # groff intermediate output
-      _OPT_Z='yes';
-      ;;
-    -X)
-      _OPT_MODE=X;
-      ;;
-    -?)
-      # delete leading `-'
-      mpa_optchar="$(echo1 "${mpa_opt}" | sed 's/^-//')";
-      exit_test;
-      if list_has _OPTS_GROFF_SHORT_NA "${mpa_optchar}"
-      then
-        list_append _ADDOPTS_GROFF "${mpa_opt}";
-      elif list_has _OPTS_GROFF_SHORT_ARG "${mpa_optchar}"
-      then
-        list_append _ADDOPTS_GROFF "${mpa_opt}" "$1";
-        shift;
-### main_parse_args()
-      else
-        error "main_parse_args(): Unknown option : \`$1'";
-      fi;
-      ;;
-    --all)
-        _OPT_ALL='yes';
-        ;;
-    --apropos)			# run `apropos'
-      _OPT_APROPOS='yes';
-      _APROPOS_SECTIONS='';
-      _OPT_WHATIS='no';
-      ;;
-    --apropos-data)		# run `apropos' for data sections
-      _OPT_APROPOS='yes';
-      _APROPOS_SECTIONS='457';
-      _OPT_WHATIS='no';
-      ;;
-    --apropos-devel)		# run `apropos' for development sections
-      _OPT_APROPOS='yes';
-      _APROPOS_SECTIONS='239';
-      _OPT_WHATIS='no';
-      ;;
-    --apropos-progs)		# run `apropos' for program sections
-      _OPT_APROPOS='yes';
-      _APROPOS_SECTIONS='168';
-      _OPT_WHATIS='no';
-      ;;
-### main_parse_args()
-    --ascii)
-      list_append _ADDOPTS_GROFF '-mtty-char';
-      if obj _OPT_MODE is_empty
-      then
-        _OPT_MODE='text';
-      fi;
-      ;;
-    --auto)			# the default automatic mode
-      _OPT_MODE='';
-      ;;
-    --bd|--bordercolor)		# border color for viewers, arg;
-      _OPT_BD="$1";
-      shift;
-      ;;
-    --bg|--backgroud)		# background color for viewers, arg;
-      _OPT_BG="$1";
-      shift;
-      ;;
-    --bw|--borderwidth)		# border width for viewers, arg;
-      _OPT_BW="$1";
-      shift;
-      ;;
-    --debug|--debug-all|--debug-filenames|--debug-func|--debug-not-func|\
---debug-grog|--debug-keep|--debug-lm|--debug-params|--debug-shell|\
---debug-stacks|--debug-tmpdir|--debug-user)
-      # debug is handled at the beginning
-      :;
-      ;;
-    --default)			# reset variables to default
-      reset;
-      ;;
-### main_parse_args()
-    --default-modes)		# sequence of modes in auto mode; arg
-      _OPT_DEFAULT_MODES="$1";
-      shift;
-      ;;
-    --display)			# set X display, arg
-      _OPT_DISPLAY="$1";
-      shift;
-      ;;
-    --do-nothing)
-      _OPT_DO_NOTHING='yes';
-      ;;
-    --dvi)
-      _OPT_MODE='dvi';
-      ;;
-    --dvi-viewer|--dvi-viewer-tty) # viewer program for dvi mode; arg
-      _OPT_VIEWER_DVI="$1";
-      shift;
-      ;;
-    --extension)		# the extension for man pages, arg
-      _OPT_EXTENSION="$1";
-      shift;
-      ;;
-### main_parse_args()
-    --fg|--foreground)		# foreground color for viewers, arg;
-      _OPT_FG="$1";
-      shift;
-      ;;
-    --fn|--ft|--font)		# set font for viewers, arg;
-      _OPT_FN="$1";
-      shift;
-      ;;
-    --geometry)			# window geometry for viewers, arg;
-      _OPT_GEOMETRY="$1";
-      shift;
-      ;;
-    --groff)
-      _OPT_MODE='groff';
-      ;;
-    --html|--www)		# display with web browser
-      _OPT_MODE=html;
-      ;;
-    --html-viewer|--www-viewer|--html-viewer-tty|--www-viewer-tty)
-      # viewer program for html mode; arg
-      _OPT_VIEWER_HTML="$1";
-      shift;
-      ;;
-    --iconic)			# start viewers as icons
-      _OPT_ICONIC='yes';
-      ;;
-### main_parse_args()
-    --locale)			# set language for man pages, arg
-      # argument is xx[_territory[.codeset[@modifier]]] (ISO 639,...)
-      _OPT_LANG="$1";
-      shift;
-      ;;
-    --local-file)		# force local files; same as `--no-man'
-      _MAN_FORCE='no';
-      _MAN_ENABLE='no';
-      ;;
-    --location|--where)		# print file locations to stderr
-      _DEBUG_PRINT_FILENAMES='yes';
-      ;;
-    --man)		       # force all file params to be man pages
-      _MAN_ENABLE='yes';
-      _MAN_FORCE='yes';
-      ;;
-    --manpath)		      # specify search path for man pages, arg
-      # arg is colon-separated list of directories
-      _OPT_MANPATH="$1";
-      shift;
-      ;;
-    --mode)			# display mode
-      mpa_arg="$1";
-      shift;
-      case "${mpa_arg}" in
-      auto|'')		     # search mode automatically among default
-        _OPT_MODE='';
-        ;;
-      groff)			# pass input to plain groff
-        _OPT_MODE='groff';
-        ;;
-### main_parse_args()
-      html|www)			# display with a web browser
-        _OPT_MODE='html';
-        ;;
-      dvi)			# display with xdvi viewer
-        _OPT_MODE='dvi';
-        ;;
-      pdf)			# display with PDF viewer
-        _OPT_MODE='pdf';
-        ;;
-      ps)			# display with Postscript viewer
-        _OPT_MODE='ps';
-        ;;
-      text)			# output on terminal
-        _OPT_MODE='text';
-        ;;
-      tty)			# output on terminal
-        _OPT_MODE='tty';
-        ;;
-      X|x)			# output on X roff viewer
-        _OPT_MODE='x';
-        ;;
-### main_parse_args()
-      Q|source)			# display source code
-        _OPT_MODE="source";
-        ;;
-      *)
-        error "main_parse_args(): unknown mode ${mpa_arg}";
-        ;;
-      esac;
-      ;;
-    --no-location)		# disable former call to `--location'
-      _DEBUG_PRINT_FILENAMES='no';
-      ;;
-    --no-man)			# disable search for man pages
-      # the same as --local-file
-      _MAN_FORCE='no';
-      _MAN_ENABLE='no';
-      ;;
-    --no-special)		# disable some special former calls
-      _OPT_ALL='no'
-      _OPT_APROPOS='no'
-      _OPT_WHATIS='no'
-      ;;
-    --pager|--tty-viewer|--tty-viewer-tty)
-      # set paging program for tty mode, arg
-      _OPT_PAGER="$1";
-      shift;
-      ;;
-    --pdf)
-      _OPT_MODE='pdf';
-      ;;
-### main_parse_args()
-    --pdf-viewer|--pdf-viewer-tty) # viewer program for pdf mode; arg
-      _OPT_VIEWER_PDF="$1";
-      shift;
-      ;;
-    --print)			# for argument test
-      echo2 "$1";
-      shift;
-      ;;
-    --ps)
-      _OPT_MODE='ps';
-      ;;
-    --ps-viewer|--ps-viewer-tty) # viewer program for ps mode; arg
-      _OPT_VIEWER_PS="$1";
-      shift;
-      ;;
-### main_parse_args()
-    --resolution)		# set resolution for X devices, arg
-      mpa_arg="$1";
-      shift;
-      case "${mpa_arg}" in
-      75|75dpi)
-        mpa_dpi=75;
-        ;;
-      100|100dpi)
-        mpa_dpi=100;
-        ;;
-      *)
-        error "main_parse_args(): \
-only resoutions of 75 or 100 dpi are supported";
-        ;;
-      esac;
-      _OPT_RESOLUTION="${mpa_dpi}";
-      ;;
-    --rv)
-      _OPT_RV='yes';
-      ;;
-    --sections)			# specify sections for man pages, arg
-      # arg is colon-separated list of section names
-      _OPT_SECTIONS="$1";
-      shift;
-      ;;
-    --shell)
-      # already done during the first run; so ignore the argument
-      shift;
-      ;;
-### main_parse_args()
-    --systems)			# man pages for different OS's, arg
-      # argument is a comma-separated list
-      _OPT_SYSTEMS="$1";
-      shift;
-      ;;
-    --text)			# text mode without pager
-      _OPT_MODE=text;
-      ;;
-    --title)			# title for X viewers; arg
-      if is_not_empty "$1"
-      then
-        list_append _OPT_TITLE "$1";
-      fi;
-      shift;
-      ;;
-     --to-stdout)		# print mode file without display
-      _OPT_STDOUT='yes';
-      ;;
-     --tty)			# tty mode, text with pager
-      _OPT_MODE=tty;
-      ;;
-    --text-device|--tty-device) # device for tty mode; arg
-      _OPT_TEXT_DEVICE="$1";
-      shift;
-      ;;
-    --whatis)
-      _OPT_WHATIS='yes';
-      _OPT_APROPOS='no';
-      ;;
-    --X|--x)
-      _OPT_MODE=x;
-      ;;
-### main_parse_args()
-    --xrm)			# pass X resource string, arg;
-      list_append _OPT_XRM "$1";
-      shift;
-      ;;
-    --x-viewer|--X-viewer|--x-viewer-tty|--X-viewer-tty)
-      # viewer program for x mode; arg
-      _OPT_VIEWER_X="$1";
-      shift;
-      ;;
-    *)
-      error 'main_parse_args(): unknown option '"\`${mpa_opt}'.";
-      ;;
-    esac;
-  done;
-  shift;			# remove `--' argument
-
-  if obj _OPT_WHATIS is_yes
-  then
-    _MAN_ALL='yes';
-    _APROPOS_SECTIONS='';
-  fi;
-
-  if obj _OPT_DO_NOTHING is_yes
-  then
-    leave;
-  fi;
-
-### main_parse_args()
-  case "$_OPT_DEFAULT_MODES" in
-  '') :; ;;
-  *,*)
-    obj_from_output _OPT_DEFAULT_MODES \
-      obj _OPT_DEFAULT_MODES list_from_split ',';
-    ;;
-  *) :; ;;
-  esac;
-
-  # Remaining arguments are file names (filespecs).
-  # Save them to list $_FILEARGS
-  if is_equal "$#" 0
-  then				# use "-" for standard input
-    _NO_FILESPECS='yes';
-    set x '-';
-    shift;
-  fi;
-  _FILEARGS='';
-  list_append _FILEARGS "$@";
-  # $_FILEARGS must be retrieved with `eval set x "$_FILEARGS"; shift;'
-  eval ${_UNSET} mpa_arg;
-  eval ${_UNSET} mpa_dpi;
-  eval ${_UNSET} mpa_opt;
-  eval ${_UNSET} mpa_optchar;
-  eval "${return_ok}";
-} # main_parse_args()
-
-
-# Called from main_parse_args() because double `case' is not possible.
-# Globals: $_OPT_DEVICE, $_OPT_MODE
-_check_device_with_mode()
-{
-  func_check _check_device_with_mode = 0 "$@";
-  case "${_OPT_DEVICE}" in
-  dvi)
-    _OPT_MODE=dvi;
-    eval "${return_ok}";
-    ;;
-  html)
-    _OPT_MODE=html;
-    eval "${return_ok}";
-    ;;
-  lbp|lj4)
-    _OPT_MODE=groff;
-    eval "${return_ok}";
-    ;;
-  ps)
-    _OPT_MODE=ps;
-    eval "${return_ok}";
-    ;;
-  ascii|cp1047|latin1|utf8)
-    if obj _OPT_MODE is_not_equal text
-    then
-      _OPT_MODE=tty;		# default text mode
-    fi;
-    eval "${return_ok}";
-    ;;
-  X*)
-    _OPT_MODE=x;
-    eval "${return_ok}";
-    ;;
-  *)				# unknown device, go to groff mode
-    _OPT_MODE=groff;
-    eval "${return_ok}";
-    ;;
-  esac;
-  eval "${return_error}";
-} # _check_device_with_mode() of main_parse_args()
-
-
-########################################################################
-# main_set_mode ()
-#
-# Determine the display mode and the corresponding viewer program.
-#
-# Globals:
-#   in:  $DISPLAY, $_OPT_MODE, $_OPT_DEVICE
-#   out: $_DISPLAY_MODE
-#
-# Variable prefix: msm
-#
-main_set_mode()
-{
-  func_check main_set_mode = 0 "$@";
-
-  # set display
-  if obj _OPT_DISPLAY is_not_empty
-  then
-    DISPLAY="${_OPT_DISPLAY}";
-  fi;
-
-  if obj _OPT_V is_yes
-  then
-    list_append _ADDOPTS_GROFF '-V';
-  fi;
-  if obj _OPT_Z is_yes
-  then
-    _DISPLAY_MODE='groff';
-    list_append _ADDOPTS_GROFF '-Z';
-  fi;
-  if obj _OPT_MODE is_equal 'groff'
-  then
-    _DISPLAY_MODE='groff';
-  fi;
-  if obj _DISPLAY_MODE is_equal 'groff'
-  then
-    eval ${_UNSET} msm_modes;
-    eval ${_UNSET} msm_viewers;
-    eval "${return_ok}";
-  fi;
-
-### main_set_mode()
-
-  case "${_OPT_MODE}" in
-  '')				# automatic mode
-    case "${_OPT_DEVICE}" in
-    X*)
-     if is_not_X
-      then
-        error_user "no X display found for device ${_OPT_DEVICE}";
-      fi;
-      _DISPLAY_MODE='x';
-      eval ${_UNSET} msm_modes;
-      eval ${_UNSET} msm_viewers;
-      eval "${return_ok}";
-      ;;
-    ascii|cp1047|latin1|utf8)
-      if obj _DISPLAY_MODE is_not_equal 'text'
-      then
-        _DISPLAY_MODE='tty';
-      fi;
-      eval ${_UNSET} msm_modes;
-      eval ${_UNSET} msm_viewers;
-      eval "${return_ok}";
-      ;;
-### main_set_mode()
-    esac;
-    if is_not_X
-    then
-      _DISPLAY_MODE='tty';
-      eval ${_UNSET} msm_modes;
-      eval ${_UNSET} msm_viewers;
-      eval "${return_ok}";
-    fi;
-
-    if obj _OPT_DEFAULT_MODES is_empty
-    then
-      msm_modes="${_DEFAULT_MODES}";
-    else
-      msm_modes="${_OPT_DEFAULT_MODES}";
-    fi;
-    ;;
-  source)
-    _DISPLAY_MODE='source';
-    eval ${_UNSET} msm_modes;
-    eval ${_UNSET} msm_viewers;
-    eval "${return_ok}";
-    ;;
-  text)
-    _DISPLAY_MODE='text';
-    eval ${_UNSET} msm_modes;
-    eval ${_UNSET} msm_viewers;
-    eval "${return_ok}";
-    ;;
-  tty)
-    _DISPLAY_MODE='tty';
-    eval ${_UNSET} msm_modes;
-    eval ${_UNSET} msm_viewers;
-    eval "${return_ok}";
-    ;;
-### main_set_mode()
-  html)
-    _DISPLAY_MODE='html';
-    msm_modes="${_OPT_MODE}";
-    ;;
-  *)				# display mode was given
-    msm_modes="${_OPT_MODE}";
-    ;;
-  esac;
-
-  eval set x "${msm_modes}";
-  shift;
-  while is_greater_than "$#" 0
-  do
-    msm_1="$1";
-    shift;
-
-    _VIEWER_BACKGROUND='no';
-
-    case "${msm_1}" in
-    dvi)
-      _get_prog_args DVI;
-      if is_not_equal "$?" 0
-      then
-        continue;
-      fi;
-      if obj _DISPLAY_PROG is_empty
-      then
-        if is_equal "$#" 0
-        then
-          error 'main_set_mode(): No viewer for dvi mode available.';
-        else
-          continue;
-        fi;
-      fi;
-### main_set_mode()
-      _DISPLAY_MODE="dvi";
-      eval ${_UNSET} msm_1;
-      eval ${_UNSET} msm_modes;
-      eval ${_UNSET} msm_viewers;
-      eval "${return_ok}";
-      ;;
-    html)
-      _get_prog_args HTML;
-      if is_not_equal "$?" 0
-      then
-        continue;
-      fi;
-      if obj _DISPLAY_PROG is_empty
-      then
-        if is_equal "$#" 0
-        then
-          error 'main_set_mode(): No viewer for html mode available.';
-        else
-          continue;
-        fi;
-      fi;
-### main_set_mode()
-      _DISPLAY_MODE=html;
-      eval ${_UNSET} msm_1;
-      eval ${_UNSET} msm_modes;
-      eval ${_UNSET} msm_viewers;
-      eval "${return_ok}";
-      ;;
-    pdf)
-      if obj _PDF_DID_NOT_WORK is_yes
-      then
-        if is_equal "$#" 0
-        then
-          error 'main_set_mode(): pdf mode did not work.';
-        else
-          continue;
-        fi;
-      fi;
-      if obj _PDF_HAS_PS2PDF is_not_yes
-      then
-        if is_prog ps2pdf
-        then
-          _PDF_HAS_PS2PDF='yes';
-        fi;
-      fi;
-      if obj _PDF_HAS_GS is_not_yes
-      then
-        if is_prog gs
-        then
-          _PDF_HAS_GS='yes';
-        fi;
-      fi;
-      _get_prog_args PDF;
-      if is_not_equal "$?" 0
-      then
-        _PDF_DID_NOT_WORK='yes';
-        continue;
-      fi;
-      if obj _DISPLAY_PROG is_empty
-      then
-        _PDF_DID_NOT_WORK='yes';
-        if is_equal "$#" 0
-        then
-          error 'main_set_mode(): No viewer for pdf mode available.';
-        else
-          continue;
-        fi;
-      fi;
-      _DISPLAY_MODE="pdf";
-      eval ${_UNSET} msm_1;
-      eval ${_UNSET} msm_modes;
-      eval ${_UNSET} msm_viewers;
-      eval "${return_ok}";
-      ;;
-### main_set_mode()
-    ps)
-      _get_prog_args PS;
-      if is_not_equal "$?" 0
-      then
-        continue;
-      fi;
-      if obj _DISPLAY_PROG is_empty
-      then
-        if is_equal "$#" 0
-        then
-          error 'main_set_mode(): No viewer for ps mode available.';
-        else
-          continue;
-        fi;
-      fi;
-      _DISPLAY_MODE="ps";
-      eval ${_UNSET} msm_1;
-      eval ${_UNSET} msm_modes;
-      eval ${_UNSET} msm_viewers;
-      eval "${return_ok}";
-      ;;
-    text)
-      _DISPLAY_MODE='text';
-      eval ${_UNSET} msm_1;
-      eval ${_UNSET} msm_modes;
-      eval ${_UNSET} msm_viewers;
-      eval "${return_ok}";
-      ;;
-### main_set_mode()
-    tty)
-      _DISPLAY_MODE='tty';
-      eval ${_UNSET} msm_1;
-      eval ${_UNSET} msm_modes;
-      eval ${_UNSET} msm_viewers;
-      eval "${return_ok}";
-      ;;
-    x)
-      _get_prog_args x;
-      if is_not_equal "$?" 0
-      then
-        continue;
-      fi;
-      if obj _DISPLAY_PROG is_empty
-      then
-        if is_equal "$#" 0
-        then
-          error 'main_set_mode(): No viewer for x mode available.';
-        else
-          continue;
-        fi;
-      fi;
-      _DISPLAY_MODE='x';
-      eval ${_UNSET} msm_1;
-      eval ${_UNSET} msm_modes;
-      eval ${_UNSET} msm_viewers;
-      eval "${return_ok}";
-      ;;
-### main_set_mode()
-    X)
-      _DISPLAY_MODE='X';
-      eval ${_UNSET} msm_1;
-      eval ${_UNSET} msm_modes;
-      eval ${_UNSET} msm_viewers;
-      eval "${return_ok}";
-      ;;
-    esac;
-  done;
-  eval ${_UNSET} msm_1;
-  eval ${_UNSET} msm_modes;
-  eval ${_UNSET} msm_viewers;
-  error_user "No suitable display mode found.";
-} # main_set_mode()
-
-
-# _get_prog_args (<MODE>)
-#
-# Simplification for loop in main_set_mode().
-#
-# Globals in/out: $_VIEWER_BACKGROUND
-# Globals in    : $_OPT_VIEWER_<MODE>, $_VIEWER_<MODE>_X, $_VIEWER_<MODE>_TTY
-#
-# Variable prefix: _gpa
-#
-_get_prog_args()
-{
-  func_check _get_prog_args '=' 1 "$@";
-
-  x="$(echo1 $1 | tr [a-z] [A-Z])";
-  eval _gpa_opt='"${_OPT_VIEWER_'"$x"'}"';
-  _gpa_xlist=_VIEWER_"$x"_X;
-  _gpa_ttylist=_VIEWER_"$x"_TTY;
-
-  if obj _gpa_opt is_empty
-  then
-    _VIEWER_BACKGROUND='no';
-    if is_X
-    then
-      _get_first_prog "${_gpa_xlist}";
-      x="$?";
-      if is_equal "$x" 0
-      then
-        _VIEWER_BACKGROUND='yes';
-      fi;
-    else
-      _get_first_prog "${_gpa_ttylist}";
-      x="$?";
-    fi;
-    exit_test;
-    eval ${_UNSET} _gpa_opt;
-    eval ${_UNSET} _gpa_prog;
-    eval ${_UNSET} _gpa_ttylist;
-    eval ${_UNSET} _gpa_xlist;
-    eval "${return_var} $x";
-### _get_prog_args() of main_set_mode()
-  else				# $_gpa_opt is not empty
-    obj_from_output _gpa_prog where_is_prog "${_gpa_opt}";
-    if is_not_equal "$?" 0 || obj _gpa_prog is_empty
-    then
-      exit_test;
-      echo2 "_get_prog_args(): '${_gpa_opt}' is not an existing program.";
-      eval ${_UNSET} _gpa_opt;
-      eval ${_UNSET} _gpa_prog;
-      eval ${_UNSET} _gpa_ttylist;
-      eval ${_UNSET} _gpa_xlist;
-      eval "${return_bad}";
-    fi;
-    exit_test;
-
-    # $_gpa_prog from opt is an existing program
-
-### _get_prog_args() of main_set_mode()
-    if is_X
-    then
-      eval _check_prog_on_list ${_gpa_prog} ${_gpa_xlist};
-      if is_equal "$?" 0
-      then
-        _VIEWER_BACKGROUND='yes';
-      else
-        _VIEWER_BACKGROUND='no';
-        eval _check_prog_on_list ${_gpa_prog} ${_gpa_ttylist};
-      fi;
-    else			# is not X
-      _VIEWER_BACKGROUND='no';
-      eval _check_prog_on_list ${_gpa_prog} ${_gpa_ttylist};
-    fi;				# is_X
-  fi;				# test of $_gpa_opt
-  eval ${_UNSET} _gpa_opt;
-  eval ${_UNSET} _gpa_prog;
-  eval ${_UNSET} _gpa_ttylist;
-  eval ${_UNSET} _gpa_xlist;
-  eval "${return_good}";
-} # _get_prog_args() of main_set_mode()
-
-
-# _get_first_prog (<prog_list_name>)
-#
-# Retrieve from the elements of the list in the argument the first
-# existing program in $PATH.
-#
-# Local function for main_set_mode().
-#
-# Return  : `1' if none found, `0' if found.
-# Output  : none
-#
-# Variable prefix: _gfp
-#
-_get_first_prog()
-{
-  func_check _get_first_prog '=' 1 "$@";
-  eval x='"${'"$1"'}"';
-  eval set x "$x";
-  shift;
-  for i
-  do
-    _gfp_i="$i";
-    if obj _gfp_i is_empty
-    then
-      continue;
-    fi;
-    obj_from_output _gfp_result where_is_prog "${_gfp_i}";
-    if is_equal "$?" 0 && obj _gfp_result is_not_empty
-    then
-      exit_test;
-      eval set x ${_gfp_result};
-      shift;
-      _DISPLAY_PROG="$1";
-      _DISPLAY_ARGS="$2";
-      eval ${_UNSET} _gfp_i;
-      eval ${_UNSET} _gfp_result;
-      eval "${return_good}";
-    fi;
-    exit_test;
-  done;
-  eval ${_UNSET} _gfp_i;
-  eval ${_UNSET} _gfp_result;
-  eval "${return_bad}";
-} # _get_first_prog() of main_set_mode()
-
-
-# _check_prog_on_list (<prog> <args> <prog_list_name>)
-#
-# Check whether the content of <prog> is in the list <prog_list_name>.
-# The globals are set correspondingly.
-#
-# Local function for main_set_mode().
-#
-# Arguments: 3
-#
-# Return  : `1' if not a part of the list, `0' if found in the list.
-# Output  : none
-#
-# Globals in    : $_VIEWER_<MODE>_X, $_VIEWER_<MODE>_TTY
-# Globals in/out: $_DISPLAY_PROG, $_DISPLAY_ARGS
-#
-# Variable prefix: _cpol
-#
-_check_prog_on_list()
-{
-  func_check _check_prog_on_list '=' 3 "$@";
-  _DISPLAY_PROG="$1";
-  _DISPLAY_ARGS="$2";
-
-  eval _cpol_3='"${'"$3"'}"';
-  eval set x "${_cpol_3}";
-  shift;
-  eval ${_UNSET} _cpol_3;
-
-  for i
-  do
-    _cpol_i="$i";
-    obj_from_output _cpol_list where_is_prog "${_cpol_i}";
-    if is_not_equal "$?" 0 || obj _cpol_list is_empty
-    then
-      exit_test;
-      continue;
-    fi;
-    exit_test;
-    _cpol_prog="$(eval set x ${_cpol_list}; shift; echo1 "$1")";
-
-    if is_not_equal "${_DISPLAY_PROG}" "${_cpol_prog}"
-    then
-      exit_test;
-      continue;
-    fi;
-    exit_test;
-### _check_prog_on_list() of main_set_mode()
-
-    # equal, prog found
-
-    _cpol_args="$(eval set x ${_cpol_list}; shift; echo1 "$2")";
-    eval ${_UNSET} _cpol_list;
-    if obj _cpol_args is_not_empty
-    then
-      if obj _DISPLAY_ARGS is_empty
-      then
-        _DISPLAY_ARGS="${_cpol_args}";
-      else
-        _DISPLAY_ARGS="${_cpol_args} ${_DISPLAY_ARGS}";
-      fi;
-    fi;
-
-    eval ${_UNSET} _cpol_i;
-    eval ${_UNSET} _cpol_args;
-    eval ${_UNSET} _cpol_prog;
-    eval "${return_good}";
-  done; # for vars in list
-
-  # prog was not in the list
-  eval ${_UNSET} _cpol_i;
-  eval ${_UNSET} _cpol_args;
-  eval ${_UNSET} _cpol_list;
-  eval ${_UNSET} _cpol_prog;
-  eval "${return_bad}";
-} # _check_prog_on_list() of main_set_mode()
-
-
-#######################################################################
-# main_do_fileargs ()
-#
-# Process filespec arguments.
-#
-# Globals:
-#   in: $_FILEARGS (process with `eval set x "$_FILEARGS"; shift;')
-#
-# Variable prefix: mdfa
-#
-main_do_fileargs()
-{
-  func_check main_do_fileargs = 0 "$@";
-  special_setup;
-  if obj _OPT_APROPOS is_yes
-  then
-    if obj _NO_FILESPECS is_yes
-    then
-      apropos_filespec;
-      eval "${return_ok}";
-    fi;
-  else
-    if list_has _FILEARGS '-'
-    then
-      save_stdin;
-    fi;
-  fi;
-  eval set x "${_FILEARGS}";
-  shift;
-  eval ${_UNSET} _FILEARGS;
-### main_do_fileargs()
-  while is_greater_than "$#" 0
-  do
-    mdfa_filespec="$1";
-    _FILESPEC_ARG="$1";
-    shift;
-    _FILESPEC_IS_MAN='no';
-    _TMP_MANSPEC='';
-    _SPECIAL_FILESPEC='no';
-
-    case "${mdfa_filespec}" in
-    '')
-      continue;
-      ;;
-    esac;
-
-    # check for file
-    case "${mdfa_filespec}" in
-    '-')
-      special_filespec;
-      if obj _OPT_APROPOS is_yes
-      then
-        continue;
-      fi;
-      register_file '-';
-      continue;
-      ;;
-### main_do_fileargs()
-    */*)
-      special_filespec;
-      if obj _OPT_APROPOS is_yes
-      then
-        continue;
-      fi;
-      if obj mdfa_filespec is_file
-      then
-        obj mdfa_filespec register_file;
-      else
-        echo2 "The argument ${mdfa_filespec} is not a file.";
-      fi;
-      continue;
-      ;;
-    *)
-      if obj _OPT_APROPOS is_yes
-      then
-        special_filespec;
-        continue;
-      fi;
-      # check whether filespec is an existing file
-      if obj _MAN_FORCE is_not_yes
-      then
-        if obj mdfa_filespec is_file
-        then
-          special_filespec;
-          obj mdfa_filespec register_file;
-          continue;
-        fi;
-      fi;
-      ;;
-    esac;
-### main_do_fileargs()
-
-    # now it must be a man page pattern
-
-    if obj _MACRO_PKG is_not_empty && obj _MACRO_PKG is_not_equal '-man'
-    then
-      echo2 "${mdfa_filespec} is not a file, man pages are ignored "\
-"due to ${_MACRO_PKG}.";
-      continue;
-    fi;
-
-    # check for man page
-    if obj _MAN_ENABLE is_not_yes
-    then
-      echo2 "The argument ${mdfa_filespec} is not a file.";
-      continue;
-    fi;
-    if obj _MAN_FORCE is_yes
-    then
-      mdfa_errmsg='is not a man page.';
-    else
-      mdfa_errmsg='is neither a file nor a man page.';
-    fi;
-### main_do_fileargs()
-    man_setup;
-    _FILESPEC_IS_MAN='yes';
-
-    # test filespec with `man:...' or `...(...)' on man page
-    mdfa_name='';
-    mdfa_section='';
-    mdfa_ext='';
-
-    mdfa_names="${mdfa_filespec}";
-    case "${mdfa_filespec}" in
-    man:*)
-        mdfa_names="${mdfa_names} "\
-"$(obj mdfa_filespec echo1 | sed 's/^man://')";
-        ;;
-    esac;
-
-    mdfa_continue='no';
-    for i in ${mdfa_names}
-    do
-      mdfa_i=$i;
-      if obj mdfa_i man_is_man
-      then
-        special_filespec;
-        obj mdfa_i man_get;
-        mdfa_continue='yes';
-        break;
-      fi;
-      case "${mdfa_i}" in
-      *\(${_MAN_AUTO_SEC_CHARS}*\))
-        mdfa_section="$(obj mdfa_i echo1 | sed 's/^[^(]*(\(.\).*)$/\1/')";
-        mdfa_name="$(obj mdfa_i echo1 | sed 's/^\([^(]*\)(.*)$/\1/')";
-        mdfa_ext="$(obj mdfa_i echo1 | sed 's/^[^(]*(.\(.*\))$/\1/')";
-        if man_is_man "${mdfa_name}" "${mdfa_section}" "${mdfa_ext}"
-        then
-          special_filespec;
-          man_get "${mdfa_name}" "${mdfa_section}" "${mdfa_ext}";
-          mdfa_continue='yes';
-          break;
-        fi;
-        ;;
-      *.${_MAN_AUTO_SEC_CHARS}*)
-        mdfa_name="$(obj mdfa_i echo1 | \
-          sed 's/^\(.*\)\.'"${_MAN_AUTO_SEC_CHARS}"'.*$/\1/')";
-        mdfa_section="$(obj mdfa_i echo1 | \
-          sed 's/^.*\.\('"${_MAN_AUTO_SEC_CHARS}"'\).*$/\1/')";
-        mdfa_ext="$(obj mdfa_i echo1 | \
-          sed 's/^.*\.'"${_MAN_AUTO_SEC_CHARS}"'\(.*\)$/\1/')";
-        if man_is_man "${mdfa_name}" "${mdfa_section}" "${mdfa_ext}"
-        then
-          special_filespec;
-          man_get "${mdfa_name}" "${mdfa_section}" "${mdfa_ext}";
-          mdfa_continue='yes';
-          break;
-        fi;
-      ;;
-      esac;
-    done;
-
-    if obj mdfa_continue is_yes
-    then
-      continue;
-    fi;
-
-### main_do_fileargs()
-    # check on "s name", where "s" is a section with or without an extension
-    if is_not_empty "$1"
-    then
-      mdfa_name="$1";
-      case "${mdfa_filespec}" in
-      ${_MAN_AUTO_SEC_CHARS})
-        mdfa_section="${mdfa_filespec}";
-        mdfa_ext='';
-        ;;
-      ${_MAN_AUTO_SEC_CHARS}*)
-        mdfa_section="$(echo1 "${mdfa_filespec}" | \
-                        sed 's/^\(.\).*$/\1/')";
-        mdfa_ext="$(echo1 "${mdfa_filespec}" | \
-                    sed 's/^.\(.*\)$/\1/')";
-        ;;
-      *)
-        echo2 "${mdfa_filespec} ${mdfa_errmsg}";
-        continue;
-        ;;
-      esac;
-      shift;
-      if man_is_man "${mdfa_name}" "${mdfa_section}" "${mdfa_ext}"
-      then
-        _FILESPEC_ARG="${mdfa_filespec} ${mdfa_name}";
-        special_filespec;
-        man_get "${mdfa_name}" "${mdfa_section}" "${mdfa_ext}";
-        continue;
-      else
-        echo2 "No man page for ${mdfa_name} with section ${mdfa_filespec}.";
-        continue;
-      fi;
-    fi;
-
-### main_do_fileargs()
-    echo2 "${mdfa_filespec} ${mdfa_errmsg}";
-    continue;
-  done;
-
-  obj _TMP_STDIN rm_file_with_debug;
-  eval ${_UNSET} mdfa_filespec;
-  eval ${_UNSET} mdfa_i;
-  eval ${_UNSET} mdfa_name;
-  eval ${_UNSET} mdfa_names;
-  eval "${return_ok}";
-} # main_do_fileargs()
-
-
-########################################################################
-# main_set_resources ()
-#
-# Determine options for setting X resources with $_DISPLAY_PROG.
-#
-# Globals: $_DISPLAY_PROG, $_OUTPUT_FILE_NAME
-#
-# Variable prefix: msr
-#
-main_set_resources()
-{
-  func_check main_set_resources = 0 "$@";
-  # $msr_prog   viewer program
-  # $msr_rl     resource list
-  for f in ${_TMP_DIR}/,man*
-  do
-    rm_file_with_debug $f;
-  done;
-  obj_from_output msr_title \
-    get_first_essential "${_OPT_TITLE}" "${_REG_TITLE_LIST}";
-  _OUTPUT_FILE_NAME='';
-  eval set x "${msr_title}";
-  shift;
-  until is_equal "$#" 0
-  do
-    msr_n="$1";
-    case "${msr_n}" in
-    '')
-      continue;
-      ;;
-    ,*)
-      msr_n="$(echo1 "$1" | sed 's/^,,*//')";
-      exit_test;
-      ;;
-    esac;
-    if obj msr_n is_empty
-    then
-      continue;
-    fi;
-    if obj _OUTPUT_FILE_NAME is_not_empty
-    then
-      _OUTPUT_FILE_NAME="${_OUTPUT_FILE_NAME}"',';
-    fi;
-    _OUTPUT_FILE_NAME="${_OUTPUT_FILE_NAME}${msr_n}";
-    shift;
-  done; # until $# is 0
-### main_set_resources()
-
-  case "${_OUTPUT_FILE_NAME}" in
-  '')
-    _OUTPUT_FILE_NAME='-';
-    ;;
-  ,*)
-    error "main_set_resources(): ${_OUTPUT_FILE_NAME} starts with a comma.";
-    ;;
-  esac;
-  _OUTPUT_FILE_NAME="${_TMP_DIR}/${_OUTPUT_FILE_NAME}";
-
-  if obj _DISPLAY_PROG is_empty
-  then				# for example, for groff mode
-    _DISPLAY_ARGS='';
-    eval ${_UNSET} msr_n;
-    eval ${_UNSET} msr_prog;
-    eval ${_UNSET} msr_rl;
-    eval ${_UNSET} msr_title;
-    eval "${return_ok}";
-  fi;
-
-  eval set x "${_DISPLAY_PROG}";
-  shift;
-  obj_from_output msr_prog base_name "$1";
-  shift;
-  if is_greater_than $# 0
-  then
-    if obj _DISPLAY_ARGS is_empty
-    then
-      _DISPLAY_ARGS="$*";
-    else
-      _DISPLAY_ARGS="$* ${_DISPLAY_ARGS}";
-    fi;
-  fi;
-### main_set_resources()
-  msr_rl='';
-  if obj _OPT_BD is_not_empty
-  then
-    case "${msr_prog}" in
-    ghostview|gv|gxditview|xditview|xdvi)
-      list_append msr_rl '-bd' "${_OPT_BD}";
-      ;;
-    esac;
-  fi;
-  if obj _OPT_BG is_not_empty
-  then
-    case "${msr_prog}" in
-    ghostview|gv|gxditview|xditview|xdvi)
-      list_append msr_rl '-bg' "${_OPT_BG}";
-      ;;
-    kghostview)
-      list_append msr_rl '--bg' "${_OPT_BG}";
-      ;;
-    xpdf)
-      list_append msr_rl '-papercolor' "${_OPT_BG}";
-      ;;
-    esac;
-  fi;
-  if obj _OPT_BW is_not_empty
-  then
-    case "${msr_prog}" in
-    ghostview|gv|gxditview|xditview|xdvi)
-      _list_append msr_rl '-bw' "${_OPT_BW}";
-      ;;
-    esac;
-  fi;
-### main_set_resources()
-  if obj _OPT_FG is_not_empty
-  then
-    case "${msr_prog}" in
-    ghostview|gv|gxditview|xditview|xdvi)
-      list_append msr_rl '-fg' "${_OPT_FG}";
-      ;;
-    kghostview)
-      list_append msr_rl '--fg' "${_OPT_FG}";
-      ;;
-    esac;
-  fi;
-  if is_not_empty "${_OPT_FN}"
-  then
-    case "${msr_prog}" in
-    ghostview|gv|gxditview|xditview|xdvi)
-      list_append msr_rl '-fn' "${_OPT_FN}";
-      ;;
-    kghostview)
-      list_append msr_rl '--fn' "${_OPT_FN}";
-      ;;
-    esac;
-  fi;
-  if is_not_empty "${_OPT_GEOMETRY}"
-  then
-    case "${msr_prog}" in
-    ghostview|gv|gxditview|xditview|xdvi|xpdf)
-      list_append msr_rl '-geometry' "${_OPT_GEOMETRY}";
-      ;;
-    kghostview)
-      list_append msr_rl '--geometry' "${_OPT_GEOMETRY}";
-      ;;
-    esac;
-  fi;
-### main_set_resources()
-  if is_empty "${_OPT_RESOLUTION}"
-  then
-    _OPT_RESOLUTION="${_DEFAULT_RESOLUTION}";
-    case "${msr_prog}" in
-    gxditview|xditview)
-      list_append msr_rl '-resolution' "${_DEFAULT_RESOLUTION}";
-      ;;
-    xpdf)
-      case "${_DISPLAY_PROG}" in
-      *-z*)
-        :;
-        ;;
-      *)			# if xpdf does not have option -z
-        case "${_DEFAULT_RESOLUTION}" in
-        75)
-          # 72dpi is '100'
-          list_append msr_rl '-z' '104';
-          ;;
-        100)
-          list_append msr_rl '-z' '139';
-          ;;
-        esac;
-        ;;
-      esac;
-      ;;
-    esac;
-  else
-    case "${msr_prog}" in
-    ghostview|gv|gxditview|xditview|xdvi)
-      list_append msr_rl '-resolution' "${_OPT_RESOLUTION}";
-      ;;
-    xpdf)
-      case "${_DISPLAY_PROG}" in
-      *-z*)
-        :;
-        ;;
-      *)			# if xpdf does not have option -z
-        case "${_OPT_RESOLUTION}" in
-        75)
-          list_append msr_rl '-z' '104';
-          # '100' corresponds to 72dpi
-          ;;
-### main_set_resources()
-        100)
-          list_append msr_rl '-z' '139';
-          ;;
-        esac;
-        ;;
-      esac;
-      ;;
-    esac;
-  fi;
-  if is_yes "${_OPT_ICONIC}"
-  then
-    case "${msr_prog}" in
-    ghostview|gv|gxditview|xditview|xdvi)
-      list_append msr_rl '-iconic';
-      ;;
-    esac;
-  fi;
-  if is_yes "${_OPT_RV}"
-  then
-    case "${msr_prog}" in
-    ghostview|gv|gxditview|xditview|xdvi)
-      list_append msr_rl '-rv';
-      ;;
-    esac;
-  fi;
-  if is_not_empty "${_OPT_XRM}"
-  then
-    case "${msr_prog}" in
-    ghostview|gv|gxditview|xditview|xdvi|xpdf)
-      eval set x "${_OPT_XRM}";
-      shift;
-      for i
-      do
-        list_append msr_rl '-xrm' "$i";
-      done;
-### main_set_resources()
-      ;;
-    esac;
-  fi;
-  if is_not_empty "${msr_title}"
-  then
-    case "${msr_prog}" in
-    gxditview|xditview)
-      list_append msr_rl '-title' "${msr_title}";
-      ;;
-    esac;
-  fi;
-  if obj _DISPLAY_ARGS is_empty
-  then
-    _DISPLAY_ARGS="${msr_rl}";
-  else
-    _DISPLAY_ARGS="${msr_l} ${_DISPLAY_ARGS}";
-  fi;
-  eval ${_UNSET} msr_n;
-  eval ${_UNSET} msr_prog;
-  eval ${_UNSET} msr_rl;
-  eval ${_UNSET} msr_title;
-  eval "${return_ok}";
-} # main_set_resources
-
-
-########################################################################
-# main_display ()
-#
-# Do the actual display of the whole thing.
-#
-# Globals:
-#   in: $_DISPLAY_MODE, $_OPT_DEVICE, $_ADDOPTS_GROFF,
-#       $_TMP_CAT, $_OPT_PAGER, $_MANOPT_PAGER, $_OUTPUT_FILE_NAME
-#
-# Variable prefix: md
-#
-main_display()
-{
-  func_check main_display = 0 "$@";
-
-  export md_addopts;
-  export md_groggy;
-  export md_modefile;
-
-  if obj _TMP_CAT is_empty_file
-  then
-    echo2 'groffer: empty input.';
-    clean_up;
-    eval "${return_ok}";
-  fi;
-
-  md_modefile="${_OUTPUT_FILE_NAME}";
-
-  # go to the temporary directory to be able to access internal data files
-  cd "${_TMP_DIR}" >"${_NULL_DEV}" 2>&1;
-
-  case "${_DISPLAY_MODE}" in
-  groff)
-    if obj _OPT_DEVICE is_not_empty
-    then
-      _ADDOPTS_GROFF="${_ADDOPTS_GROFF} -T${_OPT_DEVICE}";
-    fi;
-    md_groggy="$(tmp_cat | eval grog)";
-    if is_not_equal "$?" 0
-    then
-      exit "${_ERROR}";
-    fi;
-    echo2 "grog output: ${md_groggy}";
-    exit_test;
-    _do_opt_V;
-
-### main_display()
-    obj md_modefile rm_file;
-    mv "${_TMP_CAT}" "${md_modefile}";
-    trap_unset;
-    cat "${md_modefile}" | \
-    {
-      trap_set;
-      eval "${md_groggy}" "${_ADDOPTS_GROFF}";
-    } &
-    ;;
-  text|tty)
-    case "${_OPT_DEVICE}" in
-    '')
-      obj_from_output md_device \
-        get_first_essential "${_OPT_TEXT_DEVICE}" "${_DEFAULT_TTY_DEVICE}";
-      ;;
-    ascii|cp1047|latin1|utf8)
-      md_device="${_OPT_DEVICE}";
-      ;;
-    *)
-      warning "main_display(): \
-wrong device for ${_DISPLAY_MODE} mode: ${_OPT_DEVICE}";
-      ;;
-    esac;
-    md_addopts="${_ADDOPTS_GROFF}";
-    md_groggy="$(tmp_cat | grog -T${md_device})";
-    if is_not_equal "$?" 0
-    then
-      exit "${_ERROR}";
-    fi;
-    echo2 "grog output: ${md_groggy}";
-    exit_test;
-    if obj _DISPLAY_MODE is_equal 'text'
-    then
-      _do_opt_V;
-      tmp_cat | eval "${md_groggy}" "${md_addopts}";
-    else			# $_DISPLAY_MODE is 'tty'
-### main_display()
-      md_pager='';
-      for p in "${_OPT_PAGER}" "${_MANOPT_PAGER}" "${PAGER}"
-      do
-        if obj p is_empty
-        then
-          continue;
-        fi;
-        obj_from_output md_pager where_is_prog "$p";
-        if is_not_equal "$?" 0 || obj md_pager is_empty
-        then
-          md_pager='';
-          continue;
-        fi;
-        eval set x $md_pager;
-        shift;
-        case "$1" in
-        */less)
-          if is_empty "$2"
-          then
-            md_pager="$1"' -r -R';
-          else
-            md_pager="$1"' -r -R '"$2";
-          fi;
-          ;;
-### main_display()
-        *)
-          if is_empty "$2"
-          then
-            md_pager="$1";
-          else
-            md_pager="$1 $2";
-          fi;
-          ;;
-        esac;
-        break;
-      done;
-      if obj md_pager is_empty
-      then
-        eval set x ${_VIEWER_TTY_TTY} ${_VIEWER_TTY_X} 'cat';
-        shift;
-        # that is: 'less -r -R' 'more' 'pager' 'xless' 'cat'
-        for p
-        do
-          if obj p is_empty
-          then
-            continue;
-          fi;
-          md_p="$p";
-          if is_prog "${md_p}"
-          then
-            md_pager="${md_p}";
-            break;
-          fi;
-        done;
-      fi;
-### main_display()
-      if obj md_pager is_empty
-      then
-        error 'main_display(): no pager program found for tty mode';
-      fi;
-      _do_opt_V;
-      tmp_cat | eval "${md_groggy}" "${md_addopts}" | \
-                eval "${md_pager}";
-    fi;				# $_DISPLAY_MODE
-    clean_up;
-    ;;				# text|tty)
-  source)
-    tmp_cat;
-    clean_up;
-    ;;
-
-  #### viewer modes
-
-### main_display()
-  dvi)
-    case "${_OPT_DEVICE}" in
-    ''|dvi) do_nothing; ;;
-    *)
-      warning "main_display(): \
-wrong device for ${_DISPLAY_MODE} mode: ${_OPT_DEVICE}"
-      ;;
-    esac;
-    md_modefile="${md_modefile}".dvi;
-    md_groggy="$(tmp_cat | grog -Tdvi)";
-    if is_not_equal "$?" 0
-    then
-      exit "${_ERROR}";
-    fi;
-    echo2 "grog output: ${md_groggy}";
-    exit_test;
-    _do_display;
-    ;;
-  html)
-    case "${_OPT_DEVICE}" in
-    ''|html) do_nothing; ;;
-    *)
-      warning "main_display(): \
-wrong device for ${_DISPLAY_MODE} mode: ${_OPT_DEVICE}";
-      ;;
-    esac;
-    md_modefile="${md_modefile}".html;
-    md_groggy="$(tmp_cat | grog -Thtml)";
-    if is_not_equal "$?" 0
-    then
-      exit "${_ERROR}";
-    fi;
-    echo2 "grog output: ${md_groggy}";
-    exit_test;
-    _do_display;
-    ;;
-### main_display()
-  pdf)
-    case "${_OPT_DEVICE}" in
-    ''|ps)
-      do_nothing;
-      ;;
-    *)
-      warning "main_display(): \
-wrong device for ${_DISPLAY_MODE} mode: ${_OPT_DEVICE}";
-      ;;
-    esac;
-    md_groggy="$(tmp_cat | grog -Tps)";
-    if is_not_equal "$?" 0
-    then
-      exit "${_ERROR}";
-    fi;
-    echo2 "grog output: ${md_groggy}";
-    exit_test;
-    _do_display _make_pdf;
-    ;;
-  ps)
-    case "${_OPT_DEVICE}" in
-    ''|ps)
-      do_nothing;
-      ;;
-    *)
-      warning "main_display(): \
-wrong device for ${_DISPLAY_MODE} mode: ${_OPT_DEVICE}";
-      ;;
-    esac;
-    md_modefile="${md_modefile}".ps;
-    md_groggy="$(tmp_cat | grog -Tps)";
-    if is_not_equal "$?" 0
-    then
-      exit "${_ERROR}";
-    fi;
-    echo2 "grog output: ${md_groggy}";
-    exit_test;
-    _do_display;
-    ;;
-### main_display()
-  x)
-    case "${_OPT_DEVICE}" in
-    X*)
-      md_device="${_OPT_DEVICE}"
-      ;;
-    *)
-      case "${_OPT_RESOLUTION}" in
-      100)
-        md_device='X100';
-        if obj _OPT_GEOMETRY is_empty
-        then
-          case "${_DISPLAY_PROG}" in
-          gxditview|xditview)
-            # add width of 800dpi for resolution of 100dpi to the args
-            list_append _DISPLAY_ARGS '-geometry' '800';
-            ;;
-          esac;
-        fi;
-        ;;
-      *)
-        md_device='X75-12';
-        ;;
-      esac
-    esac;
-    md_groggy="$(tmp_cat | grog -T${md_device} -Z)";
-    if is_not_equal "$?" 0
-    then
-      exit "${_ERROR}";
-    fi;
-    echo2 "grog output: ${md_groggy}";
-    exit_test;
-    _do_display;
-    ;;
-### main_display()
-  X)
-    case "${_OPT_DEVICE}" in
-    '')
-      md_groggy="$(tmp_cat | grog -X)";
-      if is_not_equal "$?" 0
-      then
-        exit "${_ERROR}";
-      fi;
-      echo2 "grog output: ${md_groggy}";
-      exit_test;
-      ;;
-    X*|dvi|html|lbp|lj4|ps)
-      # these devices work with
-      md_groggy="$(tmp_cat | grog -T"${_OPT_DEVICE}" -X)";
-      if is_not_equal "$?" 0
-      then
-        exit "${_ERROR}";
-      fi;
-      echo2 "grog output: ${md_groggy}";
-      exit_test;
-      ;;
-    *)
-      warning "main_display(): \
-wrong device for ${_DISPLAY_MODE} mode: ${_OPT_DEVICE}";
-      md_groggy="$(tmp_cat | grog -Z)";
-      if is_not_equal "$?" 0
-      then
-        exit "${_ERROR}";
-      fi;
-      echo2 "grog output: ${md_groggy}";
-      exit_test;
-      ;;
-    esac;
-    _do_display;
-    ;;
-  *)
-    error "main_display(): unknown mode \`${_DISPLAY_MODE}'";
-    ;;
-  esac;
-  eval ${_UNSET} md_addopts;
-  eval ${_UNSET} md_device;
-  eval ${_UNSET} md_groggy;
-  eval ${_UNSET} md_modefile;
-  eval ${_UNSET} md_p;
-  eval ${_UNSET} md_pager;
-  eval "${return_ok}";
-} # main_display()
-
-
-########################
-# _do_display ([<prog>])
-#
-# Perform the generation of the output and view the result.  If an
-# argument is given interpret it as a function name that is called in
-# the midst (actually only for `pdf').
-#
-# Globals: $md_modefile, $md_groggy (from main_display())
-#
-_do_display()
-{
-  func_check _do_display '>=' 0 "$@";
-  _do_opt_V;
-  if obj _DISPLAY_PROG is_empty
-  then
-    trap_unset;
-    {
-      trap_set;
-      eval "${md_groggy}" "${_ADDOPTS_GROFF}" "${_TMP_CAT}";
-    } &
-  else
-    obj md_modefile rm_file;
-    cat "${_TMP_CAT}" | \
-      eval "${md_groggy}" "${_ADDOPTS_GROFF}" > "${md_modefile}";
-    if obj md_modefile is_empty_file
-    then
-      echo2 '_do_display(): empty output.';
-      clean_up;
-      exit;
-    fi;
-    if is_not_empty "$1"
-    then
-      eval "$1";
-    fi;
-### _do_display() of main_display()
-    obj _TMP_CAT rm_file_with_debug;
-    if obj _OPT_STDOUT is_yes
-    then
-      cat "${md_modefile}";
-      clean_up;
-      exit;
-    fi;
-    if obj _VIEWER_BACKGROUND is_not_yes # for programs that run on tty
-    then
-      eval "'${_DISPLAY_PROG}'" ${_DISPLAY_ARGS} "\"${md_modefile}\"";
-    else
-      trap_unset;
-      {
-        trap_set;
-        eval "${_DISPLAY_PROG}" ${_DISPLAY_ARGS} "\"${md_modefile}\"";
-      } &
-    fi;
-  fi;
-  eval "${return_ok}";
-} # _do_display() of main_display()
-
-
-#############
-# _do_opt_V ()
-#
-# Check on option `-V'; if set print the corresponding output and leave.
-#
-# Globals: $_ALL_PARAMS, $_ADDOPTS_GROFF, $_DISPLAY_MODE, $_DISPLAY_PROG,
-#          $_DISPLAY_ARGS, $md_groggy,  $md_modefile
-#
-# Variable prefix: _doV
-#
-_do_opt_V()
-{
-  func_check _do_opt_V '=' 0 "$@";
-  if obj _OPT_V is_yes
-  then
-    _OPT_V='no';
-    echo1 "Parameters:     ${_ALL_PARAMS}";
-    echo1 "Display mode:   ${_DISPLAY_MODE}";
-    echo1 "Output file:    ${md_modefile}";
-    echo1 "Display prog:   ${_DISPLAY_PROG} ${_DISPLAY_ARGS}";
-    a="$(eval echo1 "'${_ADDOPTS_GROFF}'")";
-    exit_test;
-    echo1 "Output of grog: ${md_groggy} $a";
-    _doV_res="$(eval "${md_groggy}" "${_ADDOPTS_GROFF}")";
-    exit_test;
-    echo1 "groff -V:       ${_doV_res}"
-    leave;
-  fi;
-  eval "${return_ok}";
-} # _do_opt_V() of main_display()
-
-
-##############
-# _make_pdf ()
-#
-# Transform to pdf format; for pdf mode in _do_display().
-#
-# Globals: $md_modefile (from main_display())
-#
-# Variable prefix: _mp
-#
-_make_pdf()
-{
-  func_check _make_pdf '=' 0 "$@";
-  _mp_psfile="${md_modefile}";
-  md_modefile="${md_modefile}.pdf";
-  obj md_modefile rm_file;
-  if obj _PDF_HAS_PS2PDF is_yes && ps2pdf "${_mp_psfile}" "${md_modefile}";
-  then
-    :;
-  elif obj _PDF_HAS_GS is_yes && gs -q -dNOPAUSE -dBATCH -sDEVICE=pdfwrite \
-       -sOutputFile="${md_modefile}" -c save pop -f "${_mp_psfile}";
-  then
-    :;
-  else
-    _PDF_DID_NOT_WORK='yes';
-    echo2 '_make_pdf(): Could not transform into pdf format. '\
-'The Postscript mode (ps) is used instead.';
-    _OPT_MODE='ps';
-    main_set_mode;
-    main_set_resources;
-    main_display;
-    exit;
-  fi;
-  obj _mp_psfile rm_file_with_debug;
-  eval ${_UNSET} _mp_psfile;
-  eval "${return_ok}";
-} # _make_pdf() of main_display()
-
-
-########################################################################
-# main (<command_line_args>*)
-#
-# The main function for groffer.
-#
-# Arguments:
-#
-main()
-{
-  func_check main '>=' 0 "$@";
-  # Do not change the sequence of the following functions!
-  landmark '13: main_init()';
-  main_init;
-  landmark '14: main_parse_MANOPT()';
-  main_parse_MANOPT;
-  landmark '15: main_parse_args()';
-  main_parse_args "$@";
-  landmark '16: main_set_mode()';
-  main_set_mode;
-  landmark '17: main_do_fileargs()';
-  main_do_fileargs;
-  landmark '18: main_set_resources()';
-  main_set_resources;
-  landmark '19: main_display()';
-  main_display;
-  eval "${return_ok}";
-}
-
-
-########################################################################
-
-main "$@";

Index: groffer/shell/roff2.sh
===================================================================
RCS file: groffer/shell/roff2.sh
diff -N groffer/shell/roff2.sh
--- groffer/shell/roff2.sh	22 Jan 2013 00:29:42 -0000	1.5
+++ /dev/null	1 Jan 1970 00:00:00 -0000
@@ -1,339 +0,0 @@
-#! /bin/sh
-
-# roff2* - transform roff files into other formats
-
-# Source file position: <groff-source>/contrib/groffer/shell/roff2.sh
-# Installed position: <prefix>/bin/roff2*
-
-# Copyright (C) 2006, 2009 Free Software Foundation, Inc.
-# Written by Bernd Warken <groff-bernd.warken-72@web.de>.
-
-# Last update: 5 Jan 2009
-
-# 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/>.
-
-########################################################################
-
-
-##############
-# echo1 (<text>*)
-#
-# Output to stdout with final line break.
-#
-# Arguments : arbitrary text including `-'.
-#
-echo1()
-{
-  cat <<EOF
-$@
-EOF
-} # echo1()
-
-
-##############
-# echo2 (<text>*)
-#
-# Output to stderr with final line break.
-#
-# Arguments : arbitrary text including `-'.
-#
-echo2()
-{
-  cat >&2 <<EOF
-$@
-EOF
-} # echo2()
-
-
-error_no_groffer='no';
-error_no_groffer() {
-  if test _"$error_no_groffer" = _yes
-  then
-    return;
-  fi;
-  error_no_groffer='yes';
-  echo2 "$name: groffer is not available.";
-}
-
-
-error_no_options='no';
-error_no_options() {
-  if test _"$error_no_options" = _yes
-  then
-    return;
-  fi;
-  error_no_groffer='yes';
-  echo2 "$name: groffer options are not allowed.";
-}
-
-
-usage_with_groffer() {
-  cat <<EOF
-usage: $Name [option]... [--] [filespec]...
-
--h | --help     print usage information
--v | --version  print version information
-
-All other options are arbitrary options of "groffer"; the options
-override the behavior of this program.
-
-"filespec"s are the same as in "groffer": either the names of
-existing, readable files or "-" for standard input or a search pattern
-for man pages.  No "filespec" assumes standard input automatically.
-EOF
-}
-
-usage_without_groffer() {
-  cat <<EOF
-usage: $Name [option]... [--] [filespec]...
-
--h | --help     print usage information
--v | --version  print version information
-
-No other options are allowed because "groffer" is not available.
-
-The only "filespec"s allowed are the names of existing, readable files
-or "-" for standard input.  No "filespec" assumes standard input
-automatically.
-EOF
-}
-
-
-where_is_prog() {
-  for p in `echo $PATH|sed "s/:/ /g"`
-  do
-    f="${p}/$1";
-    if test -f "$f" && test -x "$f"
-    then
-      echo1 "$f";
-      return;
-    fi;
-  done;
-}
-
-
-########################################################################
-
-export NULL_DEV;
-if test -c /dev/null
-then
-  NULL_DEV='/dev/null';
-else
-  NULL_DEV='NUL';
-fi;
-
-name="$(echo1 "$0" | sed 's|^.*//*\([^/]*\)$|\1|')";
-
-case "$name" in
-roff2[a-z]*)
-  mode="$(echo1 "$name" | sed 's/^roff2//')";
-  ;;
-*)
-  echo2 "wrong program name: $name";
-  exit 1;
-  ;;
-esac;
-
-groff_version="$(groff --version 2>$NULL_DEV)";
-if test $? -gt 0
-then
-  echo2 "$name error: groff does not work.";
-  exit 1;
-fi;
-groffer_version="$(groffer --version 2>$NULL_DEV)";
-if test $? -gt 0
-then
-  has_groffer='no';
-else
-  has_groffer='yes';
-fi;
-
-if test _"${has_groffer}" = _yes
-then
-  for i
-  do
-    case $i in
-    -v|--v|--ve|--ver|--vers|--versi|--versio|--version)
-      echo1 "$name in $groffer_version";
-      exit 0;
-      ;;
-    -h|--h|--he|--hel|--help)
-      usage_with_groffer;
-      exit 0;
-      ;;
-    esac;
-  done;
-  groffer --to-stdout --$mode "$@";
-else				# not has_groffer
-  reset=no;
-  double_minus=no;
-  for i
-  do
-    if test _"${reset}" = _no
-    then
-      set --;
-      reset=yes;
-    fi;
-    if test _"${double_minus}" = _yes
-    then
-      set -- "$@" "$i";
-      continue;
-    fi;
-    case "$i" in
-    --)
-      double_minus=yes;
-      continue;
-      ;;
-    -)
-      set -- "$@" '-';
-      continue;
-      ;;
-    -v|--v|--ve|--ver|--vers|--versi|--versio|--version)
-      echo1 "$name in $groff_version";
-      exit 0;
-      ;;
-    -h|--h|--he|--hel|--help)
-      usage_without_groffer;
-      exit 0;
-      ;;
-    -*)
-      error_no_groffer;
-      error_no_options;
-      ;;
-    *)
-      if test -f "$i" && test -r "$i"
-      then
-        set -- "$@" "$i";
-      else
-        error_no_groffer;
-        echo2 "$i is not an existing, readable file.";
-      fi;
-      continue;
-      ;;
-    esac;
-  done;				# for i
-
-  if test $# -eq 0
-  then
-    set -- '-';
-  fi;
-  has_stdin=no;
-  for i
-  do
-    case "$i" in
-    -)
-      has_stdin=yes;
-      break;
-      ;;
-    esac;
-  done;
-
-  if test _$has_stdin = _yes
-  then
-    umask 0077;
-    tempdir='';
-    for d in "${GROFF_TMPDIR}" "${TMPDIR}" "${TMP}" "${TEMP}" \
-           "${TEMPDIR}" "${HOME}"'/tmp' '/tmp' "${HOME}" '.'
-    do
-      if test _"$d" = _ || ! test -d "$d" || ! test -w "$d"
-      then
-        continue;
-      fi;
-      case "$d" in
-      */)
-        tempdir="$d";
-        ;;
-      *)
-        tempdir="$d"'/';
-        ;;
-      esac;
-    done;
-    if test _$tempdir = _
-    then
-      echo2 "${name}: could not find a temporary directory."
-      exit 1;
-    fi;
-    stdin=${tempdir}${name}_$$;
-    if test -e "$stdin"
-    then
-      rm -f "$stdin";
-      n=0;
-      f="${stdin}_$n";
-      while test -e "$f"
-      do
-	rm -f "$f";
-        if ! test -e "$f"
-        then
-          break;
-        fi;
-        n="$(expr $n + 1)";
-        f="${stdin}_$n";
-      done;
-      stdin="$f";
-    fi;
-    reset=no;
-    for i
-    do
-      if test _"${reset}" = _no
-      then
-        set --;
-        reset=yes;
-      fi;
-      case "$i" in
-      -)
-        set -- "$@" "$stdin";
-        ;;
-      *)
-        set -- "$@" "$i";
-        ;;
-      esac;
-    done;
-    cat>"$stdin";
-  fi;				# if has_stdin
-
-  case "$mode" in
-  x)
-    groff_options='-TX75-12 -Z';
-    ;;
-  text)
-    groff_options='-Tlatin1';
-    ;;
-  pdf)
-    ps2pdf="$(where_is_prog ps2pdf)";
-    if test _"$ps2pdf" = _
-    then
-      ps2pdf="$(where_is_prog gs)";
-      if test _"$ps2pdf" = _
-      then
-        echo2 "$name: cannot transform to pdf format.";
-        exit 1;
-      fi;
-      ps2pdf="$ps2pdf -q -dNOPAUSE -dBATCH -sDEVICE=pdfwrite '-sOutputFile=- -c save pop -f -";
-    else
-      ps2pdf="$ps2pdf -";
-    fi;
-    grog="$(grog -Tps "$@")";
-    eval $grog | ${ps2pdf};
-    exit $?;
-    ;;
-  *)
-    groff_options="-T$mode";
-    ;;
-  esac;
-  grog="$(grog $groff_options "$@")";
-  eval $grog;
-  exit $?;
-fi;				# not has_groffer


From MAILER-DAEMON Mon Aug 05 08:19:15 2013
Received: from list by lists.gnu.org with archive (Exim 4.71)
	id 1V6Jkp-0003ZT-BW
	for mharc-groff-commit@gnu.org; Mon, 05 Aug 2013 08:19:15 -0400
Received: from eggs.gnu.org ([2001:4830:134:3::10]:60858)
	by lists.gnu.org with esmtp (Exim 4.71)
	(envelope-from <werner.lemberg@gmx.de>) id 1V6Jkf-0003Y6-MO
	for groff-commit@gnu.org; Mon, 05 Aug 2013 08:19:13 -0400
Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71)
	(envelope-from <werner.lemberg@gmx.de>) id 1V6JkY-0007a1-Dx
	for groff-commit@gnu.org; Mon, 05 Aug 2013 08:19:05 -0400
Received: from mout.gmx.net ([212.227.17.21]:56257)
	by eggs.gnu.org with esmtp (Exim 4.71)
	(envelope-from <werner.lemberg@gmx.de>) id 1V6JkY-0007ZZ-3D
	for groff-commit@gnu.org; Mon, 05 Aug 2013 08:18:58 -0400
Received: from localhost ([77.117.246.221]) by mail.gmx.com (mrgmx101) with
	ESMTPA (Nemesis) id 0LtmK9-1U5JnJ1zrZ-011Cbj for <groff-commit@gnu.org>;
	Mon, 05 Aug 2013 14:18:56 +0200
Date: Mon, 05 Aug 2013 14:18:46 +0200 (CEST)
Message-Id: <20130805.141846.476557710.wl@gnu.org>
To: groff-bernd.warken-72@web.de
From: Werner LEMBERG <wl@gnu.org>
In-Reply-To: <E1V6IP6-0001gV-Tp@vcs.savannah.gnu.org>
References: <E1V6IP6-0001gV-Tp@vcs.savannah.gnu.org>
X-Mailer: Mew version 6.5 on Emacs 24.3.50.1 / Mule 6.0 (HANACHIRUSATO)
Mime-Version: 1.0
Content-Type: Text/Plain; charset=us-ascii
Content-Transfer-Encoding: 7bit
Sender: werner.lemberg@gmx.de
X-Provags-ID: V03:K0:ER/wnlpWnDFjFaYvButuSElZWOfCbhk9Bumxem8VojG40LtmqJT
	vy7PN9B8Sl0cj3vtWfaInuitzp2+/nfcAAw3EG/HJUIeOvqtF56wpNXl/3NZGUWLYdzCX66
	2v1CAN2Lw30D5O5y74lcVpB8alTy4hm7t34kvAki7ynzUBHdHnhULVZTYq7Ep8x4jP/IArC
	aRZmf6TNXaHvNhwBkmZDw==
X-detected-operating-system: by eggs.gnu.org: GNU/Linux 3.x [generic]
X-Received-From: 212.227.17.21
Cc: groff-commit@gnu.org
Subject: Re: [Groff-commit] groff/contrib RUNOFF/ChangeLog
 RUNOFF/Makefile....
X-BeenThere: groff-commit@gnu.org
X-Mailman-Version: 2.1.14
Precedence: list
List-Id: <groff-commit.gnu.org>
List-Unsubscribe: <https://lists.gnu.org/mailman/options/groff-commit>,
	<mailto:groff-commit-request@gnu.org?subject=unsubscribe>
List-Archive: <http://lists.gnu.org/archive/html/groff-commit>
List-Post: <mailto:groff-commit@gnu.org>
List-Help: <mailto:groff-commit-request@gnu.org?subject=help>
List-Subscribe: <https://lists.gnu.org/mailman/listinfo/groff-commit>,
	<mailto:groff-commit-request@gnu.org?subject=subscribe>
X-List-Received-Date: Mon, 05 Aug 2013 12:19:13 -0000


Hallo Bernd!


> Removed files: [...]

Darf ich fragen, was das wird?


    Werner


From MAILER-DAEMON Sun Aug 11 04:27:51 2013
Received: from list by lists.gnu.org with archive (Exim 4.71)
	id 1V8R0B-0004h2-MK
	for mharc-groff-commit@gnu.org; Sun, 11 Aug 2013 04:27:51 -0400
Received: from eggs.gnu.org ([2001:4830:134:3::10]:51607)
	by lists.gnu.org with esmtp (Exim 4.71) (envelope-from <wl@gnu.org>)
	id 1V8R00-0004gU-Dm
	for groff-commit@gnu.org; Sun, 11 Aug 2013 04:27:50 -0400
Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71)
	(envelope-from <wl@gnu.org>) id 1V8Qzp-0001p7-Kb
	for groff-commit@gnu.org; Sun, 11 Aug 2013 04:27:40 -0400
Received: from vcs.savannah.gnu.org ([140.186.70.72]:37995)
	by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from <wl@gnu.org>)
	id 1V8Qzp-0001oz-DV
	for groff-commit@gnu.org; Sun, 11 Aug 2013 04:27:29 -0400
Received: from wl by vcs.savannah.gnu.org with local (Exim 4.72)
	(envelope-from <wl@gnu.org>) id 1V8Qzo-0002TX-IW
	for groff-commit@gnu.org; Sun, 11 Aug 2013 08:27:28 +0000
Date: Sun, 11 Aug 2013 08:27:28 +0000
Message-Id: <E1V8Qzo-0002TX-IW@vcs.savannah.gnu.org>
To: groff-commit@gnu.org
From: Werner LEMBERG <wl@gnu.org>
X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6.x
X-Received-From: 140.186.70.72
Subject: [Groff-commit] groff/contrib chem/ChangeLog chem/Makefile.sub ...
X-BeenThere: groff-commit@gnu.org
X-Mailman-Version: 2.1.14
Precedence: list
List-Id: <groff-commit.gnu.org>
List-Unsubscribe: <https://lists.gnu.org/mailman/options/groff-commit>,
	<mailto:groff-commit-request@gnu.org?subject=unsubscribe>
List-Archive: <http://lists.gnu.org/archive/html/groff-commit>
List-Post: <mailto:groff-commit@gnu.org>
List-Help: <mailto:groff-commit-request@gnu.org?subject=help>
List-Subscribe: <https://lists.gnu.org/mailman/listinfo/groff-commit>,
	<mailto:groff-commit-request@gnu.org?subject=subscribe>
X-List-Received-Date: Sun, 11 Aug 2013 08:27:50 -0000

CVSROOT:	/sources/groff
Module name:	groff
Changes by:	Werner LEMBERG <wl>	13/08/11 08:27:28

Added files:
	contrib/chem   : ChangeLog Makefile.sub README.txt chem.man 
	                 chem.pic chem.pl 
	contrib/chem/examples: README.txt atp.chem cholesterin.chem 
	                       ethamivan.chem lsd.chem morphine.chem 
	                       penicillin.chem reserpine.chem 
	contrib/groffer: ChangeLog Makefile.sub README roff2.man 
	                 version.sh 

Log message:
	Revert last accidental removal of files.

CVSWeb URLs:
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/chem/ChangeLog?cvsroot=groff&rev=1.20
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/chem/Makefile.sub?cvsroot=groff&rev=1.18
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/chem/README.txt?cvsroot=groff&rev=1.7
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/chem/chem.man?cvsroot=groff&rev=1.15
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/chem/chem.pic?cvsroot=groff&rev=1.7
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/chem/chem.pl?cvsroot=groff&rev=1.13
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/chem/examples/README.txt?cvsroot=groff&rev=1.8
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/chem/examples/atp.chem?cvsroot=groff&rev=1.6
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/chem/examples/cholesterin.chem?cvsroot=groff&rev=1.6
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/chem/examples/ethamivan.chem?cvsroot=groff&rev=1.6
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/chem/examples/lsd.chem?cvsroot=groff&rev=1.6
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/chem/examples/morphine.chem?cvsroot=groff&rev=1.6
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/chem/examples/penicillin.chem?cvsroot=groff&rev=1.6
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/chem/examples/reserpine.chem?cvsroot=groff&rev=1.7
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/groffer/ChangeLog?cvsroot=groff&rev=1.67
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/groffer/Makefile.sub?cvsroot=groff&rev=1.35
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/groffer/README?cvsroot=groff&rev=1.17
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/groffer/roff2.man?cvsroot=groff&rev=1.8
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/groffer/version.sh?cvsroot=groff&rev=1.23

Patches:
Index: chem/ChangeLog
===================================================================
RCS file: chem/ChangeLog
diff -N chem/ChangeLog
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ chem/ChangeLog	11 Aug 2013 08:26:58 -0000	1.20
@@ -0,0 +1,232 @@
+2013-01-29  Werner LEMBERG  <wl@gnu.org>
+
+	* Makefile.sub (MOSTLYCLEANADD): Fix typo.
+
+2010-12-13  Werner LEMBERG  <wl@gnu.org>
+
+	Really fix handling of examples/122.
+
+	* examples/122/README: Renamed to...
+	* examples/122/README.txt: This.
+
+	* Makefile.sub (all, MOSTLYCLEANADD): Add `examples/122/README'.
+	(examples/122/README): New target.
+	(install_data): Fix typo.
+
+2010-06-02  Larry Jones  <lawrence.jones@siemens.com>
+
+	* Makefile.sub (install): Fix handling of examples/122.
+	It tried to process the CVS subdirectory as a file.
+
+2009-01-03  Werner LEMBERG  <wl@gnu.org>
+
+	* chem.pl: Prepare for groff version 1.20.
+
+2008-01-04  Werner LEMBERG  <wl@gnu.org>
+
+	* chem.man: Insert `\:' in URLs where appropriate.
+
+2007-02-06  Eric S. Raymond  <esr@snark.thyrsus.com>
+
+	* chem.man: Change .UR/.UE and .MT/.ME so the start macro no longer
+	takes a second argument that is pasted to the end of the generated
+	text.  Instead, the end macro takes an argument that does the same
+	thing.
+
+2007-02-02  Werner LEMBERG  <wl@gnu.org>
+
+	* chem.man: Further refinements and normalizations.
+
+2007-02-02  Eric S. Raymond  <esr@snark.thyrsus.com>
+
+	* chem.man: Converted to use .SY/.OP/.YS and for cross-viewer
+	portability.  Conversion checked using the protocol described in
+	tmac/TESTING-HINTS.
+
+2006-11-10  Bernd Warken <groff-bernd.warken-72@web.de>
+       ________________________________________________________________
+        * release of chem 0.3.1
+
+	* chem.man: Add information about example files.
+
+2006-11-10  Werner LEMBERG  <wl@gnu.org>
+
+        * chem.man1: Rename back to...
+        * chem.man: This.
+        Use @G@, @MACRODIR@, and @DATASUBDIR@.
+
+        * Makefile.sub (CLEANADD, all): Don't handle chem.man.
+        (chem.man): Remove rule.
+        (chem): s/tmacdir/MACRODIR/, s/picdir/PICDIR/.
+
+        * chem.pl: s/tmacdir/MACRODIR/, s/picdir/PICDIR/.
+
+2006-11-10  Bernd Warken <groff-bernd.warken-72@web.de>
+       ________________________________________________________________
+        * release of chem 0.3.0
+
+	* chem.man1: Rename `chem.man' to translate some `@...@'
+	constructs.  Some minor corrections.  Remove some unused macros.
+
+	* examples/README.txt, examples/122/README: Add information on
+	`roff2*' programs.
+
+	* chem.pic: Rename `macros.pic'.
+
+	* Makefile.sub, chem.pl: Replace `macros.pic' by `chem.pic'.
+
+2006-11-09  Werner LEMBERG  <wl@gnu.org>
+
+        * chem.man: Revised.
+
+2006-11-08  Bernd Warken <groff-bernd.warken-72@web.de>
+       ________________________________________________________________
+        * release of chem 0.2.0
+
+	* pic.tmac: Remove this file.  Use instead the installed pic.tmac
+	in $(tmacdir).
+
+	* Makefile.sub, chem.pl:
+	- Install macros.pic to $(tmacdir)/pic/chem.pic.
+	- Remove parts with `libdir'.
+
+2006-11-07  Werner LEMBERG  <wl@gnu.org>
+
+	* Makefile.sub: Add and fix $(srcdir) where necessary to make it
+	compile with srcdir != builddir.  Other minor fixes improvements.
+
+2006-11-07  Bernd Warken <groff-bernd.warken-72@web.de>
+       ________________________________________________________________
+        * release of chem 0.1.2
+
+	### `chem' works now with all example files (examples/*.chem and
+	examples/122/*.chem).
+	
+	* examples/122/README: Add some information on the example files.
+	
+	* examples/122/chAi_poly_vinyl_chloride.chem: Use .ps with
+	argument `-2' and recall `.ps +2' at the end of the file.  This
+	stops the size shift in the following files.
+
+	* examples/122/ch6b_dna.chem: Make the file runnable, it works
+	now.
+
+	* examples/reserpine.chem: Change access to `begin chem'.
+
+	* chem.man:
+	- Fix the BUGS section.
+	- Correct the name of the macro file to `macros.pic'.
+	- Extent section DESCRIPTION and LANGUAGE.
+	- Moieties and Strings: Rewritten section about moieties and
+	double quoted strings.
+
+	* chem.pl:
+	- parameter check: Add filespecs only when non-empty file.
+	- Set $Last_Type to $OTHER for the `pic' command.
+	- joinring(), label(), labsave(), reduce(): Remove these functions.
+	- `[', `]', `{', `}', `define': Make these and the defined
+	functions commands for `chem' without using the `pic' word.
+	- @Words: Fix it such that all double quoted strings are
+	completely in an element.
+	- `Last: ': Remove this prefix from all commands that are related
+	to `pic'.
+
+	### global variables
+	
+	* chem.pl:
+	- $Line: Add this variable to store the unchanged input line.
+	- %Params: Add the variables from setparams() to this hash.
+	- %Types: Add BOND, MOL, RING, OTHER from init() to this hash.
+	- %Put: Move %put to this.
+	- %Dbl: Move %dbl to this.
+	- %Labtype: Move %labtype to this.
+	- %Aromatic: Move $aromatic to this.
+	- %Dc: Move %dc to this.
+	- %Nput: Move $nput to this.
+	- %Define: New hash for storing the names of the `define'
+	constructs during `chem'.  Use the elements in `%Define' as `chem'
+	commands.
+
+2006-10-27  Bernd Warken <groff-bernd.warken-72@web.de>
+       ________________________________________________________________
+        * release of chem 0.1.1
+
+	* chem.pl:
+	- Add handling of `[' and `]' (extension of chem awk).
+	- Restrict line break after labels.
+
+	* ChangeLog: Correct the former entry.
+	
+2006-10-26  Bernd Warken <groff-bernd.warken-72@web.de>
+       ________________________________________________________________
+        * release of chem 0.1.0
+
+	### Extensions to the chem awk version.
+	
+	* chem.pl:
+	- parameters: -h, --help, -v, --version, -- are added as options.
+	The minus character - is added as filespec for standard input, it
+	may be used several times.
+	- remove the functions `inline', `shiftfields', and `set'.
+	- Fix the handling of the initialization commands .PS, .cstart,
+	`begin chem', and `end'.
+	- Add error massages.
+	- error(): Add file name.
+	- Add concatenation of lines with final backslash `\'.
+	- Add pic.tmac to guarantee that each pic display is centered.
+	- Warnings and strict are active.
+
+	### Source files of the chem Perl version
+
+	* chem.pl: Source file for the Perl version of chem.
+
+	* macros.pic: Pic macro file that is loaded by each run of chem.
+
+	* pic.tmac: Macro file for .PS and .PE; taken over from the groff
+	source file <groff-top-source>/tmac/pic.tmac.
+
+	* Makefile.sub: Make file for the groff system.
+
+	* ChangeLog: This file.
+	
+	* chem.man: Manual page for the Perl version of chem.
+
+	* README.txt: File for information on this chem version.
+
+	* examples/*.chem: Self-constructed example files for chem.
+
+	* examples/README.txt: Information on the example files.
+	
+	* examples/122/*.chem: Example files from the classical chem book
+	122.ps at <http://cm.bell-labs.com/cm/cs/cstr/122.ps.gz>.
+
+	* examples/122/README: Information on the example files in this
+	directory.
+
+2006-10-16  Bernd Warken <groff-bernd.warken-72@web.de>
+
+	* awk version of chem
+	chem is a roff preprocessor that generates chemical structure
+	diagrams suitable for the pic preprocessor.  The original version
+	of chem is an awk script written by Brian Kernighan.  This project
+	is a rewrite of chem in Perl.
+	
+2006-10-15  Bernd Warken <groff-bernd.warken-72@web.de>
+	________________________________________________________________
+	License
+
+	Copyright (C) 2006-2010, 2013
+	Free Software Foundation, Inc.
+	Written by Bernd Warken <groff-bernd.warken-72@web.de>.
+
+	Copying and distribution of this file, with or without
+	modification, are permitted provided the copyright notice and this
+	notice are preserved.
+
+	This file is part of `chem', which is part of the `groff' project.
+
+        ####### Emacs settings
+
+        Local Variables:
+        mode: change-log
+        End:

Index: chem/Makefile.sub
===================================================================
RCS file: chem/Makefile.sub
diff -N chem/Makefile.sub
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ chem/Makefile.sub	11 Aug 2013 08:27:05 -0000	1.18
@@ -0,0 +1,112 @@
+# Makefile.sub for `chem' (integration into the `groff' source tree)
+
+# File position: <groff-source>/contrib/chem/Makefile.sub
+
+# Copyright (C) 2006, 2009, 2010, 2013 Free Software Foundation, Inc.
+# Written by Bernd Warken <groff-bernd.warken-72@web.de>.
+
+# Last update: 29 Jan 2013
+
+# This file is part of `chem' 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/>.
+
+########################################################################
+
+MAN1=chem.n
+MOSTLYCLEANADD=\
+  chem \
+  chem.n \
+  README \
+  examples/README \
+  examples/122/README
+
+# not all make programs have $(RM) predefined.
+RM=rm -f
+
+all: README examples/README examples/122/README \
+     chem \
+     $(MAN1)
+
+README: $(srcdir)/README.txt
+	sed -e "s|@g@|$(g)|g" $? >$@
+
+examples/README: $(srcdir)/examples/README.txt
+	-test -d examples || $(mkinstalldirs) examples
+	sed -e "s|@g@|$(g)|g" $? >$@
+
+examples/122/README: $(srcdir)/examples/122/README.txt
+	-test -d examples || $(mkinstalldirs) examples
+	-test -d examples/122 || $(mkinstalldirs) examples/122
+	sed -e "s|@g@|$(g)|g" $? >$@
+
+chem: $(srcdir)/chem.pl $(SH_DEPS_SED_SCRIPT)
+	sed -f "$(SH_DEPS_SED_SCRIPT)" \
+	  -e "s|@g@|$(g)|g" \
+	  -e "s|@BINDIR@|$(DESTDIR)$(bindir)|g" \
+	  -e "s|@MACRODIR@|$(DESTDIR)$(tmacdir)|g" \
+	  -e "s|@PICDIR@|$(DESTDIR)$(datasubdir)/pic|g" \
+	  -e "s|@VERSION@|$(version)$(revision)|g" \
+	  -e "$(SH_SCRIPT_SED_CMD)" \
+	  $(srcdir)/chem.pl >$@
+	chmod +x $@
+
+install_data: chem \
+              README examples/README examples/122/README \
+              $(srcdir)/chem.pic \
+              $(srcdir)/examples/*.chem $(srcdir)/examples/122/*.chem
+	-test -d $(DESTDIR)$(bindir) || $(mkinstalldirs) $(DESTDIR)$(bindir)
+	$(RM) $(DESTDIR)$(bindir)/$(g)chem
+	$(INSTALL_SCRIPT) chem $(DESTDIR)$(bindir)/$(g)chem
+	-test -d $(DESTDIR)$(datasubdir)/pic \
+          || $(mkinstalldirs) $(DESTDIR)$(datasubdir)/pic
+	$(RM) $(DESTDIR)$(datasubdir)/pic/chem.pic
+	$(INSTALL_DATA) $(srcdir)/chem.pic \
+          $(DESTDIR)$(datasubdir)/pic/chem.pic
+	-test -d $(DESTDIR)$(exampledir)/chem \
+          || $(mkinstalldirs) $(DESTDIR)$(exampledir)/chem
+	-test -d $(DESTDIR)$(exampledir)/chem/122 \
+          || $(mkinstalldirs) $(DESTDIR)$(exampledir)/chem/122
+	-$(RM) $(DESTDIR)$(exampledir)/chem/*
+	$(INSTALL_DATA) examples/README \
+          $(DESTDIR)$(exampledir)/chem/README
+	for i in $(srcdir)/examples/*.chem; do \
+          n=`echo $$i | sed 's|$(srcdir)/examples/||g'`; \
+          $(INSTALL_DATA) $$i $(DESTDIR)$(exampledir)/chem/$$n; \
+        done
+	-$(RM) $(DESTDIR)$(exampledir)/chem/122/*
+	$(INSTALL_DATA) examples/122/README \
+          $(DESTDIR)$(exampledir)/chem/122/README
+	for i in $(srcdir)/examples/122/*.chem; do \
+          n=`echo $$i | sed 's|$(srcdir)/examples/122/||g'`; \
+          $(INSTALL_DATA) $$i $(DESTDIR)$(exampledir)/chem/122/$$n; \
+        done
+
+uninstall_sub:
+	$(RM) $(DESTDIR)$(bindir)/chem
+	$(RM) $(DESTDIR)$(datasubdir)/pic/chem.pic
+	-rmdir $(DESTDIR)$(datasubdir)/pic
+	$(RM) $(DESTDIR)$(exampledir)/chem/122/*
+	-rmdir $(DESTDIR)$(exampledir)/chem/122
+	$(RM) $(DESTDIR)$(exampledir)/chem/*
+	-rmdir $(DESTDIR)$(exampledir)/chem
+	-rmdir $(DESTDIR)$(exampledir)
+
+########################################################################
+# Emacs settings
+########################################################################
+#
+# Local Variables:
+# mode: makefile
+# End:

Index: chem/README.txt
===================================================================
RCS file: chem/README.txt
diff -N chem/README.txt
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ chem/README.txt	11 Aug 2013 08:27:05 -0000	1.7
@@ -0,0 +1,52 @@
+`chem' is a `roff' language to generate chemical structure diagrams.
+`@g@chem' is a `groff' preprocessor that produces output suitable for
+the `@g@pic' preprocessor.
+
+The original version of `chem' is an `awk' script written by Brian
+Kernighan <http://cm.bell-labs.com/cm/cs/who/bwk/index.html>.  The
+source files of the `awk' version of `chem' are available at
+<http://cm.bell-labs.com/netlib/typesetting/chem.gz>.
+
+This project is a rewrite of `chem' in Perl for the GNU `roff' project
+`groff'.  It was written under Perl v5.8.8, but at least Perl v5.6 is
+needed to run the Perl version of `chem'.
+
+In comparison to the original `awk' version of `chem', the Perl
+version does the following changements:
+- the options -h, --help, -v, --version to output usage and version
+information are added.
+- remove some functions `inline', `shiftfields', and `set' and some
+variables that are used only once.
+
+The subdirectory `examples/' contains example files for chem.  They
+are written in the `chem' language.  The file names end with .chem.
+
+
+####### License
+
+Last update: 5 Jan 2009
+
+Copyright (C) 2006, 2009 Free Software Foundation, Inc.
+Written by Bernd Warken <groff-bernd.warken-72@web.de>.
+
+This file is part of `chem', 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:

Index: chem/chem.man
===================================================================
RCS file: chem/chem.man
diff -N chem/chem.man
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ chem/chem.man	11 Aug 2013 08:27:05 -0000	1.15
@@ -0,0 +1,1017 @@
+.ig
+@g@chem.1 - man page for @g@chem (section 1).
+
+Source file position:  <groff_source_top>/contrib/chem/chem.man
+Installed position:    $prefix/share/man/man1/@g@chem.1
+
+Last update: 05 Jan 2009
+..
+.
+.
+.de au
+This file was written by Bernd Warken <groff-bernd.warken-72@web.de>.
+It is based on the documentation of
+.UR http://\:cm.bell-labs.com/\:cm/\:cs/\:who/\:bwk/\:index.html
+Brian Kernighan
+.UE 's
+original
+.I awk
+version of
+.IR chem .
+..
+.
+.
+.de co
+Copyright (C) 2006, 2007, 2008, 2009 Free Software Foundation, Inc.
+.
+.
+.P
+This file is part of
+.IR chem ,
+which is part of
+.IR groff ,
+a free software project.
+.
+You can redistribute it and/or modify it under the terms of the
+.nh
+.B "GNU General Public License"
+.hy
+as published by the
+.nh
+.BR "Free Software Foundation" ,
+.hy
+either version\~2, or (at your option) any later version.
+.
+.
+.P
+You should have received a copy of the \f(CRGNU General Public
+License\fP along with
+.IR groff ,
+see the files \%\f(CBCOPYING\fP and \%\f(CBLICENSE\fP in the top
+directory of the
+.I groff
+source package.
+.
+Or read the
+.I man page
+.BR gpl (1).
+You can also write to the
+.nh
+.B "Free Software Foundation, 51 Franklin St - Fifth Floor, Boston,"
+.BR "MA 02110-1301, USA" .
+.hy
+..
+.
+.
+.\" --------------------------------------------------------------------
+.\" Local macro definitions
+.
+.ds El \&.\|.\|.\&
+.
+.\" .File_name  (<path_name>)
+.\"
+.\" Display a file or directory name in CB font.
+.\"
+.de FN
+.  CB \\$@
+..
+.
+.\" .CB  (<path_name>)
+.\"
+.\" Display a line in CB font, for example after .TP
+.\"
+.de CB
+.nh
+\\&\\f(CB\\$1\\fP\\$2
+.hy
+..
+.
+.\" End of macro definitions
+.
+.
+.TH @G@CHEM @MAN1EXT@ "@MDATE@" "Groff Version @VERSION@"
+.SH NAME
+@g@chem \- groff preprocessor for producing chemical structure diagrams
+.
+.
+.SH "SYNOPSIS"
+.\" --------------------------------------------------------------------
+.\" SH "SYNOPSIS"
+.\" --------------------------------------------------------------------
+.
+.SY @g@chem
+.RI [ "\%option" \*(El]
+.OP \-\-
+.RI [ "\%filespec" \*(El]
+.
+.SY @g@chem
+.B \-h
+|
+.B \-\-help
+.
+.SY @g@chem
+.B \-v
+|
+.B \-\-version
+.YS
+.
+.
+.\" --------------------------------------------------------------------
+.SH OPTION USAGE
+.\" --------------------------------------------------------------------
+.
+.P
+There are no other options than
+.BR \-h ,
+.BR \-\-help ,
+.BR \-v ,
+and
+.BR \%\-\-version ;
+these options provoke the printing of a version or usage information,
+respectively, and all
+.I filespec
+arguments are ignored.
+.
+A
+.I filespec
+argument is either a file name of an existing file or a minus
+character
+.BR \- ,
+meaning standard input.
+.
+If no argument is specified then standard input is taken
+automatically.
+.
+.
+.\" --------------------------------------------------------------------
+.SH DESCRIPTION
+.\" --------------------------------------------------------------------
+.
+.I chem
+produces chemical structure diagrams.
+.
+Today's version is best suited for organic chemistry (bonds, rings).
+.
+The
+.B @g@chem
+program is a
+.B groff
+preprocessor like
+.BR @g@eqn ,
+.BR @g@pic ,
+.BR @g@tbl ,
+etc.
+.
+It generates
+.I pic
+output such that all
+.I chem
+parts are translated into diagrams of the
+.I pic
+language.
+.
+.
+.P
+The program
+.B @g@chem
+originates from the Perl source file
+.FN chem.pl .
+It tells
+.B @g@pic
+to include a copy of the macro file
+.FN chem.pic .
+.
+Moreover the
+.I groff
+source file
+.FN pic.tmac
+is loaded.
+.
+.
+.P
+In a style reminiscent of
+.I eqn
+and
+.IR pic ,
+the
+.I chem
+diagrams are written in a special language.
+.
+.
+.P
+A set of
+.I chem
+lines looks like this
+.
+.
+.IP
+.nf
+.ft B
+\&.cstart
+\fIchem data\fP
+\&.cend
+.ft
+.fi
+.
+.
+.P
+Lines containing the keywords
+.B .cstart
+and
+.B .cend
+start and end the input for
+.BR @g@chem ,
+respectively.
+.
+In
+.I pic
+context, i.e., after the call of
+.BR .PS ,
+.I chem
+input can optionally be started by the line
+.B \%begin\~chem
+and ended by the line with the single word
+.B end
+instead.
+.
+.
+.P
+Anything outside these initialization lines is copied through
+without modification;
+all data between the initialization lines is converted into
+.I pic
+commands to draw the diagram.
+.
+.
+.P
+As an example,
+.
+.IP
+.nf
+.ft B
+\&.cstart
+CH3
+bond
+CH3
+\&.cend
+.ft
+.fi
+.
+.
+.P
+prints two
+.B CH3
+groups with a bond between them.
+.
+.
+.P
+To actually view this, you must run
+.B @g@chem
+followed by
+.BR groffer :
+.
+.IP
+.B "@g@chem [file\*(El] | groffer"
+.
+.P
+If you want to create just
+.B groff
+output, you must run
+.B @g@chem
+followed by
+.B groff
+with the option
+.B \-p
+for the activation of
+.BR @g@pic :
+.IP
+.B "@g@chem [file\*(El] | groff -p \*(El"
+.
+.
+.\" --------------------------------------------------------------------
+.SH THE LANGUAGE
+.\" --------------------------------------------------------------------
+.
+The
+.I chem
+input language is rather small.  It provides rings of several styles
+and a way to glue them together as desired, bonds of several styles,
+moieties (e.g.,
+.BR C ,
+.BR NH3 ,
+\*(El), and strings.
+.
+.
+.\" --------------------------------------------------------------------
+.SS Setting Variables
+.\" --------------------------------------------------------------------
+.
+There are some variables that can be set by commands.
+.
+Such commands have two possible forms, either
+.
+.RS
+.P
+.I "variable value"
+.RE
+.
+.P
+or
+.
+.RS
+.P
+.IB "variable " = " value"
+.RE
+.
+.P
+This sets the given
+.I variable
+to the argument
+.IR value .
+If more arguments are given only the last argument is taken, all other
+arguments are ignored.
+.
+.
+.P
+There are only a few variables to be set by these commands:
+.
+.TP
+.BI textht " arg"
+Set the height of the text to
+.IR arg ;
+default is 0.16.
+.
+.TP
+.BI cwid " arg"
+Set the character width to
+.IR arg ;
+default is 0.12.
+.
+.TP
+.BI db " arg"
+Set the bond length to
+.IR arg ;
+default is 0.2.
+.
+.TP
+.BI size " arg"
+Scale the diagram to make it look plausible at point size
+.IR arg ;
+default is 10 point.
+.
+.
+.\" --------------------------------------------------------------------
+.SS Bonds
+.\" --------------------------------------------------------------------
+.
+This
+.
+.RS
+.SY bond
+.RI [ direction ]
+.RI [ length\ n ]
+.RB [ from\ \c
+.IR Name | picstuff ]
+.YS
+.RE
+.
+.P
+draws a single bond in direction from nearest corner of
+.IR Name .
+.B bond
+can also be
+.BR "double bond" ,
+.BR "front bond" ,
+.BR "back bond" ,
+etc.
+.
+(We will get back to
+.I Name
+soon.)
+.
+.
+.P
+.I direction
+is the angle in degrees (0\~up, positive clockwise)
+or a direction word like
+.BR up ,
+.BR down ,
+.B sw
+(=\~southwest), etc.
+.
+If no direction is specified, the bond goes in the current direction
+(usually that of the last bond).
+.
+.
+.P
+Normally the bond begins at the last object placed;  this
+can be changed by naming a
+.B from
+place.
+.
+For instance, to make a simple alkyl chain:
+.
+.RS
+.TS
+tab (@);
+lb l.
+CH3
+bond@(this one goes right from the CH3)
+C@(at the right end of the bond)
+double bond up@(from the C)
+O@(at the end of the double bond)
+bond right from C
+CH3
+.TE
+.RE
+.
+.
+.P
+A length in inches may be specified to override the default length.
+.
+Other
+.I pic
+commands can be tacked on to the end of a bond command, to created
+dotted or dashed bonds or to specify a
+.B to
+place.
+.
+.
+.\" --------------------------------------------------------------------
+.SS Rings
+.\" --------------------------------------------------------------------
+.
+There are lots of rings, but only 5 and 6-sided rings get
+much support.
+.
+.B ring
+by itself is a 6-sided ring;
+.B benzene
+is the benzene ring with a circle inside.
+.B aromatic
+puts a circle into any kind of ring.
+.
+.RS
+.SY ring
+.RB [ \%pointing\  ( up | right | left | down )]
+.RB [ \%aromatic ]
+.RB [ put\ Mol\ at\ \fIn\fP ]
+.RB [ \%double\ \c
+.IR i , j\ \c
+.IR k , l\ \c
+\*(El]
+.RI [ picstuff ]
+.YS
+.RE
+.
+.
+.P
+The vertices of a ring are numbered 1, 2, \*(El from the
+vertex that points in the natural compass direction.
+.
+So for a hexagonal ring with the point at the top, the top vertex
+is\~1, while if the ring has a point at the east side, that is
+vertex\~1.
+.
+This is expressed as
+.
+.IP
+.ft B
+.nf
+R1: ring pointing up
+R2: ring pointing right
+.fi
+.ft
+.
+.
+.P
+The ring vertices are named
+.BR .V1 ,
+\*(El,
+.BI .V n\fR,\fP
+with
+.B .V1
+in the pointing direction.
+.
+So the corners of
+.B R1
+are
+.B R1.V1
+(the
+.IR top ),
+.BR R1.V2 ,
+.BR R1.V3 ,
+.B R1.V4
+(the
+.IR bottom ),
+etc., whereas for
+.BR R2 ,
+.B R2.V1
+is the rightmost vertex and
+.B R2.V4
+the leftmost.
+.
+These vertex names are used for connecting bonds or other rings.  For
+example,
+.
+.IP
+.ft B
+.nf
+R1: benzene pointing right
+R2: benzene pointing right with .V6 at R1.V2
+.fi
+.ft
+.P
+creates two benzene rings connected along a side.
+.
+.
+.P
+Interior double bonds are specified as
+.BI \%double\  n1 , n2\ n3 , n4\ \fR\*(El;\fP
+each number pair adds an interior bond.
+.
+So the alternate form of a benzene ring is
+.
+.IP
+.B "ring double 1,2 3,4 5,6"
+.
+.
+.P
+Heterocycles (rings with something other than carbon at a vertex) are
+written as
+.BI put\  X\  at\  V\fR,\fP
+as in
+.
+.IP
+.B "R: ring put N at 1 put O at 2"
+.
+.
+.P
+In this heterocycle,
+.B R.N
+and
+.B R.O
+become synonyms for
+.B R.V1
+and
+.BR R.V2 .
+.
+.
+.P
+There are two 5-sided rings.
+.
+.B ring5
+is pentagonal with a side that matches the 6-sided ring; it has four
+natural directions.
+.
+A
+.B \%flatring
+is a 5-sided ring created by chopping one corner of a 6-sided ring so
+that it exactly matches the 6-sided rings.
+.
+.
+.P
+The description of a ring has to fit on a single line.
+.
+.
+.\" --------------------------------------------------------------------
+.SS Moieties and Strings
+.\" --------------------------------------------------------------------
+.
+A moiety is a string of characters beginning with a capital letter,
+such as N(C2H5)2.
+.
+Numbers are converted to subscripts (unless they appear to be
+fractional values, as in N2.5H).
+.
+The name of a moiety is determined from the moiety after special
+characters have been stripped out: e.g., N(C2H5)2) has the name NC2H52.
+.
+.
+.P
+Moieties can be specified in two kinds.
+.
+Normally a moiety is placed right after the last thing mentioned,
+separated by a semicolon surrounded by spaces, e.g.,
+.
+.IP
+.B "B1: bond ; OH"
+.
+.P
+Here the moiety is
+.BR OH ;
+it is set after a bond.
+.
+.
+.P
+As the second kind a moiety can be positioned as the first word in a
+.IR pic -like
+command, e.g.,
+.
+.IP
+.B "CH3 at C + (0.5,0.5)"
+.
+.P
+Here the moiety is
+.BR CH3 .
+It is placed at a position relative to
+.BR C ,
+a moiety used earlier in the chemical structure.
+.
+.
+.P
+So moiety names can be specified as
+.I chem
+positions everywhere in the
+.I chem
+code.
+.
+Beneath their printing moieties are names for places.
+.
+.
+.P
+The moiety
+.B BP
+is special.
+.
+It is not printed but just serves as a mark to be referred to in later
+.I chem
+commands.
+.
+For example,
+.
+.IP
+.B "bond ; BP"
+.
+.P
+sets a mark at the end of the bond.
+.
+This can be used then for specifying a place.
+.
+The name
+.B BP
+is derived from
+.I branch point
+(i.e., line crossing).
+.
+.
+.P
+A string within double quotes
+.B \(dq
+is interpreted as a part of a
+.I chem
+command.
+.
+It represents a string that should be printed (without the quotes).
+.
+Text within quotes \(dq\*(El\(dq is treated more or less
+like a moiety except that no changes are made to the quoted part.
+.
+.
+.\" --------------------------------------------------------------------
+.SS Names
+.\" --------------------------------------------------------------------
+.
+In the alkyl chain above, notice that the carbon atom
+.B C
+was used both to draw something and as the name for a place.
+.
+A moiety always defines a name for a place;  you can use
+your own names for places instead, and indeed, for rings
+you will have to.
+.
+A name is just
+.
+.IP
+.IB Name :
+\*(El
+.
+.
+.P
+.I Name
+is often the name of a moiety like
+.BR CH3 ,
+but it need not to be.
+.
+Any name that begins with a capital letter and which contains
+only letters and numbers is valid:
+.
+.RS
+.TP
+.B First:
+.B bond
+.TQ
+\&
+.B "bond 30 from First"
+.RE
+.
+.
+.\" --------------------------------------------------------------------
+.SS Miscellaneous
+.\" --------------------------------------------------------------------
+.
+The specific construction
+.RS
+.TP
+.BR bond\  \*(El " ; moiety"
+.RE
+.P
+is equivalent to
+.IP
+.ft B
+.nf
+bond
+moiety
+.fi
+.ft
+.
+.
+.P
+Otherwise, each item has to be on a separate line (and only one line).
+Note that there must be whitespace after the semicolon which separates
+the commands.
+.
+.
+.P
+A period character
+.B .\&
+or a single quote
+.B '
+in the first column of a line signals a
+.I troff
+command, which is copied through as-is.
+.
+.
+.P
+A line whose first non-blank character is a hash character
+.RB ( # )
+is treated as a comment and thus ignored.
+.
+However, hash characters within a word are kept.
+.
+.
+.P
+A line whose first word is
+.B pic
+is copied through as-is after the word
+.B pic
+has been removed.
+.
+.
+.P
+The command
+.IP
+.B size
+.I n
+.P
+scales the diagram to make it look plausible at point size\~\c
+.I n
+(default is 10\~point).
+.
+.
+.P
+Anything else is assumed to be
+.I pic
+code, which is copied through with a label.
+.
+.
+.P
+Since
+.B @g@chem
+is a
+.B @g@pic
+preprocessor, it is possible to include
+.I pic
+statements in the middle of a diagram to draw things not provided for
+by
+.I chem
+itself.
+.
+Such
+.I pic
+statements should be included in
+.I chem
+code by adding
+.B pic
+as the first word of this line for clarity.
+.
+.
+.P
+The following
+.I pic
+commands are accepted as
+.I chem
+commands, so no
+.B pic
+command word is needed:
+.
+.IP
+.B define
+Start the definition of
+.I pic
+macro within
+.IR chem .
+.
+.RS
+.TP
+.B [
+Start a block composite.
+.
+.TP
+.B ]
+End a block composite.
+.
+.TP
+.B {
+Start a macro definition block.
+.
+.TP
+.B }
+End a macro definition block.
+.RE
+.
+.P
+The macro names from
+.B define
+statements are stored and their call is accepted as a
+.I chem
+command as well.
+.
+.
+.\" --------------------------------------------------------------------
+.SS WISH LIST
+.\" --------------------------------------------------------------------
+.
+.P
+This TODO list was collected by Brian Kernighan.
+.
+.
+.P
+Error checking is minimal; errors are usually detected and reported in
+an oblique fashion by
+.IR pic .
+.
+.
+.P
+There is no library or file inclusion mechanism, and there is no
+shorthand for repetitive structures.
+.
+.
+.P
+The extension mechanism is to create
+.I pic
+macros, but these are tricky to get right and don't have all the
+properties of built-in objects.
+.
+.
+.P
+There is no in-line chemistry yet (e.g., analogous to the $\*(El$
+construct of eqn).
+.
+.
+.P
+There is no way to control entry point for bonds on groups.
+.
+Normally a bond connects to the carbon atom if entering from
+the top or bottom and otherwise to the nearest corner.
+.
+.
+.P
+Bonds from substituted atoms on heterocycles do not join at the proper
+place without adding a bit of
+.IR pic .
+.
+.
+.P
+There is no decent primitive for brackets.
+.
+.
+.P
+Text (quoted strings) doesn't work very well.
+.
+.
+.P
+A squiggle bond is needed.
+.
+.
+.\" --------------------------------------------------------------------
+.SH "FILES"
+.\" --------------------------------------------------------------------
+.
+.TP
+.FN @DATASUBDIR@/pic/chem.pic
+A collection of
+.I pic
+macros needed by
+.BR @g@chem .
+.
+.TP
+.FN @MACRODIR@/pic.tmac
+A macro file which redefines
+.B .PS
+and
+.BR .PE
+to center
+.I pic
+diagrams.
+.
+.TP
+.FN @DOCDIR@/examples/chem/*.chem
+Example files for
+.IR chem .
+.
+.TP
+.FN @DOCDIR@/examples/chem/122/*.chem
+Example files from the classical
+.I chem
+book
+.BR 122.ps .
+.
+.
+.\" --------------------------------------------------------------------
+.SH "BUGS"
+.\" --------------------------------------------------------------------
+.
+Report bugs to the
+.MT bug-groff@\:gnu.org
+bug-groff mailing list
+.ME .
+.
+Include a complete, self-contained example that will allow the bug to
+be reproduced, and say which version of
+.I groff
+and
+.I chem
+you are using.
+.
+You can get both version numbers by calling
+.BR "@g@chem --version" .
+.
+.
+.P
+You can also use the
+.MT groff@\:gnu.org
+groff mailing list
+.ME ,
+but you must first subscribe to this list.
+.
+You can do that by visiting the
+.UR http://\:lists.gnu.org/\:mailman/\:listinfo/\:groff
+groff mailing list web page
+.UE .
+.
+.
+.P
+See
+.BR \%groff (@MAN1EXT@)
+for information on availability.
+.
+.
+.\" --------------------------------------------------------------------
+.SH "SEE ALSO"
+.\" --------------------------------------------------------------------
+.
+.BR \%groff (@MAN1EXT@),
+.BR \%@g@pic (@MAN1EXT@),
+.BR \%groffer (@MAN1EXT@).
+.
+.
+.P
+You can still get the original
+.UR http://\:cm.bell-labs.com/\:netlib/\:typesetting/\:chem.gz
+chem awk source
+.UE .
+.
+Its
+.FN README
+file was used for this manual page.
+.
+.
+.P
+The other classical document on
+.I chem
+is
+.UR http://\:cm.bell-labs.com/\:cm/\:cs/\:cstr/\:122.ps.gz
+122.ps
+.UE .
+.
+.
+.\" --------------------------------------------------------------------
+.SH "AUTHOR"
+.\" --------------------------------------------------------------------
+.au
+.
+.
+.\" --------------------------------------------------------------------
+.SH "COPYING"
+.\" --------------------------------------------------------------------
+.co
+.
+.
+.\" --------------------------------------------------------------------
+.\" Emacs settings
+.\" --------------------------------------------------------------------
+.
+.\" Local Variables:
+.\" mode: nroff
+.\" End:

Index: chem/chem.pic
===================================================================
RCS file: chem/chem.pic
diff -N chem/chem.pic
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ chem/chem.pic	11 Aug 2013 08:27:06 -0000	1.7
@@ -0,0 +1,94 @@
+# macros for chem
+	
+# Source file position: <groff-source>/contrib/chem/chem.pic
+# Installed position: <prefix>/share/groff/<version>/pic
+
+# Copyright (C) 2006, 2008, 2009 Free Software Foundation, Inc.
+# Written by Brian Kernighan <http://cm.bell-labs.com/cm/cs/who/bwk>,
+# modified by Bernd Warken <groff-bernd.warken-72@web.de>.
+
+# This file is part of `chem', 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/>.
+
+########################################################################
+
+pi = 3.141592654
+deg = 57.29578
+# cr = 0.08		# radius of invis circle at ring vertices (see cr[vh])
+# crh = 0.16; crw = 0.12 # ht & wid of invis ellipse around atoms at ring vertices
+# dav = 0.015		# vertical shift up for atoms in atom macro
+
+# atom(text, wid, ht, carbon position, crh, crw, dav)
+define atom { [
+	T: $1 wid $2 ht $3-2*$7
+	C: ellipse invis ht $5 wid $6 at T.w + ($4,$7)
+	L: ellipse invis ht $5 wid $6 at T.w + (cwid/2,$7)
+	R: ellipse invis ht $5 wid $6 at T.e + (-cwid/2,$7)
+] }
+
+# bond(length, angle in degrees, whatever)
+define bond {
+	line $3 by ($1) * sin(($2)/deg), ($1) * cos(($2)/deg)
+}
+
+# fancy bonds:  r, theta, from/at
+define doublebond {
+	line $3 invis by ($1) * sin(($2)/deg), ($1) * cos(($2)/deg)
+	V1: last line.start; V2: last line.end; dx = V2.x-V1.x; dy = V2.y-V1.y
+	norm = sqrt(dx*dx + dy*dy)
+	ny = dx * .02 / norm
+	nx = -dy * .02 / norm
+	line from V1 + (nx,ny) to V2 + (nx,ny)
+	line from V1 - (nx,ny) to V2 - (nx,ny)
+	move to V2
+}
+define triplebond {
+	line $3 invis by ($1) * sin(($2)/deg), ($1) * cos(($2)/deg)
+	V1: last line.start; V2: last line.end; dx = V2.x-V1.x; dy = V2.y-V1.y
+	norm = sqrt(dx*dx + dy*dy)
+	ny = dx * .025 / norm
+	nx = -dy * .025 / norm
+	line from V1 + (nx,ny) to V2 + (nx,ny)
+	line from V1 - (nx,ny) to V2 - (nx,ny)
+	line from V1 to V2
+	move to V2
+}
+define backbond {
+	line $3 invis by ($1) * sin(($2)/deg), ($1) * cos(($2)/deg)
+	V1: last line.start; V2: last line.end; dx = V2.x-V1.x; dy = V2.y-V1.y
+	norm = sqrt(dx*dx + dy*dy)
+	n = norm / .025
+	ny = dx * .02 / norm
+	nx = -dy * .02 / norm
+	for i = 1 to n-1 do {
+		XZ: i/n <V1,V2>
+		line from XZ + (nx,ny) to XZ - (nx,ny)
+	}
+	move to V2
+}
+define frontbond {
+	line $3 invis by ($1) * sin(($2)/deg), ($1) * cos(($2)/deg)
+	V1: last line.start; V2: last line.end; dx = V2.x-V1.x; dy = V2.y-V1.y
+	ah = arrowht; aw = arrowwid; ahead = arrowhead
+	arrowht = sqrt(dx*dx + dy*dy)
+	arrowwid = 0.05
+	arrowhead = 7
+	line <- from V1 to V2
+	arrowht = ah; arrowwid = aw; arrowhead = ahead
+}
+### Emacs settings
+# Local Variables:
+# mode: Nroff
+# End:

Index: chem/chem.pl
===================================================================
RCS file: chem/chem.pl
diff -N chem/chem.pl
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ chem/chem.pl	11 Aug 2013 08:27:06 -0000	1.13
@@ -0,0 +1,1274 @@
+#! /usr/bin/env perl
+
+# chem - a groff preprocessor for producing chemical structure diagrams
+
+# Source file position: <groff-source>/contrib/chem/chem.pl
+# Installed position: <prefix>/bin/chem
+
+# Copyright (C) 2006, 2009 Free Software Foundation, Inc.
+# Written by Bernd Warken <groff-bernd.warken-72@web.de>.
+
+# This file is part of `chem', 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/>.
+
+########################################################################
+# settings
+########################################################################
+
+my $Program_Version = '0.3.1';
+my $Last_Update = '03 Jan 2009';
+
+# this setting of the groff version is only used before make is run,
+# otherwise @VERSION@ will set it.
+my $Groff_Version_Preset='1.20preset';
+
+# test on Perl version
+require v5.6;
+
+
+########################################################################
+# begin
+########################################################################
+
+use warnings;
+use strict;
+use Math::Trig;
+
+# for catfile()
+use File::Spec;
+
+# $Bin is the directory where this script is located
+use FindBin;
+
+my $Chem_Name;
+my $Groff_Version;
+my $File_chem_pic;
+my $File_pic_tmac;
+
+BEGIN {
+  {
+    my $before_make;		# script before run of `make'
+    {
+      my $at = '@';
+      $before_make = 1 if '@VERSION@' eq "${at}VERSION${at}";
+    }
+
+    my %at_at;
+
+    if ($before_make) {
+      my $chem_dir = $FindBin::Bin;
+      $at_at{'BINDIR'} = $chem_dir;
+      $at_at{'G'} = '';
+      $File_chem_pic = File::Spec->catfile($chem_dir, 'chem.pic');
+      $File_pic_tmac = File::Spec->catfile($chem_dir, '..', 'pic.tmac');
+      $Groff_Version = '';
+      $Chem_Name = 'chem';
+    } else {
+      $Groff_Version = '@VERSION@';
+      $at_at{'BINDIR'} = '@BINDIR@';
+      $at_at{'G'} = '@g@';
+      $at_at{'PICDIR'} = '@PICDIR@';
+      $at_at{'TMACDIR'} = '@MACRODIR@';
+      $File_chem_pic =
+	File::Spec->catfile($at_at{'PICDIR'}, 'chem.pic');
+      $File_pic_tmac = File::Spec->catfile($at_at{'TMACDIR'}, 'pic.tmac');
+      $Chem_Name = $at_at{'G'} . 'chem';
+    }
+  }
+}
+
+
+########################################################################
+# check the parameters
+########################################################################
+
+if (@ARGV) {
+  # process any FOO=bar switches
+  # eval '$'.$1.'$2;' while $ARGV[0] =~ /^([A-Za-z_0-9]+=)(.*)/ && shift;
+  my @filespec = ();
+  my $dbl_minus;
+  my $wrong;
+  foreach (@ARGV) {
+    next unless $_;
+    if (/=/) {
+      # ignore FOO=bar switches
+      push @filespec, $_ if -f;
+      next;
+    }
+    if ($dbl_minus) {
+      if (-f $_) {
+	push @filespec, $_ if -s $_;
+      } else {
+	warn "chem: argument $_ is not an existing file.\n";
+	$wrong = 1;
+      }
+      next;
+    }
+    if (/^--$/) {
+      $dbl_minus = 1;
+      next;
+    }
+    if (/^-$/) {
+      push @filespec, $_;
+      next;
+    }
+    if (/^-h$/ or '--help' =~ /^$_/) {
+      &usage();
+      exit 0;
+    }
+    if (/^-v$/ or '--version' =~ /^$_/) {
+      &version();
+      exit 0;
+    }
+    if (-f $_) {
+      push @filespec, $_ if -s $_;
+    } else {
+      $wrong = 1;
+      if (/^-/) {
+	warn "chem: wrong option ${_}.\n";
+      } else {
+	warn "chem: argument $_ is not an existing file.\n";
+      }
+    }
+  }
+  if (@filespec) {
+    @ARGV = @filespec;
+  } else {
+    exit 0 if $wrong;
+    @ARGV = ('-');
+  }
+} else {			# @ARGV is empty
+  @ARGV = ('-') unless @ARGV;
+}
+
+
+########################################################################
+# main process
+########################################################################
+
+my %Dc = ( 'up' => 0, 'right' => 90, 'down' => 180, 'left' => 270,
+	   'ne' => 45, 'se' => 135, 'sw' => 225, 'nw' => 315,
+	   0 => 'n', 90 => 'e', 180 => 's', 270 => 'w',
+	   30 => 'ne', 45 => 'ne', 60 => 'ne',
+	   120 => 'se', 135 => 'se', 150 => 'se',
+	   210 => 'sw', 225 => 'sw', 240 => 'sw',
+	   300 => 'nw', 315 => 'nw', 330 => 'nw',
+	 );
+
+my $Word_Count;
+my @Words;
+
+my $Line_No;
+my $Last_Name = '';
+
+# from init()
+my $First_Time = 1;
+my $Last_Type;
+my $Dir;			# direction
+my %Types = (
+	     'RING' => 'R',
+	     'MOL' => 'M',
+	     'BOND' => 'B',
+	     'OTHER' => 'O'	# manifests
+	    );
+
+# from setparams()
+my %Params;
+
+# from ring()
+my $Nput;
+my $Aromatic;
+my %Put;
+my %Dbl;
+
+my %Labtype;
+my %Define = ();
+
+my $File_Name = '';
+my $Line = '';
+
+&main();
+
+{
+  my $is_pic = '';
+  my $is_chem = '';
+  my $former_line = '';
+
+  ##########
+  # main()
+  #
+  sub main {
+    my $count_minus = 0;
+    my @stdin = ();
+    my $stdin = 0;
+
+    # for centralizing the pic code
+    open TMAC, "<$File_pic_tmac" and print <TMAC>;
+    close TMAC;
+
+    foreach (@ARGV) {
+      $count_minus++ if /^-$/;
+    }
+
+    foreach my $arg (@ARGV) {
+      &setparams(1.0);
+      next unless $arg;
+      $Line_No = 0;
+      $is_pic = '';
+      $is_chem = '';
+      if ($arg eq '-') {
+	$File_Name = 'standard input';
+	if ($stdin) {
+	  &main_line($_) foreach @stdin;
+	} else {
+	  $stdin = 1;
+	  if ($count_minus <= 1) {
+	    while (<STDIN>) {
+	      &main_line($_);
+	    }
+	  } else {
+	    @stdin = ();
+	    while (<STDIN>) {
+	      push @stdin, $_;
+	      &main_line($_);
+	    }
+	  }
+	}
+### main()
+      } else {			# $arg is not -
+	$File_Name = $arg;
+	open FILE, "<$arg";
+	&main_line($_) while <FILE>;
+	close FILE;
+      }				# if $arg
+      if ($is_pic) {
+	printf ".PE\n";
+      }
+    }
+  } # main()
+
+
+  ##########
+  # main_line()
+  #
+  sub main_line {
+    my $line = $_[0];
+#    $Last_Type = $Types{'OTHER'};
+#    $Last_Type = '';
+    my $stack;
+    $Line_No++;
+    chomp $line;
+
+    $line = $former_line . $line if $former_line;
+    if ($line =~ /^(.*)\\$/) {
+      $former_line = $1;
+      return 1;
+    } else {
+      $former_line = '';
+    }
+    $Line = $line;
+
+    {
+      @Words = ();
+      my $s = $line;
+      $s =~ s/^\s*//;
+      $s =~ s/\s+$//;
+      return 1 unless $s;
+      $s = " $s";
+      $s =~ s/\s+#.*$// if $is_pic;
+      return 1 unless $s;
+      $line = $s;
+      $line =~ s/^\s*|\s*$//g;
+      my $bool = 1;
+      while ($bool) {
+	$s =~ /^([^"]*)\s("[^"]*"?\S*)(.*)$/;
+	if (defined $1) {
+	  my $s1 = $1;
+	  my $s2 = $2;
+	  $s = $3;
+	  $s1 =~ s/^\s*|\s*$//g;
+	  push @Words, split(/\s+/, $s1) if $s1;
+	  push @Words, $s2;
+	}
+	if ($s !~ /\s"/) {
+	  $s =~ s/^\s*|\s*$//g;
+	  push @Words, split(/\s+/, $s) if $s;
+	  $bool = 0;
+	}
+      }
+
+#      @Words = split(/\s+/, $s);
+      return 1 unless @Words;
+#      foreach my $i (0..$#Words) {
+#	if ($Words[$i] =~ /^\s*#/) {
+#	  $#Words = $i - 1;
+#	  last;
+#	}
+#      }
+#      return 1 unless @Words;
+    }
+
+    if ($line =~ /^([\.']\s*PS\s*)|([\.']\s*PS\s.+)$/) {
+      # .PS
+      unless ($is_pic) {
+	$is_pic = 'running';
+	print "$line\n";
+      }
+      return 1;
+    }
+### main_line()
+    if ( $line =~ /^([\.']\s*PE\s*)|([\.']\s*PE\s.+)$/ ) {
+      # .PE
+      $is_chem = '';
+      if ($is_pic) {
+	$is_pic = '';
+	print "$line\n";
+      }
+      return 1;
+    }
+    if ($line =~ /^[\.']\s*cstart\s*$/) {
+      # line: `.cstart'
+      if ($is_chem) {
+	&error("additional `.cstart'; chem is already active.");
+	return 1;
+      }
+      unless ($is_pic) {
+	&print_ps();
+	$is_pic = 'by chem';
+      }
+      $is_chem = '.cstart';
+      &init();
+      return 1;
+    }
+### main_line()
+    if ($line =~ /^\s*begin\s+chem\s*$/) {
+      # line: `begin chem'
+      if ($is_pic) {
+	if ($is_chem) {
+	  &error("additional `begin chem'; chem is already active.");
+	  return 1;
+	}
+	$is_chem = 'begin chem';
+	&init();
+      } else {
+	print "$line\n";
+      }
+      return 1;
+    }
+    if ($line =~ /^[\.']\s*cend\s*/) {
+      # line `.cend'
+      if ($is_chem) {
+	&error("you end chem with `.cend', but started it with `begin chem'.")
+	  if $is_chem eq 'begin chem';
+	if ($is_pic eq 'by chem') {
+	  &print_pe();
+	  $is_pic = '';
+	}
+	$is_chem = '';
+      } else {
+	print "$line\n";
+      }
+      return 1;
+    }
+    if ($line =~ /^\s*end\s*$/) {
+      # line: `end'
+      if ($is_chem) {
+	&error("you end chem with `end', but started it with `.cstart'.")
+	  if $is_chem eq '.cstart';
+	if ($is_pic eq 'by chem') {
+	  &print_pe();
+	  $is_pic = '';
+	}
+	$is_chem = '';
+      } else {
+	print "$line\n";
+      }
+      return 1;
+    }
+
+### main_line()
+    if (! $is_chem) {
+      print "$line\n";
+      return 1;
+    }
+    if ($line =~ /^[.']/) {
+      # groff request line
+      print "$line\n";
+      return 1;
+    }
+
+    if ($Words[0] eq 'pic') {
+      # pic pass-thru
+      return 1 if $#Words == 0;
+      my $s = $line;
+      $s =~ /^\s*pic\s*(.*)$/;
+      $s = $1;
+      print "$s\n" if $s;
+      $Last_Type = $Types{'OTHER'};
+      $Define{ $Words[2] } = 1 if $#Words >= 2 && $Words[1] eq 'define';
+      return 1;
+    }
+
+    if ($Words[0] eq 'textht') {
+      if ($#Words == 0) {
+	&error("`textht' needs a single argument.");
+	return 0;
+      }
+      &error("only the last argument is taken for `textht', " .
+	     "all others are ignored.")
+	unless $#Words <= 1 or ($#Words == 2 && $Words[1] =~ /^=/);
+      $Params{'textht'} = $Words[$#Words];
+      return 1;
+    }
+### main_line()
+    if ($Words[0] eq 'cwid') {	# character width
+      if ($#Words == 0) {
+	&error("`cwid' needs a single argument.");
+	return 0;
+      }
+      &error("only the last argument is taken for `cwid', " .
+	     "all others are ignored.")
+	unless $#Words <= 1 or ($#Words == 2 && $Words[1] =~ /^=/);
+      $Params{'cwid'} = $Words[$#Words];
+      return 1;
+    }
+    if ($Words[0] eq 'db') {	# bond length
+      if ($#Words == 0) {
+	&error("`db' needs a single argument.");
+	return 0;
+      }
+      &error("only the last argument is taken for `db', " .
+	     "all others are ignored.")
+	unless $#Words <= 1 or ($#Words == 2 && $Words[1] =~ /^=/);
+      $Params{'db'} = $Words[$#Words];
+      return 1;
+    }
+    if ($Words[0] eq 'size') {	# size for all parts of the whole diagram
+      my $size;
+      if ($#Words == 0) {
+	&error("`size' needs a single argument.");
+	return 0;
+      }
+      &error("only the last argument is taken for `size', " .
+	     "all others are ignored.")
+	unless $#Words <= 1 or ($#Words == 2 && $Words[1] =~ /^=/);
+      if ($Words[$#Words] <= 4) {
+	$size = $Words[$#Words];
+      } else {
+	$size = $Words[$#Words] / 10;
+      }
+      &setparams($size);
+      return 1;
+    }
+
+### main_line()
+    print "\n#", $Line, "\n";  		      # debugging, etc.
+    $Last_Name = '';
+#    $Last_Type = $Types{'OTHER'};
+#    $Last_Type = '';
+
+    if ($Words[0] =~ /^[A-Z].*:$/) {
+      # label;  falls thru after shifting left
+      my $w = $Words[0];
+      $Last_Name = $w;
+      $Last_Name =~ s/:$//;
+      print "$w";
+      shift @Words;
+      if (@Words) {
+	print " ";
+	$line =~ s/^\s*$w\s*//;
+      } else {
+	print "\n";
+	return 1;
+      }
+    }
+
+    if ($Words[0] eq 'define') {
+      print "$line\n";
+      $Define{ $Words[1] } = 1 if $#Words >= 1;
+      $Last_Type = $Types{'OTHER'};
+      return 1;
+    }
+    if ($Words[0] =~ /^[\[\]{}]/) {
+      print "$line\n";
+      $Last_Type = $Types{'OTHER'};
+      return 1;
+    }
+
+    if ($Words[0] =~ /^"/) {
+      print 'Last: ', $line, "\n";
+      $Last_Type = $Types{'OTHER'};
+      return 1;
+    }
+
+    if ($Words[0] =~ /bond/) {
+      &bond($Words[0]);
+      return 1;
+    }
+
+    if ($#Words >= 1) {
+      if ($Words[0] =~ /^(double|triple|front|back)$/ &&
+	  $Words[1] eq 'bond') {
+	my $w = shift @Words;
+	$Words[0] = $w . $Words[0];
+	&bond($Words[0]);
+	return 1;
+      }
+      if ($Words[0] eq 'aromatic') {
+	my $temp = $Words[0];
+	$Words[0] = $Words[1] ? $Words[1] : '';
+	$Words[1] = $temp;
+      }
+    }
+
+    if ($Words[0] =~ /ring|benz/) {
+      &ring($Words[0]);
+      return 1;
+    }
+    if ($Words[0] eq 'methyl') {
+      # left here as an example
+      $Words[0] = 'CH3';
+    }
+### main_line()
+    if ($Words[0] =~ /^[A-Z]/) {
+      &molecule();
+      return 1;
+    }
+    if ($Words[0] eq 'left') {
+      my %left;			# not used
+      $left{++$stack} = &fields(1, $#Words);
+      printf (("Last: [\n"));
+      return 1;
+    }
+    if ($Words[0] eq 'right') {
+      &bracket();
+      $stack--;
+      return 1;
+    }
+    if ($Words[0] eq 'label') {	# prints the vertex numbers in a ring
+      if ( exists $Labtype{$Words[1]} and
+	   $Labtype{$Words[1]} =~ /^$Types{'RING'}/ ) {
+	my $v = substr($Labtype{$Words[1]}, 1, 1);
+	$Words[1] = '' unless $Words[1];
+	foreach my $i ( 1..$v ) {
+	  printf "\"\\s-3%d\\s0\" at 0.%d<%s.C,%s.V%d>\n", $i, $v + 2,
+	    $Words[1], $Words[1], $i;
+	}
+      } else {
+	&error("$Words[1] is not a ring.");
+      }
+      return 1;
+    }
+
+    if ( exists $Define{ $Words[0] } ) {
+      print $line, "\n";
+      $Last_Type = $Types{'OTHER'};
+      return 1;
+    }
+    return 1 unless $line;
+#    print STDERR "# $Line\n";
+#    &error('This is not a chem command.  To include a command for pic, ' .
+#	   "add `pic' as the first word to the command.");
+    print $line, "\n";
+    $Last_Type = $Types{'OTHER'};
+    1;
+  } # main_line()
+
+}
+
+########################################################################
+# functions
+########################################################################
+
+##########
+# atom(<string>)
+#
+sub atom {
+  # convert CH3 to atom(...)
+  my ($s) = @_;
+  my ($i, $n, $nsub, $cloc, $nsubc, @s);
+  if ($s eq "\"\"") {
+    return $s;
+  }
+  $n = length($s);
+  $nsub = $nsubc = 0;
+  $cloc = index($s, 'C');
+  if (! defined($cloc) || $cloc < 0) {
+    $cloc = 0;
+  }
+  @s = split('', $s);
+  $i = 0;
+  foreach (@s) {
+    unless (/[A-Z]/) {
+      $nsub++;
+      $nsubc++ if $i < $cloc;
+      $i++;
+    }
+  }
+  $s =~ s/([0-9]+\.[0-9]+)|([0-9]+)/\\s-3\\d$&\\u\\s+3/g;
+  if ($s =~ /([^0-9]\.)|(\.[^0-9])/) { # centered dot
+    $s =~ s/\./\\v#-.3m#.\\v#.3m#/g;
+  }
+  sprintf( "atom(\"%s\", %g, %g, %g, %g, %g, %g)",
+	   $s, ($n - $nsub / 2) * $Params{'cwid'}, $Params{'textht'},
+	   ($cloc - $nsubc / 2 + 0.5) * $Params{'cwid'}, $Params{'crh'},
+	   $Params{'crw'}, $Params{'dav'}
+	 );
+} # atom()
+
+
+##########
+# bond(<type>)
+#
+sub bond {
+  my ($type) = @_;
+  my ($i, $moiety, $from, $leng);
+  $moiety = '';
+  for ($i = 1; $i <= $#Words; $i++) {
+    if ($Words[$i] eq ';') {
+      &error("a colon `;' must be followed by a space and a single word.")
+       if $i != $#Words - 1;
+      $moiety = $Words[$i + 1] if $#Words > $i;
+      $#Words = $i - 1;
+      last;
+    }
+  }
+  $leng = $Params{'db'};	# bond length
+  $from = '';
+  for ($Word_Count = 1; $Word_Count <= $#Words; ) {
+    if ($Words[$Word_Count] =~
+	/(\+|-)?\d+|up|down|right|left|ne|se|nw|sw/) {
+      $Dir = &cvtdir($Dir);
+    } elsif ($Words[$Word_Count] =~ /^leng/) {
+      $leng = $Words[$Word_Count + 1] if $#Words > $Word_Count;
+      $Word_Count += 2;
+    } elsif ($Words[$Word_Count] eq 'to') {
+      $leng = 0;
+      $from = &fields($Word_Count, $#Words);
+      last;
+    } elsif ($Words[$Word_Count] eq 'from') {
+      $from = &dofrom();
+      last;
+    } elsif ($Words[$Word_Count] =~ /^#/) {
+      $Word_Count = $#Words + 1;
+      last;
+    } else {
+      $from = &fields($Word_Count, $#Words);
+      last;
+    }
+  }
+### bond()
+  if ($from =~ /( to )|^to/) {	# said "from ... to ...", so zap length
+    $leng = 0;
+  } elsif (! $from) {		# no from given at all
+    $from = 'from Last.' . &leave($Last_Type, $Dir) . ' ' .
+      &fields($Word_Count, $#Words);
+  }
+  printf "Last: %s(%g, %g, %s)\n", $type, $leng, $Dir, $from;
+  $Last_Type = $Types{'BOND'};
+  $Labtype{$Last_Name} = $Last_Type if $Last_Name;
+  if ($moiety) {
+    @Words = ($moiety);
+    &molecule();
+  }
+} # bond()
+
+
+##########
+# bracket()
+#
+sub bracket {
+  my $t;
+  printf (("]\n"));
+  if ($Words[1] && $Words[1] eq ')') {
+    $t = 'spline';
+  } else {
+    $t = 'line';
+  }
+  printf "%s from last [].sw+(%g,0) to last [].sw to last [].nw to last " .
+    "[].nw+(%g,0)\n", $t, $Params{'dbrack'}, $Params{'dbrack'};
+  printf "%s from last [].se-(%g,0) to last [].se to last [].ne to last " .
+    "[].ne-(%g,0)\n", $t, $Params{'dbrack'}, $Params{'dbrack'};
+  if ($Words[2] && $Words[2] eq 'sub') {
+    printf "\" %s\" ljust at last [].se\n", &fields(3, $#Words);
+  }
+} # bracket()
+
+
+##########
+# corner(<dir>)
+#
+# Return the corner name next to the given angle.
+#
+sub corner {
+  my ($d) = @_;
+  $Dc{ (45 * int(($d + 22.5) / 45)) % 360 };
+} # corner()
+
+
+##########
+# cvtdir(<dir>)
+#
+# Maps "[pointing] somewhere" to degrees.
+#
+sub cvtdir {
+  my ($d) = @_;
+  if ($Words[$Word_Count] eq 'pointing') {
+    $Word_Count++;
+  }
+  if ($Words[$Word_Count] =~ /^[+\\-]?\d+/) {
+    return ( $Words[$Word_Count++] % 360 );
+  } elsif ($Words[$Word_Count] =~ /left|right|up|down|ne|nw|se|sw/) {
+    return ( $Dc{$Words[$Word_Count++]} % 360 );
+  } else {
+    $Word_Count++;
+    return $d;
+  }
+} # cvtdir()
+
+
+##########
+# dblring(<v>)
+#
+sub dblring {
+  my ($v) = @_;
+  my ($d, $v1, $v2);
+  # should canonicalize to i,i+1 mod v
+  $d = $Words[$Word_Count];
+  for ($Word_Count++; $Word_Count <= $#Words &&
+       $Words[$Word_Count] =~ /^[1-9]/; $Word_Count++) {
+    $v1 = substr($Words[$Word_Count], 0, 1);
+    $v2 = substr($Words[$Word_Count], 2, 1);
+    if ($v2 == $v1 + 1 || $v1 == $v && $v2 == 1) { # e.g., 2,3 or 5,1
+      $Dbl{$v1} = $d;
+    } elsif ($v1 == $v2 + 1 || $v2 == $v && $v1 == 1) {	# e.g., 3,2 or 1,5
+      $Dbl{$v2} = $d;
+    } else {
+      &error(sprintf("weird %s bond in\n\t%s", $d, $_));
+    }
+  }
+} # dblring()
+
+
+##########
+# dofrom()
+#
+sub dofrom {
+  my $n;
+  $Word_Count++;			# skip "from"
+  $n = $Words[$Word_Count];
+  if (defined $Labtype{$n}) {	# "from Thing" => "from Thing.V.s"
+    return 'from ' . $n . '.' . &leave($Labtype{$n}, $Dir);
+  }
+  if ($n =~ /^\.[A-Z]/) {	# "from .V" => "from Last.V.s"
+    return 'from Last' . $n . '.' . &corner($Dir);
+  }
+  if ($n =~ /^[A-Z][^.]*\.[A-Z][^.]*$/) { # "from X.V" => "from X.V.s"
+    return 'from ' . $n . '.' . &corner($Dir);
+  }
+  &fields($Word_Count - 1, $#Words);
+} # dofrom()
+
+
+##########
+# error(<string>)
+#
+sub error {
+  my ($s) = @_;
+  printf STDERR "chem: error in %s on line %d: %s\n",
+    $File_Name, $Line_No, $s;
+} # error()
+
+
+##########
+# fields(<n1>, <n2>)
+#
+sub fields {
+  my ($n1, $n2) = @_;
+  if ($n1 > $n2) {
+    return '';
+  }
+  my $s = '';
+  foreach my $i ($n1..$n2) {
+    if ($Words[$i] =~ /^#/) {
+      last;
+    }
+    $s = $s . $Words[$i] . ' ';
+  }
+  $s;
+} # fields()
+
+
+##########
+# init()
+#
+sub init {
+  if ($First_Time) {
+    printf "copy \"%s\"\n", $File_chem_pic;
+    printf "\ttextht = %g; textwid = .1; cwid = %g\n",
+      $Params{'textht'}, $Params{'cwid'};
+    printf "\tlineht = %g; linewid = %g\n",
+      $Params{'lineht'}, $Params{'linewid'};
+    $First_Time = 0;
+  }
+  printf "Last: 0,0\n";
+  $Last_Type = $Types{'OTHER'};
+  $Dir = 90;
+} # init()
+
+
+##########
+# leave(<last>, <d>)
+#
+sub leave {
+  my ($last, $d) = @_;
+  my ($c, $c1);
+  # return vertex of $last in direction $d
+  if ( $last eq $Types{'BOND'} ) {
+    return 'end';
+  }
+  $d %= 360;
+  if ( $last =~ /^$Types{'RING'}/ ) {
+    return &ringleave($last, $d);
+  }
+  if ( $last eq $Types{'MOL'} ) {
+    if ($d == 0 || $d == 180) {
+      $c = 'C';
+    } elsif ($d > 0 && $d < 180) {
+      $c = 'R';
+    } else {
+      $c = 'L';
+    }
+    if (defined $Dc{$d}) {
+      $c1 = $Dc{$d};
+    } else {
+      $c1 = &corner($d);
+    }
+    return sprintf('%s.%s', $c, $c1);
+  }
+  if ( $last eq $Types{'OTHER'} ) {
+    return &corner($d);
+  }
+  'c';
+} # leave()
+
+
+##########
+# makering(<type>, <pt>, <v>)
+#
+sub makering {
+  my ($type, $pt, $v) = @_;
+  my ($i, $j, $a, $r, $rat, $fix, $c1, $c2);
+  if ($type =~ /flat/) {
+    $v = 6;
+    # vertices
+    ;
+  }
+  $r = $Params{'ringside'} / (2 * sin(pi / $v));
+  printf "\tC: 0,0\n";
+  for ($i = 0; $i <= $v + 1; $i++) {
+    $a = (($i - 1) / $v * 360 + $pt) / 57.29578; # 57. is $deg
+    printf "\tV%d: (%g,%g)\n", $i, $r * sin($a), $r * cos($a);
+  }
+  if ($type =~ /flat/) {
+    printf "\tV4: V5; V5: V6\n";
+    $v = 5;
+  }
+  # sides
+  if ($Nput > 0) {
+    # hetero ...
+    for ($i = 1; $i <= $v; $i++) {
+      $c1 = $c2 = 0;
+      if ($Put{$i} ne '') {
+	printf "\tV%d: ellipse invis ht %g wid %g at V%d\n",
+	  $i, $Params{'crh'}, $Params{'crw'}, $i;
+	printf "\t%s at V%d\n", $Put{$i}, $i;
+	$c1 = $Params{'cr'};
+      }
+      $j = $i + 1;
+      if ($j > $v) {
+	$j = 1;
+      }
+### makering()
+      if ($Put{$j} ne '') {
+	$c2 = $Params{'cr'};
+      }
+      printf "\tline from V%d to V%d chop %g chop %g\n", $i, $j, $c1, $c2;
+      if ($Dbl{$i} ne '') {
+	# should check i<j
+	if ($type =~ /flat/ && $i == 3) {
+	  $rat = 0.75;
+	  $fix = 5;
+	} else {
+	  $rat = 0.85;
+	  $fix = 1.5;
+	}
+	if ($Put{$i} eq '') {
+	  $c1 = 0;
+	} else {
+	  $c1 = $Params{'cr'} / $fix;
+	}
+	if ($Put{$j} eq '') {
+	  $c2 = 0;
+	} else {
+	  $c2 = $Params{'cr'} / $fix;
+	}
+	printf "\tline from %g<C,V%d> to %g<C,V%d> chop %g chop %g\n",
+	  $rat, $i, $rat, $j, $c1, $c2;
+	if ($Dbl{$i} eq 'triple') {
+	  printf "\tline from %g<C,V%d> to %g<C,V%d> chop %g chop %g\n",
+	    2 - $rat, $i, 2 - $rat, $j, $c1, $c2;
+	}
+      }
+    }
+### makering()
+  } else {
+    # regular
+    for ($i = 1; $i <= $v; $i++) {
+      $j = $i + 1;
+      if ($j > $v) {
+	$j = 1;
+      }
+      printf "\tline from V%d to V%d\n", $i, $j;
+      if ($Dbl{$i} ne '') {
+	# should check i<j
+	if ($type =~ /flat/ && $i == 3) {
+	  $rat = 0.75;
+	} else {
+	  $rat = 0.85;
+	}
+	printf "\tline from %g<C,V%d> to %g<C,V%d>\n",
+	  $rat, $i, $rat, $j;
+	if ($Dbl{$i} eq 'triple') {
+	  printf "\tline from %g<C,V%d> to %g<C,V%d>\n",
+	    2 - $rat, $i, 2 - $rat, $j;
+	}
+      }
+    }
+  }
+### makering()
+  # punt on triple temporarily
+  # circle
+  if ($type =~ /benz/ || $Aromatic > 0) {
+    if ($type =~ /flat/) {
+      $r *= .4;
+    } else {
+      $r *= .5;
+    }
+    printf "\tcircle rad %g at 0,0\n", $r;
+  }
+} # makering()
+
+
+##########
+# molecule()
+#
+sub molecule {
+  my ($n, $type);
+  if ($#Words >= 0) {
+    $n = $Words[0];
+    if ($n eq 'BP') {
+      $Words[0] = "\"\" ht 0 wid 0";
+      $type = $Types{'OTHER'};
+    } else {
+      $Words[0] = &atom($n);
+      $type = $Types{'MOL'};
+    }
+  }
+  $n =~ s/[^A-Za-z0-9]//g;	# for stuff like C(OH3): zap non-alnum
+  if ($#Words < 1) {
+    printf "Last: %s: %s with .%s at Last.%s\n",
+      $n, join(' ', @Words), &leave($type, $Dir + 180),
+	&leave($Last_Type, $Dir);
+### molecule()
+  } else {
+    if (! $Words[1]) {
+      printf "Last: %s: %s with .%s at Last.%s\n",
+	$n, join(' ', @Words), &leave($type, $Dir + 180),
+	  &leave($Last_Type, $Dir);
+    } elsif ($#Words >= 1 and $Words[1] eq 'below') {
+      $Words[2] = '' if ! $Words[2];
+      printf "Last: %s: %s with .n at %s.s\n", $n, $Words[0], $Words[2];
+    } elsif ($#Words >= 1 and $Words[1] eq 'above') {
+      $Words[2] = '' if ! $Words[2];
+      printf "Last: %s: %s with .s at %s.n\n", $n, $Words[0], $Words[2];
+    } elsif ($#Words >= 2 and $Words[1] eq 'left' && $Words[2] eq 'of') {
+      $Words[3] = '' if ! $Words[3];
+      printf "Last: %s: %s with .e at %s.w+(%g,0)\n",
+	$n, $Words[0], $Words[3], $Params{'dew'};
+    } elsif ($#Words >= 2 and $Words[1] eq 'right' && $Words[2] eq 'of') {
+      $Words[3] = '' if ! $Words[3];
+      printf "Last: %s: %s with .w at %s.e-(%g,0)\n",
+	$n, $Words[0], $Words[3], $Params{'dew'};
+    } else {
+      printf "Last: %s: %s\n", $n, join(' ', @Words);
+    }
+  }
+
+  $Last_Type = $type;
+  if ($Last_Name) {
+    #    $Last_Type = '';
+    $Labtype{$Last_Name} = $Last_Type;
+  }
+ $Labtype{$n} = $Last_Type;
+} # molecule()
+
+
+##########
+# print_hash(<hash_or_ref>)
+#
+# print the elements of a hash or hash reference
+#
+sub print_hash {
+  my $hr;
+  my $n = scalar @_;
+  if ($n == 0) {
+    print STDERR "empty hash\n;";
+    return 1;
+  } elsif ($n == 1) {
+    if (ref($_[0]) eq 'HASH') {
+      $hr = $_[0];
+    } else {
+      warn 'print_hash(): the argument is not a hash or hash reference;';
+      return 0;
+    }
+  } else {
+    if ($n % 2) {
+      warn 'print_hash(): the arguments are not a hash;';
+      return 0;
+    } else {
+      my %h = @_;
+      $hr = \%h;
+    }
+  }
+
+### print_hash()
+  unless (%$hr) {
+    print STDERR "empty hash\n";
+    return 1;
+  }
+  print STDERR "hash (ignore the ^ characters):\n";
+  for my $k (sort keys %$hr) {
+    my $hk = $hr->{$k};
+    print STDERR "  $k => ";
+    if (defined $hk) {
+      print STDERR "^$hk^";
+    } else {
+      print STDERR "undef";
+    }
+    print STDERR "\n";
+  }
+
+  1;
+}				# print_hash()
+
+
+##########
+# print_pe()
+#
+sub print_pe {
+  print ".PE\n";
+} # print_pe()
+
+
+##########
+# print_ps()
+#
+sub print_ps {
+  print ".PS\n";
+} # print_ps()
+
+##########
+# putring(<v>)
+#
+sub putring {
+  # collect "put Mol at n"
+  my ($v) = @_;
+  my ($m, $mol, $n);
+  $Word_Count++;
+  $mol = $Words[$Word_Count++];
+  if ($Words[$Word_Count] eq 'at') {
+    $Word_Count++;
+  }
+  $n = $Words[$Word_Count];
+  if ($n !~ /^\d+$/) {
+    $n =~ s/(\d)+$/$1/;
+    $n = 0 if $n !~ /^\d+$/;
+    error('use single digit as argument for "put at"');
+  }
+  if ($n >= 1 && $n <= $v) {
+    $m = $mol;
+    $m =~ s/[^A-Za-z0-9]//g;
+    $Put{$n} = $m . ':' . &atom($mol);
+  } elsif ($n == 0) {
+    error('argument of "put at" must be a single digit');
+  } else {
+    error('argument of "put at" is too large');
+  }
+  $Word_Count++;
+} # putring()
+
+
+##########
+# ring(<type>)
+#
+sub ring {
+  my ($type) = @_;
+  my ($typeint, $pt, $verts, $i, $other, $fused, $withat);
+  $pt = 0;			# points up by default
+  if ($type =~ /([1-8])$/) {
+    $verts = $1;
+  } elsif ($type =~ /flat/) {
+    $verts = 5;
+  } else {
+    $verts = 6;
+  }
+  $fused = $other = '';
+  for ($i = 1; $i <= $verts; $i++) {
+    $Put{$i} = $Dbl{$i} = '';
+  }
+  $Nput = $Aromatic = $withat = 0;
+  for ($Word_Count = 1; $Word_Count <= $#Words; ) {
+    if ($Words[$Word_Count] eq 'pointing') {
+      $pt = &cvtdir(0);
+    } elsif ($Words[$Word_Count] eq 'double' ||
+	     $Words[$Word_Count] eq 'triple') {
+      &dblring($verts);
+    } elsif ($Words[$Word_Count] =~ /arom/) {
+      $Aromatic++;
+      $Word_Count++;		# handled later
+### ring()
+    } elsif ($Words[$Word_Count] eq 'put') {
+      &putring($verts);
+      $Nput++;
+    } elsif ($Words[$Word_Count] =~ /^#/) {
+      $Word_Count = $#Words + 1;
+      last;
+    } else {
+      if ($Words[$Word_Count] eq 'with' || $Words[$Word_Count] eq 'at') {
+	$withat = 1;
+      }
+      $other = $other . ' ' . $Words[$Word_Count];
+      $Word_Count++;
+    }
+  }
+  $typeint = $Types{'RING'} . $verts . $pt; # RING | verts | dir
+  if ($withat == 0) {
+    # join a ring to something
+    if ( $Last_Type =~ /^$Types{'RING'}/ ) {
+      # ring to ring
+      if (substr($typeint, 2) eq substr($Last_Type, 2)) {
+	# fails if not 6-sided
+	$fused = 'with .V6 at Last.V2';
+      }
+    }
+    # if all else fails
+    $fused = sprintf('with .%s at Last.%s',
+	  &leave($typeint, $Dir + 180), &leave($Last_Type, $Dir));
+  }
+  printf "Last: [\n";
+  &makering($type, $pt, $verts);
+  printf "] %s %s\n", $fused, $other;
+  $Last_Type = $typeint;
+  $Labtype{$Last_Name} = $Last_Type if $Last_Name;
+} # ring()
+
+
+##########
+# ringleave(<last>, <d>)
+#
+sub ringleave {
+  my ($last, $d) = @_;
+  my ($rd, $verts);
+  # return vertex of ring in direction d
+  $verts = substr($last, 1, 1);
+  $rd = substr($last, 2);
+  sprintf('V%d.%s', int( (($d - $rd) % 360) / (360 / $verts)) + 1,
+	  &corner($d));
+} # ringleave()
+
+
+##########
+# setparams(<scale>)
+#
+sub setparams {
+  my ($scale) = @_;
+  $Params{'lineht'} = $scale * 0.2;
+  $Params{'linewid'} = $scale * 0.2;
+  $Params{'textht'} = $scale * 0.16;
+  $Params{'db'} = $scale * 0.2;	# bond length
+  $Params{'cwid'} = $scale * 0.12;	# character width
+  $Params{'cr'} = $scale * 0.08; # rad of invis circles at ring vertices
+  $Params{'crh'} = $scale * 0.16; # ht of invis ellipse at ring vertices
+  $Params{'crw'} = $scale * 0.12; # wid	
+  $Params{'dav'} = $scale * 0.015; # vertical shift up for atoms in atom macro
+  $Params{'dew'} = $scale * 0.02; # east-west shift for left of/right of
+  $Params{'ringside'} = $scale * 0.3; # side of all rings
+  $Params{'dbrack'} = $scale * 0.1; # length of bottom of bracket
+} # setparams()
+
+
+##########
+# usage()
+#
+# Print usage information for --help.
+#
+sub usage {
+  print "\n";
+  &version();
+  print <<EOF;
+
+Usage: $Chem_Name [option]... [filespec]...
+
+$Chem_Name is a groff preprocessor for producing chemical structure
+diagrams.  The output suits to the pic preprocessor.
+
+"filespec" is one of
+  "filename"       name of a readable file
+  "-"              for standard input
+
+All available options are
+
+-h --help         print this usage message.
+-v --version      print version information.
+
+EOF
+} # usage()
+
+
+##########
+# version()
+#
+# Get version information from version.sh and print a text with this.
+#
+sub version {
+  $Groff_Version = $Groff_Version_Preset unless $Groff_Version;
+  my $year = $Last_Update;
+  $year =~ s/^.* //;
+  print <<EOF;
+$Chem_Name $Program_Version of $Last_Update (Perl version)
+is part of groff version $Groff_Version.
+Copyright (C) $year Free Software Foundation, Inc.
+GNU groff and chem come with ABSOLUTELY NO WARRANTY.
+You may redistribute copies of groff and its subprograms
+under the terms of the GNU General Public License.
+EOF
+} # version()
+
+1;
+### Emacs settings
+# Local Variables:
+# mode: CPerl
+# End:

Index: chem/examples/README.txt
===================================================================
RCS file: chem/examples/README.txt
diff -N chem/examples/README.txt
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ chem/examples/README.txt	11 Aug 2013 08:27:06 -0000	1.8
@@ -0,0 +1,65 @@
+This directory contains examples for the `chem' language.
+
+You can view the graphical display of the examples by calling
+
+    groffer <file>
+
+`groffer' calls `chem' automatically.
+
+If you want to transform example files to a different format use the
+`roff2*' programs:
+
+`roff2dvi' prints dvi format to standard output,
+`roff2html' generates html output,
+`roff2pdf' outputs pdf mode,
+`roff2ps' produces PostScript output,
+`roff2text' generates text output in the groff device `latin1',
+`roff2x' prints the output  in  the  groff  device  X  that  is
+         suitable  for programs  like `gxditview' or `xditview'.
+
+To get a suitable `groff' output run
+
+    @g@chem <file> | groff -p ...
+
+On the displays, you can see rings consisting of several lines and
+bonds (lines).  All points on rings and bonds that do not have a
+notation mean a C atom (carbon) filled with H atoms (hydrogen) such
+that the valence of 4 is satisfied.
+
+For example, suppose you have just a single line without any
+characters.  That means a bond.  It has two points, one at each end of
+the line.  So each of these points stands for a C atom, the bond
+itself connects these 2 C atoms.  To fulfill the valence of 4, each
+points has to carry additionally 3 H atoms.  So the single empty bond
+stands for CH3-CH3, though this combination doesn't make much sense
+chemically.
+
+
+####### License
+
+Last update: 5 Jan 2009
+
+Copyright (C) 2006, 2009 Free Software Foundation, Inc.
+Written by Bernd Warken <groff-bernd.warken-72@web.de>.
+
+This file is part of `chem', 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:

Index: chem/examples/atp.chem
===================================================================
RCS file: chem/examples/atp.chem
diff -N chem/examples/atp.chem
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ chem/examples/atp.chem	11 Aug 2013 08:27:07 -0000	1.6
@@ -0,0 +1,63 @@
+atp.chem:
+.cstart
+
+# Example file for `chem':
+#   ATP or C10_H16_N5_O13_P3 or
+#   [[[5-(6-aminopurin-9-yl)-3,4-dihydroxy-oxolan-2-yl]methoxy-hydroxy-
+#     phosphoryl]oxy-hydroxy-phosphoryl]oxyphosphonic acid
+
+# Found at http://www.chemindustry.com/apps/chemicals.
+
+# Source file position: <groff-source>/contrib/chem/example/atp.chem
+# Installed position: <prefix>/share/doc/groff/example/chem/atp.chem
+
+# Copyright (C) 2006, 2009 Free Software Foundation, Inc.
+# Written by Bernd Warken <groff-bernd.warken-72@web.de>.
+
+# Last update: 5 Jan 2009
+
+# This file is part of `chem', 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/>.
+
+R1:	ring5 pointing left double 1,2 3,4 put N at 2 put N at 5
+B:	benzene put N at 2 with .V6 at R1.V3 with .V5 at R1.V4
+	bond up ; NH2
+	backbond 170 length .7 from R1.V5
+R2:	ring5 pointing down with .V2 put O at 1
+	bond down at R2.V2 ; H
+	bond down length .1 at R2.V3 ; H
+	bond up length .1 at R2.V3 ; OH
+	bond down length .1 at R2.V4 ; H
+	bond up length .1 at R2.V4 ; OH
+	frontbond 70 at R2.V5
+	bond 110 ; O
+	bond right ; P
+	doublebond up ; O
+	bond down from P ; OH
+	bond right from P ; O
+	bond right ; P
+	doublebond up ; O
+	bond down from P ; OH
+	bond right from P ; O
+	bond right ; P
+	doublebond up ; O
+	bond down from P ; OH
+	bond right from P ; OH
+
+### Emacs settings
+# Local Variables:
+# mode: Nroff
+# End:
+.cend

Index: chem/examples/cholesterin.chem
===================================================================
RCS file: chem/examples/cholesterin.chem
diff -N chem/examples/cholesterin.chem
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ chem/examples/cholesterin.chem	11 Aug 2013 08:27:07 -0000	1.6
@@ -0,0 +1,52 @@
+cholesterin.chem:
+.cstart
+
+# Example file for `chem':
+#   Cholesterin or C27_H46O or
+#   10,13-dimethyl-17-(6-methylheptan-2-yl)-2,3,4,5,6,9,11,12,14,15,16,17-
+#     dodecahydro-1H-cyclopenta[a]phenanthren-3-ol
+
+# Source file position: <groff-source>/contrib/chem/example/cholesterin.p
+# Installed position: <prefix>/share/doc/groff/example/chem/cholesterin.p
+
+# Copyright (C) 2006, 2009 Free Software Foundation, Inc.
+# Written by Bernd Warken <groff-bernd.warken-72@web.de>.
+
+# Last update: 5 Jan 2009
+
+# This file is part of `chem', 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/>.
+
+R1:	ring6
+	bond -120 ; HO
+R2:	ring6 with .V5 at R1.V3 with .V6 at R1.V2 double 4,5
+	bond up at R2.V6
+R3:	ring6 with .V5 at R2.V1 with .V4 at R2.V2
+R4:	flatring5 pointing up with .V4 at R3.V3 with .V5 at R3.V2
+	bond up at R4.V5
+	bond up at R4.V1
+B1:	bond -60
+	bond 60 at B1.start
+	bond 120
+	bond 60
+	bond 120
+B2:	bond 60
+	bond down at B2.start
+
+### Emacs settings
+# Local Variables:
+# mode: Nroff
+# End:
+.cend

Index: chem/examples/ethamivan.chem
===================================================================
RCS file: chem/examples/ethamivan.chem
diff -N chem/examples/ethamivan.chem
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ chem/examples/ethamivan.chem	11 Aug 2013 08:27:07 -0000	1.6
@@ -0,0 +1,48 @@
+ethamivan.chem:
+.cstart
+
+# Example file for `chem':
+#   Ethamivan or Analepticon or C12_H17_N_O3 or
+#   N,N-diethyl-4-hydroxy-3-methoxy-benzamide
+
+# Source file position: <groff-source>/contrib/chem/example/ethamivan.chem
+# Installed position: <prefix>/share/doc/groff/example/chem/ethamivan.chem
+
+# Copyright (C) 2006, 2009 Free Software Foundation, Inc.
+# Written by Bernd Warken <groff-bernd.warken-72@web.de>.
+
+# Last update: 5 Jan 2009
+
+# This file is part of `chem', 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/>.
+
+R:	ring pointing left double 2,3 4,5 6,1
+	bond left from R.V1 ; O
+	bond left ; H
+	bond -150 from R.V6 ; O
+	bond left
+	bond 60 from R.V4
+B1:	double bond up ; O
+	bond 120 from B1.start ; N
+	bond 45
+	bond right
+ 	bond 135 from N
+	bond right
+
+### Emacs settings
+# Local Variables:
+# mode: Nroff
+# End:
+.cend

Index: chem/examples/lsd.chem
===================================================================
RCS file: chem/examples/lsd.chem
diff -N chem/examples/lsd.chem
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ chem/examples/lsd.chem	11 Aug 2013 08:27:08 -0000	1.6
@@ -0,0 +1,51 @@
+lsd.chem:
+.cstart
+
+# Example file for `chem':
+#   LSD or Lysergic acid dethylamide or C20_H25_N3O or
+#   9,10-Didehydro-N,N-diethyl-6-methyl-ergoline-8-beta-carboxamide
+
+# Source file position: <groff-source>/contrib/chem/example/lsd.p
+# Installed position: <prefix>/share/doc/groff/example/chem/lsd.p
+
+# Copyright (C) 2006, 2009 Free Software Foundation, Inc.
+# Written by Bernd Warken <groff-bernd.warken-72@web.de>.
+
+# Last update: 5 Jan 2009
+
+# This file is part of `chem', 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/>.
+
+F:	flatring5 pointing left put N at 5 double 3,4
+	H below F.N
+B:	benzene pointing right with .V1 at F.V2
+R1:	ring pointing right with .V4 at B.V6
+	front bond right from R1.V6 ; H
+R2:	ring pointing right with .V2 at R1.V6 put N at 1 double 3,4
+	bond right from R2.N
+	back bond -60 from R2.V5 ; H
+	bond up from R2.V5
+B1:	double bond up ; O
+        bond right from B1.start ; N
+        bond 45
+	bond right
+        bond 135 from N
+	bond right
+
+### Emacs settings
+# Local Variables:
+# mode: Nroff
+# End:
+.cend

Index: chem/examples/morphine.chem
===================================================================
RCS file: chem/examples/morphine.chem
diff -N chem/examples/morphine.chem
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ chem/examples/morphine.chem	11 Aug 2013 08:27:08 -0000	1.6
@@ -0,0 +1,55 @@
+morphine.chem:
+.cstart
+
+# Example file for `chem':
+#    Morphine or C23_H31_N3O or
+#    N,N-diethyl-N'-(2-methoxyacridin-9-yl)-pentane-1,4-diamine
+
+# Found at http://www.chemindustry.com/apps/chemicals.
+
+# Source file position: <groff-source>/contrib/chem/example/morphine.chem
+# Installed position: <prefix>/share/doc/groff/example/chem/morphine.chem
+
+# Copyright (C) 2006, 2009 Free Software Foundation, Inc.
+# Written by Bernd Warken <groff-bernd.warken-72@web.de>.
+
+# Last update: 5 Jan 2009
+
+# This file is part of `chem', 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/>.
+
+R1:	benzene
+R2:	benzene with .V6 at R1.V2 with .V5 at R1.V3 put N at 4
+R3:	benzene with .V6 at R2.V2 with .V5 at R2.V3
+	bond 60 at R3.V2 ; O
+	bond 120
+	bond up at R2.V1 ; N
+	bond 60 ; H
+	bond -60 at N
+B1:	backbond -120
+	bond up at B1.start
+	bond -60
+	bond up
+	bond -60 ; N
+	bond up
+	bond -60
+	bond -120 at N
+	bond -60
+
+### Emacs settings
+# Local Variables:
+# mode: Nroff
+# End:
+.cend

Index: chem/examples/penicillin.chem
===================================================================
RCS file: chem/examples/penicillin.chem
diff -N chem/examples/penicillin.chem
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ chem/examples/penicillin.chem	11 Aug 2013 08:27:08 -0000	1.6
@@ -0,0 +1,56 @@
+penicillin.chem:
+.cstart
+
+# Example file for `chem':
+#    Penicillin or C16_H18_N2_O4_S or
+#    3,3-dimethyl-6-oxo-7-(2-phenylacetyl)amino-2-thia-5-
+#      azabicyclo[3.2.0]heptane-4-carboxylic acid
+
+# Found at http://www.chemindustry.com/apps/chemicals.
+
+# Source file position: <groff-source>/contrib/chem/example/morphine.chem
+# Installed position: <prefix>/share/doc/groff/example/chem/morphine.chem
+
+# Copyright (C) 2006, 2009 Free Software Foundation, Inc.
+# Written by Bernd Warken <groff-bernd.warken-72@web.de>.
+
+# Last update: 5 Jan 2009
+
+# This file is part of `chem', 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/>.
+
+R1:	flatring5 pointing up put S at 1 put N at 4
+	bond 45 at R1.V2
+	bond 135 at R1.V2
+	bond 120 at R1.V3
+D1:	doublebond 45 ; O
+	bond 135 at D1.start ; OH
+	bond left at R1.N
+	doublebond -135 ; O
+	bond left at R1.V5
+B1:	bond down length .3
+	bond -60 at B1.start ; N
+	bond up ; H
+	bond -120 at N
+D2:	doublebond down ; O
+	bond -60 at D2.start
+	bond -120
+	benzene
+
+### Emacs settings
+# Local Variables:
+# mode: Nroff
+# End:
+.cend

Index: chem/examples/reserpine.chem
===================================================================
RCS file: chem/examples/reserpine.chem
diff -N chem/examples/reserpine.chem
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ chem/examples/reserpine.chem	11 Aug 2013 08:27:09 -0000	1.7
@@ -0,0 +1,65 @@
+reserpine.chem:
+.PS
+begin chem
+
+# Example file for `chem':
+#   Reserpine or C33H40N2O9
+
+# Source file position: <groff-source>/contrib/chem/example/reserpine.chem
+# Installed position: <prefix>/share/doc/groff/example/chem/reserpine.chem
+
+# Copyright (C) 2006, 2009 Free Software Foundation, Inc.
+# Written by Bernd Warken <groff-bernd.warken-72@web.de>.
+
+# Last update: 5 Jan 2009
+
+# This file is part of `chem', 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/>.
+
+R1:	benzene pointing up
+	bond -120 from R1.V5 ; O
+	bond left
+R2:	flatring5 pointing down double 4,5 with .V2 at R1.V3 with .V3 at R1.V2 put N at 1
+	H below R2.V1
+R3:	ring put N at 3 with .V5 at R2.V5
+R4:	ring put N at 1 with .V1 at R3.V3
+	back bond -120 from R4.V4 ; H
+	back bond 60 from R4.V3 ; H
+R5:	ring with .V1 at R4.V3
+	bond -120
+D1:	double bond down ; O
+	bond left from D1.start ; O
+	bond left
+	back bond 60 from R5.V3 ; H
+	back bond down from R5.V4 ; O
+	bond down from O
+	bond 120 from R5.V3 ; O
+	bond 50 from O
+D2:	double bond up ; O
+	bond right length .1 from D2.start
+B:	benzene pointing right
+	bond 45 from B.V6 ; O
+	bond right
+	bond right from B.V1 ; O
+	bond right
+	bond 135 from B.V2 ; O
+	bond right
+
+### Emacs settings
+# Local Variables:
+# mode: Nroff
+# End:
+end
+.PE

Index: groffer/ChangeLog
===================================================================
RCS file: groffer/ChangeLog
diff -N groffer/ChangeLog
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ groffer/ChangeLog	11 Aug 2013 08:27:12 -0000	1.67
@@ -0,0 +1,314 @@
+2013-04-11  Bernd Warken  <groff-bernd.warken-72@web.de>
+
+	* contrib/groffer: There is now a free `git' package containing
+	all old `groffer' versions `v0.*' and `v1.*'.  The new versions
+	`groffer 2.*' will actually not be included.  This package can be
+	got at:
+
+	$ git clone git@github.com:RUNOFF/groffer.git
+
+2013-03-29  Bernd Warken  <groff-bernd.warken-72@web.de>
+
+	* perl/groffer.pl: Change viewers for `PS'.
+
+2013-03-29  Bernd Warken  <groff-bernd.warken-72@web.de>
+
+	* perl/groffer.pl: Change viewers for `PS' and `PDF'.
+
+	* version.sh: New version is `1.1.3'.
+
+2012-08-09  Werner LEMBERG  <wl@gnu.org>
+
+	Synchronize man pages.
+
+	* perl/groffer.man, shell/groffer.man: Fix many minor issues.
+
+2012-08-07  Eric S. Raymond  <esr@thyrsus.com>
+
+	Yet more elimination of low-level troff hackery in the
+	documentation so it can be lifted to structural markup.
+
+	* perl/groffer.man: Use .IP rather than .TP in
+	.Topic; this make structural parsing work.  Also remove a
+	pointless and somewhat out-of-date .ig section.
+
+2011-10-17  Ingo Schwarze  <schwarze@openbsd.org>
+
+	Do not use INSTALL_DATA and INSTALL_SCRIPT during build phase.
+
+	* Makefile.sub (groffer): Replace INSTALL_DATA and
+	INSTALL_SCRIPT with `cp'.  Otherwise the build phase might
+	fail with `permission denied' if you use the `-o root' flag
+	of the `install' command.  The use of INSTALL_* is an abuse
+	anyway because it's not installing anything at that point;
+	it's just copying files around locally, within in the build
+	directories.
+
+2011-03-21  Jan Vcelak  <jvcelak@redhat.com>
+	    Bernd Warken <groff-bernd.warken-72@web.de>
+
+	Remove hardcoded path to 'libdir/groff/groffer' directory.
+
+	* Makefile.sub: use @groffer_dir@
+
+	* groffer.pl: use @groffer_dir@
+
+2011-01-27  James Budiono  <james.budiono@gmail.com>
+	    Bernd Warken <groff-bernd.warken-72@web.de>
+
+	Fix display of manpages.
+
+	Reported as
+	http://lists.gnu.org/archive/html/bug-groff/2011-01/msg00015.html.
+
+	* perl/groffer.pl (_get_first_prog): Fix return value.
+	(Viewer_X): Add `okular' viewer.
+	* perl/man.pl (manpath_set_from_path): Handle `@main::Path)'
+	correctly.
+
+	* version.sh: Updated.
+
+2009-01-03  Werner LEMBERG  <wl@gnu.org>
+
+	* version.sh: Prepare for groff release 1.20.
+
+2008-01-04  Werner LEMBERG  <wl@gnu.org>
+
+	* shell/groffer.man, perl/groffer.man: Insert `\:' in URLs where
+	appropriate.
+
+2007-02-15  Eric S. Raymond  <esr@snark.thyrsus.com>
+
+	* perl/groffer.man, perl/groffer.man: Fix non-portable `if'
+	expressions.
+
+2007-02-13  Eric S. Raymond  <esr@snark.thyrsus.com>
+
+	Use an-ext.tmac macros in groffer.man.
+
+	* perl/groffer.man, perl/groffer.man: Replace ShellCommand with
+	.EX/.EE pairs.
+	Don't use .TP for examples, as some viewers won't handle a display
+	macro as a tag line.  Use .SY/.OP/.YS rather than elaborate custom
+	macros.
+
+2007-02-02  Werner LEMBERG  <wl@gnu.org>
+
+	* roff2.man: Further refinements and normalizations.
+
+2007-02-02  Eric S. Raymond  <esr@snark.thyrsus.com>
+
+	* roff2.man: Converted to use .SY/.OP/.YS and for cross-viewer
+	portability.  Conversion checked using the protocol described in
+	tmac/TESTING-HINTS.
+
+2006-11-14  Werner LEMBERG  <wl@gnu.org>
+
+	* Makefile.sub (GROFFER_REST): Add roff2.man.
+	(groffer): Use $(INSTALL_DATA) for man pages.
+	Don't call `chmod' for $(ROFF2PROGS).
+	(roff2.man): Typographical fixes.
+
+2006-11-11  Bernd Warken  <groff-bernd.warken-72@web.de>
+	________________________________________________________________
+	* release of groffer 1.1.1
+
+	* perl/roff2.pl, shell/roff2.sh: Create a new working mode without
+	`groffer' for `roff2*'.
+
+	* perl/groffer.pl: Fix test of temporary directory.
+
+2006-11-09  Bernd Warken  <groff-bernd.warken-72@web.de>
+	________________________________________________________________
+	* release of groffer 1.1.0
+
+	* perl/groffer.pl, perl/func.pl, perl/groffer.man, \
+	shell/groffer2.sh, shell/groffer.man: Add `--debug-grog' to
+	display the `grog' output.
+
+	* perl/roff2.pl, shell/roff2.sh: New files for creating the roff2*
+	programs to transform roff code to different formats.
+
+	* roff2.man: New file to create man pages for the roff2*
+	programs.
+
+	* Makefile.sub: Add roff2* and some minor fixes.
+
+2006-11-04  Bernd Warken  <groff-bernd.warken-72@web.de>
+	________________________________________________________________
+	* release of groffer 1.0.3
+
+	* Makefile.sub:
+	- Delete removing of $(CLEANADD) in `groffer'.
+	- Add $(MAN1) to `groffer'.
+
+	* perl/groffer.pl, perl/func.pl, shell/groffer2.sh:
+	- Add `groff' option with argument `-K'.
+	- Redesign the changed `grog'.
+
+2006-10-23  Bernd Warken  <groff-bernd.warken-72@web.de>
+	________________________________________________________________
+	* release of groffer 1.0.2
+
+	* perl/groffer.pl:
+	- Move all variable declarations out of BEGIN.
+	- Move all `use' commands outside of BEGIN.  Fix the arising
+	errors.
+	- Correct new position of perl/perl_test.pl.
+
+	* perl/func.pl:
+	- version(): Fix the determination of the version of groff.
+	- usage(): Sort it among the functions in this file.
+
+	* perl/groffer.man, shell/groffer.man: Fix string variable
+	Ellipsis.
+
+	* shell/README_SH: Add information on Autobook.
+
+	* shell/groffer.sh:
+	- Extent simple shell tests by testing on support for functions.
+	Test standard shell on function support.  Add error reports on
+	shell tests.
+	- Set unset variables LANG LC_ALL LC_MESSAGES LC_CTYPES LANGUAGES
+	to `C', according to Autobook, ch. 22.
+	- Remove option `-e' from `sed'.
+
+	* shell/groffer2.sh:
+	- Add test on directory in man path find.
+	- Add Bourne compatibility for zsh shell.
+	- Replace `echo -n ""' by `:'.
+	- Remove -e option from sed.
+
+2006-10-23  Werner Lemberg
+
+	* perl_test.pl: Moved to...
+	* perl/perl_test.pl: Here.
+
+	* Makefile.sub: Rewritten.  Change PERL to HAVE_PERL and SHELL to
+	HAVE_SHELL.
+
+2006-10-14  Bernd Warken  <groff-bernd.warken-72@web.de>
+	________________________________________________________________
+	* release of groffer 1.0.1
+
+	* perl/groffer.pl: Change $perl_test_pl to $file_perl_test_pl.
+
+	* perl/groffer.pl, perl/func.pl: Remove `\n' in `die' calls.
+
+2006-10-12  Bernd Warken  <groff-bernd.warken-72@web.de>
+	________________________________________________________________
+	* 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.
+
+2006-10-02  Bernd Warken  <groff-bernd.warken-72@web.de>
+
+	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.
+
+	The former part of the ChangeLog file is in `shell/ChangeLog.0'.
+
+2006-10-01  Bernd Warken  <groff-bernd.warken-72@web.de>
+________________________________________________________________
+License
+
+Copyright (C) 2006-2009, 2011
+	Free Software Foundation, Inc.
+Written by Bernd Warken <groff-bernd.warken-72@web.de>.
+
+Copying and distribution of this file, with or without
+modification, are permitted provided the copyright notice and this
+notice are preserved.
+
+This file is part of `groffer', which is part of the `groff'
+project.
+
+####### Emacs settings
+
+Local Variables:
+mode: change-log
+End:

Index: groffer/Makefile.sub
===================================================================
RCS file: groffer/Makefile.sub
diff -N groffer/Makefile.sub
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ groffer/Makefile.sub	11 Aug 2013 08:27:27 -0000	1.35
@@ -0,0 +1,149 @@
+# Makefile.sub for `groffer' (integration into the `groff' source tree)
+
+# File position: <groff-source>/contrib/groffer/Makefile.sub
+
+# Copyright (C) 2001, 2002, 2005, 2006, 2009, 2011
+#   Free Software Foundation, Inc.
+# Written by Werner Lemberg <wl@gnu.org> and
+# Bernd Warken <groff-bernd.warken-72@web.de>.
+
+# Last update: 17 Oct 2011
+
+# 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/>.
+
+########################################################################
+
+ROFF2MODES=dvi html pdf ps text x
+ROFF2PROGS=`echo $(ROFF2MODES) | sed 's/[a-z][a-z]*/roff2&/g'`
+ROFF2MAN=`echo $(ROFF2MODES) | sed 's/[a-z][a-z]*/roff2&.man/g'`
+ROFF2MANN=`echo $(ROFF2MODES) | sed 's/[a-z][a-z]*/roff2&.n/g'`
+
+MAN1=groffer.n \
+     roff2dvi.n \
+     roff2html.n \
+     roff2pdf.n \
+     roff2ps.n \
+     roff2text.n \
+     roff2x.n
+
+MOSTLYCLEANADD=groffer HAVE_PERL HAVE_SHELL groffer.man \
+               $(MAN1) $(ROFF2MAN) $(ROFF2PROGS)
+
+# not all make programs have $(RM) predefined.
+RM=rm -f
+
+all: groffer
+
+GROFFER_PERL=$(srcdir)/perl/func.pl \
+             $(srcdir)/perl/man.pl \
+             $(srcdir)/perl/perl_test.pl \
+             $(srcdir)/perl/split_env.sh
+GROFFER_SHELL=$(srcdir)/shell/groffer2.sh
+GROFFER_REST=$(srcdir)/roff2.man \
+             $(srcdir)/version.sh \
+             $(srcdir)/perl/groffer.man \
+             $(srcdir)/perl/groffer.pl \
+             $(srcdir)/perl/roff2.pl \
+             $(srcdir)/shell/roff2.sh \
+             $(srcdir)/shell/groffer.man \
+             $(srcdir)/shell/groffer.sh
+
+GROFFER_PERL_=`echo $(GROFFER_PERL) | sed 's|$(srcdir)/perl/||g'`
+GROFFER_SHELL_=`echo $(GROFFER_SHELL) | sed 's|$(srcdir)/shell||g'`
+
+# TODO: Add perl check to configure script.
+groffer: $(GROFFER_PERL) $(GROFFER_SHELL) \
+         $(GROFFER_REST) $(SH_DEPS_SED_SCRIPT)
+	if perl $(srcdir)/perl/perl_test.pl 2>&1 >/dev/null; then \
+	  : >HAVE_PERL; \
+	  echo "Using perl version of groffer."; \
+	  sed -f "$(SH_DEPS_SED_SCRIPT)" \
+            -e "s|@g@|$(g)|g" \
+	    -e "s|@BINDIR@|$(DESTDIR)$(bindir)|g" \
+	    -e "s|@libdir@|$(DESTDIR)$(libdir)|g" \
+	    -e "s|@groffer_dir@|$(DESTDIR)$(groffer_dir)|g" \
+	    -e "s|@VERSION@|$(version)$(revision)|g" \
+	    -e "$(SH_SCRIPT_SED_CMD)" \
+	    $(srcdir)/perl/groffer.pl >$@; \
+	  cp $(srcdir)/perl/groffer.man groffer.man; \
+	  for f in $(ROFF2PROGS); do \
+	    cp $(srcdir)/perl/roff2.pl $$f; \
+	  done; \
+	else \
+	  : >HAVE_SHELL; \
+	  echo "Using shell version of groffer."; \
+	  sed -f "$(SH_DEPS_SED_SCRIPT)" \
+            -e "s|@g@|$(g)|g" \
+	    -e "s|@BINDIR@|$(DESTDIR)$(bindir)|g" \
+	    -e "s|@libdir@|$(DESTDIR)$(libdir)|g" \
+	    -e "s|@groffer_dir@|$(DESTDIR)$(groffer_dir)|g" \
+	    -e "s|@VERSION@|$(version)$(revision)|g" \
+	    -e "$(SH_SCRIPT_SED_CMD)" \
+            $(srcdir)/shell/groffer.sh >$@; \
+	  cp $(srcdir)/shell/groffer.man groffer.man; \
+	  for f in $(ROFF2PROGS); do \
+	    cp $(srcdir)/shell/roff2.sh $$f; \
+	  done; \
+	fi
+	chmod +x $@
+	for m in $(ROFF2MODES); do \
+	  cat $(srcdir)/roff2.man \
+	  | sed 's/@ROFF2MODE@/'"$$m"'/g' > roff2$${m}.man; \
+	done
+
+install_data: groffer
+	-test -d $(DESTDIR)$(bindir) || $(mkinstalldirs) $(DESTDIR)$(bindir)
+	$(RM) $(DESTDIR)$(bindir)/groffer
+	$(INSTALL_SCRIPT) groffer $(DESTDIR)$(bindir)/groffer
+	for f in $(ROFF2PROGS); do \
+	  $(RM) $(DESTDIR)$(bindir)/$$f; \
+	  $(INSTALL_SCRIPT) $$f $(DESTDIR)$(bindir)/$$f; \
+	done
+	-test -d $(DESTDIR)$(groffer_dir) \
+          || $(mkinstalldirs) $(DESTDIR)$(groffer_dir)
+	$(RM) $(DESTDIR)$(groffer_dir)/version.sh
+	$(INSTALL_DATA) $(srcdir)/version.sh \
+          $(DESTDIR)$(groffer_dir)/version.sh
+	for f in $(GROFFER_PERL_) $(GROFFER_SHELL_); do \
+          $(RM) $(DESTDIR)$(groffer_dir)/$$f; \
+        done
+	if test -f HAVE_PERL; then \
+          for f in $(GROFFER_PERL_); do \
+            $(INSTALL_SCRIPT) $(srcdir)/perl/$$f \
+              $(DESTDIR)$(groffer_dir)/$$f; \
+          done; \
+        elif test -f HAVE_SHELL; then \
+          for f in $(GROFFER_SHELL_); do \
+            $(INSTALL_SCRIPT) $(srcdir)/shell/$$f \
+              $(DESTDIR)$(groffer_dir)/$$f; \
+          done; \
+        fi;
+
+uninstall_sub:
+	$(RM) $(DESTDIR)$(bindir)/groffer
+	for f in $(ROFF2PROGS); do $(RM) $(DESTDIR)$(bindir)/$$f; done
+	for f in $(GROFFER_PERL_) $(GROFFER_SHELL_) version.sh; do \
+          $(RM) $(DESTDIR)$(groffer_dir)/$$f; \
+        done
+	-rmdir $(DESTDIR)$(libdir)/groff/groffer
+
+########################################################################
+# Emacs settings
+########################################################################
+#
+# Local Variables:
+# mode: makefile
+# End:

Index: groffer/README
===================================================================
RCS file: groffer/README
diff -N groffer/README
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ groffer/README	11 Aug 2013 08:27:27 -0000	1.17
@@ -0,0 +1,123 @@
+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 <groff-bernd.warken-72@web.de>.
+
+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:

Index: groffer/roff2.man
===================================================================
RCS file: groffer/roff2.man
diff -N groffer/roff2.man
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ groffer/roff2.man	11 Aug 2013 08:27:27 -0000	1.8
@@ -0,0 +1,249 @@
+.ig
+roff2@ROFF2MODE@.1 - man page for roff2@ROFF2MODE@ (section 1).
+
+Source file position: <groff_source_top>/contrib/groffer/roff2.man
+Installed position:   $prefix/share/man/man1/roff2@ROFF2MODE@.1
+
+Last update: 5 Jan 2009
+Simplified to use .SY/.OP/.YS
+..
+.
+.
+.de au
+This file was written by Bernd Warken <groff-bernd.warken-72@web.de>.
+..
+.
+.
+.de co
+Copyright (C) 2006, 2007, 2009 Free Software Foundation, Inc.
+.
+.P
+This file is part of
+.IR \%groffer ,
+which is part of
+.IR \%groff ,
+a free software project.
+.
+You can redistribute it and/or modify it under the terms of the
+.nh
+.B "GNU General Public License"
+.hy
+as published by the
+.nh
+.BR "Free Software Foundation" ,
+.hy
+either version\~2, or (at your option) any later version.
+.
+.P
+You should have received a copy of the \f[CR]GNU General Public
+License\f[] along with
+.IR groff ,
+see the files \%\f[CB]COPYING\f[] and \%\f[CB]LICENSE\f[] in the top
+directory of the
+.I groff
+source package.
+.
+Or read the
+.I man\~page
+.BR gpl (1).
+You can also write to the
+.nh
+.B "Free Software Foundation, 51 Franklin St - Fifth Floor, Boston,"
+.BR "MA 02110-1301, USA" .
+.hy
+..
+.
+.
+.TH roff2@ROFF2MODE@ @MAN1EXT@ "@MDATE@" "Groff Version @VERSION@"
+.SH NAME
+roff2@ROFF2MODE@ \- transform roff code into @ROFF2MODE@ mode
+.
+.
+.\" --------------------------------------------------------------------
+.SH "SYNOPSIS"
+.
+.SY roff2@ROFF2MODE@
+.RI [ \%groffer_option .\|.\|.\&]
+.OP \-\-
+.RI [ \%filespec .\|.\|.\&]
+.
+.SY roff2@ROFF2MODE@
+.B \-h
+|
+.B \-\-help
+.
+.SY roff2@ROFF2MODE@
+.B \-v
+|
+.B \-\-version
+.YS
+.
+.P
+The options
+.B \-v
+and
+.B \%\-\-version
+print the version information of the program to standard output and exit.
+.
+The options
+.B \-h
+and
+.B \-\-help
+print a usage information of the program to standard output and stop
+the program instantly.
+.
+.
+.P
+All other options are assumed to be
+.B \%groffer
+options.
+.
+They are internally passed to
+.BR \%groffer .
+They override the behavior of the program.
+.
+The options are optional, they can be omitted.
+.
+.
+.P
+The
+.I \%filespec
+arguments correspond to the
+.I \%filespec
+arguments of
+.BR \%groffer .
+So they are either the names of existing, readable files or
+.B \-
+for standard input, or the name of a man page or a
+.BR \%groffer (@MAN1EXT@)
+man page search pattern.
+.
+If no
+.I \%filespec
+is specified standard input is assumed automatically.
+.
+.
+.\" --------------------------------------------------------------------
+.SH DESCRIPTION
+.
+.B \%roff2@ROFF2MODE@
+transforms
+.I roff
+code into
+.ie '@ROFF2MODE@'x' \{\
+.  I X
+mode corresponding to the
+.  I groff
+devices
+.  BR X *;
+this mode is suitable for
+.  BR \%gxditview (@MAN1EXT@).
+.\}
+.el \{\
+.  I \%@ROFF2MODE@
+mode.
+.\}
+.
+Print the result to standard output.
+.
+.
+.P
+There are more of these programs for generating other formats of
+.I \%roff
+input.
+.
+.if !'@ROFF2MODE@'dvi' \{\
+.  TP
+.  BR \%roff2dvi (@MAN1EXT@)
+is for
+.  I dvi
+mode.
+.\}
+.
+.if !'@ROFF2MODE@'html' \{\
+.  TP
+.  BR \%roff2html (@MAN1EXT@)
+generates
+.  I html
+output.
+.\}
+.
+.if !'@ROFF2MODE@'pdf' \{\
+.  TP
+.  BR \%roff2pdf (@MAN1EXT@)
+outputs
+.  I pdf
+mode.
+.\}
+.
+.if !'@ROFF2MODE@'ps' \{\
+.  TP
+.  BR \%roff2ps (@MAN1EXT@)
+prints
+.  I \%PostScript
+format to standard output.
+.\}
+.
+.if !'@ROFF2MODE@'text' \{\
+.  TP
+.  BR \%roff2text (@MAN1EXT@)
+generates text output in the
+.  B groff
+device
+.  IR latin1 .
+.\}
+.
+.if !'@ROFF2MODE@'x' \{\
+.  TP
+.  BR \%roff2x (@MAN1EXT@)
+prints the output in the
+.  B groff
+device
+.  B X
+that is suitable for programs like
+.  BR \%gxditview (@MAN1EXT@)
+or
+.  BR \%xditview (1).
+.\}
+.
+.
+.\" --------------------------------------------------------------------
+.SH "SEE ALSO"
+.\" --------------------------------------------------------------------
+.
+.BR \%groff (@MAN1EXT@),
+.BR \%groffer (@MAN1EXT@),
+.if !'@ROFF2MODE@'dvi' \
+.  BR \%roff2dvi (@MAN1EXT@),
+.if !'@ROFF2MODE@'html' \
+.  BR \%roff2html (@MAN1EXT@),
+.if !'@ROFF2MODE@'pdf' \
+.  BR \%roff2pdf (@MAN1EXT@),
+.if !'@ROFF2MODE@'ps' \
+.  BR \%roff2ps (@MAN1EXT@),
+.if !'@ROFF2MODE@'text' \
+.  BR \%roff2text (@MAN1EXT@),
+.if !'@ROFF2MODE@'x' \
+.  BR \%roff2x (@MAN1EXT@),
+.BR \%gxditview (@MAN1EXT@).
+.
+.
+.\" --------------------------------------------------------------------
+.SH "AUTHOR"
+.\" --------------------------------------------------------------------
+.au
+.
+.
+.\" --------------------------------------------------------------------
+.SH "COPYING"
+.\" --------------------------------------------------------------------
+.co
+.
+.
+.\" --------------------------------------------------------------------
+.\" Emacs settings
+.\" --------------------------------------------------------------------
+.
+.\" Local Variables:
+.\" mode: nroff
+.\" End:

Index: groffer/version.sh
===================================================================
RCS file: groffer/version.sh
diff -N groffer/version.sh
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ groffer/version.sh	11 Aug 2013 08:27:28 -0000	1.23
@@ -0,0 +1,38 @@
+#! /bin/sh
+
+# groffer - display groff files
+
+# Source file position: <groff-source>/contrib/groffer/version.sh
+# Installed position: <prefix>/lib/groff/groffer/version.sh
+
+# Copyright (C) 2001-2006, 2009, 2011, 2013
+#   Free Software Foundation, Inc.
+# Written by Bernd Warken <groff-bernd.warken-72@web.de>.
+
+# 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/>.
+
+########################################################################
+
+export _PROGRAM_VERSION;
+export _LAST_UPDATE;
+
+_PROGRAM_VERSION='1.1.3';
+_LAST_UPDATE='29 Mar 2013';
+
+# this setting of the groff version is only used before make is run,
+# otherwise @VERSION@ will set it, see groffer.sh.
+export _GROFF_VERSION_PRESET;
+_GROFF_VERSION_PRESET='1.22.2';


From MAILER-DAEMON Sun Aug 11 04:29:32 2013
Received: from list by lists.gnu.org with archive (Exim 4.71)
	id 1V8R1o-0004pk-19
	for mharc-groff-commit@gnu.org; Sun, 11 Aug 2013 04:29:32 -0400
Received: from eggs.gnu.org ([2001:4830:134:3::10]:51920)
	by lists.gnu.org with esmtp (Exim 4.71) (envelope-from <wl@gnu.org>)
	id 1V8R1U-0004nn-12
	for groff-commit@gnu.org; Sun, 11 Aug 2013 04:29:29 -0400
Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71)
	(envelope-from <wl@gnu.org>) id 1V8R1B-0002T3-I1
	for groff-commit@gnu.org; Sun, 11 Aug 2013 04:29:11 -0400
Received: from vcs.savannah.gnu.org ([140.186.70.72]:59754)
	by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from <wl@gnu.org>)
	id 1V8R1B-0002Sv-7C
	for groff-commit@gnu.org; Sun, 11 Aug 2013 04:28:53 -0400
Received: from wl by vcs.savannah.gnu.org with local (Exim 4.72)
	(envelope-from <wl@gnu.org>) id 1V8R1A-0002Ve-T1
	for groff-commit@gnu.org; Sun, 11 Aug 2013 08:28:52 +0000
Date: Sun, 11 Aug 2013 08:28:52 +0000
Message-Id: <E1V8R1A-0002Ve-T1@vcs.savannah.gnu.org>
To: groff-commit@gnu.org
From: Werner LEMBERG <wl@gnu.org>
X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6.x
X-Received-From: 140.186.70.72
Subject: [Groff-commit] groff/contrib/groffer/perl README_PERL func.pl ...
X-BeenThere: groff-commit@gnu.org
X-Mailman-Version: 2.1.14
Precedence: list
List-Id: <groff-commit.gnu.org>
List-Unsubscribe: <https://lists.gnu.org/mailman/options/groff-commit>,
	<mailto:groff-commit-request@gnu.org?subject=unsubscribe>
List-Archive: <http://lists.gnu.org/archive/html/groff-commit>
List-Post: <mailto:groff-commit@gnu.org>
List-Help: <mailto:groff-commit-request@gnu.org?subject=help>
List-Subscribe: <https://lists.gnu.org/mailman/listinfo/groff-commit>,
	<mailto:groff-commit-request@gnu.org?subject=subscribe>
X-List-Received-Date: Sun, 11 Aug 2013 08:29:29 -0000

CVSROOT:	/sources/groff
Module name:	groff
Changes by:	Werner LEMBERG <wl>	13/08/11 08:28:52

Added files:
	contrib/groffer/perl: README_PERL func.pl groffer.man groffer.pl 
	                      man.pl perl_test.pl roff2.pl split_env.sh 

Log message:
	Revert accidental removal of previous commit.

CVSWeb URLs:
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/groffer/perl/README_PERL?cvsroot=groff&rev=1.6
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/groffer/perl/func.pl?cvsroot=groff&rev=1.10
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/groffer/perl/groffer.man?cvsroot=groff&rev=1.21
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/groffer/perl/groffer.pl?cvsroot=groff&rev=1.17
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/groffer/perl/man.pl?cvsroot=groff&rev=1.9
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/groffer/perl/perl_test.pl?cvsroot=groff&rev=1.6
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/groffer/perl/roff2.pl?cvsroot=groff&rev=1.8
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/groffer/perl/split_env.sh?cvsroot=groff&rev=1.6

Patches:
Index: README_PERL
===================================================================
RCS file: README_PERL
diff -N README_PERL
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ README_PERL	11 Aug 2013 08:28:51 -0000	1.6
@@ -0,0 +1,263 @@
+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 <groff-bernd.warken-72@web.de>.
+
+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:

Index: func.pl
===================================================================
RCS file: func.pl
diff -N func.pl
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ func.pl	11 Aug 2013 08:28:51 -0000	1.10
@@ -0,0 +1,789 @@
+#! /usr/bin/env perl
+
+# groffer - display groff files
+
+# Source file position: <groff-source>/contrib/groffer/perl/func.pl
+# Installed position: <prefix>/lib/groff/groffer/func.pl
+
+# Copyright (C) 2006, 2009 Free Software Foundation, Inc.
+# Written by Bernd Warken <groff-bernd.warken-72@web.de>.
+
+# Last update: 5 Jan 2009
+
+# 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/>.
+
+########################################################################
+
+use strict;
+use warnings;
+
+########################################################################
+# some functions
+########################################################################
+
+##########
+# cat_z(<file>)
+#
+# Decompress or cat the <file>.
+#
+# Return: the decompressed file as array
+#
+sub cat_z {
+  my $n = @_;
+  die "cat_z(): one argument is needed; you used $n;"
+    unless $n == 1;
+
+  my $file = $_[0];
+  die "cat_z(): `$file' is not a readable file;" unless -f $file && -r $file;
+  return () if -z $file;
+
+  my @res;
+  if ($main::Has_Compression) {
+    if ($main::Has_bzip) {
+      # test whether bz2 compressed, shell return must be inverted
+      unless ( system("bzip2 -t $file 2>$main::Dev_Null") ) {
+	@res = `bzip2 -c -d $file 2>$main::Dev_Null`;
+	return @res;
+      }
+      # if not compressed with gz, gzip will act like `cat'
+      @res = `gzip -c -d -f $file 2>$main::Dev_Null`;
+      return @res;
+    }
+  } else {
+    my $fh;
+    open $fh, "<$file" or die "cat_z(): could not open $file";
+    @res = <$fh>;
+    close $fh;
+    return @res;
+  }
+  ();
+} # cat_z()
+
+
+##########
+# clean_up()
+#
+# Remove the temporary directory and restore the system.
+#
+sub clean_up {
+  umask $main::Umask;
+  chdir $main::Start_Dir;
+  if ($main::Debug{'KEEP'} && -d $main::tmpdir) {
+    my $glob = File::Spec->catfile($main::tmpdir, '*');
+    unlink glob($glob);		# rm $tmpdir/*
+    rmdir $main::tmpdir;
+  }
+} # clean_up()
+
+
+##########
+# get_dirname(<path>)
+#
+# Split the path and return the directory name part
+#
+# Return: string of directory name
+#
+sub get_dirname {
+  my $n = @_;
+  die "get_filename(): one argument is needed; you used $n;" unless $n == 1;
+  return '' unless $_[0];
+
+  my ($dirname, $filename) = &split_path($_[0]);
+  $dirname;
+}				# get_dirname()
+
+
+##########
+# get_filename(<path>)
+#
+# Split the path and return the file name part
+#
+# Return: string of file name
+#
+sub get_filename {
+  my $n = @_;
+  die "get_dirname(): one argument is needed; you used $n;" unless $n == 1;
+  return '' unless $_[0];
+
+  my ($dirname, $filename) = &split_path($_[0]);
+  $filename;
+}				# get_filename()
+
+
+##########
+# is_X()
+#
+# Test whether X Windows is running.
+#
+sub is_X {
+  return 1 if $ENV{'DISPLAY'};
+  return 0;
+}				# is_X()
+
+
+##########
+# list_has(<list_ref>, <string>)
+#
+# Determine if <list_ref> has <string> as element.
+#
+sub list_has {
+  my $n = @_;
+  die "list_has(): 2 arguments are needed; you used $n;"
+    unless $n == 2;
+
+  my $list_ref = $_[0];
+  my $string = $_[1];
+  die "list_has(): first argument must be an array reference;"
+    unless ref($list_ref) eq 'ARRAY';
+
+  foreach ( @$list_ref ) {
+    return 1 if $_ eq $string;
+  }
+  0;
+}
+
+
+##########
+# path_uniq(<dir>...)
+#
+# make path having unique existing directories
+#
+sub path_uniq {
+  my @a;
+  my %h;
+  foreach (@_) {
+    next if exists $h{$_};
+    next unless -d $_;
+    push @a, $_;
+    $h{$_} = 1;
+  }
+  @a;
+}				# path_uniq()
+
+
+##########
+# print_hash(<hash_or_ref>)
+#
+# print the elements of a hash or hash reference
+#
+sub print_hash {
+  my $hr;
+  my $n = scalar @_;
+  if ($n == 0) {
+    print "empty hash\n;";
+    return 1;
+  } elsif ($n == 1) {
+    if (ref($_[0]) eq 'HASH') {
+      $hr = $_[0];
+    } else {
+      warn 'print_hash(): the argument is not a hash or hash reference;';
+      return 0;
+    }
+  } else {
+    if ($n % 2) {
+      warn 'print_hash(): the arguments are not a hash;';
+      return 0;
+    } else {
+      my %h = @_;
+      $hr = \%h;
+    }
+  }
+
+### print_hash()
+  unless (%$hr) {
+    print "empty hash\n";
+    return 1;
+  }
+  print "hash (ignore the ^ characters):\n";
+  for my $k (sort keys %$hr) {
+    my $hk = $hr->{$k};
+    print "  $k => ";
+    if (defined $hk) {
+      print "^$hk^";
+    } else {
+      print "undef";
+    }
+    print "\n";
+  }
+
+  1;
+}				# print_hash()
+
+
+##########
+# print_times(<string>)
+#
+# print the time, result: user, system, child process user, child system
+#
+sub print_times {
+  my @t = times;
+  my $s = '';
+  $s = $_[0] if $_[0];
+#  print STDERR "$s: @t\n";
+}				# print_times()
+
+BEGIN { &print_times("start"); }
+END { &print_times("end"); }
+
+
+##########
+# split_path(<path>)
+#
+# Split the path into directory and file name parts
+#
+# Return: array with 2 elements consisting of directory and file name
+#
+sub split_path {
+  my $n = @_;
+  die "split_path(): one argument is needed; you used $n;" unless $n == 1;
+  my $arg = $_[0];
+  return () unless $arg;
+
+  my $basename = basename($arg);
+  if ( $basename ne $arg ) { # path with dir
+    # fileparse() is from File::Basename
+    my($filename, $dirname, $suffix) = fileparse($arg);
+    return ($dirname, $basename);
+  }
+  return ('', $arg);
+}
+
+
+{
+  my $nr_file = 0;
+  my $nr_so = 0;
+
+  my $tmp_file_base;
+  my $tmp_so_base;
+
+  my $soelim_r = '';
+  $soelim_r = '-r'
+    if ! system("echo -n '' | soelim -r 2>$main::Dev_Null >$main::Dev_Null");
+
+  ##########
+  # to_tmp (<filename>)
+  #
+  # Print file (decompressed) to the temporary cat file with handling .SO
+  # for man pages.
+  #
+  sub to_tmp {
+    my $n = @_;
+    die "to_tmp(): one argument is needed; you used $n;"
+      unless $n == 1;
+
+    my $arg = $_[0];
+    return 1 unless $arg;
+    die "to_tmp(): $arg is not an existing file;" unless -f $arg;
+    die "to_tmp(): could not read file $arg;" unless -r $arg;
+    return 1 if -z $arg;
+
+    $tmp_file_base = File::Spec->catfile($main::tmpdir, ',file')
+      unless $tmp_file_base;
+    $tmp_so_base = File::Spec->catfile($main::tmpdir, ',so')
+      unless $tmp_so_base;
+
+    open $main::fh_cat, ">>$main::tmp_cat" or
+      die "to_tmp(): could not open temporary cat file";
+
+    if ($main::Opt{'WHATIS'}) {
+      &whatis_filename($arg);
+      return 1;
+    }
+
+    ### to_tmp()
+    my $dir = &get_dirname($arg);
+
+    my ($fh_file, $tmp_file, $fh_tmp, $tmp_tmp);
+    ++$nr_file;
+    $tmp_file = $tmp_file_base . $nr_file;
+    $tmp_tmp = File::Spec->catfile($main::tmpdir, ',tmp');
+
+    print STDERR "file: $arg\n" if $main::Debug{'FILENAMES'};
+
+    if ($main::Filespec_Is_Man) {
+      my ($fh_so, $tmp_so);
+
+      open $fh_file, ">$tmp_file" or
+	die "to_tmp(): could not open $tmp_file;";
+      foreach ( &cat_z($arg) ) {
+	print $fh_file "$_";
+      }
+      close $fh_file;
+
+      open $fh_file, "<$tmp_file" or
+	die "to_tmp(): could not open $tmp_file;";
+      my @list;
+      foreach (<$fh_file>) {
+	if (/^[\.']\s*so\s/) {
+	  chomp;
+	  s/^[\.']\s*so\s*//;
+	  push @list, $_;
+	}
+      }
+      close $fh_file;
+
+      if ( @list && $main::Debug{'KEEP'} ) {
+	my $f = $tmp_file . '+man';
+	copy($tmp_file, $f);
+      }
+
+      ### to_tmp()
+    DO_MAN_SO:  foreach (@list) {
+	# start of _do_man_so() in shell version
+	my $so = $_;
+	my $soname = $so;
+	$soname =~ s/\\\s/ /g;
+
+	my $sofound;
+	my $path = File::Spec->rootdir();
+	if ($soname =~ m#^$path#) {	  # absolute path name
+	  next DO_MAN_SO if -f $soname;
+	  foreach ('.gz', '.Z', '.bz2') {
+	    my $name = $soname . $_;
+	    if (-f $name) {
+	      $sofound = $name;
+	      last;
+	    }
+	  }			# foreach
+	  next DO_MAN_SO unless $sofound;
+	} else {		# relative to man path
+	LOOP: foreach my $ext ('', '.gz', '.Z', '.bz2') {
+	    foreach my $p ( @{$main::Man{'PATH'}} ) {
+	      my $f = File::Spec->catfile($p, "$soname$ext");
+	      if (-f $f) {
+		$sofound = $f if -f $f;
+		last LOOP;
+	      }
+	    }			# foreach
+	  }			# LOOP:
+	  next DO_MAN_SO unless $sofound;
+	}			# if on path
+
+	print STDERR "file from .so: $so\n" if $main::Debug{'FILENAMES'};
+
+	### to_tmp()
+	++$nr_so;
+	$tmp_so = $tmp_so_base . $nr_so;
+	unlink $tmp_so if -e $tmp_so;
+	open $fh_so, ">$tmp_so" or
+	  die "to_tmp(): could not open $tmp_so;";
+	foreach ( &cat_z($sofound) ) {
+	  print $fh_so $_;
+	}
+	close $fh_so;
+
+	my $esc = $so;
+	$esc =~ s/\\/\\\\/g;
+	open $fh_file, "<$tmp_file" or
+	  die "to_tmp(): could not open $tmp_file;";
+	open $fh_tmp, ">$tmp_tmp" or
+	  die "to_tmp(): could not open $tmp_tmp;";
+	foreach (<$fh_file>) {
+	  s#^([\.'])\s*so\s+($so|$esc|$soname)\s*\n$#${1}so $tmp_so\n#s;
+	  print $fh_tmp $_;
+	}
+	### to_tmp()
+	close $fh_tmp;
+	close $fh_file;
+	unlink $tmp_file if -e $tmp_file;
+	rename $tmp_tmp, $tmp_file;
+	# end of _do_man_so() in shell version
+      }				# foreach (@list)
+
+      if ( @list && $main::Debug{'KEEP'} ) {
+	my $f = $tmp_file . '+tmp';
+	copy($tmp_file, $f);
+      }
+
+      unlink $tmp_tmp if -e $tmp_tmp;
+      rename $tmp_file, $tmp_tmp;
+      system("soelim -I$dir $soelim_r $tmp_tmp >$tmp_file");
+      unlink $tmp_tmp if -e $tmp_tmp;
+
+    } else {			# $Filespec_Is_Man is empty
+      open $fh_tmp, ">$tmp_tmp" or
+	die "to_tmp(): could not open $tmp_tmp;";
+      foreach (cat_z $arg) {
+	print $fh_tmp $_;
+      }
+      close $fh_tmp;
+      if ($dir) {
+	system("soelim -I$dir $soelim_r $tmp_tmp >$tmp_file");
+      } else {
+	system("soelim $soelim_r $tmp_tmp >$tmp_file");
+      }
+      unlink $tmp_tmp;
+    }				# if ($Filespec_Is_Man)
+
+    ### to_tmp()
+    my $grog = `grog $tmp_file`;
+    die "to_tmp(): grog error on $tmp_file;" if $?;
+    chomp $grog;
+    print STDERR "grog output: $grog\n" if $main::Debug{'GROG'};
+    if ($grog =~ /^.*\s-m.*$/) {
+      $grog =~ s/\s+/ /g;
+      $grog =~ s/ -m / -m/g;
+      $grog =~ s/ -mm([^ ]) / -m$1/g;
+      foreach my $g (split / /, $grog) {
+	if ($g =~ /^-m/) {
+	  my $ref = \@main::Macro_Packages;
+	  if ( &list_has($ref, $g) ) {
+	    if (! $main::Macro_Pkg) {
+	      $main::Macro_Pkg = $g;
+	    } elsif ($main::Macro_Pkg eq $g) {
+	      1;
+	    } elsif ($main::Macro_Pkg =~ /^-m/) {
+	      warn "to_tmp(): Ignore $arg because it needs $g " .
+		"instead of $main::Macro_Pkg";
+	      unlink $tmp_file unless $main::Debug{'KEEP'};
+	      return 0;
+	    } elsif ($main::Macro_Pkg ne $g) {
+	      die "to_tmp(): \$Macro_Pkg does not start with -m: " .
+		"$main::Macro_Pkg";
+	    }			# if (! $main::Macro_Pkg)
+	  }			# if (&list_has
+	}			# if (/^-m/)
+      }				# foreach my $g
+    }				# if $grog
+
+    open $fh_file, "<$tmp_file" or
+      die "to_tmp(): could not open $tmp_file for reading;";
+    open $main::fh_cat, ">>$main::tmp_cat" or
+      die "to_tmp(): could not open $main::tmp_cat for appending;";
+    foreach (<$fh_file>) {
+      print $main::fh_cat $_;
+    }
+    close $main::fh_cat;
+    close $fh_file;
+
+    unless ( $main::Debug{'KEEP'} ) {
+      unlink $tmp_file;
+      foreach ( glob("$tmp_so_base*") ) {
+	unlink $_;
+      }
+    }
+    1;
+  }				# to_tmp()
+}
+
+##########
+# to_tmp_line (<text>...)
+#
+# Print array of lines with <text> to the temporary cat file.  \n is added
+# if a line does not end with \n.
+#
+sub to_tmp_line {
+  my $n = @_;
+  return 1 if $n == 0;
+  open $main::fh_cat, ">>$main::tmp_cat" or
+    die "to_tmp_line(): could not open temporary cat file";
+  foreach (@_) {
+    my $line = $_;
+    chomp($line);
+    print $main::fh_cat "$line\n";
+  }
+  close $main::fh_cat;
+  1;
+} # to_tmp_line()
+
+
+##########
+# usage()
+#
+# Print usage information for --help.
+#
+sub usage {
+  print "\n";
+  &version();
+  print <<EOF;
+
+Usage: groffer [option]... [filespec]...
+
+Display roff files, standard input, and/or Unix manual pages with an X
+Window viewer or in several text modes.  All input is decompressed
+on-the-fly with all formats that gzip can handle.
+
+"filespec" is one of
+  "filename"       name of a readable file
+  "-"              for standard input
+  "man:name(n)"    man page "name" in section "n"
+  "man:name.n"     man page "name" in section "n"
+  "man:name"       man page "name" in first section found
+  "name(n)"        man page "name" in section "n"
+  "name.n"         man page "name" in section "n"
+  "n name"         man page "name" in section "n"
+  "name"           man page "name" in first section found
+where `section' is a single character out of [1-9on], optionally followed
+by some more letters that are called the `extension'.
+
+-h --help         print this usage message.
+-T --device=name  pass to groff using output device "name".
+-v --version      print version information.
+-V                display the groff execution pipe instead of formatting.
+-X                display with "gxditview" using groff -X.
+-Z --ditroff --intermediate-output
+                  generate groff intermediate output without
+                  post-processing and viewing, like groff -Z.
+All other short options are interpreted as "groff" formatting options.
+
+The most important groffer long options are
+
+--apropos=name    start man's "apropos" program for "name".
+--apropos-data=name
+                  "apropos" for "name" in man's data sections 4, 5, 7.
+--apropos-devel=name
+                  "apropos" for "name" in development sections 2, 3, 9.
+--apropos-progs=name
+                  "apropos" for "name" in man's program sections 1, 6, 8.
+--auto            choose mode automatically from the default mode list.
+--default         reset all options to the default value.
+--default-modes=mode1,mode2,...
+                  set sequence of automatically tried modes.
+--dvi             display in a viewer for TeX device independent format.
+--dvi-viewer=prog choose the viewer program for dvi mode.
+--groff           process like groff, disable viewing features.
+--help            display this helping output.
+--html            display in a web browser.
+--html-viewer=program
+                  choose the web browser for html mode.
+--man             check file parameters first whether they are man pages.
+--mode=auto|dvi|groff|html|pdf|ps|source|text|tty|www|x|X
+                  choose display mode.
+--no-man          disable man-page facility.
+--no-special      disable --all, --apropos*, and --whatis
+--pager=program   preset the paging program for tty mode.
+--pdf             display in a PDF viewer.
+--pdf-viewer=prog choose the viewer program for pdf mode.
+--ps              display in a Postscript viewer.
+--ps-viewer=prog  choose the viewer program for ps mode.
+--source          output as roff source.
+--text            output in a text device without a pager.
+--to-stdout       output the content of the mode file without display.
+--tty             display with a pager on text terminal even when in X.
+--tty-viewer=prog select a pager for tty mode; same as --pager.
+--whatis          display the file name and description of man pages
+--www             same as --html.
+--www-viewer=prog same as --html-viewer
+--x --X           display with "gxditview" using an X* device.
+--x-viewer=prog   choose viewer program for x mode (X mode).
+--X-viewer=prog   same as "--xviewer".
+
+The usual X Windows toolkit options transformed into GNU long options:
+--background=color, --bd=size, --bg=color, --bordercolor=color,
+--borderwidth=size, --bw=size, --display=Xdisplay, --fg=color,
+--fn=font, --font=font, --foreground=color, --geometry=geom, --iconic,
+--resolution=dpi, --rv, --title=text, --xrm=resource
+
+Long options of GNU "man":
+--all, --ascii, --ditroff, --extension=suffix, --locale=language,
+--local-file=name, --location, --manpath=dir1:dir2:...,
+--sections=s1:s2:..., --systems=s1,s2,..., --where, ...
+
+Development options that are not useful for normal usage:
+--debug, --debug-filenames, --debug-grog, --debug-keep, --debug-params,
+--debug-tmpdir, --do-nothing, --print=text
+
+EOF
+} # usage()
+
+
+##########
+# version()
+#
+# Get version information from version.sh and print a text with this.
+#
+sub version {
+  my $groff_version;
+  my $program_version = '';
+  my $last_update = '';
+  my $groff_version_preset = '';
+
+  die "$main::File_version_sh does not exist;"
+    unless -f "$main::File_version_sh";
+  my $fh;
+  open $fh, "<$main::File_version_sh";
+  foreach (<$fh>) {
+    chomp;
+    if (/^\s*_PROGRAM_VERSION\s*=\s*['"]*([^'"]*)['"]*\s*;?\s*$/) {
+      $program_version = $1;
+      next;
+    }
+    if (/^\s*_LAST_UPDATE\s*=\s*['"]*([^'"]*)['"]*\s*;?\s*$/) {
+      $last_update = $1;
+      next;
+    }
+    if (/^\s*_GROFF_VERSION_PRESET\s*=\s*['"]*([^'"]*)['"]*\s*;?\s*$/) {
+      # this setting of the groff version is only used before make is run,
+      # otherwise @VERSION@ will set it, see groffer.sh.
+      $groff_version_preset = $1;
+      next;
+    }
+  }
+  close $fh;
+
+  if ($main::Groff_Version) {
+    $groff_version = $main::Groff_Version;
+  } else {
+    $groff_version = $groff_version_preset;
+  }
+  my $year = $last_update;
+  $year =~ s/^.* //;
+  print <<EOF;
+groffer $program_version of $last_update (Perl version)
+is part of groff version $groff_version.
+Copyright (C) $year Free Software Foundation, Inc.
+GNU groff and groffer come with ABSOLUTELY NO WARRANTY.
+You may redistribute copies of groff and its subprograms
+under the terms of the GNU General Public License.
+EOF
+} # version()
+
+
+##########
+# where_is_prog(<program>)
+#
+# Test whether <program> without its arguments exists or is a program
+# in $PATH.
+#
+# Arguments : 1, <program> can have spaces and arguments.
+# Return    : a hash with `dir', `file', `fullname', `args' if
+#             argument exists or is a program in $PATH, empty hash else.
+#
+sub where_is_prog {
+  scalar @_ eq 1 or die "where_is_prog(): only one argument is allowed";
+  my $p1 = $_[0];
+  return () unless $p1;
+
+  $p1 =~ s/\s+/ /g;
+  $p1 =~ s/(\\)+ / /g;
+  $p1 =~ s/^ | $//g;
+  return () unless $p1;
+
+  my $noarg = $p1;
+  $noarg =~ s/ -.*$//;
+  return () unless $noarg;
+
+  my $args;
+  if ($p1 =~ /^.* -.*$/) {
+    $args = $p1;
+    $args =~ s#^$noarg ##;
+  }
+  $args = '' unless defined $args;
+
+  my %result;
+
+  # test whether $noarg has directory, so it is not tested with $PATH
+  my ($dir, $name) = &split_path($noarg);
+  $result{'dir'} = $dir;
+
+### where_is_prog()
+  if (-f $noarg && -x $noarg) {
+    $result{'args'} = $args;
+    $result{'file'} = $name;
+    $result{'fullname'} = File::Spec->catfile($dir, $name);
+    return %result;
+  }
+
+  if ($dir) {			# $noarg has name with directory
+    # now $wip_noarg (with directory) is not an executable file
+
+    # test name with space
+    if ($name =~ / /) {
+      my @base = split(/ /, $name);
+      my $n = pop @base;
+      my @baseargs = ($n);
+      while (@base) {
+	my $base = join(' ', @base);
+	my $file = File::Spec->catpath($dir, $base);
+	if (-f $file && -x $file) {
+	  my $baseargs = join(' ', @baseargs);
+	  ### where_is_prog()
+	  if ($args) {
+	    $args = "$baseargs $args";
+	  } else {
+	    $args = $baseargs;
+	  }
+	  $result{'args'} = $args;
+	  $result{'file'} = $base;
+	  $result{'fullname'} = $file;
+	  return %result;
+	}			# file test $file
+	$n = pop @base;
+	unshift(@baseargs, $n);
+      }				# while (@base)
+    }				# end of test name with space
+    return ();
+  }				# test on $dir
+
+  # now $noarg doesn't have a directory part
+
+  $name = $noarg;
+
+  # check with $PATH
+
+  # test path with $win_noarg as a whole, evt. with spaces
+  foreach my $d (@main::Path) {
+    my $file = File::Spec->catfile($d, $name);
+    if (-f $file && -x $file) {
+      $result{'args'} = $args;
+      $result{'fullname'} = $file;
+      ($result{'dir'}, $result{'file'}) = &split_path($file);
+      return %result;
+    }				# file test $file
+  }				# foreach (@main::Path)
+
+### where_is_prog()
+  if ($name =~ / /) {
+    my @base = split(/ /, $name);
+    my $n = pop @base;
+    my @baseargs = ($n);
+    while (@base) {
+      my $base = join(' ', @base);
+      foreach my $d (@maon::Path) {
+	my $file = File::Spec->catfile($d, $base);
+	if (-f $file && -x $file) {
+	  my $baseargs = join(' ', @baseargs);
+	  if ($args) {
+	    $args = "$baseargs $args";
+	  } else {
+	    $args = $baseargs;
+	  }
+	  $result{'args'} = $args;
+	  $result{'fullname'} = $file;
+	  ($result{'dir'}, $result{'file'}) = &split_path($file);
+	  return %result;
+	}			# file test $file
+      }				# foreach (@main::Path)
+      $n = pop @base;
+      unshift(@baseargs, $n);
+    }				# while (@base)
+  }				# test $name on space
+  return ();
+} # where_is_prog()
+
+
+##########
+# wait()
+#
+# stop for checking temp files, etc.
+#
+sub wait {
+  print "push Ctrl-D";
+  my @x = <STDIN>;
+  print "\n";
+}				# wait()
+
+1;

Index: groffer.man
===================================================================
RCS file: groffer.man
diff -N groffer.man
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ groffer.man	11 Aug 2013 08:28:52 -0000	1.21
@@ -0,0 +1,3920 @@
+.TH GROFFER @MAN1EXT@ "@MDATE@" "Groff Version @VERSION@"
+.SH NAME
+groffer \- display groff files and man\~pages on X and tty
+.
+.SH "SYNOPSIS"
+.\" The .SH was moved to this place in order to appease `apropos'.
+.
+.\" --------------------------------------------------------------------
+.\" Legalese
+.\" --------------------------------------------------------------------
+.
+.de author
+This file was written by Bernd Warken <groff-bernd.warken-72@web.de>.
+..
+.de copyleft
+Copyright (C) 2001, 2002, 2004-2006, 2009-2012
+  Free Software Foundation, Inc.
+.
+.P
+This file is part of
+.IR \%groffer ,
+which is part of
+.IR \%groff ,
+a free software project.
+.
+You can redistribute it and/or modify it under the terms of the
+.nh
+.B GNU General Public License
+.hy
+as published by the
+.nh
+.BR "Free Software Foundation" ,
+.hy
+either version 3 of the License, or (at your option) any later version.
+.
+.P
+You should have received a copy of the \f[CR]GNU General Public
+License\f[] along with
+.IR groff ,
+see the files \%\f[CB]COPYING\f[] and \%\f[CB]LICENSE\f[] in the top
+directory of the
+.I groff
+source package.
+.
+Or read the
+.I man\~page
+.BR gpl (1).
+You can also visit
+.nh
+.B <http://www.gnu.org/licenses/>.
+.hy
+..
+.
+.\" --------------------------------------------------------------------
+.\" Setup
+.\" --------------------------------------------------------------------
+.
+.ds Ellipsis "\&.\|.\|.\&\"
+.
+.\" --------------------------------------------------------------------
+.\" Macro definitions
+.
+.\" --------------------------------------------------------------------
+.\" .CB  (<text>...)
+.\"
+.\" Print in constant-width bold font.
+.\"
+.de CB
+.  ft CB
+.  Text \\$*
+.  ft
+..
+.\" --------------------------------------------------------------------
+.\" .CI  (<text>...)
+.\"
+.\" Print in constant-width italic font.
+.\"
+.de CI
+.  ft CI
+.  Text \\$*
+.  ft
+..
+.\" --------------------------------------------------------------------
+.\" .CR  (<text>...)
+.\"
+.\" Print in constant-width roman font.
+.\"
+.de CR
+.  ft CR
+.  Text \\$*
+.  ft
+..
+.\" --------------------------------------------------------------------
+.\" .Error  (<text>...)
+.\"
+.\" Print error message to terminal and abort.
+.\"
+.de Error
+.  tm \\$*
+.  ab
+..
+.\" --------------------------------------------------------------------
+.\" .Env_var  (<env_var_name> [<punct>])
+.\"
+.\" Display an environment variable, with optional punctuation.
+.\"
+.de Env_var
+.  nh
+.  SM
+.  Text \f[CB]\\$1\f[]\\$2
+.  hy
+..
+.\" --------------------------------------------------------------------
+.\" .File_name  (<path_name>)
+.\"
+.\" Display a file or directory name in CB font.
+.\"
+.de File_name
+.  Header_CB \\$@
+..
+.\" --------------------------------------------------------------------
+.\" .Header_CB  (<path_name>)
+.\"
+.\" Display a line in CB font, for example after .TP
+.\"
+.de Header_CB
+.  nh
+.  Text \f[CB]\\$1\f[]\\$2
+.  hy
+..
+.\"  --------------------------------------------------------------------
+.\" .Text  (<text>...)
+.\"
+.\" Treat the arguments as text, no matter how they look.
+.\"
+.de Text
+.  if \\n[.$]=0 \
+.    return
+.  nh
+.  nop \)\\$*\)
+.  hy
+..
+.\" --------------------------------------------------------------------
+.\" .Topic  ([<indent>])
+.\"
+.\" A bulleted paragraph
+.\"
+.de Topic
+.  ie \\n[.$]=0 \
+.    ds @indent 2m\"
+.  el \
+.    ds @indent \\$1\"
+.  IP \[bu] \\*[@indent]
+.  rm @indent
+..
+
+.\" End of macro definitions
+.
+.
+.\" --------------------------------------------------------------------
+.\" SH "SYNOPSIS"
+.\" --------------------------------------------------------------------
+.
+.SY groffer
+.OP option \*[Ellipsis]
+.OP --
+.OP \%filespec \*[Ellipsis]
+.YS
+.
+.SY groffer
+.BR -h | --help
+.YS
+.
+.SY groffer
+.BR -v | --version
+.YS
+.
+.
+.\" --------------------------------------------------------------------
+.SH DESCRIPTION
+.\" --------------------------------------------------------------------
+.
+The
+.B \%groffer
+program is the easiest way to use
+.BR \%groff (@MAN1EXT@).
+It can display arbitrary documents written in the
+.I \%groff
+language, see
+.BR \%groff (@MAN7EXT@),
+or other
+.I \%roff
+languages, see
+.BR \%roff (@MAN7EXT@),
+that are compatible to the original
+.I \%troff
+language.
+.
+It finds and runs all necessary
+.I groff
+preprocessors, such as
+.BR @g@chem .
+.
+.
+.P
+The
+.B \%groffer
+program also includes many of the features for finding and displaying
+the \%\f[CR]Unix\f[] manual pages
+.nh
+.RI ( man\~pages ),
+.hy
+such that it can be used as a replacement for a
+.BR \%man (1)
+program.
+.
+Moreover, compressed files that can be handled by
+.BR \%gzip (1)
+or
+.BR \%bzip2 (1)
+are decompressed on-the-fly.
+.
+.
+.P
+The normal usage is quite simple by supplying a file name or name of a
+.I \%man\~page
+without further options.
+.
+But the option handling has many possibilities for creating special
+behaviors.
+.
+This can be done either in configuration files, with the shell
+environment variable
+.Env_var \%$GROFFER_OPT ,
+or on the command line.
+.
+.
+.P
+The output can be generated and viewed in several different ways
+available for
+.IR \%groff .
+.
+This includes the
+.I \%groff
+native \%\f[CR]X\~Window\f[] viewer
+.BR \%gxditview (@MAN1EXT@),
+each
+.IR \%Postcript ,
+.IR \%pdf ,
+or
+.I \%dvi
+display program, a web browser by generating
+.I \%html
+in
+.IR \%www\~mode ,
+or several
+.I \%text\~modes
+in text terminals.
+.
+.
+.P
+Most of the options that must be named when running
+.B \%groff
+directly are determined automatically for
+.BR \%groffer ,
+due to the internal usage of the
+.BR \%grog (@MAN1EXT@)
+program.
+.
+But all parts can also be controlled manually by arguments.
+.
+.
+.P
+Several file names can be specified on the command line arguments.
+.
+They are transformed into a single document in the normal way of
+.BR \%groff .
+.
+.
+.P
+Option handling is done in \f[CR]GNU\f[] style.
+.
+Options and file names can be mixed freely.
+.
+The option
+.RB ` \-\- '
+closes the option handling, all following arguments are treated as
+file names.
+.
+Long options can be abbreviated in several ways.
+.
+.
+.\" --------------------------------------------------------------------
+.SH "OPTION OVERVIEW"
+.\" --------------------------------------------------------------------
+.
+.TP
+.I breaking options
+.RS
+.P
+.SY
+.OP -h\~\fR|\fB\~--help
+.OP -v\~\fR|\fB\~--version
+.YS
+.RE
+.
+.
+.TP
+.I \%groffer mode options
+.RS
+.P
+.SY
+.OP --auto
+.OP --default
+.OP --default\-modes mode1,mode2,\*[Ellipsis]
+.OP --dvi
+.OP --dvi\-viewer prog
+.OP --groff
+.OP --html
+.OP --html\-viewer prog
+.OP --mode display_mode
+.OP --pdf
+.OP --pdf\-viewer prog
+.OP --ps
+.OP --ps\-viewer prog
+.OP --source
+.OP --text
+.OP --to\-stdout
+.OP --tty
+.OP --tty\-viewer prog
+.OP --www
+.OP --www\-viewer prog
+.OP --x\~\fR|\fB\~--X
+.OP --x\-viewer\~\fR|\fB\~--X\-viewer prog
+.YS
+.RE
+.
+.
+.TP
+.I options related to \%groff
+.RS
+.P
+.SY
+.OP -T\~\fR|\fB\~--device device
+.OP -Z\~\fR|\fB\~--intermediate\-output\~\fR|\fB\~--ditroff
+.YS
+.P
+All further
+.B \%groff
+short options are accepted.
+.RE
+.
+.
+.TP
+.I options for man\~pages
+.RS
+.P
+.SY
+.OP --apropos
+.OP --apropos\-data
+.OP --apropos\-devel
+.OP --apropos\-progs
+.OP --man
+.OP --no\-man
+.OP --no\-special
+.OP --whatis
+.YS
+.RE
+.
+.
+.TP
+.I long options taken over from GNU man
+.RS
+.P
+.SY
+.OP --all
+.OP --ascii
+.OP --ditroff
+.OP --extension suffix
+.OP --locale language
+.OP --local\-file
+.OP --location\~\fR|\fB\~--where
+.OP --manpath dir1:dir2:\*[Ellipsis]
+.OP --no\-location
+.OP --pager program
+.OP --sections sec1:sec2:\*[Ellipsis]
+.OP --systems sys1,sys2,\*[Ellipsis]
+.OP --troff\-device device
+.YS
+.P
+Further long options of \f[CR]GNU\f[]
+.B man
+are accepted as well.
+.RE
+.
+.
+.TP
+.I X Window Toolkit options
+.RS
+.P
+.SY
+.OP --bd\~\fR|\fB\~--bordercolor pixels
+.OP --bg\~\fR|\fB\~--background color
+.OP --bw\~\fR|\fB\~--borderwidth pixels
+.OP --display X-display
+.OP --fg\~\fR|\fB\~--foreground color
+.OP --fn\~\fR|\fB\~--ft\~\fR|\fB\~--font font_name
+.OP --geometry size_pos
+.OP --resolution value
+.OP --rv
+.OP --title string
+.OP --xrm X\-resource
+.YS
+.RE
+.
+.
+.TP
+.I options for development
+.RS
+.P
+.SY
+.OP --debug
+.OP --debug\-filenames
+.OP --debug\-grog
+.OP --debug\-keep
+.OP --debug\-params
+.OP --debug\-tmpdir
+.OP --do\-nothing
+.OP --print text
+.OP -V
+.YS
+.RE
+.
+.
+.TP
+.I \%filespec arguments
+.RS
+.P
+The
+.I \%filespec
+parameters are all arguments that are neither an option nor an option
+argument.
+.
+They usually mean a file name or a
+.I man page
+searching scheme.
+.
+.
+.P
+In the following, the term
+.I section_extension
+is used.
+.
+It means a word that consists of a
+.I man section
+that is optionally followed by an
+.IR extension .
+.
+The name of a
+.I man section
+is a single character from
+.BR \%[1-9on] ,
+the
+.I extension
+is some word.
+.
+The
+.I extension
+is mostly lacking.
+.
+.
+.P
+No
+.I \%filespec
+parameters means standard input.
+.
+.
+.TP 10m
+.B -
+stands for standard input (can occur several times).
+.
+.
+.TP
+.I filename
+the path name of an existing file.
+.
+.
+.TP
+.BI man: name ( section_extension )
+.TQ
+.BI man: name . section_extension
+.TQ
+.IB name ( section_extension )
+.TQ
+.IB name . section_extension
+.TQ
+.I "section_extension name"
+search the \%man\~page
+.I \%name
+in the section with optional extension
+.IR section_extension .
+.
+.
+.TP
+.BI man: name
+\%man\~page in the lowest
+.I \%man\~section
+that has
+.IR \%name .
+.
+.
+.TP
+.I name
+if
+.I \%name
+is not an existing file search for the man\~page
+.I \%name
+in the lowest man\~section.
+.
+.RE
+.
+.
+.\" --------------------------------------------------------------------
+.SH "OPTION DETAILS"
+.\" --------------------------------------------------------------------
+.
+The
+.B \%groffer
+program can usually be run with very few options.
+.
+But for special purposes, it supports many options.
+.
+These can be classified in 5 option classes.
+.
+.
+.P
+All short options of
+.B \%groffer
+are compatible with the short options of
+.BR \%groff (@MAN1EXT@).
+.
+All long options of
+.B \%groffer
+are compatible with the long options of
+.BR \%man (1).
+.
+.
+.P
+Arguments for long option names can be abbreviated in several ways.
+.
+First, the argument is checked whether it can be prolonged as is.
+.
+Furthermore, each minus sign
+.B -
+is considered as a starting point for a new abbreviation.
+.
+This leads to a set of multiple abbreviations for a single argument.
+.
+For example,
+.B --de\-n\-f
+can be used as an abbreviation for
+.BR --debug\-not\-func ,
+but
+.B --de\-n
+works as well.
+.
+If the abbreviation of the argument leads to several resulting options
+an error is raised.
+.
+.
+.P
+These abbreviations are only allowed in the environment variable
+.Env_var \%$GROFFER_OPT ,
+but not in the configuration files.
+.
+In configuration, all long options must be exact.
+.
+.
+.\" --------------------------------------------------------------------
+.SS "groffer breaking Options"
+.\" --------------------------------------------------------------------
+.
+As soon as one of these options is found on the command line it is
+executed, printed to standard output, and the running
+.B \%groffer
+is terminated thereafter.
+.
+All other arguments are ignored.
+.
+.
+.TP
+.B -h\~\fR|\fB\~--help
+Print help information with a short explanation of options to
+standard output.
+.
+.
+.TP
+.B -v\~\fR|\fB\~--version
+Print version information to standard output.
+.
+.
+.\" --------------------------------------------------------------------
+.SS "groffer Mode Options"
+.\" --------------------------------------------------------------------
+.
+The display mode and the viewer programs are determined by these
+options.
+.
+If none of these mode and viewer options is specified
+.B \%groffer
+tries to find a suitable display mode automatically.
+.
+The default modes are
+.IR "mode pdf" ,
+.IR "mode ps" ,
+.IR "mode html" ,
+.IR "mode x" ,
+and
+.I "mode dvi"
+in \%\f[CR]X\~Window\f[] with different viewers and
+.I mode tty
+with device
+.I latin1
+under
+.B less
+on a terminal; other modes are tested if the programs for the main
+default mode do not exist.
+.
+.
+.P
+In \%\f[CR]X\~Window\f[],
+many programs create their own window when called.
+.B \%groffer
+can run these viewers as an independent program in the background.
+.
+As this does not work in text mode on a terminal (tty) there must be a
+way to know which viewers are \%\f[CR]X\~Window\f[] graphical
+programs.
+.
+The
+.B \%groffer
+script has a small set of information on some viewer names.
+.
+If a viewer argument of the command\-line chooses an element that is
+kept as \%\f[CR]X\~Window\f[] program in this list it is treated as a
+viewer that can run in the background.
+.
+All other, unknown viewer calls are not run in the background.
+.
+.
+.P
+For each mode, you are free to choose whatever viewer you want.
+.
+That need not be some graphical viewer suitable for this mode.
+.
+There is a chance to view the output source; for example, the
+combination of the options
+.B --mode=ps
+and
+.B --ps\-viewer=less
+shows the content of the
+.I Postscript
+output, the source code, with the pager
+.BR less .
+.
+.
+.TP
+.B --auto
+Equivalent to
+.BR --mode=auto .
+.
+.
+.TP
+.B --default
+Reset all configuration from previously processed command line options
+to the default values.
+.
+This is useful to wipe out all former options of the configuration, in
+.Env_var \%$GROFFER_OPT ,
+and restart option processing using only the rest of the command line.
+.
+.
+.TP
+.BI --default\-modes \ mode1,mode2,\*[Ellipsis]
+Set the sequence of modes for
+.I \%auto\~mode
+to the comma separated list given in the argument.
+.
+See
+.B --mode
+for details on modes.  Display in the default manner; actually, this
+means to try the modes
+.IR x ,
+.IR ps ,
+and
+.I \%tty
+in this sequence.
+.
+.
+.
+.TP
+.B --dvi
+Equivalent to
+.BR --mode=\%dvi .
+.
+.
+.TP
+.BI --dvi\-viewer \ prog
+Choose a viewer program for
+.IR \%dvi\~mode .
+.
+This can be a file name or a program to be searched in
+.Env_var $PATH .
+.
+Known \%\f[CR]X\~Window\f[]
+.I \%dvi
+viewers include
+.BR \%xdvi (1)
+and
+.BR \%dvilx (1).
+.
+In each case, arguments can be provided additionally.
+.
+.
+.TP
+.B --groff
+Equivalent to
+.BR --mode=groff .
+.
+.
+.TP
+.B --html
+Equivalent to
+.BR --mode=html .
+.
+.
+.TP
+.B --html\-viewer
+Choose a web browser program for viewing in
+.IR \%html\~mode .
+.
+It can be the path name of an executable file or a program in
+.Env_var $PATH .
+.
+In each case, arguments can be provided additionally.
+.
+.
+.TP
+.BI --mode \ value
+.
+Set the display mode.
+.
+The following mode values are recognized:
+.
+.RS
+.
+.TP
+.Header_CB auto
+Select the automatic determination of the display mode.
+.
+The sequence of modes that are tried can be set with the
+.B --default\-modes
+option.
+.
+Useful for restoring the
+.I \%default\~mode
+when a different mode was specified before.
+.
+.
+.TP
+.Header_CB dvi
+Display formatted input in a
+.I \%dvi
+viewer program.
+.
+By default, the formatted input is displayed with the
+.BR \%xdvi (1)
+program.
+.
+.
+.TP
+.Header_CB groff
+After the file determination, switch
+.B \%groffer
+to process the input like
+.BR \%groff (@MAN1EXT@)
+would do.
+.
+This disables the
+.I \%groffer
+viewing features.
+.
+.
+.TP
+.Header_CB html
+Translate the input into html format and display the result in a web
+browser program.
+.
+By default, the existence of a sequence of standard web browsers is
+tested, starting with
+.BR \%konqueror (1)
+and
+.BR \%mozilla (1).
+The text html viewer is
+.BR \%lynx (1).
+.
+.
+.TP
+.Header_CB pdf
+Display formatted input in a
+.I \%PDF
+(Portable Document Format) viewer
+program.
+.
+By default, the input is formatted by
+.B \%groff
+using the Postscript device, then it is transformed into the PDF file
+format using
+.BR \%gs (1),
+or
+.BR ps2pdf (1).
+If that's not possible, the
+.I Postscript mode (ps)
+is used instead.
+.
+Finally it is displayed using different viewer programs.
+.
+.I \%pdf
+has a big advantage because the text is displayed graphically and
+is searchable as well.
+.
+.
+.TP
+.Header_CB ps
+Display formatted input in a Postscript viewer program.
+.
+By default, the formatted input is displayed in one of many viewer
+programs.
+.
+.
+.TP
+.Header_CB text
+Format in a
+.I \%groff\~text\~mode
+and write the result to standard output without a pager or viewer
+program.
+.
+The text device,
+.I \%latin1
+by default, can be chosen with option
+.BR -T .
+.
+.
+.TP
+.Header_CB tty
+Format in a
+.I \%groff\~text\~mode
+and write the result to standard output using a text pager program,
+even when in \%\f[CR]X\~Window\f[].
+.
+.
+.TP
+.Header_CB www
+Equivalent to
+.BR --mode=html .
+.
+.
+.TP
+.Header_CB x
+Display the formatted input in a native
+.I roff
+viewer.
+.
+By default, the formatted input is displayed with the
+.BR \%gxditview (@MAN1EXT@)
+program being distributed together with
+.BR \%groff .
+But the standard \%\f[CR]X\~Window\f[] tool
+.BR \%xditview (1)
+can also be chosen with the option
+.BR --x\-viewer .
+The default resolution is
+.BR 75dpi ,
+but
+.B 100dpi
+are also possible.
+.
+The default
+.I groff
+device
+for the resolution of
+.B 75dpi
+is
+.BR X75\-12 ,
+for
+.B 100dpi
+it is
+.BR X100 .
+.
+The corresponding
+.I "groff intermediate output"
+for the actual device is generated and the result is displayed.
+.
+For a resolution of
+.BR 100dpi ,
+the default width of the geometry of the display program is chosen to
+.BR 850dpi .
+.
+.
+.TP
+.Header_CB X
+Equivalent to
+.BR --mode=x .
+.
+.
+.P
+The following modes do not use the
+.I \%groffer
+viewing features.
+.
+They are only interesting for advanced applications.
+.
+.
+.TP
+.Header_CB groff
+Generate device output with plain
+.I \%groff
+without using the special viewing features of
+.IR \%groffer .
+If no device was specified by option
+.B -T
+the
+.I \%groff
+default
+.B \%ps
+is assumed.
+.
+.
+.TP
+.Header_CB source
+Output the roff source code of the input files without further
+processing.
+.
+.
+.RE
+.
+.
+.TP
+.B --pdf
+Equivalent to
+.BR --mode=pdf .
+.
+.
+.TP
+.BI --pdf\-viewer \ prog
+Choose a viewer program for
+.IR \%pdf\~mode .
+.
+This can be a file name or a program to be searched in
+.Env_var $PATH ;
+arguments can be provided additionally.
+.
+.
+.TP
+.B --ps
+Equivalent to
+.BR --mode=ps .
+.
+.
+.TP
+.BI --ps\-viewer \ prog
+Choose a viewer program for
+.IR \%ps\~mode .
+.
+This can be a file name or a program to be searched in
+.Env_var $PATH .
+.
+Common Postscript viewers include
+.BR \%gv (1),
+.BR \%ghostview (1),
+and
+.BR \%gs (1),
+.
+In each case, arguments can be provided additionally.
+.
+.
+.TP
+.B --source
+Equivalent to
+.BR --mode=source .
+.
+.
+.TP
+.B --text
+Equivalent to
+.BR --mode=text .
+.
+.
+.TP
+.B --to\-stdout
+The file for the chosen mode is generated and its content is printed
+to standard output.
+.
+It will not be displayed in graphical mode.
+.
+.
+.TP
+.B --tty
+Equivalent to
+.BR --mode=tty .
+.
+.
+.TP
+.BI --tty\-viewer \ prog
+Choose a text pager for mode
+.IR tty .
+The standard pager is
+.BR less (1).
+This option is equivalent to
+.I man
+option
+.BR --pager=\fIprog\fP .
+The option argument can be a file name or a program to be searched in
+.Env_var $PATH ;
+arguments can be provided additionally.
+.
+.
+.TP
+.B --www
+Equivalent to
+.BR --mode=html .
+.
+.
+.TP
+.BI --www\-viewer \ prog
+Equivalent to
+.BR --html\-viewer .
+.
+.
+.TP
+.B --X\~\fR|\fB\~--x
+Equivalent to
+.BR --mode=x .
+.
+.
+.TP
+.BI --X\-viewer\~\fR|\fB\~--x\-viewer \ prog
+Choose a viewer program for
+.IR \%x\~mode .
+Suitable viewer programs are
+.BR \%gxditview (@MAN1EXT@)
+which is the default and
+.BR \%xditview (1).
+The argument can be any executable file or a program in
+.Env_var $PATH ;
+arguments can be provided additionally.
+.
+.
+.TP
+.B --
+Signals the end of option processing; all remaining arguments are
+interpreted as
+.I \%filespec
+parameters.
+.
+.
+.P
+Besides these,
+.B \%groffer
+accepts all short options that are valid for the
+.BR \%groff (@MAN1EXT@)
+program.
+.
+All
+.RB \%non- groffer
+options are sent unmodified via
+.B \%grog
+to
+.BR \%groff .
+.
+So postprocessors, macro packages, compatibility with
+.I classical
+.IR \%troff ,
+and much more can be manually specified.
+.
+.
+.\" --------------------------------------------------------------------
+.SS "Options related to groff"
+.\" --------------------------------------------------------------------
+.
+All short options of
+.B \%groffer
+are compatible with the short options of
+.BR \%groff (@MAN1EXT@).
+.
+The following of
+.B \%groff
+options have either an additional special meaning within
+.B \%groffer
+or make sense for normal usage.
+.
+.
+.P
+Because of the special outputting behavior of the
+.B \%groff
+option
+.B -Z
+.B \%groffer
+was designed to be switched into
+.IR \%groff\~mode ;
+the
+.I \%groffer
+viewing features are disabled there.
+.
+The other
+.B \%groff
+options do not switch the mode, but allow to customize the formatting
+process.
+.
+.
+.TP
+.B --a
+This generates an ascii approximation of output in the
+.IR \%text\~modes .
+.
+That could be important when the text pager has problems with control
+sequences in
+.IR "tty mode" .
+.
+.
+.TP
+.BI --m \ file
+Add
+.I \%file
+as a
+.I \%groff
+macro file.
+.
+This is useful in case it cannot be recognized automatically.
+.
+.
+.TP
+.BI --P \ opt_or_arg
+Send the argument
+.I \%opt_or_arg
+as an option or option argument to the actual
+.B \%groff
+postprocessor.
+.
+.
+.TP
+.B --T \fIdevname\fR\~\fR|\fB\~--device \fIdevname\fR
+.
+This option determines
+.BR \%groff 's
+output device.
+.
+The most important devices are the text output devices for referring
+to the different character sets, such as
+.BR \%ascii ,
+.BR \%utf8 ,
+.BR \%latin1 ,
+and others.
+.
+Each of these arguments switches
+.B \%groffer
+into a
+.I \%text\~mode
+using this device, to
+.I \%mode\~tty
+if the actual mode is not a
+.IR \%text\~mode .
+.
+The following
+.I \%devname
+arguments are mapped to the corresponding
+.B \%groffer
+.B --mode=\fIdevname\fR
+option:
+.BR \%dvi ,
+.BR \%html ,
+and
+.BR \%ps .
+All
+.B \%X*
+arguments are mapped to
+.IR \%mode\~x .
+Each other
+.I \%devname
+argument switches to
+.I \%mode\~groff
+using this device.
+.
+.
+.TP
+.B --X
+is equivalent to
+.BR "groff \-X" .
+It displays the
+.I groff intermediate output
+with
+.BR gxditview .
+As the quality is relatively bad this option is deprecated; use
+.B --X
+instead because the
+.I \%x\~mode
+uses an
+.IR X *
+device for a better display.
+.
+.
+.TP
+.B -Z\~\fR|\fB\~--intermediate-output\~\fR|\fB\~--ditroff
+Switch into
+.I \%groff\~mode
+and format the input with the
+.I \%groff intermediate output
+without postprocessing; see
+.BR \%groff_out (@MAN5EXT@).
+This is equivalent to option
+.B --ditroff
+of
+.IR \%man ,
+which can be used as well.
+.
+.
+.P
+All other
+.B \%groff
+options are supported by
+.BR \%groffer ,
+but they are just transparently transferred to
+.B \%groff
+without any intervention.
+.
+The options that are not explicitly handled by
+.B \%groffer
+are transparently passed to
+.BR \%groff .
+.
+Therefore these transparent options are not documented here, but in
+.BR \%groff (@MAN1EXT@).
+Due to the automatism in
+.BR \%groffer ,
+none of these
+.B \%groff
+options should be needed, except for advanced usage.
+.
+.
+.\" --------------------------------------------------------------------
+.SS "Options for man\~pages"
+.\" --------------------------------------------------------------------
+.
+.TP
+.B --apropos
+Start the
+.BR \%apropos (1)
+command or facility of
+.BR \%man (1)
+for searching the
+.I \%filespec
+arguments within all
+.I \%man\~page
+descriptions.
+.
+Each
+.I \%filespec
+argument is taken for search as it is;
+.I section
+specific parts are not handled, such that
+.B 7 groff
+searches for the two arguments
+.B 7
+and
+.BR groff ,
+with a large result; for the
+.I \%filespec
+.B groff.7
+nothing will be found.
+.
+The
+.I language
+locale is handled only when the called programs do support this; the
+GNU
+.B apropos
+and
+.B man \-k
+do not.
+.
+The display differs from the
+.B \%apropos
+program by the following concepts:
+.RS
+.Topic
+Construct a
+.I \%groff
+frame similar to a
+.I \%man\~page
+to the output of
+.BR \%apropos ,
+.Topic
+each
+.I \%filespec
+argument is searched on its own.
+.Topic
+The restriction by
+.B --sections
+is handled as well,
+.Topic
+wildcard characters are allowed and handled without a further option.
+.RE
+.
+.
+.TP
+.B --apropos\-data
+Show only the
+.B \%apropos
+descriptions for data documents, these are the
+.BR \%man (7)
+.IR sections\~4 ", " 5 ", and " 7 .
+.
+Direct
+.I section
+declarations are ignored, wildcards are accepted.
+.
+.
+.TP
+.B --apropos\-devel
+Show only the
+.B \%apropos
+descriptions for development documents, these are the
+.BR man (7)
+.IR sections\~2 ", " 3 ", and " 9 .
+.
+Direct
+.I section
+declarations are ignored, wildcards are accepted.
+.
+.
+.TP
+.B --apropos\-progs
+Show only the
+.B \%apropos
+descriptions for documents on programs, these are the
+.BR \%man (7)
+.IR sections\~1 ", " 6 ", and " 8 .
+.
+Direct
+.I section
+declarations are ignored, wildcards are accepted.
+.
+.
+.TP
+.B --whatis
+For each
+.I \%filespec
+argument search all
+.I \%man\~pages
+and display their description \[em] or say that it is not a
+.IR \%man\~page .
+This is written from anew, so it differs from
+.IR man 's
+.B whatis
+output by the following concepts
+.RS
+.Topic
+each retrieved file name is added,
+.Topic
+local files are handled as well,
+.Topic
+the \fIlanguage\fP and \fIsystem\fP locale is supported,
+.Topic
+the display is framed by a
+.I groff
+output format similar to a
+.IR \%man\~page ,
+.Topic
+wildcard characters are allowed without a further option.
+.RE
+.
+.
+.P
+The following options were added to
+.B \%groffer
+for choosing whether the file name arguments are interpreted as names
+for local files or as a search pattern for
+.IR \%man\~pages .
+.
+The default is looking up for local files.
+.
+.
+.TP
+.B --man
+Check the non-option command line arguments
+.nh
+.RI ( filespecs )
+.hy
+first on being
+.IR \%man\~pages ,
+then whether they represent an existing file.
+.
+By default, a
+.I \%filespec
+is first tested whether it is an existing file.
+.
+.
+.TP
+.B --no-man\~\fR|\fB\~--local-file
+Do not check for
+.IR \%man\~pages .
+.
+.B --local-file
+is the corresponding
+.B man
+option.
+.
+.
+.TP
+.B --no-special
+Disable former calls of
+.BR --all ,
+.BR --apropos* ,
+and
+.BR --whatis .
+.
+.
+.\" --------------------------------------------------------------------
+.SS "Long options taken over from GNU man"
+.\" --------------------------------------------------------------------
+.
+The long options of
+.B \%groffer
+were synchronized with the long options of \f[CR]GNU\f[]
+.BR man .
+.
+All long options of \f[CR]GNU\f[]
+.B man
+are recognized, but not all of these options are important to
+.BR \%groffer ,
+so most of them are just ignored.
+.
+These ignored
+.B man
+options are
+.BR --catman ,
+.BR --troff ,
+and
+.BR --update .
+.
+.
+.P
+In the following, the
+.B man
+options that have a special meaning for
+.B \%groffer
+are documented.
+.
+.
+.P
+If your system has \f[CR]GNU\f[]
+.B man
+installed the full set of long and short options of the \f[CR]GNU\f[]
+.B man
+program can be passed via the environment variable
+.Env_var \%$MANOPT ;
+see
+.BR \%man (1).
+.
+.
+.TP
+.B --all
+In searching
+.IR \%man\~pages ,
+retrieve all suitable documents instead of only one.
+.
+.
+.TP
+.B -7\~\fR|\fB\~--ascii
+In
+.IR \%text\~modes ,
+display ASCII translation of special characters for critical environment.
+.
+This is equivalent to
+.BR "groff \%-mtty_char" ;
+see
+.BR groff_tmac (@MAN5EXT@).
+.
+.
+.TP
+.B --ditroff
+Produce
+.IR "groff intermediate output" .
+This is equivalent to
+.B \%groffer
+.BR -Z .
+.
+.
+.TP
+.BI --extension \ suffix
+Restrict
+.I \%man\~page
+search to file names that have
+.I \%suffix
+appended to their section element.
+.
+For example, in the file name
+.I \%/usr/share/man/man3/terminfo.3ncurses.gz
+the
+.I \%man\~page
+extension is
+.IR \%ncurses .
+.
+.
+.TP
+.BI --locale \ language
+.
+Set the language for
+.IR \%man\~pages .
+.
+This has the same effect, but overwrites
+.Env_var $LANG .
+.
+.
+.TP
+.B --location
+Print the location of the retrieved files to standard error.
+.
+.
+.TP
+.B --no-location
+Do not display the location of retrieved files; this resets a former
+call to
+.BR --location .
+.
+This was added by
+.BR \%groffer .
+.
+.
+.TP
+.BI --manpath \ 'dir1:dir2:\*[Ellipsis]'
+Use the specified search path for retrieving
+.I \%man\~pages
+instead of the program defaults.
+.
+If the argument is set to the empty string "" the search for
+.I \%man\~page
+is disabled.
+.
+.
+.TP
+.B --pager
+Set the pager program in
+.IR \%tty\~mode ;
+default is
+.BR \%less .
+This is equivalent to
+.BR --tty\-viewer .
+.
+.
+.TP
+.BI --sections \ sec1:sec2:\*[Ellipsis]
+Restrict searching for
+.I \%man\~pages
+to the given
+.IR sections ,
+a colon-separated list.
+.
+.
+.TP
+.BI --systems \ sys1,sys2,\*[Ellipsis]
+Search for
+.I \%man\~pages
+for the given operating systems; the argument
+.I \%systems
+is a comma-separated list.
+.
+.
+.TP
+.B --where
+Equivalent to
+.BR --location .
+.
+.
+.\" --------------------------------------------------------------------
+.SS "X\~\%Window\~\%Toolkit Options"
+.\" --------------------------------------------------------------------
+.
+The following long options were adapted from the corresponding
+\%\f[CR]X\~Window\~Toolkit\f[] options.
+.
+.B \%groffer
+will pass them to the actual viewer program if it is an
+\%\f[CR]X\~Window\f[] program.
+.
+Otherwise these options are ignored.
+.
+.
+.P
+Unfortunately these options use the old style of a single minus for
+long options.
+.
+For
+.B \%groffer
+that was changed to the standard with using a double minus for long
+options, for example,
+.B \%groffer
+uses the option
+.B --font
+for the \%\f[CR]X\~Window\f[] option
+.BR -font .
+.
+.
+.P
+See
+.BR X (7)
+and the documentation on the \%\f[CR]X\~Window\~Toolkit\f[] options
+for more details on these options and their arguments.
+.
+.
+.TP
+.BI --background \ color
+Set the background color of the viewer window.
+.
+.
+.TP
+.BI --bd \ pixels
+This is equivalent to
+.BR --bordercolor .
+.
+.
+.TP
+.BI --bg \ color
+This is equivalent to
+.BR --background .
+.
+.
+.TP
+.BI --bw \ pixels
+This is equivalent to
+.BR --borderwidth .
+.
+.
+.TP
+.BI --bordercolor \ pixels
+Specifies the color of the border surrounding the viewer window.
+.
+.
+.TP
+.BI --borderwidth \ pixels
+Specifies the width in pixels of the border surrounding the viewer
+window.
+.
+.
+.TP
+.BI --display \ X-display
+Set the \%\f[CR]X\~Window\f[] display on which the viewer program
+shall be started, see the \%\f[CR]X\~Window\f[] documentation for the
+syntax of the argument.
+.
+.
+.TP
+.BI --foreground \ color
+Set the foreground color of the viewer window.
+.
+.
+.TP
+.BI --fg \ color
+This is equivalent to
+.BR -foreground .
+.
+.
+.TP
+.BI --fn \ font_name
+This is equivalent to
+.BR --font .
+.
+.
+.TP
+.BI --font \ font_name
+Set the font used by the viewer window.
+.
+The argument is an \%\f[CR]X\~Window\f[] font name.
+.
+.
+.TP
+.BI --ft \ font_name
+This is equivalent to
+.BR --font .
+.
+.
+.TP
+.BI --geometry \ size_pos
+Set the geometry of the display window, that means its size and its
+starting position.
+.
+See
+.BR \%X (7)
+for the syntax of the argument.
+.
+.
+.TP
+.BI --resolution \ value
+Set \%\f[CR]X\~Window\f[] resolution in dpi (dots per inch) in some
+viewer programs.
+.
+The only supported dpi values are
+.B 75
+and
+.BR 100 .
+.
+Actually, the default resolution for
+.B \%groffer
+is set to
+.BR 75dpi .
+The resolution also sets the default device in
+.IR "mode x" .
+.
+.
+.TP
+.B --rv
+Reverse foreground and background color of the viewer window.
+.
+.
+.TP
+.BI --title "\ 'some text'"
+Set the title for the viewer window.
+.
+.
+.TP
+.BI --xrm \ 'resource'
+Set \f[CR]\%X\~Window\f[] resource.
+.
+.
+.\" --------------------------------------------------------------------
+.SS "Options for Development"
+.\" --------------------------------------------------------------------
+.
+.TP
+.B --debug
+Enable all debugging options
+.BR --debug\-\fItype\fP .
+.
+The temporary files are kept and not deleted, the
+.B grog
+output is printed, the name of the temporary directory is printed, the
+displayed file names are printed, and the parameters are printed.
+.
+.
+.TP
+.B --debug\-filenames
+Print the names of the files and
+.I \%man\~pages
+that are displayed by
+.BR \&groffer .
+.
+.
+.TP
+.B --debug\-grog
+Print the output of all
+.B grog
+commands.
+.
+.
+.TP
+.B --debug\-keep
+Enable two debugging informations.
+.
+Print the name of the temporary directory and keep the temporary
+files, do not delete them during the run of
+.BR \%groffer .
+.
+.
+.TP
+.B --debug\-params
+Print the parameters, as obtained from the configuration files, from
+.Env_var \%GROFFER_OPT ,
+and the command line arguments.
+.
+.
+.TP
+.B --debug\-tmpdir
+Print the name of the temporary directory.
+.
+.
+.TP
+.B --do-nothing
+This is like
+.BR --version ,
+but without the output; no viewer is started.
+.
+This makes only sense in development.
+.
+.
+.TP
+.B --print=\fItext\fR
+Just print the argument to standard error.
+.
+This is good for parameter check.
+.
+.
+.TP 
+.B -V
+This is an advanced option for debugging only.
+.
+Instead of displaying the formatted input, a lot of
+.I \%groffer
+specific information is printed to standard output:
+.
+.RS
+.Topic
+the output file name in the temporary directory,
+.
+.Topic
+the display mode of the actual
+.B \%groffer
+run,
+.
+.Topic
+the display program for viewing the output with its arguments,
+.
+.Topic
+the active parameters from the config files, the arguments in
+.Env_var \%$GROFFER_OPT ,
+and the arguments of the command line,
+.
+.Topic
+the pipeline that would be run by the
+.B \%groff
+program, but without executing it.
+.RE
+.
+.
+.P
+Other useful debugging options are the
+.B \%groff
+option
+.B -Z
+and
+.BR --mode=groff .
+.
+.
+.\" --------------------------------------------------------------------
+.SS "Filespec Arguments"
+.\" --------------------------------------------------------------------
+.
+A
+.I \%filespec
+parameter is an argument that is not an option or option argument.
+.
+In
+.BR \%groffer ,
+.I \%filespec
+parameters are a file name or a template for searching
+.IR \%man\~pages .
+.
+These input sources are collected and composed into a single output
+file such as
+.B \%groff
+does.
+.
+.
+.P
+The strange \%\f[CR]POSIX\f[] behavior to regard all arguments behind
+the first non-option argument as
+.I \%filespec
+arguments is ignored.
+.
+The \f[CR]GNU\f[] behavior to recognize options even when mixed with
+.I \%filespec
+arguments is used throughout.
+.
+But, as usual, the double minus argument
+.B --
+ends the option handling and interprets all following arguments as
+.I \%filespec
+arguments; so the \%\f[CR]POSIX\f[] behavior can be easily adopted.
+.
+.
+.P
+The options
+.B --apropos*
+have a special handling of
+.I filespec
+arguments.
+.
+Each argument is taken as a search scheme of its own.
+.
+Also a regexp (regular expression) can be used in the filespec.
+.
+For example,
+.B groffer --apropos '^gro.f$'
+searches
+.B groff
+in the
+.I man\~page
+name, while
+.B groffer --apropos groff
+searches
+.B groff
+somewhere in the name or description of the
+.IR man\~pages .
+.
+.
+.P
+All other parts of
+.IR groffer ,
+such as the normal display or the output with
+.B --whatis
+have a different scheme for
+.IR filespecs .
+No regular expressions are used for the arguments.
+.
+The
+.I filespec
+arguments are handled by the following scheme.
+.
+.
+.P
+It is necessary to know that on each system the
+.I \%man\~pages
+are sorted according to their content into several sections.
+.
+The
+.I classical man sections
+have a single-character name, either a digit from
+.B 1
+to
+.B 9
+or one of the characters
+.B n
+or
+.BR o .
+.
+.
+.P
+This can optionally be followed by a string, the so-called
+.IR extension .
+The
+.I extension
+allows to store several
+.I man\~pages
+with the same name in the same
+.IR section .
+But the
+.I extension
+is only rarely used, usually it is omitted.
+.
+Then the
+.I extensions
+are searched automatically by alphabet.
+.
+.
+.P
+In the following, we use the name
+.I section_extension
+for a word that consists of a single character
+.I section
+name or a
+.I section
+character that is followed by an
+.IR extension .
+.
+Each
+.I \%filespec
+parameter can have one of the following forms in decreasing sequence.
+.
+.
+.Topic
+No
+.I \%filespec
+parameters means that
+.B \%groffer
+waits for standard input.
+.
+The minus option
+.B -
+always stands for standard input; it can occur several times.
+.
+If you want to look up a
+.I \%man\~page
+called
+.B -
+use the argument
+.BR man:\- .
+.
+.
+.Topic
+Next a
+.I \%filespec
+is tested whether it is the path name of an existing file.
+.
+Otherwise it is assumed to be a searching pattern for a
+.IR \%man\~page .
+.
+.
+.Topic
+.BI \%man: name ( section_extension ) ,
+.BI \%man: name . section_extension,
+.IB \%name ( section_extension ) ,
+or
+.IB \%name . section_extension
+search the \%man\~page
+.I \%name
+in \%man\~section and possibly extension of
+.IR \%section_extension .
+.
+.
+.Topic
+Now
+.BI \%man: name
+searches for a
+.I \%man\~page
+in the lowest
+.I \%man\~section
+that has a document called
+.IR \%name .
+.
+.
+.Topic
+.I \%section_extension\~name
+is a pattern of 2 arguments that originates from a strange argument
+parsing of the
+.B man
+program.
+.
+Again, this searches the man page
+.I name
+with
+.IR \%section_extension ,
+a combination of a
+.I section
+character optionally followed by an
+.IR extension .
+.
+.
+.Topic
+We are left with the argument
+.I \%name
+which is not an existing file.
+.
+So this searches for the
+.I \%man\~page
+called
+.I \%name
+in the lowest
+.I \%man\~section
+that has a document for this name.
+.
+.
+.P
+Several file name arguments can be supplied.
+.
+They are mixed by
+.B \%groff
+into a single document.
+.
+Note that the set of option arguments must fit to all of these file
+arguments.
+.
+So they should have at least the same style of the
+.I \%groff
+language.
+.
+.
+.\" --------------------------------------------------------------------
+.SH "OUTPUT MODES"
+.\" --------------------------------------------------------------------
+.
+By default, the
+.B \%groffer
+program collects all input into a single file, formats it with the
+.B \%groff
+program for a certain device, and then chooses a suitable viewer
+program.
+.
+The device and viewer process in
+.B \%groffer
+is called a
+.IR \%mode .
+.
+The mode and viewer of a running
+.B \%groffer
+program is selected automatically, but the user can also choose it
+with options.
+.
+.
+The modes are selected by option the arguments of
+.BR --mode=\fIanymode .
+Additionally, each of this argument can be specified as an option of
+its own, such as
+.BR anymode .
+Most of these modes have a viewer program, which can be chosen by an
+option that is constructed like
+.BR --\fIanymode\fR\-viewer .
+.
+.
+.P
+Several different modes are offered, graphical modes for
+\f[CR]\%X\~Window\f[],
+.IR \%text\~modes ,
+and some direct
+.I \%groff\~modes
+for debugging and development.
+.
+.
+.P
+By default,
+.B \%groffer
+first tries whether
+.I \%x\~mode
+is possible, then
+.IR \%ps\~mode ,
+and finally
+.IR \%tty\~mode .
+.
+This mode testing sequence for
+.I \%auto\~mode
+can be changed by specifying a comma separated list of modes with the
+option
+.B --default\-modes.
+.
+.
+.P
+The searching for
+.I \%man\~pages
+and the decompression of the input are active in every mode.
+.
+.
+.\" --------------------------------------------------------------------
+.SS "Graphical Display Modes"
+.\" --------------------------------------------------------------------
+.
+The graphical display modes work mostly in the \%\f[CR]X\~Window\f[]
+environment (or similar implementations within other windowing
+environments).
+.
+The environment variable
+.Env_var \%$DISPLAY
+and the option
+.B --display
+are used for specifying the \%\f[CR]X\~Window\f[] display to be used.
+.
+If this environment variable is empty
+.B \%groffer
+assumes that no \%\f[CR]X\~Window\f[] is running and changes to a
+.IR \%text\~mode .
+.
+You can change this automatic behavior by the option
+.BR --default\-modes .
+.
+.
+.P
+Known viewers for the graphical display modes and their standard
+\%\f[CR]X\~Window\f[] viewer programs are
+.
+.Topic
+in a PDF viewer
+.nh
+.RI ( \%pdf\~mode )
+.hy
+.
+.Topic
+in a web browser
+.nh
+.RI ( html
+or
+.IR \%www\~mode )
+.hy
+.RE
+.
+.Topic
+in a Postscript viewer
+.nh
+.RI ( \%ps\~mode )
+.hy
+.
+.Topic
+\%\f[CR]X\~Window\f[]
+.I roff
+viewers such as
+.BR \%gxditview (@MAN1EXT@)
+or
+.BR \%xditview (1)
+(in
+.IR \%x\~mode )
+.
+.Topic
+in a dvi viewer program
+.nh
+.RI ( \%dvi\~mode )
+.hy
+.
+.
+.P
+The
+.I \%pdf\~mode
+has a major advantage \[em] it is the only graphical display mode that
+allows to search for text within the viewer; this can be a really
+important feature.
+.
+Unfortunately, it takes some time to transform the input into the PDF
+format, so it was not chosen as the major mode.
+.
+.
+.P
+These graphical viewers can be customized by options of the
+\%\f[CR]X\~Window\~Toolkit\f[].
+.
+But the
+.B \%groffer
+options use a leading double minus instead of the single minus used by
+the \%\f[CR]X\~Window\~Toolkit\f[].
+.
+.
+.\" --------------------------------------------------------------------
+.SS "Text modes"
+.\" --------------------------------------------------------------------
+.
+There are two modes for text output,
+.I \%mode\~text
+for plain output without a pager and
+.I \%mode\~tty
+for a text output on a text terminal using some pager program.
+.
+.
+.P
+If the variable
+.Env_var \%$DISPLAY
+is not set or empty,
+.B \%groffer
+assumes that it should use
+.IR \%tty\~\%mode .
+.
+.
+.P
+In the actual implementation, the
+.I groff
+output device
+.I \%latin1
+is chosen for
+.IR \%text\~modes .
+.
+This can be changed by specifying option
+.B -T
+or
+.BR \%--device .
+.
+.
+.P
+The pager to be used can be specified by one of the options
+.B --pager
+and
+.BR --tty\-viewer ,
+or by the environment variable
+.Env_var \%$PAGER .
+If all of this is not used the
+.BR \%less (1)
+program with the option
+.B -r
+for correctly displaying control sequences is used as the default
+pager.
+.
+.
+.\" --------------------------------------------------------------------
+.SS "Special Modes for Debugging and Development"
+.\" --------------------------------------------------------------------
+.
+These modes use the
+.I \%groffer
+file determination and decompression.
+.
+This is combined into a single input file that is fed directly into
+.B \%groff
+with different strategy without the
+.I \%groffer
+viewing facilities.
+.
+These modes are regarded as advanced, they are useful for debugging
+and development purposes.
+.
+.
+.P
+The
+.I \%source\~mode
+with option
+.B --source
+just displays the decompressed input.
+.
+.
+.P
+Otion
+.B --to\-stdout
+does not display in a graphical mode.
+.
+It just generates the file for the chosen mode and then prints its
+content to standard output.
+.
+.
+.P
+The
+.I \%groff\~mode
+passes the input to
+.B \%groff
+using only some suitable options provided to
+.BR \%groffer .
+.
+This enables the user to save the generated output into a file or pipe
+it into another program.
+.
+.
+.P
+In
+.IR \%groff\~\%mode ,
+the option
+.B -Z
+disables post-processing, thus producing the
+.nh
+.I groff intermediate
+.IR output .
+.hy
+.
+In this mode, the input is formatted, but not postprocessed; see
+.BR \%groff_out (@MAN5EXT@)
+for details.
+.
+.
+.P
+All
+.B \%groff
+short options are supported by
+.BR \%groffer .
+.
+.
+.\" --------------------------------------------------------------------
+.SH "MAN PAGE SEARCHING"
+.\" --------------------------------------------------------------------
+.
+The default behavior of
+.B \%groffer
+is to first test whether a file parameter represents a local file; if
+it is not an existing file name, it is assumed to represent the name
+of a
+.IR \%man\~page .
+The following options can be used to determine whether the arguments
+should be handled as file name or
+.I \%man\~page
+arguments.
+.
+.TP
+.B --man
+forces to interpret all file parameters as
+.I \%filespecs
+for searching
+.IR \%man\~pages .
+.
+.TP
+.B --no\-man
+.TQ
+.B --local\-file
+disable the
+.I man
+searching; so only local files are displayed.
+.
+.
+.P
+If neither a local file nor a
+.I \%man\~page
+was retrieved for some file parameter a warning is issued on standard
+error, but processing is continued.
+.
+.
+.\" --------------------------------------------------------------------
+.SS "Search Algorithm"
+.\" --------------------------------------------------------------------
+.
+Let us now assume that a
+.I \%man\~page
+should be searched.
+.
+The
+.B \%groffer
+program provides a search facility for
+.IR \%man\~pages .
+.
+All long options, all environment variables, and most of the
+functionality of the \f[CR]GNU\fP
+.BR \%man (1)
+program were implemented.
+.
+The search algorithm shall determine which file is displayed for a given
+.IR \%man\~page .
+The process can be modified by options and environment variables.
+.
+.
+.P
+The only
+.I man
+action that is omitted in
+.B \%groffer
+are the preformatted
+.IR \%man\~pages ,
+also called
+.IR cat\~pages .
+.
+With the excellent performance of the actual computers, the
+preformatted
+.I \%man\~pages
+aren't necessary any longer.
+.
+Additionally,
+.B \%groffer
+is a
+.I roff
+program; it wants to read
+.I roff
+source files and format them itself.
+.
+.
+.P
+The algorithm for retrieving the file for a
+.I \%man\~page
+needs first a set of directories.
+.
+This set starts with the so-called
+.I man\~path
+that is modified later on by adding names of
+.I operating system
+and
+.IR language .
+.
+This arising set is used for adding the section directories which
+contain the
+.I \%man\~page
+files.
+.
+.
+.P
+The
+.I man\~path
+is a list of directories that are separated by colon.
+.
+It is generated by the following methods.
+.
+.Topic
+The environment variable
+.Env_var \%$MANPATH
+can be set.
+.
+.Topic
+It can be read from the arguments of the environment variable
+.Env_var \%$MANOPT .
+.
+.Topic
+The
+.I man\~path
+can be manually specified by using the option
+.BR --manpath .
+An empty argument disables the
+.I \%man\~page
+searching.
+.
+.Topic
+When no
+.I man\~path
+was set the
+.BR \%manpath (1)
+program is tried to determine one.
+.
+.Topic
+If this does not work a reasonable default path from
+.Env_var $PATH
+is determined.
+.
+.
+.P
+We now have a starting set of directories.
+.
+The first way to change this set is by adding names of
+.I operating
+.IR systems .
+.
+This assumes that
+.I \%man\~pages
+for several
+.I operating systems
+are installed.
+.
+This is not always true.
+.
+The names of such
+.I operating systems
+can be provided by 3 methods.
+.
+.Topic
+The environment variable
+.Env_var \%$SYSTEM
+has the lowest precedence.
+.
+.Topic
+This can be overridden by an option in
+.Env_var \%$MANOPT .
+.
+.Topic
+This again is overridden by the command line option
+.BR --systems .
+.
+.
+.P
+Several names of
+.I operating systems
+can be given by appending their names, separated by a comma.
+.
+.
+.P
+The
+.I man\~path
+is changed by appending each
+.I system
+name as subdirectory at the end of each directory of the set.
+.
+No directory of the
+.I man\~path
+set is kept.
+.
+But if no
+.I system
+name is specified the
+.I man\~path
+is left unchanged.
+.
+.
+.P
+After this, the actual set of directories can be changed by
+.I language
+information.
+.
+This assumes that there exist
+.I man\~pages
+in different languages.
+.
+The wanted
+.I language
+can be chosen by several methods.
+.
+.Topic
+Environment variable
+.Env_var $LANG .
+.
+.Topic
+This is overridden by
+.Env_var \%$LC_MESSAGES .
+.
+.Topic
+This is overridden by
+.Env_var $LC_ALL .
+.
+.Topic
+This can be overridden by providing an option in
+.Env_var \%$MANOPT .
+.
+.Topic
+All these environment variables are overridden by the command line
+option
+.BR --locale .
+.
+.
+.P
+The
+.I default language
+can be specified by specifying one of the pseudo-language parameters
+\f[CR]C\fP or \f[CR]\%POSIX\fP.
+.
+This is like deleting a formerly given
+.I language
+information.
+.
+The
+.I \%man\~pages
+in the
+.I default language
+are usually in English.
+.
+.
+.P
+Of course, the
+.I language
+name is determined by
+.BR man .
+In \f[CR]GNU\fP
+.BR man ,
+it is specified in the \%\f[CR]POSIX\~1003.1\fP based format:
+.P
+.nh
+\f[I]<language>\f[][\f[CB]_\f[]\f[I]<territory>\f[][\f[CB].\fP\
+\f[I]<character-set>\f[][\f[CB],\fP\f[I]<version>\fP]]],
+.hy
+.P
+but the two-letter code in
+.nh
+.I <language>
+.hy
+is sufficient for most purposes.
+.
+If for a complicated
+.I language
+formulation no
+.I \%man\~pages
+are found
+.B \%groffer
+searches the country part consisting of these first two characters as
+well.
+.
+.
+.P
+The actual directory set is copied thrice.
+.
+The
+.I language
+name is appended as subdirectory to each directory in the first copy
+of the actual directory set (this is only done when a language
+information is given).
+.
+Then the 2-letter abbreviation of the
+.I language
+name is appended as subdirectories to the second copy of the directory
+set (this is only done when the given language name has more than 2
+letters).
+.
+The third copy of the directory set is kept unchanged (if no
+.I language
+information is given this is the kept directory set).
+.
+These maximally 3 copies are appended to get the new directory set.
+.
+.
+.P
+We now have a complete set of directories to work with.
+.
+In each of these directories, the
+.I man
+files are separated in
+.IR sections .
+.
+The name of a
+.I section
+is represented by a single character, a digit between
+.I 1
+and
+.IR 9 ,
+or the character
+.I o
+or
+.IR n ,
+in this order.
+.
+.
+.P
+For each available
+.IR section ,
+a subdirectory
+.File_name man \fI<section>\fP
+exists containing all
+.I man
+files for this
+.IR section ,
+where
+.I <section>
+is a single character as described before.
+.
+Each
+.I man
+file in a
+.I section
+directory has the form
+.IR \%\f[CB]man\fP<section>\f[CB]/\fP<name>\f[CB].\fP<section>\
+[<extension>][\f[CB].\fP<compression>] ,
+where
+.I \%<extension>
+and
+.I \%<compression>
+are optional.
+.
+.I \%<name>
+is the name of the
+.I \%man\~page
+that is also specified as filespec argument on the command line.
+.
+.
+.P
+The
+.I extension
+is an addition to the section.
+.
+This postfix acts like a subsection.
+.
+An
+.I extension
+occurs only in the file name, not in name of the
+.I section
+subdirectory.
+.
+It can be specified on the command line.
+.
+.
+.P
+On the other hand, the
+.I compression
+is just an information on how the file is compressed.
+.
+This is not important for the user, such that it cannot be specified
+on the command line.
+.
+.
+.P
+There are 4 methods to specify a
+.I section
+on the command line:
+.
+.Topic
+Environment variable
+.Env_var \%$MANSECT
+.
+.Topic
+Command line option
+.B --sections
+.
+.Topic
+Appendix to the
+.I name
+argument in the form
+.I <name>.<section>
+.
+.Topic
+Preargument before the
+.I name
+argument in the form
+.I <section> <name>
+.
+.
+.P
+It is also possible to specify several
+.I sections
+by appending the single characters separated by colons.
+.
+One can imagine that this means to restrict the
+.I \%man\~page
+search to only some
+.IR sections .
+.
+The multiple
+.I sections
+are only possible for
+.Env_var \%$MANSECT
+and
+.BR --sections .
+.
+.
+.P
+If no
+.I section
+is specified all
+.I sections
+are searched one after the other in the given order, starting with
+.IR section\~1 ,
+until a suitable file is found.
+.
+.
+.P
+There are 4 methods to specify an
+.I extension
+on the command line.
+.
+But it is not necessary to provide the whole extension name, some
+abbreviation is good enough in most cases.
+.
+.Topic
+Environment variable
+.Env_var \%$EXTENSION
+.
+.Topic
+Command line option
+.B --extension
+.
+.Topic
+Appendix to the
+.I <name>.<section>
+argument in the form
+.I <name>.<section><extension>
+.
+.Topic
+Preargument before the
+.I name
+argument in the form
+.I <section><extension> <name>
+.
+.
+.P
+For further details on
+.I \%man\~page
+searching, see
+.BR \%man (1).
+.
+.
+.\" --------------------------------------------------------------------
+.SS "Examples of man files"
+.\" --------------------------------------------------------------------
+.
+.TP
+.File_name /usr/share/man/man1/groff.1
+This is an uncompressed file for the
+.I \%man\~page
+\f[CR]groff\fP in
+.IR section\~1 .
+.
+It can be called by
+.EX
+\fIsh#\fR groffer\~groff
+.EE
+No
+.I section
+is specified here, so all
+.I sections
+should be searched, but as
+.I section\~1
+is searched first this file will be found first.
+.
+The file name is composed of the following components.
+.File_name /usr/share/man
+must be part of the
+.IR \%man\~path ;
+the subdirectory
+.File_name man1/
+and the part
+.File_name .1
+stand for the
+.IR section ;
+.File_name groff
+is the name of the
+.IR \%man\~page .
+.
+.
+.TP
+.File_name /usr/local/share/man/man7/groff.7.gz
+The file name is composed of the following components.
+.File_name /usr/local/share/man
+must be part of the
+.IR \%man\~path ;
+the subdirectory
+.File_name man7/
+and the part
+.File_name .7
+stand for the
+.IR section ;
+.File_name groff
+is the name of the
+.IR \%man\~page ;
+the final part
+.File_name .gz
+stands for a compression with
+.BR gzip (1).
+As the
+.I section
+is not the first one it must be specified as well.
+.
+This can be done by one of the following commands.
+.EX
+\fIsh#\fR\~groffer\~groff.7
+\fIsh#\fR\~groffer\~7\~groff
+\fIsh#\fR\~groffer\~\-\-sections=7\~groff
+.EE
+.
+.TP
+.File_name /usr/local/man/man1/ctags.1emacs21.bz2
+Here
+.File_name /usr/local/man
+must be in
+.IR \%man\~path ;
+the subdirectory
+.File_name man1/
+and the file name part
+.File_name .1
+stand for
+.IR section\~1 ;
+the name of the
+.I \%man\~page
+is
+.File_name ctags ;
+the section has an extension
+.File_name emacs21 ;
+and the file is compressed as
+.File_name .bz2
+with
+.BR bzip2 (1).
+The file can be viewed with one of the following commands
+.EX
+\fIsh#\fR\~groffer\~ctags.1e
+\fIsh#\fR\~groffer\~1e\~ctags
+\fIsh#\fR\~groffer\~\-\-extension=e\~\-\-sections=1\~ctags
+.EE
+where \f[CR]e\fP works as an abbreviation for the extension
+\f[CR]emacs21\fP.
+.
+.
+.TP
+.File_name /usr/man/linux/de/man7/man.7.Z
+The directory
+.File_name /usr/man
+is now part of the
+.IR \%man\~path ;
+then there is a subdirectory for an
+.I operating system
+name
+.File_name linux/ ;
+next comes  a subdirectory
+.File_name de/
+for the German
+.IR language ;
+the
+.I section
+names
+.File_name man7
+and
+.File_name .7
+are known so far;
+.File_name man
+is the name of the
+.IR \%man\~page ;
+and
+.File_name .Z
+signifies the compression that can be handled by
+.BR gzip (1).
+We want now show how to provide several values for some options.
+.
+That is possible for
+.I sections
+and
+.I operating system
+names.
+.
+So we use as
+.I sections\~5
+and
+.I 7
+and as
+.I system
+names
+.I linux
+and
+.IR aix .
+The command is then
+.sp
+.EX
+\fIsh#\fR groffer\~\-\-locale=de\~\-\-sections=5:7\~\-\-systems=linux,aix\~man
+\fIsh#\fR LANG=de\~MANSECT=5:7\~SYSTEM=linux,aix\~groffer\~man
+.EE
+.
+.
+.\" --------------------------------------------------------------------
+.SH DECOMPRESSION
+.\" --------------------------------------------------------------------
+.
+The program has a decompression facility.
+.
+If standard input or a file that was retrieved from the command line
+parameters is compressed with a format that is supported by either
+.BR \%gzip (1)
+or
+.BR \%bzip2 (1)
+it is decompressed on-the-fly.
+.
+This includes the \f[CR]GNU\fP
+.BR \%.gz ,
+.BR \%.bz2 ,
+and the traditional
+.B \%.Z
+compression.
+.
+The program displays the concatenation of all decompressed input in
+the sequence that was specified on the command line.
+.
+.
+.\" --------------------------------------------------------------------
+.SH "ENVIRONMENT"
+.\" --------------------------------------------------------------------
+.
+The
+.B \%groffer
+program supports many system variables, most of them by courtesy of
+other programs.
+.
+All environment variables of
+.BR \%groff (@MAN1EXT@)
+and \f[CR]GNU\fP
+.BR \%man (1)
+and some standard system variables are honored.
+.
+.
+.\" --------------------------------------------------------------------
+.SS "Native groffer Variables"
+.\" --------------------------------------------------------------------
+.
+.TP
+.Env_var \%$GROFFER_OPT
+Store options for a run of
+.BR \%groffer .
+.
+The options specified in this variable are overridden by the options
+given on the command line.
+.
+The content of this variable is run through the shell builtin `eval';
+so arguments containing white-space or special shell characters should
+be quoted.
+.
+Do not forget to export this variable, otherwise it does not exist
+during the run of
+.BR groffer .
+.
+.
+.\" --------------------------------------------------------------------
+.SS "System Variables"
+.\" --------------------------------------------------------------------
+.
+The following variables have a special meaning for
+.BR \%groffer .
+.
+.
+.TP
+.Env_var \%$DISPLAY
+If this variable is set this indicates that the \%\f[CR]X\~Window\fP
+system is running.
+.
+Testing this variable decides on whether graphical or text output is
+generated.
+.
+This variable should not be changed by the user carelessly, but it can
+be used to start the graphical
+.B \%groffer
+on a remote \%\f[CR]X\~Window\fP terminal.
+.
+For example, depending on your system,
+.B \%groffer
+can be started on the second monitor by the command
+.sp
+.EX
+\fIsh#\fR DISPLAY=:0.1\~groffer\~what.ever &
+.EE
+.
+.
+.TP
+.Env_var \%$LC_ALL
+.TQ
+.Env_var \%$LC_MESSAGES
+.TQ
+.Env_var $LANG
+If one of these variables is set (in the above sequence), its content
+is interpreted as the locale, the language to be used, especially when
+retrieving
+.IR \%man\~pages .
+.
+A locale name is typically of the form
+.nh
+.IR language [\c
+.B _\c
+.IR territory [\c
+.B .\c
+.IR codeset [\c
+.B @\c
+.IR modifier ]]],
+.hy
+where
+.I \%language
+is an ISO 639 language code,
+.I \%territory
+is an ISO 3166 country code, and
+.I \%codeset
+is a character set or encoding identifier like ISO-8859-1 or UTF-8;
+see
+.BR \%setlocale (3).
+.
+The locale values \f[CR]C\fP and \%\f[CR]POSIX\fP
+stand for the default, i.e. the
+.I \%man\~page
+directories without a language prefix.
+.
+This is the same behavior as when all 3\~variables are unset.
+.
+.
+.TP
+.Env_var \%$PAGER
+This variable can be used to set the pager for the tty output.
+.
+For example, to disable the use of a pager completely set this
+variable to the
+.BR \%cat (1)
+program
+.sp
+.EX
+\fIsh#\fR PAGER=cat\~groffer\~anything
+.EE
+.sp
+.
+.TP
+.Env_var $PATH
+All programs within the
+.B \%groffer
+script are called without a fixed path.
+.
+Thus this environment variable determines the set of programs used
+within the run of
+.BR \%groffer .
+.
+.
+.\" --------------------------------------------------------------------
+.SS "Groff Variables"
+.\" --------------------------------------------------------------------
+.
+The
+.B \%groffer
+program internally calls
+.BR \%groff ,
+so all environment variables documented in
+.BR \%groff (@MAN1EXT@)
+are internally used within
+.B \%groffer
+as well.
+.
+The following variable has a direct meaning for the
+.B \%groffer
+program.
+.
+.TP
+.Env_var \%$GROFF_TMPDIR
+If the value of this variable is an existing, writable directory,
+.B \%groffer
+uses it for storing its temporary files, just as
+.B groff
+does.
+.
+See the
+.BR \%groff (@MAN1EXT@)
+man page for more details on the location of temporary files.
+.
+.
+.\" --------------------------------------------------------------------
+.SS "Man Variables"
+.\" --------------------------------------------------------------------
+.
+Parts of the functionality of the
+.B man
+program were implemented in
+.BR \%groffer ;
+support for all environment variables documented in
+.BR \%man (1)
+was added to
+.BR \%groffer ,
+but the meaning was slightly modified due to the different approach in
+.BR \%groffer ;
+but the user interface is the same.
+.
+The
+.B man
+environment variables can be overwritten by options provided with
+.Env_var \%$MANOPT ,
+which in turn is overwritten by the command line.
+.
+.
+.TP
+.Env_var \%$EXTENSION
+Restrict the search for
+.I \%man\~pages
+to files having this extension.
+.
+This is overridden by option
+.BR --extension ;
+see there for details.
+.
+.
+.TP
+.Env_var \%$MANOPT
+This variable contains options as a preset for
+.BR \%man (1).
+As not all of these are relevant for
+.B \%groffer
+only the essential parts of its value are extracted.
+.
+The options specified in this variable overwrite the values of the
+other environment variables that are specific to
+.IR man .
+.
+All options specified in this variable are overridden by the options
+given on the command line.
+.
+.
+.TP
+.Env_var \%$MANPATH
+If set, this variable contains the directories in which the
+.I \%man\~page
+trees are stored.
+.
+This is overridden by option
+.BR \%--manpath .
+.
+.
+.TP
+.Env_var \%$MANSECT
+If this is a colon separated list of section names, the search for
+.I \%man\~pages
+is restricted to those manual sections in that order.
+.
+This is overridden by option
+.BR --sections .
+.
+.
+.TP
+.Env_var \%$SYSTEM
+If this is set to a comma separated list of names these are interpreted
+as
+.I \%man\~page
+trees for different operating systems.
+.
+This variable can be overwritten by option
+.BR --systems ;
+see there for details.
+.
+.
+.P
+The environment variable
+.Env_var \%$MANROFFSEQ
+is ignored by
+.B \%groffer
+because the necessary preprocessors are determined automatically.
+.
+.
+.\" --------------------------------------------------------------------
+.SH "CONFIGURATION FILES"
+.\" --------------------------------------------------------------------
+.
+The
+.B \%groffer
+program can be preconfigured by two configuration files.
+.
+.
+.TP
+.File_name \%/etc/groff/groffer.conf
+System-wide configuration file for
+.BR \%groffer .
+.
+.
+.TP
+.File_name \%$HOME/.groff/groffer.conf
+User-specific configuration file for
+.BR \%groffer ,
+where
+.Env_var \%$HOME
+denotes the user's home directory.
+.
+This file is called after the system-wide configuration file to enable
+overriding by the user.
+.
+.
+.P
+Both files are handled for the configuration, but the configuration
+file in
+.File_name /etc
+comes first; it is overwritten by the configuration file in the home
+directory; both configuration files are overwritten by the environment
+variable
+.Env_var \%$GROFFER_OPT ;
+everything is overwritten by the command line arguments.
+.
+.
+.P
+The configuration files contain options that should be called as
+default for every
+.B \%groffer
+run.
+.
+These options are written in lines such that each contains either a
+long option, a short option, or a short option cluster; each with or
+without an argument.
+.
+So each line with configuration information starts with a minus
+character
+.RB ` \- ';
+a line with a long option starts with two minus characters
+.RB ` \-\- ',
+a line with a short option or short option cluster starts with a
+single minus
+.RB ` \- '.
+.
+.
+.P
+The option names in the configuration files may not be abbreviated,
+they must be exact.
+.
+.
+.P
+The argument for a long option can be separated from the option name
+either by an equal sign
+.RB ` = '
+or by whitespace, i.e. one or several space or tab characters.
+.
+An argument for a short option or short option cluster can be directly
+appended to the option name or separated by whitespace.
+.
+The end of an argument is the end of the line.
+.
+It is not allowed to use a shell environment variable in an option
+name or argument.
+.
+.
+.P
+It is not necessary to use quotes in an option or argument, except for
+empty arguments.
+.
+An empty argument can be provided by appending a pair of quotes to the
+separating equal sign or whitespace; with a short option, the
+separator can be omitted as well.
+.
+For a long option with a separating equal sign
+.RB ` = ',
+the pair of quotes can be omitted, thus ending the line with the
+separating equal sign.
+.
+All other quote characters are cancelled internally.
+.
+.
+.P
+In the configuration files, arbitrary whitespace is allowed at the
+beginning of each line, it is just ignored.
+.
+Each whitespace within a line is replaced by a single space character
+` ' internally.
+.
+.
+.P
+All lines of the configuration lines that do not start
+with a minus character are ignored, such that comments starting with
+.RB ` # '
+are possible.
+.
+So there are no shell commands in the configuration files.
+.
+.
+.P
+As an example, consider the following configuration file that can be
+used either in
+.File_name \%/etc/groff/groffer.conf
+or
+.File_name \%~/.groff/groffer.conf .
+.
+.
+.P
+.ft CR
+.nh
+.nf
+# groffer configuration file
+#
+# groffer options that are used in each call of groffer
+\-\-foreground=DarkBlue
+\-\-resolution=100
+\-\-x\-viewer=gxditview \-geometry 900x1200
+\-\-pdf\-viewer xpdf \-Z 150
+.fi
+.hy
+.ft
+.
+.
+.P
+The lines starting with
+.B #
+are just ignored, so they act as command lines.
+.
+This configuration sets four
+.B \%groffer
+options (the lines starting with
+.RB ` \- ').
+This has the following effects:
+.
+.
+.Topic
+Use a text color of
+.B \%DarkBlue
+in all viewers that support this, such as
+.BR \%gxditview .
+.
+.
+.Topic
+Use a resolution of
+.B 100dpi
+in all viewers that support this, such as
+.BR \%gxditview .
+.
+By this, the default device in
+.I x mode
+is set to
+.BR X100 .
+.
+.
+.Topic
+Force
+.BR \%gxditview (@MAN1EXT@)
+as the
+.I \%x-mode
+viewer using the geometry option for setting the width to
+.B 900px
+and the height to
+.BR 1200px .
+This geometry is suitable for a resolution of
+.BR 100dpi .
+.
+.
+.Topic
+Use
+.BR \%xpdf (1)
+as the
+.I \%pdf-mode
+viewer with the argument
+.B \-Z
+.BR 150 .
+.
+.
+.\" --------------------------------------------------------------------
+.SH "EXAMPLES"
+.\" --------------------------------------------------------------------
+.
+The usage of
+.B \%groffer
+is very easy.
+.
+Usually, it is just called with a file name or
+.IR \%man\~page .
+.
+The following examples, however, show that
+.B \%groffer
+has much more fancy capabilities.
+.
+.sp
+.EX
+\fIsh#\fR\~groffer\~/usr/local/share/doc/groff/meintro.ms.gz
+.EE
+.sp
+Decompress, format and display the compressed file
+.File_name meintro.ms.gz
+in the directory
+.File_name /usr/local/share/doc/groff ,
+using the standard viewer
+.B \%gxditview
+as graphical viewer when in \%\f[CR]X\~Window\fP, or the
+.BR \%less (1)
+pager program when not in \%\f[CR]X\~Window\fP.
+.
+.sp
+.EX
+\fIsh#\fR\~groffer\~groff
+.EE
+.sp
+If the file
+.File_name \%./groff
+exists use it as input.
+.
+Otherwise interpret the argument as a search for the
+.I \%man\~page
+named
+.B \%groff
+in the smallest possible
+.IR \%man\~section ,
+being section 1 in this case.
+.
+.sp
+.EX
+\fIsh#\fR\~groffer\~man:groff
+.EE
+.sp
+search for the
+.I \%man\~page
+of
+.B \%groff
+even when the file
+.File_name ./groff
+exists.
+.
+.sp
+.EX
+\fIsh#\fR\~groffer\~groff.7
+\fIsh#\fR\~groffer\~7\~groff
+.EE
+.sp
+search the
+.I \%man\~page
+of
+.B \%groff
+in
+.I \%man\~section
+.BR 7 .
+This section search works only for a digit or a single character from
+a small set.
+.
+.sp
+.EX
+\fIsh#\fR\~groffer\~fb.modes
+.EE
+.sp
+If the file
+.File_name ./fb.modes
+does not exist interpret this as a search for the
+.I \%man\~page
+of
+.BR fb.modes .
+As the extension
+.I \%modes
+is not a single character in classical section style the argument is
+not split to a search for
+.BR fb .
+.
+.sp
+.EX
+\fIsh#\fR\~groffer\~groff\~\[cq]troff(1)\[cq]\~man:roff
+.EE
+.sp
+The arguments that are not existing files are looked-up as the
+following
+.IR \%man\~pages :
+.B \%groff
+(automatic search, should be found in \fIman\fP\~section\~1),
+.B \%troff
+(in section\~1),
+and
+.B \%roff
+(in the section with the lowest number, being\~7 in this case).
+.
+The quotes around
+.nh
+.I \[cq]troff(1)\[cq]
+.hy
+are necessary because the parentheses are special shell characters;
+escaping them with a backslash character
+.I \[rs](
+and
+.I \[rs])
+would be possible, too.
+.
+The formatted files are concatenated and displayed in one piece.
+.
+.sp
+.EX
+\fIsh#\fR\~LANG=de\~groffer\~--man\~--www\~--www-viewer=galeon\~ls
+.EE
+.sp
+Retrieve the German
+.I \%man\~page
+(language
+.IR de )
+for the
+.B ls
+program, decompress it, format it to
+.I \%html
+format
+.nh
+.RI ( \%www\~mode )
+.hy
+and view the result in the web browser
+.BR \%galeon .
+The option
+.B --man
+guarantees that the
+.I \%man\~page
+is retrieved, even when a local file
+.File_name \%ls
+exists in the actual directory.
+.
+.
+.sp
+.EX
+\fIsh#\fR\~groffer\~--source\~'man:roff(7)'
+.EE
+.sp
+Get the
+.I \%man\~page
+called
+.I \%roff
+in \fIman\fP\~section 7, decompress it, and print its unformatted
+content, its source code.
+.
+.
+.sp
+.EX
+\fIsh#\fR\~groffer\~--de-p\~--in\~--ap
+.EE
+.sp
+This is a set of abbreviated arguments, it is determined as
+.br
+.sp
+.EX
+\fIsh#\fR\~groffer\~--debug-params\~--intermediate-output\~--apropos
+.EE
+.sp
+.
+.sp
+.EX
+\fIsh#\fR\~cat\~file.gz\~|\~groffer\~-Z\~-mfoo
+.EE
+.sp
+.
+The file
+.File_name file.gz
+is sent to standard input, this is decompressed, and then this is
+transported to the
+.I \%groff intermediate output mode
+without post-processing
+.RB ( groff
+option
+.BR -Z ),
+using macro package
+.I \%foo
+.RB ( groff
+option
+.BR -m ).
+.
+.
+.sp
+.EX
+\fIsh#\fR\~echo\~'\[rs]f[CB]WOW!'\~|
+> groffer --x --bg red --fg yellow --geometry 200x100 -
+.EX
+.sp
+.
+Display the word \f[CB]WOW!\fP in a small window in constant-width
+bold font, using color yellow on red background.
+.
+.
+.\" --------------------------------------------------------------------
+.SH "COMPATIBILITY"
+.\" --------------------------------------------------------------------
+.
+The
+.B \%groffer
+program is written in Perl, the Perl version during writing was v5.8.8.
+.
+.
+.P
+.B \%groffer
+provides its own parser for command line arguments that is compatible
+to both \%\f[CR]POSIX\fP
+.BR \%getopts (1)
+and \%\f[CR]GNU\fP
+.BR \%getopt (1).
+It can handle option arguments and file names containing white space
+and a large set of special characters.
+.
+The following standard types of options are supported.
+.
+.
+.Topic
+The option consisting of a single minus
+.B -
+refers to standard input.
+.
+.
+.Topic
+A single minus followed by characters refers to a single character
+option or a combination thereof; for example, the
+.B \%groffer
+short option combination
+.B -Qmfoo
+is equivalent to
+.BR -Q\~\-m\~foo .
+.
+.
+.Topic
+Long options are options with names longer than one character; they
+are always preceded by a double minus.
+.
+An option argument can either go to the next command line argument or
+be appended with an equal sign to the argument; for example,
+.B --long=arg
+is equivalent to
+.BR --long\~arg .
+.
+.
+.Topic
+An argument of
+.B --
+ends option parsing; all further command line arguments are
+interpreted as
+.I \%filespec
+parameters, i.e. file names or constructs for searching
+.IR \%man\~pages ).
+.
+.
+.Topic
+All command line arguments that are neither options nor option
+arguments are interpreted as
+.I \%filespec
+parameters and stored until option parsing has finished.
+.
+For example, the command line
+.sp
+.EX
+\fIsh#\fR\~groffer file1 -a -o arg file2
+.EE
+.sp
+is equivalent to
+.sp
+.EX
+\fIsh#\fR\~groffer -a -o arg -- file1 file2
+.EE
+.sp
+.
+.P
+The free mixing of options and
+.I \%filespec
+parameters follows the GNU principle.
+.
+That does not fulfill the strange option behavior of \%\f[CR]POSIX\fP
+that ends option processing as soon as the first non-option argument
+has been reached.
+.
+The end of option processing can be forced by the option
+.RB ` \-\- '
+anyway.
+.
+.
+.\" --------------------------------------------------------------------
+.SH "BUGS"
+.\" --------------------------------------------------------------------
+.
+Report bugs to the
+.MT bug-groff@gnu.org
+bug-groff mailing list 
+.ME .
+.
+Include a complete, self-contained example that will allow the bug to
+be reproduced, and say which version of
+.B \%groffer
+you are using.
+.
+.
+.P
+You can also use the
+.MT groff@gnu.org
+groff mailing list
+.ME ,
+but you must first subscribe to this list.
+.
+You can do that by visiting the
+.UR http://\:lists.gnu.org/\:mailman/\:listinfo/\:groff
+groff mailing list web page
+.UE .
+.
+.
+.P
+See
+.BR \%groff (@MAN1EXT@)
+for information on availability.
+.
+.
+.\" --------------------------------------------------------------------
+.SH "SEE ALSO"
+.\" --------------------------------------------------------------------
+.
+.P
+.BR \%groff (@MAN1EXT@),
+.BR \%@g@troff (@MAN1EXT@)
+.RS
+Details on the options and environment variables available in
+.BR \%groff ;
+all of them can be used with
+.BR \%groffer .
+.RE
+.
+.
+.TP
+.BR \%groff (@MAN7EXT@)
+Documentation of the
+.I \%groff
+language.
+.
+.
+.TP
+.BR \%grog (@MAN1EXT@)
+Internally,
+.B \%groffer
+tries to guess the
+.B \%groff
+command line options from the input using this program.
+.
+.
+.TP
+.BR groff_out (@MAN5EXT@)
+Documentation on the
+.I \%groff intermediate output
+.nh
+.RI ( ditroff
+output).
+.hy
+.
+.
+.TP
+.BR groff_tmac (@MAN5EXT@)
+Documentation on the
+.I \%groff
+macro files.
+.
+.
+.TP
+.BR \%man (1)
+The standard program to display
+.IR \%man\~pages .
+.
+The information there is only useful if it is the
+.I \%man\~page
+for GNU
+.BR man .
+Then it documents the options and environment variables that are
+supported by
+.BR \%groffer .
+.
+.
+.P
+.BR \%gxditview (@MAN1EXT@),
+.BR \%xditview (1x)
+.RS
+Viewers for
+.BR \%groffer 's
+.IR \%x\~mode .
+.RE
+.
+.
+.P
+.BR \%kpdf (1),
+.BR \%kghostview (1),
+.BR \%evince (1),
+.BR \%ggv (1),
+.BR \%gv (1),
+.BR \%ghostview (1),
+.BR \%gs (1)
+.RS
+Viewers for
+.BR \%groffer 's
+.IR \%ps\~mode .
+.RE
+.
+.
+.P
+.BR \%kpdf (1),
+.BR \%acroread (1),
+.BR \%evince (1),
+.BR \%xpdf (1),
+.BR \%gpdf (1),
+.BR \%kghostview (1),
+.BR \%ggv (1)
+.RS
+Viewers for
+.BR \%groffer 's
+.IR \%pdf\~mode .
+.RE
+.
+.
+.P
+.BR \%kdvi (1),
+.BR \%xdvi (1),
+.BR \%dvilx (1)
+.RS
+Viewers for
+.BR \%groffer 's
+.IR \%dvi\~mode .
+.RE
+.
+.
+.P
+.BR \%konqueror (1),
+.BR \%epiphany (1),
+.BR \%firefox (1),
+.BR \%mozilla (1),
+.BR \%netscape (1),
+.BR \%lynx (1)
+.RS
+Web-browsers for
+.BR \%groffer 's
+.I \%html
+or
+.IR \%www\~mode .
+.RE
+.
+.
+.TP
+.BR \%less (1)
+Standard pager program for the
+.IR \%tty\~mode .
+.
+.
+.P
+.BR \%gzip (1),
+.BR \%bzip2 (1)
+.RS
+The decompression programs supported by
+.BR \%groffer .
+.RE
+.
+.
+.\" --------------------------------------------------------------------
+.SH "AUTHOR"
+.\" --------------------------------------------------------------------
+.author
+.
+.
+.\" --------------------------------------------------------------------
+.SH "COPYING"
+.\" --------------------------------------------------------------------
+.copyleft
+.
+.
+.\" --------------------------------------------------------------------
+.\" Emacs settings
+.\" --------------------------------------------------------------------
+.
+.\" Local Variables:
+.\" mode: nroff
+.\" End:

Index: groffer.pl
===================================================================
RCS file: groffer.pl
diff -N groffer.pl
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ groffer.pl	11 Aug 2013 08:28:52 -0000	1.17
@@ -0,0 +1,2209 @@
+#! /usr/bin/env perl
+
+# groffer - display groff files
+
+# Source file position: <groff-source>/contrib/groffer/perl/groffer.pl
+# Installed position: <prefix>/bin/groffer
+
+# Copyright (C) 2006, 2009, 2011, 2013
+#   Free Software Foundation, Inc.
+
+# Written by Bernd Warken <groff-bernd.warken-72@web.de>.
+
+# Last update: 29 Mar 2013
+
+# 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/>.
+
+########################################################################
+
+use strict;
+use warnings;
+#use diagnostics;
+
+# temporary dir and files
+use File::Temp qw/ tempfile tempdir /;
+
+# needed for temporary dir
+use File::Spec;
+
+# for `copy' and `move'
+use File::Copy;
+
+# for fileparse, dirname and basename
+use File::Basename;
+
+# current working directory
+use Cwd;
+
+# $Bin is the directory where this script is located
+use FindBin;
+
+
+########################################################################
+# system variables and exported variables
+########################################################################
+
+our $Dev_Null;
+our $Umask;
+our @Path;
+our $Start_Dir;
+
+our $tmpdir = '';
+our ($fh_cat, $tmp_cat);
+our ($fh_stdin, $tmp_stdin);
+
+our @Addopts_Groff;
+our %Debug;
+our %Opt;
+
+our $Has_Compression;
+our $Has_bzip;
+
+our $Output_File_Name;
+
+our $Apropos_Prog;
+our $Filespec_Arg;
+our $Filespec_Is_Man;
+our $Macro_Pkg;
+our $Manspec;
+our $No_Filespecs;
+our $Special_Filespec;
+our $Special_Setup;
+
+our %Man;
+
+BEGIN {
+  $Dev_Null = File::Spec->devnull();
+
+  $Umask = umask 077;
+
+  $Start_Dir = getcwd;
+
+  # flush after each print or write command
+  $| = 1;
+}
+
+
+########################################################################
+# read-only variables with double-@ construct
+########################################################################
+
+our $File_split_env_sh;
+our $File_version_sh;
+our $Groff_Version;
+
+BEGIN {
+  {
+    my $before_make;		# script before run of `make'
+    {
+      my $at = '@';
+      $before_make = 1 if '@VERSION@' eq "${at}VERSION${at}";
+    }
+
+    my %at_at;
+    my $file_perl_test_pl;
+    my $groffer_libdir;
+
+    if ($before_make) {
+      my $groffer_perl_dir = $FindBin::Bin;
+      my $groffer_top_dir = File::Spec->catdir($groffer_perl_dir, '..');
+      $groffer_top_dir = Cwd::realpath($groffer_top_dir);
+      $at_at{'BINDIR'} = $groffer_perl_dir;
+      $at_at{'G'} = '';
+      $at_at{'LIBDIR'} = '';
+      $groffer_libdir = $groffer_perl_dir;
+      $file_perl_test_pl = File::Spec->catfile($groffer_perl_dir,
+					       'perl_test.pl');
+      $File_version_sh = File::Spec->catfile($groffer_top_dir, 'version.sh');
+      $Groff_Version = '';
+    } else {
+      $Groff_Version = '@VERSION@';
+      $at_at{'BINDIR'} = '@BINDIR@';
+      $at_at{'G'} = '@g@';
+      $at_at{'LIBDIR'} = '@libdir@';
+      $groffer_libdir = '@groffer_dir@';
+      $file_perl_test_pl = File::Spec->catfile($groffer_libdir,
+					       'perl_test.pl');
+      $File_version_sh = File::Spec->catfile($groffer_libdir, 'version.sh');
+    }
+
+    die "$groffer_libdir is not an existing directory;"
+      unless -d $groffer_libdir;
+
+    unshift(@INC, $groffer_libdir);
+
+    $File_split_env_sh = File::Spec->catfile($groffer_libdir, 'split_env.sh');
+    die "$File_split_env_sh does not exist;" unless -f "$File_split_env_sh";
+
+    # test perl on suitable version
+    die "$file_perl_test_pl does not exist;" unless -f "$file_perl_test_pl";
+    do "$file_perl_test_pl" or die "Perl test: $@";
+
+    require 'func.pl';
+    require 'man.pl';
+
+    @Path = &path_uniq( File::Spec->path() );
+
+    if ( &where_is_prog('gzip') ) {
+      $Has_Compression = 1;
+      $Has_bzip = 1 if &where_is_prog('bzip2');
+    }
+  }
+}
+
+
+########################################################################
+# modes, viewers, man sections, and defaults
+########################################################################
+
+# configuration files
+my @Conf_Files = (File::Spec->catfile(File::Spec->rootdir(),
+				      'etc', 'groff', 'groffer.conf'),
+		  File::Spec->catfile("$ENV{'HOME'}", '.groff',
+				      'groffer.conf')
+		 );
+
+my @Default_Modes = ('pdf', 'html', 'ps', 'x', 'dvi', 'tty');
+my $Default_Resolution = 75;
+my $Default_tty_Device = 'latin1';
+
+my @Macro_Packages = ('-man', '-mdoc', '-me', '-mm', '-mom', '-ms');
+
+my %Viewer_tty = ('DVI' => [],
+		  'HTML' => ['lynx', 'w3m'],
+		  'PDF' => [],
+		  'PS' => [],
+		  'TTY' => ['less -r -R', 'more', 'pager'],
+		  'X' => [],
+		 );
+
+my %Viewer_X = ('DVI' => ['kdvi', 'xdvi', 'dvilx'],
+		'HTML' => ['konqueror', 'epiphany'. 'mozilla-firefox',
+			   'firefox', 'mozilla', 'netscape', 'galeon',
+			   'opera', 'amaya','arena', 'mosaic'],
+		'PDF' => ['okular', 'kpdf', 'acroread', 'evince',
+			  'xpdf -z 150', 'gpdf', 'xpdf', 'zathura'.
+			  'epdfview', 'qpdfview', 'apvlv', 'qpdfview',
+			  'kghostview --scale 1.45', 'gv', 'ggv'],
+		'PS' => ['gs', 'gs_x11', 'ghostscript', 'ghostview',
+			 'kghostview --scale 1.45',
+			 'gv', 'okular', 'kpdf', 'evince', 'ggv'],
+		'TTY' => ['xless'],
+		'X' => ['gxditview', 'xditview'],
+	      );
+
+%Man = ('ALL' => 0,
+	'AUTO_SEC' => ['1', '2', '3', '4', '5', '6', '7', '8', '9',
+			  'n', 'o'],
+	'ENABLE' => 1,
+	   'EXT' => '',
+	   'FORCE' => 0,
+	   'IS_SETUP' => 0,
+	   'MANSPEC' => {},
+	   'LANG' => '',
+	   'LANG2' => '',
+	   'PATH' => [],
+	   'SEC' => [],
+	   'SEC_CHARS' => '',
+	   'SYS' => [],
+	  );
+$Man{'AUTO_SEC_CHARS'} = join('', @{$Man{'AUTO_SEC'}});
+
+
+########################################################################
+# given options, main_set_options()
+########################################################################
+
+my %Opts_Cmdline_Short;
+my %Opts_Cmdline_Long;
+my $Opts_Cmdline_Long_Str;
+my %Opts_Cmdline_Double;
+my %Opts_Groff_Short;
+
+sub main_set_options {
+  # the following options are ignored in groffer.pl, but are kept from
+  # groffer.sh: --shell arg, --debug-shell
+
+  my @opts_ignored_short_na = ();
+  my @opts_ignored_short_arg = ();
+
+  my @opts_ignored_long_na = ('debug-shell');
+
+  my @opts_ignored_long_arg = ('shell');
+
+
+  ###### groffer native options
+
+  my @opts_groffer_short_na = ('h', 'Q', 'v', 'V', 'X', 'Z');
+  my @opts_groffer_short_arg = ('T');
+
+  my @opts_groffer_long_na = ('auto', 'apropos', 'apropos-data',
+  'apropos-devel', 'apropos-progs', 'debug', 'debug-all',
+  'debug-filenames', 'debug-func', 'debug-grog', 'debug-not-func',
+  'debug-keep', 'debug-lm', 'debug-params', 'debug-stacks',
+  'debug-tmpdir', 'debug-user', 'default', 'do-nothing', 'dvi',
+  'groff', 'help', 'intermediate-output', 'html', 'man',
+  'no-location', 'no-man', 'no-special', 'pdf', 'ps', 'rv', 'source',
+  'text', 'to-stdout', 'text-device', 'tty', 'tty-device', 'version',
+  'whatis', 'where', 'www', 'x', 'X');
+
+### main_set_options()
+  my @opts_groffer_long_arg = ('default-modes', 'device',
+  'dvi-viewer', 'dvi-viewer-tty', 'extension', 'fg', 'fn', 'font',
+  'foreground', 'html-viewer', 'html-viewer-tty', 'mode',
+  'pdf-viewer', 'pdf-viewer-tty', 'print', 'ps-viewer',
+  'ps-viewer-tty', 'title', 'tty-viewer', 'tty-viewer-tty',
+  'www-viewer', 'www-viewer-tty', 'x-viewer', 'x-viewer-tty',
+  'X-viewer', 'X-viewer-tty');
+
+  ##### groffer options inhereted from groff
+
+  my @opts_groff_short_na = ('a', 'b', 'c', 'C', 'e', 'E', 'g', 'G',
+  'i', 'k', 'l', 'N', 'p', 'R', 's', 'S', 't', 'U', 'z');
+
+  my @opts_groff_short_arg = ('d', 'f', 'F', 'I', 'K', 'L', 'm', 'M', 'n',
+  'o', 'P', 'r', 'w', 'W');
+
+  my @opts_groff_long_na = ();
+  my @opts_groff_long_arg = ();
+
+  ##### groffer options inhereted from the X Window toolkit
+
+  my @opts_x_short_na = ();
+  my @opts_x_short_arg = ();
+
+  my @opts_x_long_na = ('iconic', 'rv');
+
+  my @opts_x_long_arg = ('background', 'bd', 'bg', 'bordercolor',
+  'borderwidth', 'bw', 'display', 'fg', 'fn', 'font', 'foreground',
+  'ft', 'geometry', 'resolution', 'title', 'xrm');
+
+### main_set_options()
+  ###### groffer options inherited from man
+
+  my @opts_man_short_na = ();
+  my @opts_man_short_arg = ();
+
+  my @opts_man_long_na = ('all', 'ascii', 'catman', 'ditroff',
+  'local-file', 'location', 'troff', 'update');
+
+  my @opts_man_long_arg = ('locale', 'manpath', 'pager',
+  'preprocessor', 'prompt', 'sections', 'systems', 'troff-device');
+
+  ###### additional options for parsing evironment variable $MANOPT only
+
+  my @opts_manopt_short_na = ('7', 'a', 'c', 'd', 'D', 'f', 'h', 'k',
+  'l', 't', 'u', 'V', 'w', 'Z');
+
+  my @opts_manopt_short_arg = ('e', 'L', 'm', 'M', 'p', 'P', 'r', 'S',
+  'T');
+
+  my @opts_manopt_long_na = (@opts_man_long_na, 'apropos', 'debug',
+  'default', 'help', 'html', 'ignore-case', 'location-cat',
+  'match-case', 'troff', 'update', 'version', 'whatis', 'where',
+  'where-cat');
+
+  my @opts_manopt_long_arg = (@opts_man_long_na, 'config_file',
+  'encoding', 'extension', 'locale');
+
+### main_set_options()
+  ###### collections of command line options
+
+  # There are two hashes that control the whole of the command line
+  # options, one for short and one for long options.  Options without
+  # and with arguments are mixed by advicing a value of 0 for an option
+  # without argument and a value of 1 for an option with argument.
+  # The options are with leading minus.
+
+  foreach (@opts_groffer_short_na, @opts_groff_short_na,
+	   @opts_x_short_na, @opts_man_short_na, @opts_ignored_short_na) {
+    $Opts_Cmdline_Short{"-$_"} = 0 if $_;
+  }
+  foreach (@opts_groffer_short_arg, @opts_groff_short_arg,
+	   @opts_x_short_arg, @opts_man_short_arg, @opts_ignored_short_arg) {
+    $Opts_Cmdline_Short{"-$_"} = 1 if $_;
+  }
+
+  foreach (@opts_groffer_long_na, @opts_groff_long_na,
+	   @opts_x_long_na, @opts_man_long_na, @opts_ignored_long_na) {
+    $Opts_Cmdline_Long{"--$_"} = 0 if $_;
+  }
+  foreach (@opts_groffer_long_arg, @opts_groff_long_arg,
+	   @opts_x_long_arg, @opts_man_long_arg, @opts_ignored_long_arg) {
+    $Opts_Cmdline_Long{"--$_"} = 1 if $_;
+  }
+
+  # For determining abbreviations of an option take two spaces as join
+  # for better check.
+  # The options are without leading minus.
+  $Opts_Cmdline_Long_Str = join '  ', keys %Opts_Cmdline_Long;
+  if ($Opts_Cmdline_Long_Str) {
+    $Opts_Cmdline_Long_Str = " $Opts_Cmdline_Long_Str ";
+    $Opts_Cmdline_Long_Str =~ s/--//g;
+  }
+
+### main_set_options()
+  # options with equal meaning are mapped to a single option name
+  # all of these have leading minus characters
+  %Opts_Cmdline_Double = ('-h' => '--help',
+			  '-Q' => '--source',
+			  '-T' => '--device',
+			  '-v' => '--version',
+			  '-Z' => '--intermediate-output',
+			  '--bd' => '--bordercolor',
+			  '--bg' => '--background',
+			  '--bw' => '--borderwidth',
+			  '--debug-all' => '--debug',
+			  '--ditroff' => '--intermediate-output',
+			  '--dvi-viewer-tty' => '--dvi-viewer',
+			  '--fg' => '--foreground',
+			  '--fn' => '--font',
+			  '--ft' => '--font',
+			  '--html-viewer-tty' => '--html-viewer',
+			  '--pdf-viewer-tty' => '--pdf-viewer',
+			  '--ps-viewer-tty' => '--ps-viewer',
+			  '--troff-device' => '--device',
+			  '--tty-device' => '--text-device',
+			  '--tty-viewer' => '--pager',
+			  '--tty-viewer-tty' => '--pager',
+			  '--where' => '--location',
+			  '--www' => '--html',
+			  '--www-viewer' => '--html-viewer',
+			  '--www-viewer-tty' => '--html-viewer',
+			  '--x-viewer-tty' => '--x-viewer',
+			  '--X' => '--x',
+			  '--X-viewer' => '--x-viewer',
+			  '--X-viewer-tty' => '--x-viewer',
+			 );
+
+  # groff short options with leading minus
+  foreach (@opts_groff_short_na) {
+    $Opts_Groff_Short{"-$_"} = 0;
+  }
+  foreach (@opts_groff_short_arg) {
+    $Opts_Groff_Short{"-$_"} = 1;
+  }
+
+}				# main_set_options()
+
+
+########################################################################
+# $MANOPT, main_parse_MANOPT()
+########################################################################
+
+# handle environment variable $MANOPT
+my @Manopt;
+
+sub main_parse_MANOPT {
+  if ($ENV{'MANOPT'}) {
+    @Manopt = `sh $File_split_env_sh MANOPT`;
+    chomp @Manopt;
+
+    my @manopt;
+    # %opts stores options that are used by groffer for $MANOPT
+    # All options not in %opts are ignored.
+    # Check options used with %Opts_Cmdline_Double.
+    # 0: option used ('' for ignore), 1: has argument or not
+### main_parse_MANOPT()
+    my %opts = ('-7' => ['--ascii', 0],
+		'--ascii' => ['--ascii', 0],
+		'-a' => ['--all', 0],
+		'--all' => ['--all', 0],
+		'-c' => ['', 1],
+		'--catman' => ['', 1],
+		'-e' => ['--extension', 1],
+		'--extension' => ['--extension', 1],
+		'-f' => ['--whatis', 1],
+		'--whatis' => ['--whatis', 1],
+		'-L' => ['--locale', 1],
+		'--locale' => ['--locale', 1],
+		'-m' => ['--systems', 1],
+		'--systems' => ['--systems', 1],
+		'-M' => ['--manpath', 1],
+		'-manpath' => ['--manpath', 1],
+		'--manpath' => ['--manpath', 1],
+		'-p' => ['', 1],
+		'--preprocessor' => ['', 1],
+		'-P' => ['--pager', 1],
+		'-pager' => ['--pager', 1],
+		'-r' => ['', 1],
+		'-prompt' => ['', 1],
+		'-S' => ['--sections', 1],
+		'-sections' => ['--sections', 1],
+		'-T' => ['-T', 1],
+		'--device' => ['-T', 1],
+		'-w' => ['--location', 0],
+		'--where' => ['--location', 0],
+		'--location' => ['--location', 0],
+	       );
+
+### main_parse_MANOPT()
+    my ($opt, $has_arg);
+    my $i = 0;
+    my $n = $#Manopt;
+    while ($i <= $n) {
+      my $o = $Manopt[$i];
+      ++$i;
+      # ignore, when not in %opts
+      next unless (exists $opts{$o});
+      if (($o eq '-D') or ($o eq '--default')) {
+	@manopt = ();
+	next;
+      }
+      $opt = $opts{$o}[0];
+      $has_arg = $opts{$o}[1];
+      # ignore, when empty in %opts
+      unless ($opt) {
+	# ignore without argument
+	next unless ($has_arg);
+	# ignore the argument as well
+	++$i;
+	next;
+      }
+      if ($has_arg) {
+	last if ($i > $n);
+	push @manopt, $opt, $Manopt[$i];
+	++$i;
+	next;
+      } else {
+	push @manopt, $opt;
+	next;
+      }
+    }
+    @Manopt = @manopt;
+  }
+}				# main_parse_MANOPT()
+
+
+########################################################################
+# configuration files, $GROFFER_OPT, and command line, main_config_params()
+########################################################################
+
+my @Options;
+my @Filespecs;
+my @Starting_Conf;
+my @Starting_ARGV = @ARGV;
+sub main_config_params {	# handle configuration files
+  # options may not be abbreviated, but must be exact
+  my @conf_args;
+  foreach my $f (@Conf_Files) {
+    if (-s $f) {
+      my $fh;
+      open $fh, "<$f" || next;
+      my $nr = 0;
+    LINE: foreach my $line (<$fh>) {
+	++ $nr;
+	chomp $line;
+	# remove starting and ending whitespace
+	$line =~ s/^\s+|\s+$//g;
+	# replace whitespace by single space
+	$line =~ s/\s+/ /g;
+	# ignore all lines that do not start with minus
+	next unless $line =~ /^-/;
+	# three minus
+	if ($line =~ /^---/) {
+	  warn "Wrong option $line in configuration file $f.\n";
+	  next;
+	}
+	if ($line =~ /^--[ =]/) {
+	  warn "No option name in `$line' in configuration " .
+	    "file $f.\n";
+	  next;
+	}
+	push @Starting_Conf, $line;
+	# -- or -
+	if ($line =~ /^--?$/) {
+	  warn "`$line' is not allowed in configuration files.\n";
+	  next;
+	}
+	### main_config_params()
+	if ($line =~ /^--/) {	# line is long option
+	  my ($name, $arg);
+	  if ($line =~ /[ =]/) { # has arg on line
+	    $line =~ /^(--[^ =]+)[ =] ?(.*)$/;
+	    ($name, $arg) = ($1, $2);
+	    $arg =~ s/[\'\"]//g;
+	  } else {		# does not have an argument on line
+	    $name = $line;
+	  }
+	  $name =~ s/[\'\"]//g;
+	  unless (exists $Opts_Cmdline_Long{$name}) {
+	    # option does not exist
+	    warn "Option `$name' does not exist.\n";
+	    next LINE;
+	  }
+	  # option exists
+	  if ($Opts_Cmdline_Long{$name}) { # option has arg
+	    if (defined $arg) {
+	      push @conf_args, $name, $arg;
+	      next LINE;
+	    } else {
+	      warn "Option `$name' needs an argument in " .
+		"configuration file $f\n";
+	      next LINE;
+	    }
+	  } else {		# option has no arg
+	    if (defined $arg) {
+	      warn "Option `$name' may not have an argument " .
+		"in configuration file $f\n";
+	      next LINE;
+	    } else {
+	      push @conf_args, $name;
+	      next LINE;
+	    }
+	  }
+	  ### main_config_params()
+	} else {		# line is short option or cluster
+	  $line =~ s/^-//;
+	  while ($line) {
+	    $line =~ s/^(.)//;
+	    my $opt = "-$1";
+	    next if ($opt =~ /\'\"/);
+	    if ($opt =~ /- /) {
+	      warn "Option `$conf_args[$#conf_args]' does not " .
+		"have an argument.\n";
+	      next LINE;
+	    }
+	    if (exists $Opts_Cmdline_Short{$opt}) {
+	      # short opt exists
+	      push @conf_args, $opt;
+	      if ($Opts_Cmdline_Short{$opt}) { # with arg
+		my $arg = $line;
+		$arg =~ s/^ //;
+		$arg =~ s/\'\"//g;
+		push @conf_args, "$arg";
+		next LINE;
+	      } else {		# no arg
+		next;
+	      }
+	    } else {		# short option does not exist
+	      warn "Wrong short option `-$opt' from " .
+		"configuration.  Rest of line ignored.\n";
+	      next LINE;
+	    }
+	  }
+	}
+      }
+      close $fh;
+    }
+  }
+
+### main_config_params()
+  # handle environment variable $GROFFER_OPT
+  my @GROFFER_OPT;
+  if ($ENV{'GROFFER_OPT'}) {
+    @GROFFER_OPT = `sh $File_split_env_sh GROFFER_OPT`;
+    chomp @GROFFER_OPT;
+  }
+
+  # Handle command line parameters together with $GROFFER_OPT.
+  # Options can be abbreviated, with each - as abbreviation place.
+  {
+    my @argv0 = (@GROFFER_OPT, @ARGV);
+    my @argv;
+    my $only_files = 0;
+    my $n = $#argv0;		  # last element
+    my $n1 = scalar @GROFFER_OPT; # first element of @ARGV
+    my $i = 0;			# number of the element
+    my @s = ('the environment variable $GROFFER_OPT', 'the command line');
+    my $j = 0;			# index in @s, 0 before $n1, 1 then
+  ELT: while ($i <= $n) {
+      my $elt = $argv0[$i];
+      $j = 1 if $i >= $n1;
+      ++$i;
+      # remove starting and ending whitespace
+      $elt =~ s/^\s+|\s+$//g;
+      # replace whitespace by single space
+      $elt =~ s/\s+/ /g;
+
+      if ($only_files) {
+	push @Filespecs, $elt;
+	next ELT;
+      }
+
+### main_config_params()
+      if ($elt =~ /^-$/) {	# -
+	push @Filespecs, $elt;
+	next ELT;
+      }
+      if ($elt =~ /^--$/) {	# --
+	$only_files = 1;
+	next ELT;
+      }
+
+      if ($elt =~ /^--[ =]/) {	# no option name
+	warn "No option name in `$elt' at $s[$j].\n";
+	next ELT;
+      }
+      if ($elt =~ /^---/) {	# wrong with three minus
+	warn "Wrong option `$elt' at $s[$j].\n";
+	next ELT;
+      }
+
+      if ($elt =~ /^--[^-]/) {	# long option
+	my ($name, $opt, $abbrev, $arg);
+	if ($elt =~ /[ =]/) {	# has arg on elt
+	  $elt =~ /^--([^ =]+)[ =] ?(.*)$/;
+	  ($name, $arg) = ($1, $2);
+	  $opt = "--$name";
+	  $abbrev = $name;
+	  $arg =~ s/[\'\"]//g;
+	} else {		# does not have an argument in the element
+	  $opt = $name = $elt;
+	  $name =~ s/^--//;
+	  $abbrev = $name;
+	}
+### main_config_params()
+	# remove quotes in name
+	$name =~ s/[\'\"]//g;
+	my $match = $name;
+	$match =~ s/-/[^- ]*-/g;
+	### main_config_params()
+	if (exists $Opts_Cmdline_Long{$opt}) {
+	  # option exists exactly
+	} elsif ($Opts_Cmdline_Long_Str =~ / (${match}[^- ]*?) /) {
+	  # option is an abbreviation without further -
+	  my $n0 = $1;
+	  if ($Opts_Cmdline_Long_Str =~
+	      / (${match}[^- ]*) .* (${match}[^- ]*) /) {
+	    warn "Option name `--$abbrev' is not unique: " .
+	      "--$1 --$2 \n";
+	    next ELT;
+	  }
+	  $name = $n0;
+	  $opt = "--$n0";
+	} elsif ($Opts_Cmdline_Long_Str =~ / (${match}[^ ]*) /) {
+	  # option is an abbreviation with further -
+	  my $n0 = $1;
+	  if ($Opts_Cmdline_Long_Str =~
+	      / (${match}[^ ]*) .* (${match}[^ ]*) /) {
+	    warn "Option name `--$abbrev' is not unique: " .
+	      "--$1 --$2 \n";
+	    next ELT;
+	  }
+	  $name = $n0;
+	  $opt = "--$n0";
+	} else {
+	  warn "Option `--$abbrev' does not exist.\n";
+	  next ELT;
+	}
+### main_config_params()
+	if ($Opts_Cmdline_Long{$opt}) { # option has arg
+	  if (defined $arg) {
+	    push @argv, "--$name", $arg;
+	    next ELT;
+	  } else {		# $arg not defined, argument at next element
+	    if (($i == $n1) || ($i > $n)) {
+	      warn "No argument left for option " .
+		"`$elt' at $s[$j].\n";
+	      next ELT;
+	    }
+	    ### main_config_params()
+	    # add argument as next element
+	    push @argv, "--$name", $argv0[$i];
+	    ++$i;
+	    next ELT;
+	  }			# if (defined $arg)
+	} else {		# option has no arg
+	  if (defined $arg) {
+	    warn "Option `$abbrev' may not have an argument " .
+	      "at $s[$j].\n";
+	    next ELT;
+	  } else {
+	    push @argv, "--$name";
+	    next ELT;
+	  }
+	}			# if ($Opts_Cmdline_Long{$opt})
+### main_config_params()
+      } elsif ($elt =~ /^-[^-]/) { # short option or cluster
+	my $cluster = $elt;
+	$cluster =~ s/^-//;
+	while ($cluster) {
+	  $cluster =~ s/^(.)//;
+	  my $opt = "-$1";
+	  if (exists $Opts_Cmdline_Short{$opt}) { # opt exists
+	    if ($Opts_Cmdline_Short{$opt}) { # with arg
+	      if ($cluster) {	# has argument in this element
+		$cluster =~ s/^ //;
+		$cluster =~ s/\'\"//g;
+				# add argument as rest of this element
+		push @argv, $opt, $cluster;
+		next ELT;
+	      } else {		# argument at next element
+		if (($i == $n1) || ($i > $n)) {
+		  warn "No argument left for option " .
+		    "`$opt' at $s[$j].\n";
+		  next ELT;
+		}
+		### main_config_params()
+				# add argument as next element
+		push @argv, $opt, $argv0[$i];
+		++$i;
+		next ELT;
+	      }
+	    } else {		# no arg
+	      push @argv, $opt;
+	      next;
+	    }
+	  } else {		# short option does not exist
+	    warn "Wrong short option `$opt' at $s[$j].\n";
+	    next ELT;
+	  }			# if (exists $Opts_Cmdline_Short{$opt})
+	}			# while ($cluster)
+      } else {			# not an option, file name
+	push @Filespecs, $elt;
+	next;
+      }
+    }
+### main_config_params()
+    @Options = (@Manopt, @conf_args, @argv);
+    foreach my $i (0..$#Options) {
+      if ( exists $Opts_Cmdline_Double{ $Options[$i] } ) {
+	$Options[$i] = $Opts_Cmdline_Double{ $Options[$i] };
+      }
+    }
+    @Filespecs = ('-') unless (@Filespecs);
+    @ARGV = (@Options, '--', @Filespecs);
+  }
+} # main_config_params()
+
+if (0) {
+  print STDERR "<$_>\n" foreach @ARGV;
+}
+
+
+########################################################################
+# main_parse_params()
+########################################################################
+
+my $i;
+my $n;
+
+$Opt{'XRM'} = [];
+
+sub main_parse_params {
+  $i = 0;
+  $n = $#Options;
+
+  # options that are ignored in this part
+  # shell version of groffer: --debug*, --shell
+  # man options: --catman (only special in man),
+  #              --preprocessor (force groff preproc., handled by grog),
+  #              --prompt (prompt for less, ignored),
+  #              --troff (-mandoc, handled by grog),
+  #              --update (inode check, ignored)
+  my %ignored_opts = (
+		      '--catman' => 0,
+		      '--debug-func' => 0,
+		      '--debug-not-func' => 0,
+		      '--debug-lm' => 0,
+		      '--debug-shell' => 0,
+		      '--debug-stacks' => 0,
+		      '--debug-user' => 0,
+		      '--preprocessor' => 1,
+		      '--prompt' => 1,
+		      '--shell' => 1,
+		      '--troff' => 0,
+		      '--update' => 0,
+		     );
+
+### main_parse_params()
+  my %long_opts =
+    (
+     '--debug' =>
+     sub { $Debug{$_} = 1 foreach (qw/FILENAMES GROG KEEP PARAMS TMPDIR/); },
+     '--debug-filenames' => sub { $Debug{'FILENAMES'} = 1; },
+     '--debug-grog' => sub { $Debug{'GROG'} = 1; },
+     '--debug-keep' => sub { $Debug{'KEEP'} = 1; $Debug{'PARAMS'} = 1; },
+     '--debug-params' => sub { $Debug{'PARAMS'} = 1; },
+     '--debug-tmpdir' => sub { $Debug{'TMPDIR'} = 1; },
+     '--help' => sub { &usage(); $Opt{'DO_NOTHING'} = 1; },
+     '--source' => sub { $Opt{'MODE'} = 'source'; },
+     '--device' =>
+     sub {  $Opt{'DEVICE'} = &_get_arg();
+	    my %modes = ( 'dvi'=> 'dvi',
+			  'html' => 'html',
+			  'lbp' => 'groff',
+			  'lj4' => 'groff',
+			  'ps' => 'ps',
+			  'ascii' => 'tty',
+			  'cp1047' => 'tty',
+			  'latin1' => 'tty',
+			  'utf8' => 'tty',
+			);
+	    if ($Opt{'DEVICE'} =~ /^X.*/) {
+	      $Opt{'MODE'} = 'x';
+	    } elsif ( exists $modes{ $Opt{'DEVICE'} } ) {
+	      if ( $modes{ $Opt{'DEVICE'} } eq 'tty' ) {
+		$Opt{'MODE'} = 'tty'
+		  unless ($Opt{'MODE'} eq 'text');
+	      } else {
+		$Opt{'MODE'} = $modes{ $Opt{'DEVICE'} };
+	      }
+	    } else {
+	      # for all elements not in %modes
+	      $Opt{'MODE'} = 'groff';
+	    }
+	  },
+### main_parse_params()
+     '--version' => sub { &version(); $Opt{'DO_NOTHING'} = 1; },
+     '--intermediate-output' => sub { $Opt{'Z'} = 1; },
+     '--all' => sub { $Opt{'ALL'} = 1; },
+     '--apropos' =>		# run apropos
+     sub { $Opt{'APROPOS'} = 1;
+	   delete $Opt{'APROPOS_SECTIONS'};
+	   delete $Opt{'WHATIS'}; },
+     '--apropos-data' =>	# run apropos for data sections
+     sub { $Opt{'APROPOS'} = 1;
+	   $Opt{'APROPOS_SECTIONS'} = '457';
+	   delete $Opt{'WHATIS'}; },
+     '--apropos-devel' =>	# run apropos for devel sections
+     sub { $Opt{'APROPOS'} = 1;
+	   $Opt{'APROPOS_SECTIONS'} = '239';
+	   delete $Opt{'WHATIS'}; },
+     '--apropos-progs' =>	# run apropos for prog sections
+     sub { $Opt{'APROPOS'} = 1;
+	   $Opt{'APROPOS_SECTIONS'} = '168';
+	   delete $Opt{'WHATIS'}; },
+     '--ascii' =>
+     sub { push @Addopts_Groff, '-mtty-char';
+	   $Opt{'MODE'} = 'text' unless $Opt{'MODE'}; },
+     '--auto' =>		# the default automatic mode
+     sub { delete $Opt{'MODE'}; },
+     '--bordercolor' =>		# border color for viewers, arg
+     sub { $Opt{'BD'} = &_get_arg(); },
+     '--background' =>		# background color for viewers, arg
+     sub { $Opt{'BG'} = &_get_arg(); },
+### main_parse_params()
+     '--borderwidth' =>		# border width for viewers, arg
+     sub { $Opt{'BW'} = &_get_arg(); },
+     '--default' =>		# reset variables to default
+     sub { %Opt = (); },
+     '--default-modes' =>	# sequence of modes in auto mode; arg
+     sub { $Opt{'DEFAULT_MODES'} = &_get_arg(); },
+     '--display' =>		# set X display, arg
+     sub { $Opt{'DISPLAY'} = &_get_arg(); },
+     '--do-nothing' => sub { $Opt{'DO_NOTHING'} = 1; },
+     '--dvi' => sub { $Opt{'MODE'} = 'dvi'; },
+     '--dvi-viewer' =>		# viewer program for dvi mode; arg
+     sub { $Opt{'VIEWER_DVI'} = &_get_arg(); },
+     '--extension' =>		# the extension for man pages, arg
+     sub { $Opt{'EXTENSION'} = &_get_arg(); },
+     '--foreground' =>		# foreground color for viewers, arg
+     sub { $Opt{'FG'} = &_get_arg(); },
+     '--font' =>		# set font for viewers, arg
+     sub { $Opt{'FN'} = &_get_arg(); },
+     '--geometry' =>		# window geometry for viewers, arg
+     sub { $Opt{'GEOMETRY'} = &_get_arg(); },
+     '--groff' => sub { $Opt{'MODE'} = 'groff'; },
+     '--html' => sub { $Opt{'MODE'} = 'html'; },
+     '--html-viewer' =>		# viewer program for html mode; arg
+     sub { $Opt{'VIEWER_HTML'} = &_get_arg(); },
+     '--iconic' =>		# start viewers as icons
+     sub { $Opt{'ICONIC'} = 1; },
+     '--locale' =>		# set language for man pages, arg
+     # argument is xx[_territory[.codeset[@modifier]]] (ISO 639,...)
+     sub { $Opt{'LANG'} = &_get_arg(); },
+     '--local-file' =>		# force local files; same as `--no-man'
+     sub { delete $Man{'ENABLE'}; delete $Man{'FORCE'}; },
+     '--location' =>		# print file locations to stderr
+     sub { $Opt{'LOCATION'} = 1; },
+### main_parse_params()
+     '--man' =>			# force all file params to be man pages
+     sub { $Man{'ENABLE'} = 1; $Man{'FORCE'} = 1; },
+     '--manpath' =>		# specify search path for man pages, arg
+     # arg is colon-separated list of directories
+     sub { $Opt{'MANPATH'} = &_get_arg(); },
+     '--mode' =>		# display mode
+     sub { my $arg = &_get_arg();
+	   my %modes = ( '' => '',
+			 'auto' => '',
+			 'groff' => 'groff',
+			 'html' => 'html',
+			 'www' => 'html',
+			 'dvi' => 'dvi',
+			 'pdf' => 'pdf',
+			 'ps' => 'ps',
+			 'text' => 'text',
+			 'tty' => 'tty',
+			 'X' => 'x',
+			 'x' => 'x',
+			 'Q' => 'source',
+			 'source' => 'source',
+		       );
+	   if ( exists $modes{$arg} ) {
+	     if ( $modes{$arg} ) {
+	       $Opt{'MODE'} = $modes{$arg};
+	     } else {
+	       delete $Opt{'MODE'};
+	     }
+	   } else {
+	     warn "Unknown mode in `$arg' for --mode\n";
+	   }
+	 },
+### main_parse_params()
+     '--no-location' =>		# disable former call to `--location'
+     sub { delete $Opt{'LOCATION'}; },
+     '--no-man' =>		# disable search for man pages
+     sub { delete $Man{'ENABLE'}; delete $Man{'FORCE'}; },
+     '--no-special' =>		# disable some special former calls
+     sub { delete $Opt{'ALL'}; delete $Opt{'APROPOS'};
+	   delete $Opt{'WHATIS'}; },
+     '--pager' =>		# set paging program for tty mode, arg
+     sub { $Opt{'PAGER'} = &_get_arg(); },
+     '--pdf' => sub { $Opt{'MODE'} = 'pdf'; },
+     '--pdf-viewer' =>		# viewer program for pdf mode; arg
+     sub { $Opt{'VIEWER_PDF'} = &_get_arg(); },
+     '--print' =>		# print argument, for argument test
+     sub { my $arg = &_get_arg; print STDERR "$arg\n"; },
+     '--ps' => sub { $Opt{'MODE'} = 'ps'; },
+     '--ps-viewer' =>		# viewer program for ps mode; arg
+     sub { $Opt{'VIEWER_PS'} = &_get_arg(); },
+     '--resolution' =>		# set resolution for X devices, arg
+     sub { my $arg = &_get_arg();
+	   my %res = ( '75' => 75,
+		       '75dpi' => 75,
+		       '100' => 100,
+		       '100dpi' => 100,
+		     );
+	   if (exists $res{$arg}) {
+	     $Opt{'RESOLUTION'} = $res{$arg};
+	   } else {
+	     warn "--resolution allows only 75, 75dpi, " .
+	       "100, 100dpi as argument.\n";
+	   }
+	 },
+### main_parse_params()
+     '--rv' => sub { $Opt{'RV'} = 1; },
+     '--sections' =>		# specify sections for man pages, arg
+     # arg is a `:'-separated (colon) list of section names
+     sub { my $arg = &_get_arg();
+	   my @arg = split /:/, $arg;
+	   my $s;
+	   foreach (@arg) {
+	     /^(.)/;
+	     my $c = $1;
+	     if ($Man{'AUTO_SEC_CHARS'} =~ /$c/) {
+	       $s .= $c;
+	     } else {
+	       warn "main_parse_params(): not a man section `$c';";
+	     }
+	   }
+	   $Opt{'SECTIONS'} = $s; },
+     '--systems' =>		# man pages for different OS's, arg
+     # argument is a comma-separated list
+     sub { $Opt{'SYSTEMS'} = &_get_arg(); },
+     '--text' =>		# text mode without pager
+     sub { $Opt{'MODE'} = 'text'; },
+     '--title' =>		# title for X viewers; arg
+     sub { my $arg = &_get_arg();
+	   if ($arg) {
+	     if ( $Opt{'TITLE'} ) {
+	       $Opt{'TITLE'} = "$Opt{'TITLE'} $arg";
+	     } else {
+	       $Opt{'TITLE'} = $arg;
+	     }
+	   }
+	 },
+     '--tty' =>			# tty mode, text with pager
+     sub { $Opt{'MODE'} = 'tty'; },
+     '--to-stdout' =>		# print mode file without display
+     sub { $Opt{'STDOUT'} = 1; },
+     '--text-device' =>		# device for tty mode; arg
+     sub { $Opt{'TEXT_DEVICE'} = &_get_arg(); },
+     '--whatis' => sub { delete $Opt{'APROPOS'}; $Opt{'WHATIS'} = 1; },
+     '--x' => sub { $Opt{'MODE'} = 'x'; },
+### main_parse_params()
+     '--xrm' =>			# pass X resource string, arg
+     sub { my $arg = &_get_arg(); push @{$Opt{'XRM'}}, $arg if $arg; },
+     '--x-viewer' =>		# viewer program for x mode; arg
+     sub { $Opt{'VIEWER_X'} = &_get_arg(); },
+    );
+
+  my %short_opts = (
+		    '-V' => sub { $Opt{'V'} = 1; },
+		    '-X' => sub { $Opt{'X'} = 1; },
+		   );
+
+  if (0) {
+    # check if all options are handled in parse parameters
+
+    #short options
+    my %these_opts = (%ignored_opts, %short_opts, %Opts_Groff_Short,
+		      %Opts_Cmdline_Double);
+    foreach my $key (keys %Opts_Cmdline_Short) {
+      warn "unused option: $key" unless exists $these_opts{$key};
+    }
+
+    # long options
+    %these_opts = (%ignored_opts, %long_opts, %Opts_Cmdline_Double);
+    foreach my $key (keys %Opts_Cmdline_Long) {
+      warn "unused option: $key" unless exists $these_opts{$key};
+    }
+  }				# if (0)
+
+### main_parse_params()
+ OPTION: while ($i <= $n) {
+    my $opt = $Options[$i];
+    ++$i;
+    if ($opt =~ /^-([^-])$/) {	# single minus for short option
+      if (exists $short_opts{$opt}) { # short option handled by hash
+	$short_opts{$opt}->();
+	next OPTION;
+      } else {			# $short_opts{$opt} does not exist
+	my $c = $1;		# the option character
+	next OPTION unless $c;
+	if ( exists $Opts_Groff_Short{ $opt } ) { # groff short option
+	  if ( $Opts_Groff_Short{ $opt } ) { # option has argument
+	    my $arg = $Options[$i];
+	    ++$i;
+	    push @Addopts_Groff, $opt, $arg;
+	    next OPTION;
+	  } else {		# no argument for this option
+	    push @Addopts_Groff, $opt;
+	    next OPTION;
+	  }
+	} elsif ( exists $Opts_Cmdline_Short{ $opt } ) {
+	  # is a groffer short option
+	  warn "Groffer option $opt not handled " .
+	    "in parameter parsing";
+	} else {
+	  warn "$opt is not a groffer option.\n";
+	}
+      }				# if (exists $short_opts{$opt})
+    }				# if ($opt =~ /^-([^-])$/)
+    # Now it is a long option
+
+    # handle ignored options
+    if ( exists $ignored_opts{ $opt } ) {
+      ++$i if ( $ignored_opts{ $opt } );
+      next OPTION;
+    }
+### main_parse_params()
+
+    # handle normal long options
+    if (exists $long_opts{$opt}) {
+      $long_opts{$opt}->();
+    } else {
+      warn "Unknown option $opt.\n";
+    }
+    next OPTION;
+  }				# while ($i <= $n)
+
+  if ($Debug{'PARAMS'}) {
+    print STDERR '$MANOPT: ' . "$ENV{'MANOPT'}\n" if $ENV{'MANOPT'};
+    foreach (@Starting_Conf) {
+      print STDERR "configuration: $_\n";
+    }
+    print STDERR '$GROFFER_OPT: ' . "$ENV{'GROFFER_OPT'}\n"
+      if $ENV{'GROFFER_OPT'};
+    print STDERR "command line: @Starting_ARGV\n";
+    print STDERR "parameters: @ARGV\n";
+  }
+
+  if ( $Opt{'WHATIS'} ) {
+    die "main_parse_params(): cannot handle both `whatis' and `apropos';"
+      if $Opt{'APROPOS'};
+    $Man{'ALL'} = 1;
+    delete $Opt{'APROPOS_SECTIONS'};
+  }
+
+  if ( $Opt{'DO_NOTHING'} ) {
+    exit;
+  }
+
+  if ( $Opt{'DEFAULT_MODES'} ) {
+    @Default_Modes = split /,/, $Opt{'DEFAULT_MODES'};
+  }
+}				# main_parse_params()
+
+
+sub _get_arg {
+  if ($i > $n) {
+    die '_get_arg(): No argument left for last option;';
+  }
+  my $arg = $Options[$i];
+  ++$i;
+  $arg;
+}				# _get_arg() of main_parse_params()
+
+
+########################################################################
+# main_set_mode()
+########################################################################
+
+my $Viewer_Background;
+my $PDF_Did_Not_Work;
+my $PDF_Has_gs;
+my $PDF_Has_ps2pdf;
+my %Display = ('MODE' => '',
+	       'PROG' => '',
+	       'ARGS' => ''
+	      );
+
+sub main_set_mode {
+  my @modes;
+
+  # set display
+  $ENV{'DISPLAY'} = $Opt{'DISPLAY'} if $Opt{'DISPLAY'};
+
+  push @Addopts_Groff, '-V' if $Opt{'V'};
+
+  if ( $Opt{'X'} ) {
+    $Display{'MODE'} = 'groff';
+    push @Addopts_Groff, '-X';
+  }
+
+  if ( $Opt{'Z'} ) {
+    $Display{'MODE'} = 'groff';
+    push @Addopts_Groff, '-Z';
+  }
+
+  $Display{'MODE'} = 'groff' if $Opt{'MODE'} and $Opt{'MODE'} eq 'groff';
+
+  return 1 if $Display{'MODE'} and $Display{'MODE'} eq 'groff';
+
+### main_set_mode()
+  if ($Opt{'MODE'}) {
+    if ($Opt{'MODE'} =~ /^(source|text|tty)$/) {
+      $Display{'MODE'} = $Opt{'MODE'};
+      return 1;
+    }
+    $Display{'MODE'} = $Opt{'MODE'} if $Opt{'MODE'} =~ /^html$/;
+    @modes = ($Opt{'MODE'});
+  } else {			# empty mode
+    if ($Opt{'DEVICE'}) {
+      if ($Opt{'DEVICE'} =~ /^X/) {
+	&is_X() || die "no X display found for device $Opt{'DEVICE'}";
+	$Display{'MODE'} = 'x';
+	return 1;
+      }
+      ;
+      if ($Opt{'DEVICE'} =~ /^(ascii|cp1047|latin1|utf8)$/) {
+	$Display{'MODE'} ne 'text' and $Display{'MODE'} = 'tty';
+	return 1;
+      }
+      ;
+      unless (&is_X) {
+	$Display{'MODE'} = 'tty';
+	return 1;
+      }
+    }				# check device
+    @modes = @Default_Modes;
+  }				# check mode
+
+### main_set_mode()
+ LOOP: foreach my $m (@modes) {
+    $Viewer_Background = 0;
+    if ($m =~ /^(test|tty|X)$/) {
+      $Display{'MODE'} = $m;
+      return 1;
+    } elsif ($m eq 'pdf') {
+      next LOOP if $PDF_Did_Not_Work;
+      $PDF_Has_gs = &where_is_prog('gs') ? 1 : 0
+	unless (defined $PDF_Has_gs);
+      $PDF_Has_ps2pdf = &where_is_prog('ps2pdf') ? 1 : 0
+	unless (defined $PDF_Has_ps2pdf);
+      if ( (! $PDF_Has_gs) and (! $PDF_Has_ps2pdf) ) {
+	$PDF_Did_Not_Work = 1;
+	next LOOP;
+      }
+
+      if (&_get_prog_args($m)) {
+	return 1;
+      } else {
+	$PDF_Did_Not_Work = 1;
+	next LOOP;
+      }
+    } else {			# other modes
+      &_get_prog_args($m) ? return 1 : next LOOP;
+    }				# if $m
+  }				# LOOP: foreach
+  die 'set mode: no suitable display mode found under ' .
+    join(', ', @modes) . ';' unless $Display{'MODE'};
+  die 'set mode: no viewer available for mode ' . $Display{'MODE'} . ';'
+    unless $Display{'PROG'};
+  0;
+} # main_set_mode()
+
+
+########################################################################
+# functions to main_set_mode()
+########################################################################
+
+##########
+# _get_prog_args(<MODE>)
+#
+# Simplification for loop in set mode.
+#
+# Globals in/out: $Viewer_Background
+# Globals in    : $Opt{VIEWER_<MODE>}, $Viewer_X{<MODE>},
+#                 $Viewer_tty{<MODE>}
+#
+sub _get_prog_args {
+  my $n = @_;
+  die "_get_prog_args(): one argument is needed; you used $n;"
+    unless $n == 1;
+
+  my $mode = lc($_[0]);
+  my $MODE = uc($mode);
+
+  my $xlist = $Viewer_X{$MODE};
+  my $ttylist = $Viewer_tty{$MODE};
+
+  my $vm = "VIEWER_${MODE}";
+  my $opt = $Opt{$vm};
+
+  if ($opt) {
+    my %prog = where_is_prog $opt;
+    my $prog_ref = \%prog;
+    unless (%prog) {
+      warn "_get_prog_args(): `$opt' is not an existing program;";
+      return 0;
+    }
+
+    # $prog from $opt is an existing program
+
+### _get_prog_args() of main_set_mode()
+    if (&is_X) {
+      if ( &_check_prog_on_list($prog_ref, $xlist) ) {
+	$Viewer_Background = 1;
+      } else {
+	$Viewer_Background = 0;
+	&_check_prog_on_list($prog_ref, $ttylist);
+      }
+    } else {			# is not X
+      $Viewer_Background = 0;
+      &_check_prog_on_list($prog_ref, $ttylist);
+    }				# if is X
+  } else {			# $opt is empty
+    $Viewer_Background = 0;
+    my $x;
+    if (&is_X) {
+      $x = &_get_first_prog($xlist);
+      $Viewer_Background = 1 if $x;
+    } else {			# is not X
+      $x = &_get_first_prog($ttylist);
+    }				# test on X
+    $Display{'MODE'} = $mode if $x;
+    return $x;
+  }
+  $Display{'MODE'} = $mode;
+  return 1;
+} # _get_prog_args() of main_set_mode()
+
+
+##########
+# _get_first_prog(<prog_list_ref>)
+#
+# Retrieve from the elements of the list in the argument the first
+# existing program in $PATH.
+#
+# Local function of main_set_mode().
+#
+# Return  : `0' if not a part of the list, `1' if found in the list.
+#
+sub _get_first_prog {
+  my $n = @_;
+  die "_get_first_prog(): one argument is needed; you used $n;"
+    unless $n == 1;
+
+  foreach my $i (@{$_[0]}) {
+    next unless $i;
+    my %prog = &where_is_prog($i);
+    if (%prog) {
+      $Display{'PROG'} = $prog{'fullname'};
+      $Display{'ARGS'} = $prog{'args'};
+      return 1;
+    }
+  }
+  return 0;
+} # _get_first_prog() of main_set_mode()
+
+
+##########
+# _check_prog_on_list (<prog-hash-ref> <prog_list_ref>)
+#
+# Check whether the content of <prog-hash-ref> is in the list
+# <prog_list_ref>.
+# The globals are set correspondingly.
+#
+# Local function for main_set_mode().
+#
+# Arguments: 2
+#
+# Return  : `0' if not a part of the list, `1' if found in the list.
+# Output  : none
+#
+# Globals in    : $Viewer_X{<MODE>}, $Viewer_tty{<MODE>}
+# Globals in/out: $Display{'PROG'}, $Display{'ARGS'}
+#
+sub _check_prog_on_list {
+  my $n = @_;
+  die "_get_first_prog(): 2 arguments are needed; you used $n;"
+    unless $n == 2;
+
+  my %prog = %{$_[0]};
+
+  $Display{'PROG'} = $prog{'fullname'};
+  $Display{'ARGS'} = $prog{'args'};
+
+  foreach my $i (@{$_[1]}) {
+    my %p = &where_is_prog($i);
+    next unless %p;
+    next unless $Display{'PROG'} eq $p{'fullname'};
+    if ($p{'args'}) {
+      if ($Display{'ARGS'}) {
+	$Display{'ARGS'} = $p{'args'};
+      } else {
+	$Display{'ARGS'} = "$p{'args'} $Display{'ARGS'}";
+      }
+    }				# if args
+    return 1;
+  }				# foreach $i
+  # prog was not in the list
+  return 0;
+} # _check_prog_on_list() of main_set_mode()
+
+
+########################################################################
+# groffer temporary directory, main_temp()
+########################################################################
+
+sub main_temp {
+  my $template = 'groffer_' . "$$" . '_XXXX';
+  foreach ($ENV{'GROFF_TMPDIR'}, $ENV{'TMPDIR'}, $ENV{'TMP'}, $ENV{'TEMP'},
+	   $ENV{'TEMPDIR'}, File::Spec->catfile($ENV{'HOME'}, 'tmp')) {
+    if ($_ && -d $_ && -w $_) {
+      if ($Debug{'KEEP'}) {
+	eval { $tmpdir = tempdir( $template, DIR => "$_" ); };
+      } else {
+	eval { $tmpdir = tempdir( $template,
+				  CLEANUP => 1, DIR => "$_" ); };
+      }
+      last if $tmpdir;
+    }
+  }
+  $tmpdir = tempdir( $template, CLEANUP => 1, DIR => File::Spec->tmpdir )
+    unless ($tmpdir);
+
+  # see Lerning Perl, page 205, or Programming Perl, page 413
+  # $SIG{'INT'} is for Ctrl-C interruption
+  $SIG{'INT'} = sub { &clean_up(); die "interrupted..."; };
+  $SIG{'QUIT'} = sub { &clean_up(); die "quit..."; };
+
+  if ($Debug{'TMPDIR'}) {
+    if ( $Debug{'KEEP'}) {
+      print STDERR "temporary directory is kept: $tmpdir\n";
+    } else {
+      print STDERR "temporary directory will be cleaned: $tmpdir\n";
+    }
+  }
+
+  # further argument: SUFFIX => '.sh'
+  if ($Debug{'KEEP'}) {
+    ($fh_cat, $tmp_cat) = tempfile(',cat_XXXX', DIR => $tmpdir);
+    ($fh_stdin, $tmp_stdin) = tempfile(',stdin_XXXX', DIR => $tmpdir);
+  } else {
+    ($fh_cat, $tmp_cat) = tempfile(',cat_XXXX', UNLINK => 1,
+				   DIR => $tmpdir);
+    ($fh_stdin, $tmp_stdin) = tempfile(',stdin_XXXX', UNLINK => 1,
+				       DIR => $tmpdir);
+  }
+}				# main_temp()
+
+
+########################################################################
+# tmp functions and compression
+########################################################################
+
+########################################################################
+# further functions needed for main_do_fileargs()
+########################################################################
+
+my @REG_TITLE = ();
+
+##########
+# register_file(<filename>)
+#
+# Write a found file and register the title element.
+#
+# Arguments: 1: a file name
+# Output: none
+#
+sub register_file {
+  my $n = @_;
+  die "register_file(): one argument is needed; you used $n;"
+    unless $n == 1;
+  die 'register_file(): file name is empty;' unless $_[0];
+
+  if ($_[0] eq '-') {
+    &to_tmp($tmp_stdin) && &register_title('stdin');
+  } else {
+    &to_tmp($_[0]) && &register_title($_[0]);
+  }
+  1;
+}				# register_file()
+
+
+##########
+# register_title(<filespec>)
+#
+# Create title element from <filespec> and append to $_REG_TITLE_LIST.
+# Basename is created.
+#
+# Globals in/out: @REG_TITLE
+#
+# Variable prefix: rt
+#
+sub register_title {
+  my $n = @_;
+  die "register_title(): one argument is needed; you used $n;"
+    unless $n == 1;
+  return 1 unless $_[0];
+
+  return 1 if scalar @REG_TITLE > 3;
+
+  my $title = &get_filename($_[0]);
+  $title =~ s/\s/_/g;
+  $title =~ s/\.bz2$//g;
+  $title =~ s/\.gz$//g;
+  $title =~ s/\.Z$//g;
+
+  if ($Debug{'FILENAMES'}) {
+    if ($_[0] eq 'stdin') {
+      print STDERR "register_title(): file title is stdin\n";
+    } else {
+      print STDERR "register_title(): file title is $title\n";
+    }
+  }				# if ($Debug{'FILENAMES'})
+
+  return 1 unless $title;
+  push @REG_TITLE, $title;
+  1;
+}				# register_title()
+
+
+##########
+# save_stdin()
+#
+# Store standard input to temporary file (with decompression).
+#
+sub save_stdin {
+  my ($fh_input, $tmp_input);
+  $tmp_input = File::Spec->catfile($tmpdir, ',input');
+  open $fh_input, ">$tmp_input" or
+    die "save_stdin(): could not open $tmp_input";
+  foreach (<STDIN>) {
+    print $fh_input $_;
+  }
+  close $fh_input;
+  open $fh_stdin, ">$tmp_stdin" or
+    die "save_stdin(): could not open $tmp_stdin";
+  foreach ( &cat_z("$tmp_input") ) {
+    print $fh_stdin "$_";
+  }
+  close $fh_stdin;
+  unlink $tmp_input unless $Debug{'KEEP'};
+}				# save_stdin()
+
+
+########################################################################
+# main_do_fileargs()
+########################################################################
+
+sub main_do_fileargs {
+  &special_setup();
+  if ($Opt{'APROPOS'}) {
+    if ($No_Filespecs) {
+      &apropos_filespec();
+      return 1;
+    }
+  } else {
+    foreach (@Filespecs) {
+      if (/^-$/) {
+	&save_stdin();
+	last;
+      }
+    }				# foreach (@Filespecs)
+  }				# if ($Opt{'APROPOS'})
+
+  my $section = '';
+  my $ext = '';
+  my $twoargs = 0;
+  my $filespec;
+  my $former_arg;
+
+ FILESPEC: foreach (@Filespecs) {
+    $filespec = $_;
+    $Filespec_Arg = $_;
+    $Filespec_Is_Man = 0;
+    $Manspec = '';
+    $Special_Filespec = 0;
+
+    next FILESPEC unless $filespec;
+
+### main_do_fileargs()
+    if ($twoargs) {		# second run
+      $twoargs = 0;
+      # $section and $ext are kept from earlier run
+      my $h = { 'name' => $filespec, 'sec' => $section, 'ext' => $ext };
+      &man_setup();
+      if ( &is_man($h) ) {
+	$Filespec_Arg = "$former_arg $Filespec_Arg";
+	&special_filespec();
+	$Filespec_Is_Man = 1;
+	&man_get($h);
+	next FILESPEC;
+      } else {
+	warn "main_do_fileargs(): $former_arg is neither a file nor a " .
+	  "man page nor a section argument for $filespec;";
+      }
+    }
+    $twoargs = 0;
+
+    if ( $Opt{'APROPOS'} ) {
+      &apropos_filespec();
+      next FILESPEC;
+    }
+
+    if ($filespec eq '-') {
+      &register_file('-');
+      &special_filespec();
+      next FILESPEC;
+    } elsif ( &get_filename($filespec) ne $filespec ) { # path with dir
+      &special_filespec();
+      if (-f $filespec && -r $filespec) {
+	&register_file($filespec)
+      } else {
+	warn "main_do_fileargs: the argument $filespec is not a file;";
+      }
+      next FILESPEC;
+    } else {			# neither `-' nor has dir
+      # check whether filespec is an existing file
+      unless ( $Man{'FORCE'} ) {
+	if (-f $filespec && -r $filespec) {
+	  &special_filespec();
+	  &register_file($filespec);
+	  next FILESPEC;
+	}
+      }
+    }				# if ($filespec eq '-')
+
+### main_do_fileargs()
+    # now it must be a man page pattern
+
+    if ($Macro_Pkg and $Macro_Pkg ne '-man') {
+      warn "main_do_fileargs(): $filespec is not a file, " .
+	"man pages are ignored due to $Macro_Pkg;";
+      next FILESPEC;
+    }
+
+    # check for man page
+    &man_setup();
+    unless ( $Man{'ENABLE'} ) {
+      warn "main_do_fileargs(): the argument $filespec is not a file;";
+      next FILESPEC;
+    }
+    my $errmsg;
+    if ( $Man{'FORCE'} ) {
+      $errmsg = 'is not a man page';
+    } else {
+      $errmsg = 'is neither a file nor a man page';
+    }
+
+    $Filespec_Is_Man = 1;
+
+### main_do_fileargs()
+    # test filespec with `man:...' or `...(...)' on man page
+
+    my @names = ($filespec);
+    if ($filespec =~ /^man:(.*)$/) {
+      push @names, $1;
+    }
+
+    foreach my $i (@names) {
+      next unless $i;
+      my $h = { 'name' => $i };
+      if ( &is_man($h) ) {
+	&special_filespec();
+	&man_get($h);
+	next FILESPEC;
+      }
+      if ( $i =~ /^(.*)\(([$Man{'AUTO_SEC_CHARS'}])(.*)\)$/ ) {
+	$h = { 'name' => $1, 'sec' => $2, 'ext' => $3 };
+	if ( &is_man($h) ) {
+	  &special_filespec();
+	  &man_get($h);
+	  next FILESPEC;
+	}
+      }				# if //
+      if ( $i =~ /^(.*)\.([$Man{'AUTO_SEC_CHARS'}])(.*)$/ ) {
+	$h = { 'name' => $1, 'sec' => $2, 'ext' => $3 };
+	if ( &is_man($h) ) {
+	  &special_filespec();
+	  &man_get($h);
+	  next FILESPEC;
+	}
+      }				# if //
+    }				# foreach (@names)
+
+### main_do_fileargs()
+    # check on "s name", where "s" is a section with or without an extension
+    if ($filespec =~ /^([$Man{'AUTO_SEC_CHARS'}])(.*)$/) {
+      unless ( $Man{'ENABLE'} ) {
+	warn "main_do_fileargs(): $filespec $errmsg;";
+	next FILESPEC;
+      }
+      $twoargs = 1;
+      $section = $1;
+      $ext = $2;
+      $former_arg = $filespec;
+      next FILESPEC;
+    } else {
+      warn "main_do_fileargs(): $filespec $errmsg;";
+      next FILESPEC;
+    }
+  }				# foreach (@Filespecs)
+
+  if ($twoargs) {
+    warn "main_do_fileargs(): no filespec arguments left for second run;";
+    return 0;
+  }
+  1;
+} # main_do_fileargs()
+
+
+########################################################################
+# main_set_resources()
+########################################################################
+
+##########
+# main_set_resources ()
+#
+# Determine options for setting X resources with $_DISPLAY_PROG.
+#
+# Globals: $Display{PROG}, $Output_File_Name
+#
+sub main_set_resources {
+  # $prog   viewer program
+  # $rl     resource list
+  unlink $tmp_stdin unless $Debug{'KEEP'};
+  $Output_File_Name = '';
+
+  my @title = @REG_TITLE;
+  @title = ($Opt{'TITLE'}) unless @title;
+  @title = () unless @title;
+
+  foreach my $n (@title) {
+    next unless $n;
+    $n =~ s/^,+// if $n =~ /^,/;
+    next unless $n;
+    $Output_File_Name = $Output_File_Name . ',' if $Output_File_Name;
+    $Output_File_Name = "$Output_File_Name$n";
+  }				# foreach (@title)
+
+  $Output_File_Name =~ s/^,+//;
+  $Output_File_Name = '-' unless $Output_File_Name;
+  $Output_File_Name = File::Spec->catfile($tmpdir, $Output_File_Name);
+
+### main_set_resources()
+  unless ($Display{'PROG'}) {	# for example, for groff mode
+    $Display{'ARGS'} = '';
+    return 1;
+  }
+
+  my %h = &where_is_prog($Display{'PROG'});
+  my $prog = $h{'file'};
+  if ($Display{'ARGS'}) {
+    $Display{'ARGS'} = "$h{'args'} $Display{'ARGS'}";
+  } else {
+    $Display{'ARGS'} = $h{'args'};
+  }
+
+  my @rl = ();
+
+  if ($Opt{'BD'}) {
+    if ($prog =~ /^(ghostview|gv|gxditview|xditview|xdvi)$/) {
+      push @rl, '-bd', $Opt{'BD'};
+    }
+  }
+
+  if ($Opt{'BG'}) {
+    if ($prog =~ /^(ghostview|gv|gxditview|xditview|xdvi)$/) {
+      push @rl, '-bg', $Opt{'BG'};
+    } elsif ($prog eq 'kghostview') {
+      push @rl, '--bg', $Opt{'BG'};
+    } elsif ($prog eq 'xpdf') {
+      push @rl, '-papercolor', $Opt{'BG'};
+    }
+  }
+
+### main_set_resources()
+  if ($Opt{'BW'}) {
+    if ($prog =~ /^(ghostview|gv|gxditview|xditview|xdvi)$/) {
+      push @rl, '-bw', $Opt{'BW'};
+    }
+  }
+
+  if ($Opt{'FG'}) {
+    if ($prog =~ /^(ghostview|gv|gxditview|xditview|xdvi)$/) {
+      push @rl, '-fg', $Opt{'FG'};
+    } elsif ($prog eq 'kghostview') {
+      push @rl, '--fg', $Opt{'FG'};
+    }
+  }
+
+  if ($Opt{'FN'}) {
+    if ($prog =~ /^(ghostview|gv|gxditview|xditview|xdvi)$/) {
+      push @rl, '-fn', $Opt{'FN'};
+    } elsif ($prog eq 'kghostview') {
+      push @rl, '--fn', $Opt{'FN'};
+    }
+  }
+
+  if ($Opt{'GEOMETRY'}) {
+    if ($prog =~ /^(ghostview|gv|gxditview|xditview|xdvi)$/) {
+      push @rl, '-geometry', $Opt{'GEOMETRY'};
+    } elsif ($prog eq 'kghostview') {
+      push @rl, '--geometry', $Opt{'GEOMETRY'};
+    }
+  }
+
+### main_set_resources()
+  if ($Opt{'RESOLUTION'}) {
+    if ($prog =~ /^(ghostview|gv|gxditview|xditview|xdvi)$/) {
+      push @rl, '-resolution', $Opt{'RESOLUTION'};
+    } elsif ($prog eq 'xpdf') {
+      if ($Display{'PROG'} !~ / -z/) { # if xpdf does not have option -z
+	if ($Default_Resolution == 75) {
+	  push @rl, '-z', 104;
+	} elsif ($Default_Resolution == 100) { # 72dpi is '100'
+	  push @rl, '-z', 139;
+	}
+      }
+    }				# if $prog
+  } else {			# empty $Opt{RESOLUTION}
+    $Opt{'RESOLUTION'} = $Default_Resolution;
+    if ($prog =~ /^(gxditview|xditview)$/) {
+      push @rl, '-resolution', $Default_Resolution;
+    } elsif ($prog eq 'xpdf') {
+      if ($Display{'PROG'} !~ / -z/) { # if xpdf does not have option -z
+	if ($Default_Resolution == 75) {
+	  push @rl, '-z', 104;
+	} elsif ($Default_Resolution == 100) { # 72dpi is '100'
+	  push @rl, '-z', 139;
+	}
+      }
+    }				# if $prog
+  }				# if $Opt{RESOLUTION}
+
+  if ($Opt{'ICONIC'}) {
+    if ($prog =~ /^(ghostview|gv|gxditview|xditview|xdvi)$/) {
+      push @rl, '-iconic';
+    }
+  }
+
+### main_set_resources()
+  if ($Opt{'RV'}) {
+    if ($prog =~ /^(ghostview|gv|gxditview|xditview|xdvi)$/) {
+      push @rl, '-rv';
+    }
+  }
+
+  if (@{$Opt{'XRM'}}) {
+    if ($prog =~ /^(ghostview|gv|gxditview|xditview|xdvi|xpdf)$/) {
+      foreach (@{$Opt{'XRM'}}) {
+	push @rl, '-xrm', $_;
+      }
+    }
+  }
+
+  if (@title) {
+    if ($prog =~ /^(gxditview|xditview)$/) {
+      push @rl, '-title', $Output_File_Name;
+    }
+  }
+
+  my $args = join ' ', @rl;
+  if ($Display{'ARGS'}) {
+    $Display{'ARGS'} = "$args $Display{'ARGS'}";
+  } else {
+    $Display{'ARGS'} = $args;
+  }
+
+  1;
+}				# main_set_resources()
+
+
+########################################################################
+# set resources
+########################################################################
+
+my $groggy;
+my $modefile;
+my $addopts;
+
+##########
+# main_display ()
+#
+# Do the actual display of the whole thing.
+#
+# Globals:
+#   in: $Display{MODE}, $Opt{DEVICE}, @Addopts_Groff,
+#       $fh_cat, $tmp_cat, $Opt{PAGER}, $Output_File_Name
+#
+sub main_display {
+  $addopts = join ' ', @Addopts_Groff;
+
+  if (-z $tmp_cat) {
+    warn "groffer: empty input\n";
+    &clean_up();
+    return 1;
+  }
+
+  $modefile = $Output_File_Name;
+
+  # go to the temporary directory to be able to access internal data files
+  chdir $tmpdir;
+
+### main_display()
+ SWITCH: foreach ($Display{'MODE'}) {
+    /^groff$/ and do {
+      push @Addopts_Groff, "-T$Opt{'DEVICE'}" if $Opt{'DEVICE'};
+      $addopts = join ' ', @Addopts_Groff;
+      $groggy = `cat $tmp_cat | grog`;
+      die "main_display(): grog error;" if $?;
+      chomp $groggy;
+      print STDERR "grog output: $groggy\n" if $Debug{'GROG'};
+      &_do_opt_V();
+      unlink $modefile;
+      rename $tmp_cat, $modefile;
+      system("cat $modefile | $groggy $addopts");
+      &clean_up();
+      next SWITCH;
+    };				# /groff/
+
+    /^(text|tty)$/ and do {
+      my $device;
+      if (! $Opt{'DEVICE'}) {
+	$device = $Opt{'TEXT_DEVICE'};
+	$device = $Default_tty_Device unless $device;
+      } elsif ($Opt{'DEVICE'} =~ /^(ascii||cp1047|latin1|utf8)$/) {
+	$device = $Opt{'DEVICE'};
+      } else {
+	warn "main_display(): wrong device for $Display{'MODE'} mode: " .
+	  "$Opt{'DEVICE'}";
+      }
+      $groggy = `cat $tmp_cat | grog -T$device`;
+      die "main_display(): grog error;" if $?;
+      chomp $groggy;
+      print STDERR "grog output: $groggy\n" if $Debug{'GROG'};
+      if ($Display{'MODE'} eq 'text') {
+	&_do_opt_V();
+	system("cat $tmp_cat | $groggy $addopts");
+	&clean_up();
+	next SWITCH;
+      }
+
+### main_display()
+      # mode is not 'text', but `tty'
+      my %pager;
+      my @p;
+      push @p, $Opt{'PAGER'} if $Opt{'PAGER'};
+      push @p, $ENV{'PAGER'} if $ENV{'PAGER'};
+      foreach (@p) {
+	%pager = &where_is_prog($_);
+	next unless %pager;
+	if ($pager{'file'} eq 'less') {
+	  if ($pager{'args'}) {
+	    $pager{'args'} = "-r -R $pager{'args'}";
+	  } else {
+	    $pager{'args'} = '-r -R';
+	  }
+	}
+	last if $pager{'file'};
+      }				# foreach @p
+      unless (%pager) {
+	foreach (@{$Viewer_tty{'TTY'}}, @{$Viewer_X{'TTY'}}, 'cat') {
+	  next unless $_;
+	  %pager = &where_is_prog($_);
+	  last if %pager;
+	}
+      }
+      die "main_display(): no pager program found for tty mode;"
+	unless %pager;
+      &_do_opt_V();
+      system("cat $tmp_cat | $groggy $addopts | " .
+	     "$pager{'fullname'} $pager{'args'}");
+      &clean_up();
+      next SWITCH;
+    };				# /text|tty/
+
+    /^source$/ and do {
+      open $fh_cat, "<$tmp_cat";
+      foreach (<$fh_cat>) {
+	print "$_";
+      }
+      &clean_up();
+      next SWITCH;
+    };
+
+### main_display()
+    /^dvi$/ and do {
+      if ($Opt{'DEVICE'} && $Opt{'DEVICE'} ne 'dvi') {
+	warn "main_display(): " .
+	  "wrong device for $Display{'MODE'} mode: $Opt{'DEVICE'};"
+      }
+      $modefile .= '.dvi';
+      $groggy = `cat $tmp_cat | grog -Tdvi`;
+      die "main_display(): grog error;" if $?;
+      chomp $groggy;
+      print STDERR "grog output: $groggy\n" if $Debug{'GROG'};
+      &_do_display();
+      next SWITCH;
+    };
+
+    /^html$/ and do {
+      if ($Opt{'DEVICE'} && $Opt{'DEVICE'} ne 'html') {
+	warn "main_display(): " .
+	  "wrong device for $Display{'MODE'} mode: $Opt{'DEVICE'};"
+      }
+      $modefile .= '.html';
+      $groggy = `cat $tmp_cat | grog -Thtml`;
+      die "main_display(): grog error;" if $?;
+      chomp $groggy;
+      print STDERR "grog output: $groggy\n" if $Debug{'GROG'};
+      &_do_display();
+      next SWITCH;
+    };
+
+    /^pdf$/ and do {
+      if ($Opt{'DEVICE'} && $Opt{'DEVICE'} ne 'ps') {
+	warn "main_display(): " .
+	  "wrong device for $Display{'MODE'} mode: $Opt{'DEVICE'};"
+      }
+      $modefile .= '.ps';
+      $groggy = `cat $tmp_cat | grog -Tps`;
+      die "main_display(): grog error;" if $?;
+      chomp $groggy;
+      print STDERR "grog output: $groggy\n" if $Debug{'GROG'};
+      &_do_display(\&_make_pdf);
+      next SWITCH;
+    };
+
+### main_display()
+    /^ps$/ and do {
+      if ($Opt{'DEVICE'} && $Opt{'DEVICE'} ne 'ps') {
+	warn "main_display(): " .
+	  "wrong device for $Display{'MODE'} mode: $Opt{'DEVICE'};"
+      }
+      $modefile .= '.ps';
+      $groggy = `cat $tmp_cat | grog -Tps`;
+      die "main_display(): grog error;" if $?;
+      chomp $groggy;
+      print STDERR "grog output: $groggy\n" if $Debug{'GROG'};
+      &_do_display();
+      next SWITCH;
+    };
+
+    /^x$/ and do {
+      my $device;
+      if ($Opt{'DEVICE'} && $Opt{'DEVICE'} =~ /^X/) {
+	$device = $Opt{'DEVICE'};
+      } else {
+	if ($Opt{'RESOLUTION'} == 100) {
+	  if ( $Display{'PROG'} =~ /^(g|)xditview$/ ) {
+	    # add width of 800dpi for resolution of 100dpi to the args
+	    $Display{'ARGS'} .= ' -geometry 800';
+	    $Display{'ARGS'} =~ s/^ //;
+	  }
+	} else {		# RESOLUTIOM != 100
+	  $device = 'X75-12';
+	}			# if RESOLUTIOM
+      }				# if DEVICE
+      $groggy = `cat $tmp_cat | grog -T$device -Z`;
+      die "main_display(): grog error;" if $?;
+      chomp $groggy;
+      print STDERR "grog output: $groggy\n" if $Debug{'GROG'};
+      &_do_display();
+      next SWITCH;
+    };
+
+### main_display()
+    /^X$/ and do {
+      if (! $Opt{'DEVICE'}) {
+	$groggy = `cat $tmp_cat | grog -X`;
+	die "main_display(): grog error;" if $?;
+	chomp $groggy;
+	print STDERR "grog output: $groggy\n" if $Debug{'GROG'};
+      } elsif ($Opt{'DEVICE'} =~ /^(X.*|dvi|html|lbp|lj4|ps)$/) {
+	# these devices work with
+	$groggy = `cat $tmp_cat | grog -T$Opt{'DEVICE'} -X`;
+	die "main_display(): grog error;" if $?;
+	chomp $groggy;
+	print STDERR "grog output: $groggy\n" if $Debug{'GROG'};
+      } else {
+	warn "main_display(): wrong device for " .
+	  "$Display{'MODE'} mode: $Opt{'DEVICE'};";
+	$groggy = `cat $tmp_cat | grog -Z`;
+	die "main_display(): grog error;" if $?;
+	chomp $groggy;
+	print STDERR "grog output: $groggy\n" if $Debug{'GROG'};
+      }				# if DEVICE
+      &_do_display();
+      next SWITCH;
+    };
+
+    /^.*$/ and do {
+      die "main_display(): unknown mode `$Display{'MODE'}';";
+    };
+
+  }				# SWITCH
+  1;
+} # main_display()
+
+
+########################
+# _do_display ([<prog>])
+#
+# Perform the generation of the output and view the result.  If an
+# argument is given interpret it as a function name that is called in
+# the midst (actually only for `pdf').
+#
+sub _do_display {
+  &_do_opt_V();
+  unless ($Display{'PROG'}) {
+    system("$groggy $addopts $tmp_cat");
+    &clean_up();
+    return 1;
+  }
+  unlink $modefile;
+  die "_do_display(): empty output;" if -z $tmp_cat;
+  system("cat $tmp_cat | $groggy $addopts >$modefile");
+  die "_do_display(): empty output;" if -z $modefile;
+  &print_times("before display");
+  if ($_[0] && ref($_[0]) eq 'CODE') {
+    $_[0]->();
+  }
+  unlink $tmp_cat unless $Debug{'KEEP'};
+
+  if ( $Opt{'STDOUT'} ) {
+    my $fh;
+    open $fh, "<$modefile";
+    foreach (<$fh>) {
+      print;
+    }
+    close $fh;
+    return 1;
+  }
+
+  if ($Viewer_Background) {
+    if ($Debug{'KEEP'}) {
+      exec "$Display{'PROG'} $Display{'ARGS'} $modefile &";
+    } else {
+      exec "{ $Display{'PROG'} $Display{'ARGS'} $modefile; " .
+	"rm -rf $tmpdir; } &";
+    }
+  } else {
+    system("$Display{'PROG'} $Display{'ARGS'} $modefile");
+    &clean_up();
+  }
+} # _do_display() of main_display()
+
+
+#############
+# _do_opt_V ()
+#
+# Check on option `-V'; if set print the corresponding output and leave.
+#
+# Globals: @ARGV, $Display{MODE}, $Display{PROG},
+#          $Display{ARGS}, $groggy,  $modefile, $addopts
+#
+sub _do_opt_V {
+  if ($Opt{'V'}) {
+    $Opt{'V'} = 0;
+    print "Parameters: @ARGV\n";
+    print "Display Mode: $Display{'MODE'}\n";
+    print "Output file: $modefile\n";
+    print "Display prog: $Display{'PROG'} $Display{'ARGS'}\n";
+    print "Output of grog: $groggy $addopts\n";
+    my $res = `$groggy $addopts\n`;
+    chomp $res;
+    print "groff -V: $res\n";
+    exit 0;
+  }
+  1;
+} # _do_opt_V() of main_display()
+
+##############
+# _make_pdf ()
+#
+# Transform to pdf format; for pdf mode in _do_display().
+#
+# Globals: $md_modefile (from main_display())
+#
+sub _make_pdf {
+  die "_make_pdf(): pdf mode did not work;" if $PDF_Did_Not_Work;
+  my $psfile = $modefile;
+  die "_make_pdf(): empty output;" if -z $modefile;
+  $modefile =~ s/\.ps$/.pdf/;
+  unlink $modefile;
+  my $done;
+  if ($PDF_Has_ps2pdf) {
+    system("ps2pdf $psfile $modefile 2>$Dev_Null");
+    $done = ! $?;
+  }
+  if (! $done && $PDF_Has_gs) {
+    system("gs -q -dNOPAUSE -dBATCH -sDEVICE=pdfwrite " .
+       "-sOutputFile=$modefile -c save pop -f $psfile 2>$Dev_Null");
+    $done = ! $?;
+  }
+  if (! $done) {
+    $PDF_Did_Not_Work = 1;
+    warn '_make_pdf(): Could not transform into pdf format, ' .
+      'the Postscript mode (ps) is used instead;';
+    $Opt{'MODE'} = 'ps';
+    &main_set_mode();
+    &main_set_resources();
+    &main_display();
+    exit 0;
+  }
+  unlink $psfile unless $Debug{'KEEP'};
+  1;
+} # _make_pdf() of main_display()
+
+
+########################################################################
+
+&main_set_options();
+&main_parse_MANOPT();
+&main_config_params();
+&main_parse_params();
+&main_set_mode();
+&main_temp();
+&main_do_fileargs();
+&main_set_resources();
+&main_display();
+
+&clean_up();
+
+1;
+########################################################################
+### Emacs settings
+# Local Variables:
+# mode: CPerl
+# End:

Index: man.pl
===================================================================
RCS file: man.pl
diff -N man.pl
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ man.pl	11 Aug 2013 08:28:52 -0000	1.9
@@ -0,0 +1,731 @@
+#! /usr/bin/env perl
+
+# groffer - display groff files
+
+# Source file position: <groff-source>/contrib/groffer/perl/man.pl
+# Installed position: <prefix>/lib/groff/groffer/man.pl
+
+# Copyright (C) 2006, 2009, 2011 Free Software Foundation, Inc.
+# Written by Bernd Warken <groff-bernd.warken-72@web.de>.
+
+# Last update: 27 Jan 2011
+
+# 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/>.
+
+########################################################################
+
+use strict;
+use warnings;
+
+########################################################################
+# functions for apropos, man, whatis
+########################################################################
+
+##########
+# apropos_filespec()
+#
+# Compose temporary file for filspec.
+#
+# Globals:  in: $main::Opt{'APROPOS'}, $main::Special_Setup, $main::Filespec_Arg,
+#               $main::Apropos_Prog, $main::Opt{'APROPOS_SECTIONS'}, $main::Opt{'SECTIONS'}
+#          out: $main::Special_Filespec
+#
+sub apropos_filespec {
+  return 0 unless $main::Opt{'APROPOS'};
+  die 'apropos_filespec(): apropos_setup() must be run first;'
+    unless $main::Special_Setup;
+  die 'apropos_filespec(): no $main::Filespec_Arg is set;'
+    unless defined $main::Filespec_Arg;
+  $main::Special_Filespec = 1;
+
+  my $s;
+  if ($main::No_Filespecs) {
+    &to_tmp_line('.SH no filespec');
+    $s = `$main::Apropos_Prog`;
+    $s =~ s/^/\\\&/;
+    &to_tmp_line($s);
+    return 1;
+  }
+
+  $s = $main::Filespec_Arg;
+  $s =~ s/[^\\]-/\\-/g;
+  &to_tmp_line(".SH $s");
+
+  if ( $main::Opt{'APROPOS_SECTIONS'} ) {
+    $s = qr/^[^\(]*\([$main::Opt{'APROPOS_SECTIONS'}]/;
+  } else {
+    if ( $main::Opt{'SECTIONS'} ) {
+      $s = $main::Opt{'SECTIONS'};
+      $s = qr/^[^\(]*\([$s]/;
+    } else {
+      $s = qr/^.*\(.+\).*$/;
+    }
+  }
+
+### apropos_filespec()
+  my $filespec = $main::Filespec_Arg;
+  $filespec =~ s#/#\\/#g;
+  $filespec =~ s#\.#\\./#g;
+  my @ap;
+  foreach ( `$main::Apropos_Prog $main::Filespec_Arg 2>$main::Dev_Null` ) {
+    chomp;
+    if (/^$filespec:\s/) {	# for error messages of this script
+      my $line = $_;
+      $line =~ s/^(.*)$/\\\&$1/s;
+      push @ap, $line;
+    }
+    if (/$s/) {
+      push @ap, $_;
+    }
+  }
+  my @res;
+  foreach (sort @ap) {
+    s/^
+      ([^\(]+\(+[$main::Man{'AUTO_SEC_CHARS'}][^\)]*\)+)
+      (\s*-*)*\s*
+      (.*)
+      $/.br\n.TP 15\n.BR "$1"\n\\\&$3\n/sx;
+    push @res, $_;
+  }
+  &to_tmp_line(@res);
+  1;
+}				# apropos_filespec()
+
+
+##########
+# apropos_setup()
+#
+# Setup for the --apropos* options, just 2 global variables are set.
+#
+# Globals:  in: $main::Opt{'APROPOS'}
+#          out: $main::Special_Setup, $main::Apropos_Prog
+#
+sub apropos_setup {
+  return 0 unless $main::Opt{'APROPOS'};
+  if ( &where_is_prog('apropos') ) {
+    $main::Apropos_Prog = 'apropos';
+  } elsif ( &where_is_prog('man') ) {
+    if (! system("man --apropos man >$main::Dev_Null 2>$main::Dev_Null")) {
+      $main::Apropos_Prog = 'man --apropos';
+    } elsif (! system("man -k man >$main::Dev_Null 2>$main::Dev_Null")) {
+      $main::Apropos_Prog = 'man --k';
+    }
+  }				# test man
+  die 'apropos_setup(): no apropos program available;'
+    unless $main::Apropos_Prog;
+  &to_tmp_line('.TH GROFFER APROPOS');
+  $main::Special_Setup = 1;
+  $main::Opt{'TITLE'} = 'apropos' unless $main::Opt{'TITLE'};
+  1;
+}				# apropos_setup()
+
+
+##########
+# is_man(<man_sec_ext-hash-ref>)
+#
+# Test whether the argument hash exists as man page (from is_man()).
+#
+# Globals: in: $main::Man{AUTO_SEC_CHARS},$main::Man{SEC_CHARS},
+#              $main::Man{EXT}, $tmpdir
+#         out: $main::Manspec
+#
+# Arguments: 1, a hash reference with keys 'name', 'sec', 'ext', where
+#               'sec' is a string of one or several section characters
+#
+sub is_man {
+  my $n = @_;
+  die "is_man(): one argument is needed, you used $n;"
+    unless $n == 1;
+  die "is_man(): the argument is not a hash reference `$_[0]';"
+    if ref($_[0]) ne 'HASH';
+  die 'is_man(): temporary directory is not set;' unless $main::tmpdir;
+  die 'is_man(): man_setup() must be run first;' unless $main::Man{'IS_SETUP'};
+
+  my $name = $_[0]->{'name'};
+  unless ($name) {
+    $main::Manspec = '';
+    return 0;
+  }
+
+  my $sec;
+  $sec = $_[0]->{'sec'};
+  $sec = $main::Man{'SEC_CHARS'} unless $sec;
+  $sec = $main::Man{'AUTO_SEC_CHARS'} unless $sec;
+  $sec = '' unless defined $sec;
+  # take care, $sec may be several sections
+
+### is_man()
+  my $ext;
+  $ext = $_[0]->{'ext'};
+  $ext = $main::Man{'EXT'} unless $ext;
+  $ext = '' unless defined $ext;
+
+  $main::Manspec = "$name.$sec,$ext";
+  my @m;
+  if (exists $main::Man{'MANSPEC'}{$main::Manspec}) {
+    return 1;
+  } else {
+    foreach my $p ( @{$main::Man{'PATH'}} ) {
+      foreach my $s (split //, $sec) {
+	my $dir = File::Spec->catdir($p, "man$s");
+	next unless -d $dir;
+	my $file = File::Spec->catfile($dir, "$name.$s$ext");
+	push @m, glob("$file*");
+      }
+    }
+    $main::Man{'MANSPEC'}{$main::Manspec} = \@m;
+  }
+  return 0 unless (@m);
+  return 1;
+} # is_man()
+
+
+##########
+# man_get (<man_sec_ext-hash-ref>)
+#
+# Write a man page to the temporary file.
+#
+# Globals in: $main::Manspec, $main::Man{MANSPEC}, $main::Man{SEC_CHARS},
+#             $main::Man{EXT}, $main::Man{ALL}
+#
+# Arguments: 1, a hash reference with keys 'name', 'sec', 'ext', where
+#               'sec' is a string of one or several section characters
+#
+sub man_get {
+  my $n = @_;
+  die "man_get(): one argument is needed, you used $n;"
+    unless $n == 1;
+  die "man_get(): the argument is not a hash reference `$_[0]';"
+    if ref($_[0]) ne 'HASH';
+  die "man_get(): is_man() must be run first on the argument;"
+    unless $main::Manspec;
+  die "man_get(): wrong hash reference `$_[0]', no 'name' key;"
+    unless exists $_[0]->{'name'};
+
+  my ($name, $sec, $ext, $f, $path);
+  $name = $_[0]->{'name'};
+  die "man_get(): empty 'name' key in the argument;" unless $name;
+
+  $sec = $_[0]->{'sec'};
+  $sec = $main::Man{'SEC_CHARS'} if (! $sec) and $main::Man{'SEC_CHARS'};
+  $sec = '' unless defined $sec;
+  # take care $sec may be several sections
+
+### man_get()
+  $ext = $_[0]->{'ext'};
+  $ext = $main::Man{'EXT'} unless $ext;
+  $ext = '' unless defined $ext;
+
+  die 'man_get(): $main::Manspec does not suit the arguments;'
+    if ($main::Manspec ne "$name.$sec,$ext") and
+      (! exists $main::Man{'MANSPEC'}{$main::Manspec});
+
+  if ($main::Man{'ALL'}) {
+    my $ok;
+    my %list;
+    foreach ( @{$main::Man{'MANSPEC'}{$main::Manspec}} ) {
+      next if exists $list{$_};
+      if (-f $_ and -r $_) {
+	$list{$_} = 1;
+	&to_tmp($_);
+	$ok = 1;
+      }
+    }
+    &register_title("man:$name") if $ok;
+    return 1;
+  }
+
+  # not $main::Man{'ALL'}
+
+  if ($_[0]->{'sec'}) {
+    my $path = File::Spec->catfile('', "man$sec", $name);
+    if ($ext) {
+      foreach $f ( @{$main::Man{'MANSPEC'}{$main::Manspec}} ) {
+	if ($f =~ m#$path\.$sec$ext($|\..*$)#) {
+	  if (-f $f && -r $f) {
+	    &register_file($f);
+	    return 1;
+	  }
+	}			# if $f =~
+      }				# foreach $f
+### man_get()
+      foreach $f ( @{$main::Man{'MANSPEC'}{$main::Manspec}} ) {
+	if ($f =~ m#$path\.$sec$ext.*$#) {
+	  if (-f $f && -r $f) {
+	    &register_file($f);
+	    return 1;
+	  }
+	}			# if $f =~
+      }				# foreach $f
+    } else {			# $ext is empty
+      foreach $f ( @{$main::Man{'MANSPEC'}{$main::Manspec}} ) {
+	if ($f =~ m#$path\.$sec($|\..*$)#) {
+	  if (-f $f && -r $f) {
+	    #	    &to_tmp($f) && &register_file($f);
+	    &register_file($f);
+	    return 1;
+	  }
+	}			# if $f =~
+      }				# foreach $f
+      foreach $f ( @{$main::Man{'MANSPEC'}{$main::Manspec}} ) {
+	if ($f =~ m#$path\.$sec.*$#) {
+	  if (-f $f && -r $f) {
+	    #	    &to_tmp($f) && &register_file($f);
+	    &register_file($f);
+	    return 1;
+	  }
+	}			# if $f =~
+      }				# foreach $f
+    }				# if $ext
+### man_get()
+  } else {			# sec is empty
+    my $m = $main::Man{'SEC_CHARS'};
+    $m = $main::Man{'AUTO_SEC_CHARS'} unless $m;
+    foreach my $s (split //, $m) {
+      my $path = File::Spec->catfile('', "man$s", $name);
+      unless ($ext) {
+	foreach my $f ( @{$main::Man{'MANSPEC'}{$main::Manspec}} ) {
+	  if ( $f =~ m#$path\.$s($|\..*$)# ) {
+	    if (-f $f && -r $f) {
+	      #	      &to_tmp($f) && &register_file($f);
+	      &register_file($f);
+	      return 1;
+	    }
+	  }			# if $f =~
+	}			# foreach $f
+      }				# unless $ext
+      foreach $f ( @{$main::Man{'MANSPEC'}{$main::Manspec}} ) {
+	if ($f =~ m#$path\.$s$ext.*$#) {
+	  if (-f $f && -r $f) {
+	    #	    &to_tmp($f) && &register_file($f);
+	    &register_file($f);
+	    return 1;
+	  }
+	}			# if $f =~
+      }				# foreach $f
+    }				# foreach $s
+  }				# if sec
+
+  1;
+} # man_get()
+
+
+##########
+# man_setup ()
+#
+# Setup the variables in %MAN needed for man page searching.
+#
+# Globals:
+#   in:     %OPT, $LANG, $LC_MESSAGES, $LC_ALL,
+#           $MANPATH, $MANSEC, $PAGER, $SYSTEM, $MANOPT.
+#   out:    $main::Man{PATH}, $main::Man{LANG}, $main::Man{LANG2}, $main::Man{SYS},
+#           $main::Man{SEC}, $main::Man{ALL}
+#   in/out: $main::Man{ENABLE}
+#
+# The precedence for the variables related to `man' is that of GNU
+# `man', i.e.
+#
+# $LANG; overridden by
+# $LC_MESSAGES; overridden by
+# $LC_ALL; this has the same precedence as
+# $MANPATH, $MANSEC, $PAGER, $SYSTEM; overridden by
+# $MANOPT; overridden by
+# the groffer command line options.
+#
+# $MANROFFSEQ is ignored because grog determines the preprocessors.
+#
+sub man_setup {
+  return 1 if $main::Man{'IS_SETUP'};
+  $main::Man{'IS_SETUP'} = 1;
+  return 1 unless $main::Man{'ENABLE'};
+
+  # determine basic path for man pages
+  my $path;
+  if (defined $main::Opt{'MANPATH'}) {
+    $path = $main::Opt{'MANPATH'};
+  } elsif ($ENV{'MANPATH'}) {
+    $path = $ENV{'MANPATH'};
+  } elsif ( &where_is_prog('manpath') ) {
+    $path = `manpath 2>$main::Dev_Null`;
+  }
+  if ($path) {
+    chomp $path;
+    $main::Man{'PATH'} = [split /:/, $path];
+  } else {
+    $main::Man{'PATH'} = [];
+    &manpath_set_from_path();
+  }
+  unless ( @{$main::Man{'PATH'}} ) {
+    $main::Man{'ENABLE'} = 0;
+    warn "man_setup(): man path is empty;";
+    return 1;
+  }
+
+### man_setup()
+  # make man path list consisting of unique existing directories
+  @{$main::Man{'PATH'}} = &path_uniq( @{$main::Man{'PATH'}} );
+
+  unless ($main::Man{'ALL'}) {
+    $main::Man{'ALL'} = $main::Opt{'ALL'} ? 1 : 0;
+  }
+
+  # handle man systems
+  my $sys = $ENV{'SYSTEM'};
+  $sys = $main::Opt{'SYSTEMS'} if $main::Opt{'SYSTEMS'};
+  if ($sys) {
+    chomp $sys;
+    $main::Man{'SYS'} = [split /,/, $sys];
+  } else {
+    $main::Man{'SYS'} = [];
+    $sys = '';
+  }
+
+### man_setup()
+  # handle language
+  my $lang = '';
+  $lang = $main::Opt{'LANG'} if $main::Opt{'LANG'};
+  unless ($lang) {
+    foreach ('LC_ALL', 'LC_MESSAGES', 'LANG') {
+      if ($ENV{$_}) {
+	$lang = $ENV{$_};
+	last;
+      }
+    }
+  }
+  if ($lang) {
+    if ($lang eq 'C' or $lang eq 'POSIX') {
+      $main::Man{'LANG'} = '';
+      $main::Man{'LANG2'} = '';
+    } elsif ($lang =~ /^.$/) {
+      $main::Man{'LANG'} = $lang;
+      $main::Man{'LANG2'} = '';
+    } elsif ($lang =~ /^..$/) {
+      $main::Man{'LANG'} = $lang;
+      $main::Man{'LANG2'} = $lang;
+    } else {
+      $main::Man{'LANG'} = $lang;
+      $main::Man{'LANG2'} = $lang;
+      $main::Man{'LANG2'} =~ s/^(..).*$/$1/;
+    }
+  }				# if ($lang)
+  # from now on, use only $main::Man{LANG*}, forget about $main::Opt{LANG}, $ENV{LC_*}.
+
+  &manpath_add_lang_sys();
+
+### man_setup()
+  # section
+  my $sec;
+  $sec = $main::Opt{'SECTIONS'} if $main::Opt{'SECTIONS'};
+  unless ($sec) {
+    $sec = $ENV{'MANSEC'} if $ENV{'MANSEC'};
+  }
+  $main::Man{'SEC'} = [];
+  $main::Man{'SEC_CHARS'} = '';
+  if ($sec) {
+    foreach (split /:/, $sec) {
+      push @{$main::Man{'SEC'}}, $_ if /^[$main::Man{'AUTO_SEC_CHARS'}]$/;
+    }
+    $main::Man{'SEC_CHARS'} = join '', @{$main::Man{'SEC'}} if @{$main::Man{'SEC'}};
+  }				# if ($sec)
+
+  # extension
+  my $ext = '';
+  $ext = $main::Opt{'EXTENSION'} if $main::Opt{'EXTENSION'};
+  unless ($ext) {
+    $ext = $ENV{'EXTENSION'} if $ENV{'EXTENSION'};
+  }
+  $main::Man{'EXT'} = $ext;
+
+  # creation of man temporary is omitted, because of globs in perl
+  1;
+} # man_setup()
+
+
+##########
+# manpath_add_lang_sys()
+#
+# Add language and operating system specific directories to man path.
+#
+# Globals:
+#   in:     $main::Man{SYS}: a list of names of operating systems.
+#           $main::Man{LANG} and $main::Man{LANG2}: each a single name
+#   in/out: @{$main::Man{PATH}}: list of directories which shall have the `man?'
+#           subdirectories.
+#
+sub manpath_add_lang_sys {
+  return 1 unless $main::Man{'PATH'};
+  return 1 unless @{$main::Man{'PATH'}};
+
+  my @mp;
+
+  if ( @{$main::Man{'SYS'}} ) {
+    foreach ( @{$main::Man{'SYS'}} ) {
+      if ($_ eq 'man') {
+	@mp = (@mp, @{$main::Man{'PATH'}});
+      } elsif ($_) {
+	my $sys = $_;
+	foreach my $p (@{$main::Man{'PATH'}}) {
+	  my $dir = File::Spec->catdir($p, $sys);
+	  push @mp, $dir;
+	}
+      }				# if eq 'man'
+    }				# foreach SYS
+  } else {			# no SYS
+    @mp = @{$main::Man{'PATH'}};
+  }
+
+  if (@mp && $main::Man{'LANG'}) {
+    my @lang_path;
+    my $man_lang2 = '';
+    $man_lang2 = $main::Man{'LANG2'} if $main::Man{'LANG'} ne $main::Man{'LANG2'};
+    foreach my $i ($main::Man{'LANG'}, $man_lang2) {
+      next unless $i;
+      my $lang = $i;
+      foreach my $p (@mp) {
+	my $dir = File::Spec->catdir($p, $lang);
+	push @lang_path, $dir;
+      }				# foreach $p
+    }				# foreach $i
+    @mp = (@lang_path, @mp);
+  }				# if $mp
+
+  $main::Man{PATH} = [&path_uniq(@mp)];
+  1;
+} # manpath_add_lang_sys()
+
+
+##########
+# manpath_set_from_path()
+#
+# Determine basic search path for man pages from $PATH.
+#
+# Return:    `1' if a valid man path was retrieved.
+# Output:    none
+# Globals:
+#   in:  $PATH
+#   out: $_MAN_PATH
+#
+sub manpath_set_from_path {
+  my @path =
+    qw( /usr/local /usr /usr/X11R6 /usr/openwin /opt /opt/gnome /opt/kde );
+  # get a basic man path from $ENV{PATH}
+  my @path2 = @main::Path;
+  foreach (@path2) {
+    s#bin/*$##;
+    push @path, $_;
+  }
+  @path = &path_uniq(@path);
+  foreach my $d (@path) {
+    foreach my $e ( File::Spec->catdir( qw(share man) ),
+		 File::Spec->catdir( qw(share MAN) ),
+		 'man',  'MAN' ) {
+      my $dir = File::Spec->catdir($d, $e);
+      push @{$main::Man{'PATH'}}, $dir if -d $dir;
+    }
+  }
+  1;
+} # manpath_set_from_path()
+
+
+##########
+# special_filespec()
+#
+# Handle special modes like whatis and apropos.  Run their filespec
+# functions if suitable.
+#
+# Globals:  in: $main::Opt{'APROPOS'}, $main::Opt{'WHATIS'}, $main::Special_Setup
+#          out: $main::Special_Filespec (internal)
+#
+sub special_filespec {
+  return 0 unless $main::Opt{'APROPOS'} || $main::Opt{'WHATIS'};
+  die 'special_filespec(): setup for apropos or whatis must be run first;'
+    unless $main::Special_Setup;
+  if ( $main::Opt{'APROPOS'} ) {
+    die "special_setup(): both apropos and whatis option variables are set;"
+      if $main::Opt{'WHATIS'};
+    return &apropos_filespec() ? 1 : 0;
+  }
+  if ( $main::Opt{'WHATIS'} ) {
+    return &whatis_filespec() ? 1 : 0;
+  }
+  0;
+} # special_filespec
+
+
+##########
+# special_setup()
+#
+# Handle special modes like whatis and apropos.  Run their setup
+# functions if suitable.
+#
+sub special_setup {
+  if ( $main::Opt{'APROPOS'} ) {
+    die "special_setup(): both --apropos and --whatis option variables " .
+      "are set;" if $main::Opt{'WHATIS'};
+    return &apropos_setup() ? 1 : 0;
+  }
+  if ( $main::Opt{'WHATIS'} ) {
+    return &whatis_setup() ? 1 : 0;
+  }
+  0;
+} # special_setup()
+
+
+##########
+# whatis_filename(<filename>)
+#
+# Interpret <filename> as a man page and display its `whatis'
+# information as a fragment written in the groff language.
+#
+# Globals:  in: $main::Opt{'WHATIS'}, $main::Special_Setup, $main::Special_Filespec,
+#               $main::Filespec_Arg
+#
+sub whatis_filename {
+  my $n = @_;
+  die "whatis_filename(): one argument is needed; you used $n;"
+    unless $n == 1;
+  die "whatis_filename(): whatis is not setup;" unless $main::Opt{'WHATIS'};
+  die "whatis_filename(): setup for whatis must be run first;"
+    unless $main::Special_Setup;
+  die "whatis_filename(): whatis_filespec() must be run first;"
+    unless $main::Special_Filespec;
+  die 'whatis_filename(): no $main::Filespec_Arg is set;'
+    unless defined $main::Filespec_Arg;
+
+  my $arg = $_[0];
+  die "whatis_file_name(): $arg is not an existing file" unless -f $arg;
+  die "whatis_file_name(): could not read file $arg" unless -r $arg;
+  return 1 if -z $arg;
+  $arg = 'stdin' if $main::Filespec_Arg eq '-';
+
+  &to_tmp_line('.br', '\\f[CR]' . $arg . '\\f[]:', '.br');
+
+### whatis_filename()
+  # get the parts of the file name according to the naming of man pages
+  my ($dir, $name) = &split_path( $_[0] );
+  my $section = $_[0];
+  my $path = File::Spec->catfile('', 'man');
+  $section =~ s#^.*$path([$main::Man{'AUTO_SEC_CHARS'}]).*$#$1#;
+  $section = '' if $section eq $_[0];
+  if ($section) {
+    if ($name =~ m#^.*\.$section.*$#) {
+      $name =~ s/^(.*)\.$section.*$/$1/;
+    } else {
+      $section = '';
+    }
+  }
+
+  # traditional man style; grep the line containing `.TH' macro, if any
+  my @catz = &cat_z($_[0]);
+  my $res;
+  my $test;
+  foreach (@catz) {
+    if (/^[\.']\s*TH\s/) {		# search .TH, traditional man style
+      $test = 1;
+      last;
+    }
+  }				# foreach (@catz)
+### whatis_filename()
+  if ($test) {			# traditional man style
+    # get the first line after the first `.SH' macro before the next `.SH'
+    my $test1;
+    foreach (@catz) {
+      if ($test1) {
+	chomp;
+	next unless $_;
+	next if /^[\.']?\s*$/;
+	last if /^[\.']/;		# especially for .SH
+	if ($res) {
+	  $res = "$res $_";
+	} else {
+	  $res = $_;
+	}
+      } else {			# $test1 is empty
+	$test1 = 1 if (/^[\.']\s*SH\s/);
+      }				# if ($test1)
+    }				# foreach (@catz)
+
+    if ($section) {
+      if ($res =~ m|^
+		    $name
+		    \s
+		    [^-]*
+		    -
+		    \s*
+		    (.*)
+		    $|sx) {
+	$res = "$name ($section) \\[em] $1";
+      }
+    }				# if ($section)
+### whatis_filename()
+    &to_tmp_line($res, '.br', '', '.br');
+    return 1;
+  }				# if ($test)
+
+  # mdoc style (BSD doc); grep the line containing `.Nd' macro, if any
+  foreach (@catz) {
+    if (/^[\.']\s*Nd\s/) {		# BSD doc style
+      $res =~ s/^(.*)$/$name ($section) \\[em] $1/;
+      &to_tmp_line($res);
+      return 1;
+    }
+  }
+
+  &to_tmp_line('is not a man page', '.br', '', '.br');
+  1;
+} # whatis_filename()
+
+
+##########
+# whatis_filespec()
+#
+# Print the filespec name as .SH to the temporary cat file.
+#
+# Globals: in: $main::Opt{'WHATIS'}, $main::Filespec_Arg
+#      in/out: $main::Special_Filespec
+#
+sub whatis_filespec {
+  return 0 unless ($main::Opt{'WHATIS'});
+  die 'whatis_filespec(): whatis_setup() must be run first.'
+    unless $main::Special_Setup;
+  die 'whatis_filespec(): no $main::Filespec_Arg is set;'
+    unless defined $main::Filespec_Arg;
+  $main::Special_Filespec = 1;
+  my $arg = $main::Filespec_Arg;
+  $arg =~ s/[^\\]-/\\-/g;
+  to_tmp_line(".SH $arg");
+} # whatis_filespec()
+
+
+##########
+# whatis_setup ()
+#
+# Print the whatis header to the temporary cat file; this is the setup
+# for whatis.
+#
+# Globals:  in: $main::Opt{'WHATIS'}
+#          out: $main::Special_Setup
+sub whatis_setup {
+  if ( $main::Opt{'WHATIS'} ) {
+    &to_tmp_line('.TH GROFFER WHATIS');
+    $main::Special_Setup = 1;
+    $main::Opt{'TITLE'} = 'whatis' unless $main::Opt{'TITLE'};
+    return 1;
+  }
+  0;
+} # whatis_setup ()
+
+1;

Index: perl_test.pl
===================================================================
RCS file: perl_test.pl
diff -N perl_test.pl
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ perl_test.pl	11 Aug 2013 08:28:52 -0000	1.6
@@ -0,0 +1,34 @@
+#! /usr/bin/env perl
+
+# groffer - display groff files
+
+# Source file position: <groff-source>/contrib/groffer/perl/perl_test.sh
+# Installed position: <prefix>/lib/groff/groffer/perl_test.sh
+
+# Copyright (C) 2006, 2009 Free Software Foundation, Inc.
+# Written by Bernd Warken <groff-bernd.warken-72@web.de>.
+
+# Last update: 5 Jan 2009
+
+# 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/>.
+
+########################################################################
+
+# This file tests whether perl has a suitable version.  It is used by
+# groffer.pl and Makefile.sub.
+
+# require 5.004_05;
+require v5.6.1;

Index: roff2.pl
===================================================================
RCS file: roff2.pl
diff -N roff2.pl
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ roff2.pl	11 Aug 2013 08:28:52 -0000	1.8
@@ -0,0 +1,223 @@
+#! /usr/bin/env perl
+
+# roff2* - transform roff files into other formats
+
+# Source file position: <groff-source>/contrib/groffer/perl/roff2.pl
+# Installed position: <prefix>/bin/roff2*
+
+# Copyright (C) 2006, 2008, 2009 Free Software Foundation, Inc.
+# Written by Bernd Warken <groff-bernd.warken-72@web.de>.
+
+# Last update: 5 Jan 2009
+
+# 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/>.
+
+########################################################################
+
+require v5.6;
+
+use strict;
+use warnings;
+use File::Spec;
+
+# temporary dir and files
+use File::Temp qw/ tempfile /;
+
+my $Dev_Null = File::Spec->devnull();
+my $Mode;
+my $Name;
+{
+  my ($v, $d);
+  ($v, $d, $Name) = File::Spec->splitpath($0);
+  die "wrong program name: $Name;"
+    if $Name !~ /^roff2[a-z]/;
+}
+$Mode = $Name;
+$Mode =~ s/^roff2//;
+
+my $Groff_Version = `groff --version 2>$Dev_Null`;
+die "$Name error: groff does not work;" if $?;
+my $Groffer_Version = `groffer --version 2>$Dev_Null`;
+my $Has_Groffer = ! $?;
+
+if ($Has_Groffer) {
+  foreach (@ARGV) {
+    last if $_ eq '--';
+    next if $_ eq '-';
+    if ($_ eq '-v' || '--version' =~ m|^$_|) {
+      print $Name, ' in ', $Groffer_Version;
+      exit 0;
+    }
+    if ($_ eq '-h' || '--help' =~ m|^$_|) {
+      &usage_with_groffer();
+      exit 0;
+    }
+  }
+  system('groffer', '--to-stdout', "--$Mode", @ARGV);
+  exit $?;
+} else {
+  my @filespec;
+  my $double_minus;
+  foreach (@ARGV) {
+    if ($double_minus) {
+      push @filespec, $_;
+      next;
+    }
+    if ($_ eq '--') {
+      $double_minus = 1;
+      next;
+    }
+    if ($_ eq '-') {
+      push @filespec, '-';
+      next;
+    }
+    if ($_ eq '-v' || '--version' =~ m|^$_|) {
+      print $Name, ' in ', $Groff_Version;
+      exit 0;
+    }
+    if ($_ eq '-h' || '--help' =~ m|^$_|) {
+      &usage_without_groffer();
+      exit 0;
+    }
+    if ($_ =~ /^-/) {
+      &error_no_groffer();
+      &error_no_options();
+      next;
+    }
+    if (-f && -r) {
+      push @filespec, $_;
+    } else {
+      &error_no_groffer();
+      print STDERR "$_ is not an existing, readable file.\n";
+    }
+  }
+
+  @filespec = ('-') unless @filespec;
+  my $has_stdin;
+  foreach (@filespec) {
+    if ($_ eq '-') {
+      $has_stdin =1;
+      last;
+    }
+  }
+
+  if ($has_stdin) {
+    my $tempdir;
+    foreach ($ENV{'GROFF_TMPDIR'}, $ENV{'TMPDIR'}, $ENV{'TMP'},
+	     $ENV{'TEMP'}, $ENV{'TEMPDIR'},
+	     File::Spec->catfile($ENV{'HOME'}, 'tmp')) {
+      if ($_ && -d $_ && -w $_) {
+	$tempdir = $_;
+	last;
+      }
+    }
+    my $template = $Name . '_XXXX';
+    my ($fh, $stdin);
+    if ($tempdir) {
+      ($fh, $stdin) = tempfile($template, UNLINK => 1, DIR => $tempdir) ||
+	die "$Name: could not create temporary file;";
+    } else {
+      ($fh, $stdin) = tempfile($template, UNLINK => 1) ||
+	die "$Name: could not create temporary file;";
+    }
+    open $fh, ">$stdin";
+    print $fh $_ foreach <STDIN>;
+
+    foreach (@filespec) {
+      $_ = $stdin if $_ eq '-';
+    }
+  }				# if $has_stdin
+
+  my $grog;
+  my $groff_options = "-T$Mode";
+  $groff_options = '-TX75-12 -Z' if $Mode eq 'x';
+  $groff_options = '-Tlatin1' if $Mode eq 'text';
+  if ($Mode eq 'pdf') {
+    my $ps2pdf;
+    my @path = File::Spec->path();
+    foreach (@path) {
+      my $file = File::Spec->catfile($_, 'ps2pdf');
+      if (-f $file && -x $file) {
+	$ps2pdf = "$file -";
+	last;
+      }
+    }
+    unless ($ps2pdf) {
+      foreach (@path) {
+	my $file = File::Spec->catfile($_, 'gs');
+	if (-f $file && -x $file) {
+	  $ps2pdf = $file . ' -q -dNOPAUSE -dBATCH -sDEVICE=pdfwrite ' .
+	    '-sOutputFile=- -c save pop -f -';
+	  last;
+	}
+      }
+    }
+    $grog = `grog -Tps @filespec`;
+    chomp $grog;
+    system("$grog | $ps2pdf");
+    exit $?;
+  } else {
+    $grog = `grog $groff_options @filespec`;
+    chomp $grog;
+    system($grog);
+    exit $?;
+  }
+}
+
+my $error_no_groffer;
+sub error_no_groffer {
+  return 1 if $error_no_groffer;
+  $error_no_groffer = 1;
+  print STDERR "$Name: groffer is not available.\n";
+}
+
+my $error_no_options;
+sub error_no_options {
+  return 1 if $error_no_options;
+  $error_no_groffer = 1;
+  print STDERR "$Name: groffer options are not allowed.\n";
+}
+
+sub usage_with_groffer {
+  print <<EOF;
+usage: $Name [option]... [--] [filespec]...
+
+-h | --help     print usage information
+-v | --version  print version information
+
+All other options are arbitrary options of `groffer'; the options
+override the behavior of this program.
+
+`filespec's are the same as in `groffer': either the names of
+existing, readable files or `-' for standard input or a search pattern
+for man pages.  No `filespec' assumes standard input automatically.
+EOF
+}
+
+sub usage_without_groffer {
+  print <<EOF;
+usage: $Name [option]... [--] [filespec]...
+
+-h | --help     print usage information
+-v | --version  print version information
+
+No other options are allowed because `groffer' is not available.
+
+The only `filespec's allowed are the names of existing, readable files
+or `-' for standard input.  No `filespec' assumes standard input
+automatically.
+EOF
+}

Index: split_env.sh
===================================================================
RCS file: split_env.sh
diff -N split_env.sh
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ split_env.sh	11 Aug 2013 08:28:52 -0000	1.6
@@ -0,0 +1,48 @@
+#! /bin/sh
+
+# groffer - display groff files
+
+# Source file position: <groff-source>/contrib/groffer/perl/split_env.sh
+# Installed position: <prefix>/lib/groff/groffer/split_env.sh
+
+# Copyright (C) 2006, 2009 Free Software Foundation, Inc.
+# Written by Bernd Warken <groff-bernd.warken-72@web.de>.
+
+# Last update: 5 Jan 2009
+
+# 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/>.
+
+########################################################################
+
+# This file is called from groffer.pl.  The environment variable
+# of the name in $1 will be split at output.  The corresponding variable
+# must be exported before the call of groffer.pl.
+
+if test $# = 0
+then
+    echo 'split_env.sh was called without an argument.' >&2;
+else
+    eval v='"$'"$1"'"';
+    if test _"$v"_ != __
+    then
+	eval set x $v;
+	shift;
+	for i in "$@";
+	  do
+	  echo $i;
+	done;
+    fi;
+fi;


From MAILER-DAEMON Sun Aug 11 04:30:00 2013
Received: from list by lists.gnu.org with archive (Exim 4.71)
	id 1V8R2G-0005Tl-Id
	for mharc-groff-commit@gnu.org; Sun, 11 Aug 2013 04:30:00 -0400
Received: from eggs.gnu.org ([2001:4830:134:3::10]:52027)
	by lists.gnu.org with esmtp (Exim 4.71) (envelope-from <wl@gnu.org>)
	id 1V8R24-0005Dq-Tl
	for groff-commit@gnu.org; Sun, 11 Aug 2013 04:29:58 -0400
Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71)
	(envelope-from <wl@gnu.org>) id 1V8R1v-0002wE-FQ
	for groff-commit@gnu.org; Sun, 11 Aug 2013 04:29:48 -0400
Received: from vcs.savannah.gnu.org ([140.186.70.72]:59764)
	by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from <wl@gnu.org>)
	id 1V8R1v-0002w8-AM
	for groff-commit@gnu.org; Sun, 11 Aug 2013 04:29:39 -0400
Received: from wl by vcs.savannah.gnu.org with local (Exim 4.72)
	(envelope-from <wl@gnu.org>) id 1V8R1u-0002XW-RB
	for groff-commit@gnu.org; Sun, 11 Aug 2013 08:29:39 +0000
Date: Sun, 11 Aug 2013 08:29:38 +0000
Message-Id: <E1V8R1u-0002XW-RB@vcs.savannah.gnu.org>
To: groff-commit@gnu.org
From: Werner LEMBERG <wl@gnu.org>
X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6.x
X-Received-From: 140.186.70.72
Subject: [Groff-commit] groff/contrib/chem/examples/122 README.txt ch2a...
X-BeenThere: groff-commit@gnu.org
X-Mailman-Version: 2.1.14
Precedence: list
List-Id: <groff-commit.gnu.org>
List-Unsubscribe: <https://lists.gnu.org/mailman/options/groff-commit>,
	<mailto:groff-commit-request@gnu.org?subject=unsubscribe>
List-Archive: <http://lists.gnu.org/archive/html/groff-commit>
List-Post: <mailto:groff-commit@gnu.org>
List-Help: <mailto:groff-commit-request@gnu.org?subject=help>
List-Subscribe: <https://lists.gnu.org/mailman/listinfo/groff-commit>,
	<mailto:groff-commit-request@gnu.org?subject=subscribe>
X-List-Received-Date: Sun, 11 Aug 2013 08:29:58 -0000

CVSROOT:	/sources/groff
Module name:	groff
Changes by:	Werner LEMBERG <wl>	13/08/11 08:29:38

Added files:
	contrib/chem/examples/122: README.txt ch2a_ethyl.chem 
	                           ch2b_benzene.chem 
	                           ch2c_benzene_right.chem 
	                           ch4a_stick.chem 
	                           ch4b_methyl_acetate.chem 
	                           ch4c_colon.chem ch4d_HCl.H2O.chem 
	                           ch4e_CaSO4.2H2O.chem ch4f_C.chem 
	                           ch4g_BP.chem ch4h_methacrylate.chem 
	                           ch4i_cyclo.chem ch4j_ring4.chem 
	                           ch4k_ring3.chem ch4l_vertex.chem 
	                           ch4m_double.chem ch4n_triple.chem 
	                           ch4o_aromatic.chem 
	                           ch4p_cholestanol.chem ch4q_rings.chem 
	                           ch4r_spiro.chem ch4s_heteroatoms.chem 
	                           ch4t_polycyclic.chem 
	                           ch4u_nicotine.chem 
	                           ch4v_histidine.chem ch4w_lsd.chem 
	                           ch4x_anisole.chem ch4y_reserpine.chem 
	                           ch4z1_eqn_glutamic.chem 
	                           ch4z2_text.chem ch5a_size.chem 
	                           ch6a_pic.chem ch6b_dna.chem 
	                           chAa_polymer.chem 
	                           chAb_vinyl_chloro.chem 
	                           chAc_morphine.chem 
	                           chAd_chlorophyll.chem chAe_chair.chem 
	                           chAf_arrow.chem chAg_circle.chem 
	                           chAh_brackets.chem 
	                           chAi_poly_vinyl_chloride.chem 
	                           chBa_jump.chem chBb_bonds.chem 
	                           chBc_rings.chem 

Log message:
	Revert accidental removal of previous commit.

CVSWeb URLs:
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/chem/examples/122/README.txt?cvsroot=groff&rev=1.4
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/chem/examples/122/ch2a_ethyl.chem?cvsroot=groff&rev=1.6
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/chem/examples/122/ch2b_benzene.chem?cvsroot=groff&rev=1.6
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/chem/examples/122/ch2c_benzene_right.chem?cvsroot=groff&rev=1.6
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/chem/examples/122/ch4a_stick.chem?cvsroot=groff&rev=1.6
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/chem/examples/122/ch4b_methyl_acetate.chem?cvsroot=groff&rev=1.6
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/chem/examples/122/ch4c_colon.chem?cvsroot=groff&rev=1.6
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/chem/examples/122/ch4d_HCl.H2O.chem?cvsroot=groff&rev=1.6
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/chem/examples/122/ch4e_CaSO4.2H2O.chem?cvsroot=groff&rev=1.6
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/chem/examples/122/ch4f_C.chem?cvsroot=groff&rev=1.6
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/chem/examples/122/ch4g_BP.chem?cvsroot=groff&rev=1.6
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/chem/examples/122/ch4h_methacrylate.chem?cvsroot=groff&rev=1.6
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/chem/examples/122/ch4i_cyclo.chem?cvsroot=groff&rev=1.6
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/chem/examples/122/ch4j_ring4.chem?cvsroot=groff&rev=1.6
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/chem/examples/122/ch4k_ring3.chem?cvsroot=groff&rev=1.6
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/chem/examples/122/ch4l_vertex.chem?cvsroot=groff&rev=1.6
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/chem/examples/122/ch4m_double.chem?cvsroot=groff&rev=1.6
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/chem/examples/122/ch4n_triple.chem?cvsroot=groff&rev=1.6
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/chem/examples/122/ch4o_aromatic.chem?cvsroot=groff&rev=1.6
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/chem/examples/122/ch4p_cholestanol.chem?cvsroot=groff&rev=1.6
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/chem/examples/122/ch4q_rings.chem?cvsroot=groff&rev=1.6
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/chem/examples/122/ch4r_spiro.chem?cvsroot=groff&rev=1.6
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/chem/examples/122/ch4s_heteroatoms.chem?cvsroot=groff&rev=1.6
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/chem/examples/122/ch4t_polycyclic.chem?cvsroot=groff&rev=1.6
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/chem/examples/122/ch4u_nicotine.chem?cvsroot=groff&rev=1.6
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/chem/examples/122/ch4v_histidine.chem?cvsroot=groff&rev=1.6
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/chem/examples/122/ch4w_lsd.chem?cvsroot=groff&rev=1.6
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/chem/examples/122/ch4x_anisole.chem?cvsroot=groff&rev=1.6
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/chem/examples/122/ch4y_reserpine.chem?cvsroot=groff&rev=1.7
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/chem/examples/122/ch4z1_eqn_glutamic.chem?cvsroot=groff&rev=1.6
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/chem/examples/122/ch4z2_text.chem?cvsroot=groff&rev=1.6
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/chem/examples/122/ch5a_size.chem?cvsroot=groff&rev=1.6
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/chem/examples/122/ch6a_pic.chem?cvsroot=groff&rev=1.7
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/chem/examples/122/ch6b_dna.chem?cvsroot=groff&rev=1.7
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/chem/examples/122/chAa_polymer.chem?cvsroot=groff&rev=1.6
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/chem/examples/122/chAb_vinyl_chloro.chem?cvsroot=groff&rev=1.6
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/chem/examples/122/chAc_morphine.chem?cvsroot=groff&rev=1.6
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/chem/examples/122/chAd_chlorophyll.chem?cvsroot=groff&rev=1.6
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/chem/examples/122/chAe_chair.chem?cvsroot=groff&rev=1.6
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/chem/examples/122/chAf_arrow.chem?cvsroot=groff&rev=1.6
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/chem/examples/122/chAg_circle.chem?cvsroot=groff&rev=1.7
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/chem/examples/122/chAh_brackets.chem?cvsroot=groff&rev=1.6
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/chem/examples/122/chAi_poly_vinyl_chloride.chem?cvsroot=groff&rev=1.7
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/chem/examples/122/chBa_jump.chem?cvsroot=groff&rev=1.6
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/chem/examples/122/chBb_bonds.chem?cvsroot=groff&rev=1.6
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/chem/examples/122/chBc_rings.chem?cvsroot=groff&rev=1.6

Patches:
Index: README.txt
===================================================================
RCS file: README.txt
diff -N README.txt
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ README.txt	11 Aug 2013 08:29:33 -0000	1.4
@@ -0,0 +1,74 @@
+This directory contains the examples for the `chem' language written
+in the book:
+
+    Computing Science Technical Report No. 122
+    CHEM - A Program for Typesetting Chemical Diagrams: User Manual
+    by Jon L. Bentley, Lynn W. Jelinski, Brian W. Kernighan
+
+The book is available in the internet at
+<http://cm.bell-labs.com/cm/cs/cstr/122.ps.gz>.
+
+Many of the examples had to be fixed.  Unfortunately, the `chem' akw
+version does not run on many of these programs.  But the Perl version
+of `chem' works on all examples.
+
+Most examples do not use the modern chemical display.  They have C
+atoms added, whereas the modern method omits all C atoms and their
+directly appended H atoms.
+
+The examples are named and sorted by the chapter where they are found
+in the book.  For example, the file `ch4c_colon.chem' means a `chem'
+example in chapter 4; according to `c', it is the third example in
+this chapter; the name `colon' is used to describe the context of the
+example.
+
+You can view the graphical display of the examples by calling
+
+    groffer <file>
+
+`groffer' calls `chem' automatically.
+
+If you want to transform example files to a different format use the
+`roff2*' programs:
+
+`roff2dvi' prints dvi format to standard output,
+`roff2html' generates html output,
+`roff2pdf' outputs pdf mode,
+`roff2ps' produces PostScript output,
+`roff2text' generates text output in the groff device `latin1',
+`roff2x' prints the output  in  the  groff  device  X  that  is
+         suitable  for programs  like `gxditview' or `xditview'.
+
+To get a suitable `groff' output run
+
+    @g@chem <file> | groff -p ...
+
+
+####### License
+
+Last update: 5 Jan 2009
+
+Copyright (C) 2006, 2009 Free Software Foundation, Inc.
+Written by Bernd Warken <groff-bernd.warken-72@web.de>.
+
+This file is part of `chem', 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:

Index: ch2a_ethyl.chem
===================================================================
RCS file: ch2a_ethyl.chem
diff -N ch2a_ethyl.chem
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ ch2a_ethyl.chem	11 Aug 2013 08:29:33 -0000	1.6
@@ -0,0 +1,43 @@
+ch2a_ethyl.chem:
+.br
+.cstart
+
+# Example file for `chem':
+
+# This originates from Computing Science Technical Report No. 122
+#   CHEM - A Program for Typesetting Chemical Diagrams: User Manual
+#   by Jon L. Bentley, Lynn W. Jelinski, Brian W. Kernighan
+#   <http://cm.bell-labs.com/cm/cs/cstr/122.ps.gz>.
+
+# Copyright (C) 2006, 2009 Free Software Foundation, Inc.
+
+# Last update: 5 Jan 2009
+
+# This file is part of `chem', 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/>.
+
+########################################################################
+
+	CH3
+	bond
+	CH2
+	bond
+
+########################################################################
+### Emacs settings
+# Local Variables:
+# mode: Nroff
+# End:
+.cend

Index: ch2b_benzene.chem
===================================================================
RCS file: ch2b_benzene.chem
diff -N ch2b_benzene.chem
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ ch2b_benzene.chem	11 Aug 2013 08:29:33 -0000	1.6
@@ -0,0 +1,40 @@
+ch2b_benzene.chem:
+.br
+.cstart
+
+# Example file for `chem':
+
+# This originates from Computing Science Technical Report No. 122
+#   CHEM - A Program for Typesetting Chemical Diagrams: User Manual
+#   by Jon L. Bentley, Lynn W. Jelinski, Brian W. Kernighan
+#   <http://cm.bell-labs.com/cm/cs/cstr/122.ps.gz>.
+
+# Copyright (C) 2006, 2009 Free Software Foundation, Inc.
+
+# Last update: 5 Jan 2009
+
+# This file is part of `chem', 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/>.
+
+########################################################################
+
+	benzene
+
+########################################################################
+### Emacs settings
+# Local Variables:
+# mode: Nroff
+# End:
+.cend

Index: ch2c_benzene_right.chem
===================================================================
RCS file: ch2c_benzene_right.chem
diff -N ch2c_benzene_right.chem
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ ch2c_benzene_right.chem	11 Aug 2013 08:29:33 -0000	1.6
@@ -0,0 +1,40 @@
+ch2c_benzene_right.chem:
+.br
+.cstart
+
+# Example file for `chem':
+
+# This originates from Computing Science Technical Report No. 122
+#   CHEM - A Program for Typesetting Chemical Diagrams: User Manual
+#   by Jon L. Bentley, Lynn W. Jelinski, Brian W. Kernighan
+#   <http://cm.bell-labs.com/cm/cs/cstr/122.ps.gz>.
+
+# Copyright (C) 2006, 2009 Free Software Foundation, Inc.
+
+# Last update: 5 Jan 2009
+
+# This file is part of `chem', 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/>.
+
+########################################################################
+
+	benzene pointing right       # a rotated benzene ring
+
+########################################################################
+### Emacs settings
+# Local Variables:
+# mode: Nroff
+# End:
+.cend

Index: ch4a_stick.chem
===================================================================
RCS file: ch4a_stick.chem
diff -N ch4a_stick.chem
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ ch4a_stick.chem	11 Aug 2013 08:29:33 -0000	1.6
@@ -0,0 +1,45 @@
+ch4a_stick.chem:
+.br
+.cstart
+
+# Example file for `chem':
+
+# This originates from Computing Science Technical Report No. 122
+#   CHEM - A Program for Typesetting Chemical Diagrams: User Manual
+#   by Jon L. Bentley, Lynn W. Jelinski, Brian W. Kernighan
+#   <http://cm.bell-labs.com/cm/cs/cstr/122.ps.gz>.
+
+# Copyright (C) 2006, 2009 Free Software Foundation, Inc.
+
+# Last update: 5 Jan 2009
+
+# This file is part of `chem', 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/>.
+
+########################################################################
+
+	bond right
+	bond 60
+	bond 120
+	bond 60
+	bond 120
+	bond down
+
+########################################################################
+### Emacs settings
+# Local Variables:
+# mode: Nroff
+# End:
+.cend

Index: ch4b_methyl_acetate.chem
===================================================================
RCS file: ch4b_methyl_acetate.chem
diff -N ch4b_methyl_acetate.chem
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ ch4b_methyl_acetate.chem	11 Aug 2013 08:29:33 -0000	1.6
@@ -0,0 +1,49 @@
+ch4b_methyl_acetate.chem:
+.br
+.cstart
+
+# Example file for `chem':
+
+# This originates from Computing Science Technical Report No. 122
+#   CHEM - A Program for Typesetting Chemical Diagrams: User Manual
+#   by Jon L. Bentley, Lynn W. Jelinski, Brian W. Kernighan
+#   <http://cm.bell-labs.com/cm/cs/cstr/122.ps.gz>.
+
+# Copyright (C) 2006, 2009 Free Software Foundation, Inc.
+
+# Last update: 5 Jan 2009
+
+# This file is part of `chem', 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/>.
+
+########################################################################
+
+CH3      # the 3 is automatically turned into a subscript
+bond     # the implicit direction is right
+         # implicit connection is to right side of CH3
+C
+double bond 30     # by default, from the substituent C
+O
+bond 120 from C    # must be "from C"; otherwise would leave from O
+O
+bond right
+CH3
+
+########################################################################
+### Emacs settings
+# Local Variables:
+# mode: Nroff
+# End:
+.cend

Index: ch4c_colon.chem
===================================================================
RCS file: ch4c_colon.chem
diff -N ch4c_colon.chem
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ ch4c_colon.chem	11 Aug 2013 08:29:33 -0000	1.6
@@ -0,0 +1,44 @@
+ch4c_colon.chem:
+.br
+.cstart
+
+# Example file for `chem':
+
+# This originates from Computing Science Technical Report No. 122
+#   CHEM - A Program for Typesetting Chemical Diagrams: User Manual
+#   by Jon L. Bentley, Lynn W. Jelinski, Brian W. Kernighan
+#   <http://cm.bell-labs.com/cm/cs/cstr/122.ps.gz>.
+
+# Copyright (C) 2006, 2009 Free Software Foundation, Inc.
+
+# Last update: 5 Jan 2009
+
+# This file is part of `chem', 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/>.
+
+########################################################################
+
+	CH3
+	bond ; C
+	double bond 30 ; O
+	bond 120 from C ; O
+	bond right ; CH3
+
+########################################################################
+### Emacs settings
+# Local Variables:
+# mode: Nroff
+# End:
+.cend

Index: ch4d_HCl.H2O.chem
===================================================================
RCS file: ch4d_HCl.H2O.chem
diff -N ch4d_HCl.H2O.chem
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ ch4d_HCl.H2O.chem	11 Aug 2013 08:29:33 -0000	1.6
@@ -0,0 +1,40 @@
+ch4d_HCl.H2O.chem:
+.br
+.cstart
+
+# Example file for `chem':
+
+# This originates from Computing Science Technical Report No. 122
+#   CHEM - A Program for Typesetting Chemical Diagrams: User Manual
+#   by Jon L. Bentley, Lynn W. Jelinski, Brian W. Kernighan
+#   <http://cm.bell-labs.com/cm/cs/cstr/122.ps.gz>.
+
+# Copyright (C) 2006, 2009 Free Software Foundation, Inc.
+
+# Last update: 5 Jan 2009
+
+# This file is part of `chem', 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/>.
+
+########################################################################
+
+	HCl.H2O
+
+########################################################################
+### Emacs settings
+# Local Variables:
+# mode: Nroff
+# End:
+.cend

Index: ch4e_CaSO4.2H2O.chem
===================================================================
RCS file: ch4e_CaSO4.2H2O.chem
diff -N ch4e_CaSO4.2H2O.chem
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ ch4e_CaSO4.2H2O.chem	11 Aug 2013 08:29:34 -0000	1.6
@@ -0,0 +1,40 @@
+ch4e_CaSO4.2H2O.chem:
+.br
+.cstart
+
+# Example file for `chem':
+
+# This originates from Computing Science Technical Report No. 122
+#   CHEM - A Program for Typesetting Chemical Diagrams: User Manual
+#   by Jon L. Bentley, Lynn W. Jelinski, Brian W. Kernighan
+#   <http://cm.bell-labs.com/cm/cs/cstr/122.ps.gz>.
+
+# Copyright (C) 2006, 2009 Free Software Foundation, Inc.
+
+# Last update: 5 Jan 2009
+
+# This file is part of `chem', 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/>.
+
+########################################################################
+
+	CaSO4.2H2O
+
+########################################################################
+### Emacs settings
+# Local Variables:
+# mode: Nroff
+# End:
+.cend

Index: ch4f_C.chem
===================================================================
RCS file: ch4f_C.chem
diff -N ch4f_C.chem
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ ch4f_C.chem	11 Aug 2013 08:29:34 -0000	1.6
@@ -0,0 +1,50 @@
+ch4f_C.chem:
+.br
+.cstart
+
+# Example file for `chem':
+
+# This originates from Computing Science Technical Report No. 122
+#   CHEM - A Program for Typesetting Chemical Diagrams: User Manual
+#   by Jon L. Bentley, Lynn W. Jelinski, Brian W. Kernighan
+#   <http://cm.bell-labs.com/cm/cs/cstr/122.ps.gz>.
+
+# Copyright (C) 2006, 2009 Free Software Foundation, Inc.
+
+# Last update: 5 Jan 2009
+
+# This file is part of `chem', 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/>.
+
+########################################################################
+
+	bond ; C             # 1st definition of C
+	bond up from C
+	bond down from C
+	bond right from C ; C         # 2nd definition of C
+	bond up from C
+	bond down from C
+	bond right from C ; C         # 3rd definition of C
+	bond up from C
+	bond down from C
+	bond right from C
+
+
+########################################################################
+### Emacs settings
+# Local Variables:
+# mode: Nroff
+# End:
+.cend

Index: ch4g_BP.chem
===================================================================
RCS file: ch4g_BP.chem
diff -N ch4g_BP.chem
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ ch4g_BP.chem	11 Aug 2013 08:29:34 -0000	1.6
@@ -0,0 +1,50 @@
+ch4g_BP.chem:
+.br
+.cstart
+
+# Example file for `chem':
+
+# This originates from Computing Science Technical Report No. 122
+#   CHEM - A Program for Typesetting Chemical Diagrams: User Manual
+#   by Jon L. Bentley, Lynn W. Jelinski, Brian W. Kernighan
+#   <http://cm.bell-labs.com/cm/cs/cstr/122.ps.gz>.
+
+# Copyright (C) 2006, 2009 Free Software Foundation, Inc.
+
+# Last update: 5 Jan 2009
+
+# This file is part of `chem', 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/>.
+
+########################################################################
+
+# this is the isopropyl group
+    bond 120 ; BP       # BP is right end of this bond
+    bond -120 from BP
+    bond right from BP ; C
+    front bond up ; CH3
+    back bond down from C ; D
+    bond right from C ; BP
+# redefine BP to mean the center carbon of this t-butyl group
+    bond up from BP
+    bond right from BP
+    bond down from BP
+
+########################################################################
+### Emacs settings
+# Local Variables:
+# mode: Nroff
+# End:
+.cend

Index: ch4h_methacrylate.chem
===================================================================
RCS file: ch4h_methacrylate.chem
diff -N ch4h_methacrylate.chem
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ ch4h_methacrylate.chem	11 Aug 2013 08:29:34 -0000	1.6
@@ -0,0 +1,67 @@
+ch4h_methacrylate.chem:
+.br
+.cstart
+
+# Example file for `chem':
+
+# This originates from Computing Science Technical Report No. 122
+#   CHEM - A Program for Typesetting Chemical Diagrams: User Manual
+#   by Jon L. Bentley, Lynn W. Jelinski, Brian W. Kernighan
+#   <http://cm.bell-labs.com/cm/cs/cstr/122.ps.gz>.
+
+# Copyright (C) 2006, 2009 Free Software Foundation, Inc.
+
+# Last update: 5 Jan 2009
+
+# This file is part of `chem', 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/>.
+
+########################################################################
+
+    bond dotted
+    bond right ; BP
+    bond up from BP ; C
+    double bond -60 from C ; O
+    bond 60 length .1 from C ; OCH3
+    bond down from BP ; CH3
+# begin second segment of polymer
+    bond right length .5 from BP ; BP
+    bond up length .1 from BP ; H
+    bond down length .1 from BP ; H
+# begin third segment of polymer
+    bond right length .5 from BP ; BP
+    bond up from BP ; C
+    double bond -60 from C ; O
+    bond 60 length .1 from C ; OCH3
+    bond down from BP ; CH3
+# begin fourth segment of polymer
+    bond right length .5 from BP ; BP
+    bond up length .1 from BP ; H
+    bond down length .1 from BP ; H
+# begin fifth segment of polymer
+    bond right length .5 from BP ; BP
+    bond up from BP ; C
+    double bond -60 from C ; O
+    bond 60 length .1 from C ; OCH3
+    bond down from BP ; CH3
+    bond right from BP
+    bond dotted
+
+########################################################################
+### Emacs settings
+# Local Variables:
+# mode: Nroff
+# End:
+.cend

Index: ch4i_cyclo.chem
===================================================================
RCS file: ch4i_cyclo.chem
diff -N ch4i_cyclo.chem
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ ch4i_cyclo.chem	11 Aug 2013 08:29:34 -0000	1.6
@@ -0,0 +1,47 @@
+ch4i_cyclo.chem:
+.br
+.cstart
+
+# Example file for `chem':
+
+# This originates from Computing Science Technical Report No. 122
+#   CHEM - A Program for Typesetting Chemical Diagrams: User Manual
+#   by Jon L. Bentley, Lynn W. Jelinski, Brian W. Kernighan
+#   <http://cm.bell-labs.com/cm/cs/cstr/122.ps.gz>.
+
+# Copyright (C) 2006, 2009 Free Software Foundation, Inc.
+
+# Last update: 5 Jan 2009
+
+# This file is part of `chem', 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/>.
+
+########################################################################
+
+R3:	ring3
+R4:	ring4 at R3 + (.75,0)
+R5:	ring5 at R4 + (.75,0)
+R6:	ring6 at R5 + (.75,0)
+B:	benzene at R6 + (.75,0)
+R7:	ring7 at B + (.75,0)
+R8:	ring8 at R7 + (.75,0)
+
+
+########################################################################
+### Emacs settings
+# Local Variables:
+# mode: Nroff
+# End:
+.cend

Index: ch4j_ring4.chem
===================================================================
RCS file: ch4j_ring4.chem
diff -N ch4j_ring4.chem
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ ch4j_ring4.chem	11 Aug 2013 08:29:34 -0000	1.6
@@ -0,0 +1,40 @@
+ch4j_ring4.chem:
+.br
+.cstart
+
+# Example file for `chem':
+
+# This originates from Computing Science Technical Report No. 122
+#   CHEM - A Program for Typesetting Chemical Diagrams: User Manual
+#   by Jon L. Bentley, Lynn W. Jelinski, Brian W. Kernighan
+#   <http://cm.bell-labs.com/cm/cs/cstr/122.ps.gz>.
+
+# Copyright (C) 2006, 2009 Free Software Foundation, Inc.
+
+# Last update: 5 Jan 2009
+
+# This file is part of `chem', 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/>.
+
+########################################################################
+
+	ring4 pointing 45
+
+########################################################################
+### Emacs settings
+# Local Variables:
+# mode: Nroff
+# End:
+.cend

Index: ch4k_ring3.chem
===================================================================
RCS file: ch4k_ring3.chem
diff -N ch4k_ring3.chem
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ ch4k_ring3.chem	11 Aug 2013 08:29:34 -0000	1.6
@@ -0,0 +1,42 @@
+ch4k_ring3.chem:
+.br
+.cstart
+
+# Example file for `chem':
+
+# This originates from Computing Science Technical Report No. 122
+#   CHEM - A Program for Typesetting Chemical Diagrams: User Manual
+#   by Jon L. Bentley, Lynn W. Jelinski, Brian W. Kernighan
+#   <http://cm.bell-labs.com/cm/cs/cstr/122.ps.gz>.
+
+# Copyright (C) 2006, 2009 Free Software Foundation, Inc.
+
+# Last update: 5 Jan 2009
+
+# This file is part of `chem', 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/>.
+
+########################################################################
+
+R: ring3
+   back bond 120 from R.V2 ; C2H5
+   front bond -120 from R.V3 ; HO
+
+########################################################################
+### Emacs settings
+# Local Variables:
+# mode: Nroff
+# End:
+.cend

Index: ch4l_vertex.chem
===================================================================
RCS file: ch4l_vertex.chem
diff -N ch4l_vertex.chem
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ ch4l_vertex.chem	11 Aug 2013 08:29:35 -0000	1.6
@@ -0,0 +1,47 @@
+ch4l_vertex.chem:
+.br
+.cstart
+
+# Example file for `chem':
+
+# This originates from Computing Science Technical Report No. 122
+#   CHEM - A Program for Typesetting Chemical Diagrams: User Manual
+#   by Jon L. Bentley, Lynn W. Jelinski, Brian W. Kernighan
+#   <http://cm.bell-labs.com/cm/cs/cstr/122.ps.gz>.
+
+# Copyright (C) 2006, 2009 Free Software Foundation, Inc.
+
+# Last update: 5 Jan 2009
+
+# This file is part of `chem', 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/>.
+
+########################################################################
+
+R: benzene pointing right
+   bond left from R.V4 ; HO
+   bond -150 from R.V3 ; CH3O
+   bond right from R.V1 ; C
+   double bond up from C ; O
+   bond right from C ; N
+   bond 45 ; C2H5
+   bond 135 from N ; C2H5
+
+########################################################################
+### Emacs settings
+# Local Variables:
+# mode: Nroff
+# End:
+.cend

Index: ch4m_double.chem
===================================================================
RCS file: ch4m_double.chem
diff -N ch4m_double.chem
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ ch4m_double.chem	11 Aug 2013 08:29:35 -0000	1.6
@@ -0,0 +1,40 @@
+ch4m_double.chem:
+.br
+.cstart
+
+# Example file for `chem':
+
+# This originates from Computing Science Technical Report No. 122
+#   CHEM - A Program for Typesetting Chemical Diagrams: User Manual
+#   by Jon L. Bentley, Lynn W. Jelinski, Brian W. Kernighan
+#   <http://cm.bell-labs.com/cm/cs/cstr/122.ps.gz>.
+
+# Copyright (C) 2006, 2009 Free Software Foundation, Inc.
+
+# Last update: 5 Jan 2009
+
+# This file is part of `chem', 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/>.
+
+########################################################################
+
+	ring double 1,2 3,4 5,6
+
+########################################################################
+### Emacs settings
+# Local Variables:
+# mode: Nroff
+# End:
+.cend

Index: ch4n_triple.chem
===================================================================
RCS file: ch4n_triple.chem
diff -N ch4n_triple.chem
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ ch4n_triple.chem	11 Aug 2013 08:29:35 -0000	1.6
@@ -0,0 +1,40 @@
+ch4n_triple.chem:
+.br
+.cstart
+
+# Example file for `chem':
+
+# This originates from Computing Science Technical Report No. 122
+#   CHEM - A Program for Typesetting Chemical Diagrams: User Manual
+#   by Jon L. Bentley, Lynn W. Jelinski, Brian W. Kernighan
+#   <http://cm.bell-labs.com/cm/cs/cstr/122.ps.gz>.
+
+# Copyright (C) 2006, 2009 Free Software Foundation, Inc.
+
+# Last update: 5 Jan 2009
+
+# This file is part of `chem', 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/>.
+
+########################################################################
+
+	ring8 triple 3,4
+
+########################################################################
+### Emacs settings
+# Local Variables:
+# mode: Nroff
+# End:
+.cend

Index: ch4o_aromatic.chem
===================================================================
RCS file: ch4o_aromatic.chem
diff -N ch4o_aromatic.chem
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ ch4o_aromatic.chem	11 Aug 2013 08:29:35 -0000	1.6
@@ -0,0 +1,41 @@
+ch4o_aromatic.chem:
+.br
+.cstart
+
+# Example file for `chem':
+
+# This originates from Computing Science Technical Report No. 122
+#   CHEM - A Program for Typesetting Chemical Diagrams: User Manual
+#   by Jon L. Bentley, Lynn W. Jelinski, Brian W. Kernighan
+#   <http://cm.bell-labs.com/cm/cs/cstr/122.ps.gz>.
+
+# Copyright (C) 2006, 2009 Free Software Foundation, Inc.
+
+# Last update: 5 Jan 2009
+
+# This file is part of `chem', 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/>.
+
+########################################################################
+
+R: aromatic ring7
+   "+" at R
+
+########################################################################
+### Emacs settings
+# Local Variables:
+# mode: Nroff
+# End:
+.cend

Index: ch4p_cholestanol.chem
===================================================================
RCS file: ch4p_cholestanol.chem
diff -N ch4p_cholestanol.chem
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ ch4p_cholestanol.chem	11 Aug 2013 08:29:35 -0000	1.6
@@ -0,0 +1,62 @@
+ch4p_cholestanol.chem:
+.br
+.cstart
+
+# Example file for `chem':
+
+# This originates from Computing Science Technical Report No. 122
+#   CHEM - A Program for Typesetting Chemical Diagrams: User Manual
+#   by Jon L. Bentley, Lynn W. Jelinski, Brian W. Kernighan
+#   <http://cm.bell-labs.com/cm/cs/cstr/122.ps.gz>.
+
+# Copyright (C) 2006, 2009 Free Software Foundation, Inc.
+
+# Last update: 5 Jan 2009
+
+# This file is part of `chem', 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/>.
+
+########################################################################
+
+R1: ring6
+    "R1" at R1     # this puts a label at R1
+    front bond -120 from R1.V5 ; HO
+         # the following line says "fuse the next six-
+         # membered ring with its 6th vertex joining
+         # the second vertex of R1"
+R2: ring6 with .V6 at R1.V2
+    front bond up from R2.V6 ; CH3
+    back bond down from R2.V4 ; H
+    back bond down from R2.V1 ; H
+    front bond up from R2.V2 ; H
+R3: ring6 with .V4 at R2.V2
+R4: flatring with .V5 at R3.V2
+    front bond up from R4.V5 ; CH3
+    back bond down from R4.V4 ; H # this is the alkyl chain
+    bond up from R4.V1 ; BP
+    bond -60 from BP
+    bond 60 from BP
+    bond 120
+    bond 60
+    bond 120 ; BP
+    bond down from BP
+    bond 60 from BP
+
+########################################################################
+### Emacs settings
+# Local Variables:
+# mode: Nroff
+# End:
+.cend

Index: ch4q_rings.chem
===================================================================
RCS file: ch4q_rings.chem
diff -N ch4q_rings.chem
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ ch4q_rings.chem	11 Aug 2013 08:29:35 -0000	1.6
@@ -0,0 +1,48 @@
+ch4q_rings.chem:
+.br
+.cstart
+
+# Example file for `chem':
+
+# This originates from Computing Science Technical Report No. 122
+#   CHEM - A Program for Typesetting Chemical Diagrams: User Manual
+#   by Jon L. Bentley, Lynn W. Jelinski, Brian W. Kernighan
+#   <http://cm.bell-labs.com/cm/cs/cstr/122.ps.gz>.
+
+# Copyright (C) 2006, 2009 Free Software Foundation, Inc.
+
+# Last update: 5 Jan 2009
+
+# This file is part of `chem', 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/>.
+
+########################################################################
+
+R3: ring3
+R4: ring4 pointing 45 with .V1 at R3.V2
+R5: ring5 pointing down with .V4 at R4.V2
+R6: ring6 pointing 54 with .V6 at R5.V5
+    # the following lines specify the labels inside the rings
+    "3" at R3
+    "4" at R4
+    "5" at R5
+    "6" at R6
+
+########################################################################
+### Emacs settings
+# Local Variables:
+# mode: Nroff
+# End:
+.cend

Index: ch4r_spiro.chem
===================================================================
RCS file: ch4r_spiro.chem
diff -N ch4r_spiro.chem
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ ch4r_spiro.chem	11 Aug 2013 08:29:35 -0000	1.6
@@ -0,0 +1,44 @@
+ch4r_spiro.chem:
+.br
+.cstart
+
+# Example file for `chem':
+
+# This originates from Computing Science Technical Report No. 122
+#   CHEM - A Program for Typesetting Chemical Diagrams: User Manual
+#   by Jon L. Bentley, Lynn W. Jelinski, Brian W. Kernighan
+#   <http://cm.bell-labs.com/cm/cs/cstr/122.ps.gz>.
+
+# Copyright (C) 2006, 2009 Free Software Foundation, Inc.
+
+# Last update: 5 Jan 2009
+
+# This file is part of `chem', 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/>.
+
+########################################################################
+
+R1: ring6
+R2: ring6 with .V1 at R1.V4
+R3: ring5 with .V5 at R2.V3
+    back bond 60 from R3.V2 ; OH
+    front bond 150 from R3.V3 ; OH
+
+########################################################################
+### Emacs settings
+# Local Variables:
+# mode: Nroff
+# End:
+.cend

Index: ch4s_heteroatoms.chem
===================================================================
RCS file: ch4s_heteroatoms.chem
diff -N ch4s_heteroatoms.chem
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ ch4s_heteroatoms.chem	11 Aug 2013 08:29:35 -0000	1.6
@@ -0,0 +1,40 @@
+ch4s_heteroatoms.chem:
+.br
+.cstart
+
+# Example file for `chem':
+
+# This originates from Computing Science Technical Report No. 122
+#   CHEM - A Program for Typesetting Chemical Diagrams: User Manual
+#   by Jon L. Bentley, Lynn W. Jelinski, Brian W. Kernighan
+#   <http://cm.bell-labs.com/cm/cs/cstr/122.ps.gz>.
+
+# Copyright (C) 2006, 2009 Free Software Foundation, Inc.
+
+# Last update: 5 Jan 2009
+
+# This file is part of `chem', 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/>.
+
+########################################################################
+
+	ring put N at 2 put S at 4 double 2,3 4,5 6,1
+
+########################################################################
+### Emacs settings
+# Local Variables:
+# mode: Nroff
+# End:
+.cend

Index: ch4t_polycyclic.chem
===================================================================
RCS file: ch4t_polycyclic.chem
diff -N ch4t_polycyclic.chem
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ ch4t_polycyclic.chem	11 Aug 2013 08:29:35 -0000	1.6
@@ -0,0 +1,51 @@
+ch4t_polycyclic.chem:
+.br
+.cstart
+
+# Example file for `chem':
+
+# This originates from Computing Science Technical Report No. 122
+#   CHEM - A Program for Typesetting Chemical Diagrams: User Manual
+#   by Jon L. Bentley, Lynn W. Jelinski, Brian W. Kernighan
+#   <http://cm.bell-labs.com/cm/cs/cstr/122.ps.gz>.
+
+# Copyright (C) 2006, 2009 Free Software Foundation, Inc.
+
+# Last update: 5 Jan 2009
+
+# This file is part of `chem', 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/>.
+
+########################################################################
+
+R1: benzene pointing right
+    bond 30 from R1.V6 ; Br
+R2: benzene pointing right with .V5 at R1.V1
+R3: benzene pointing right with .V1 at R2.V3
+    bond 150 from R3.V2 ; CO2H
+R4: benzene pointing right with .V1 at R1.V3
+# next line names bond B1 so we can refer to its end
+B1: bond left from R4.V4
+    ring6 put N at 4 double 2,3 4,5 6,1 with .V3 at B1.end
+B2: bond right from R2.V1
+R5: benzene with .V5 at B2.end
+    ring6 put N at 4 double 1,2 3,4 with .V5 at R5.V3
+
+########################################################################
+### Emacs settings
+# Local Variables:
+# mode: Nroff
+# End:
+.cend

Index: ch4u_nicotine.chem
===================================================================
RCS file: ch4u_nicotine.chem
diff -N ch4u_nicotine.chem
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ ch4u_nicotine.chem	11 Aug 2013 08:29:36 -0000	1.6
@@ -0,0 +1,44 @@
+ch4u_nicotine.chem:
+.br
+.cstart
+
+# Example file for `chem':
+
+# This originates from Computing Science Technical Report No. 122
+#   CHEM - A Program for Typesetting Chemical Diagrams: User Manual
+#   by Jon L. Bentley, Lynn W. Jelinski, Brian W. Kernighan
+#   <http://cm.bell-labs.com/cm/cs/cstr/122.ps.gz>.
+
+# Copyright (C) 2006, 2009 Free Software Foundation, Inc.
+
+# Last update: 5 Jan 2009
+
+# This file is part of `chem', 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/>.
+
+########################################################################
+
+	benzene put N at 4
+	bond right
+	ring5 pointing down put N at 1
+	bond down from .N ; CH3        # or .V1
+
+
+########################################################################
+### Emacs settings
+# Local Variables:
+# mode: Nroff
+# End:
+.cend

Index: ch4v_histidine.chem
===================================================================
RCS file: ch4v_histidine.chem
diff -N ch4v_histidine.chem
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ ch4v_histidine.chem	11 Aug 2013 08:29:36 -0000	1.6
@@ -0,0 +1,46 @@
+ch4v_histidine.chem:
+.br
+.cstart
+
+# Example file for `chem':
+
+# This originates from Computing Science Technical Report No. 122
+#   CHEM - A Program for Typesetting Chemical Diagrams: User Manual
+#   by Jon L. Bentley, Lynn W. Jelinski, Brian W. Kernighan
+#   <http://cm.bell-labs.com/cm/cs/cstr/122.ps.gz>.
+
+# Copyright (C) 2006, 2009 Free Software Foundation, Inc.
+
+# Last update: 5 Jan 2009
+
+# This file is part of `chem', 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/>.
+
+########################################################################
+
+R1: flatring pointing down put N at 2 put N at 5 double 1,2 3,4
+    H right of R1.V5
+    bond right from R1.V4 ; CH2
+    bond right ; C
+    bond up from C ; H
+    bond down from C ; NH2
+    bond right from C ; CO2H
+
+########################################################################
+### Emacs settings
+# Local Variables:
+# mode: Nroff
+# End:
+.cend

Index: ch4w_lsd.chem
===================================================================
RCS file: ch4w_lsd.chem
diff -N ch4w_lsd.chem
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ ch4w_lsd.chem	11 Aug 2013 08:29:36 -0000	1.6
@@ -0,0 +1,52 @@
+ch4w_lsd.chem:
+.br
+.cstart
+
+# Example file for `chem':
+
+# This originates from Computing Science Technical Report No. 122
+#   CHEM - A Program for Typesetting Chemical Diagrams: User Manual
+#   by Jon L. Bentley, Lynn W. Jelinski, Brian W. Kernighan
+#   <http://cm.bell-labs.com/cm/cs/cstr/122.ps.gz>.
+
+# Copyright (C) 2006, 2009 Free Software Foundation, Inc.
+
+# Last update: 5 Jan 2009
+
+# This file is part of `chem', 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/>.
+
+########################################################################
+
+B: benzene pointing right
+F: flatring pointing left put N at 5 double 3,4 with .V1 at B.V2
+   H below F.N
+R: ring pointing right with .V4 at B.V6
+   front bond right from R.V6 ; H
+W: ring pointing right with .V2 at R.V6 put N at 1 double 3,4
+   bond right from W.N ; CH3
+   back bond -60 from W.V5 ; H
+   bond up from W.V5 ; C
+   double bond up from C ; O
+   bond right from C ; N
+   bond 45 from N ; C2H5
+   bond 135 from N ; C2H5
+
+########################################################################
+### Emacs settings
+# Local Variables:
+# mode: Nroff
+# End:
+.cend

Index: ch4x_anisole.chem
===================================================================
RCS file: ch4x_anisole.chem
diff -N ch4x_anisole.chem
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ ch4x_anisole.chem	11 Aug 2013 08:29:36 -0000	1.6
@@ -0,0 +1,44 @@
+ch4x_anisole.chem:
+.br
+.cstart
+
+# Example file for `chem':
+
+# This originates from Computing Science Technical Report No. 122
+#   CHEM - A Program for Typesetting Chemical Diagrams: User Manual
+#   by Jon L. Bentley, Lynn W. Jelinski, Brian W. Kernighan
+#   <http://cm.bell-labs.com/cm/cs/cstr/122.ps.gz>.
+
+# Copyright (C) 2006, 2009 Free Software Foundation, Inc.
+
+# Last update: 5 Jan 2009
+
+# This file is part of `chem', 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/>.
+
+########################################################################
+
+R1: benzene
+    bond down from R1.V4 ; OCH3
+R2: benzene at R1 + (1.5,0)
+    bond down from R2.V4 ; O
+    CH3 right of O
+
+########################################################################
+### Emacs settings
+# Local Variables:
+# mode: Nroff
+# End:
+.cend

Index: ch4y_reserpine.chem
===================================================================
RCS file: ch4y_reserpine.chem
diff -N ch4y_reserpine.chem
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ ch4y_reserpine.chem	11 Aug 2013 08:29:36 -0000	1.7
@@ -0,0 +1,64 @@
+ch4y_reserpine.chem:
+.br
+.cstart
+
+# Example file for `chem':
+
+# This originates from Computing Science Technical Report No. 122
+#   CHEM - A Program for Typesetting Chemical Diagrams: User Manual
+#   by Jon L. Bentley, Lynn W. Jelinski, Brian W. Kernighan
+#   <http://cm.bell-labs.com/cm/cs/cstr/122.ps.gz>.
+# Some corrections were added.
+
+# Copyright (C) 2006, 2009 Free Software Foundation, Inc.
+
+# Last update: 5 Jan 2009
+
+# This file is part of `chem', 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/>.
+
+########################################################################
+
+    CH3O
+    bond 60
+R1: benzene
+R2: aromatic flatring5 pointing down put N at 1 with .V3 at R1.V2
+    H below R2.V1
+R3: ring put N at 3 with .V5 at R2.V5
+R4: ring put N at 1 with .V1 at R3.V3
+    back bond -120 from R4.V4 ; H
+    back bond 60 from R4.V3 ; H
+R5: ring with .V1 at R4.V3
+    bond -120 ; C
+    double bond down from C ; O
+    CH3O left of C
+    back bond 60 from R5.V3 ; H
+    back bond down from R5.V4 ; O
+    CH3 right of O
+    bond 120 from R5.V3 ; O
+    bond right length .1 from O ; C
+    double bond down ; O
+    bond right length .1 from C
+B:  benzene pointing right
+    bond 30 from B.V6 ; OCH3
+    bond right from B.V1 ; OCH3
+    bond 150 from B.V2 ; OCH3
+
+########################################################################
+### Emacs settings
+# Local Variables:
+# mode: Nroff
+# End:
+.cend

Index: ch4z1_eqn_glutamic.chem
===================================================================
RCS file: ch4z1_eqn_glutamic.chem
diff -N ch4z1_eqn_glutamic.chem
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ ch4z1_eqn_glutamic.chem	11 Aug 2013 08:29:36 -0000	1.6
@@ -0,0 +1,80 @@
+ch4z1_eqn_glutamic.chem:
+.br
+.EQ
+delim $$
+.EN
+.cstart
+
+# Example file for `chem':
+
+# This originates from Computing Science Technical Report No. 122
+#   CHEM - A Program for Typesetting Chemical Diagrams: User Manual
+#   by Jon L. Bentley, Lynn W. Jelinski, Brian W. Kernighan
+#   <http://cm.bell-labs.com/cm/cs/cstr/122.ps.gz>.
+# Some corrections were added.
+
+# Copyright (C) 2006, 2009 Free Software Foundation, Inc.
+
+# Last update: 5 Jan 2009
+
+# This file is part of `chem', 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/>.
+
+########################################################################
+
+# a left bracket
+    bond right length .1 ; BP
+    bond up length .3
+    bond right length .1
+    bond down length .3 from BP
+    bond right length .1
+# this is the mainchain amide structure
+    bond right length .1 from BP ; NH
+    bond right ; CH
+# label the CH with an alpha, intended for eqn.
+# this line says "put the north edge of the alpha at the
+# south edge of the CH"
+    "$alpha$" with .n at CH.s
+    bond right from CH ; C
+    double bond up from C ; O
+    bond right length .1 from C ; BP
+# a right bracket
+    bond up length .3
+    bond left length .1
+    bond right length .1 from BP
+    bond down length .3 from BP ; BP
+    bond left length .1
+# label the degree of polymerization
+    "$n$" with .w at BP.se
+# this is the sidechain
+    bond up from CH ; CH2
+    "$beta$" with .e at CH2.w
+    bond up from CH2 ; CH2
+    "$gamma$" with .e at CH2.w
+    bond up from CH2 ; C
+# this is the benzyl ester part
+    double bond -60 from C ; O
+    bond 60 from C ; O
+    bond right ; CH2C6H5
+
+########################################################################
+### Emacs settings
+# Local Variables:
+# mode: Nroff
+# End:
+.cend
+.EQ
+delim off
+.EN

Index: ch4z2_text.chem
===================================================================
RCS file: ch4z2_text.chem
diff -N ch4z2_text.chem
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ ch4z2_text.chem	11 Aug 2013 08:29:36 -0000	1.6
@@ -0,0 +1,55 @@
+ch4z2_text.chem:
+.br
+.cstart
+
+# Example file for `chem':
+
+# This originates from Computing Science Technical Report No. 122
+#   CHEM - A Program for Typesetting Chemical Diagrams: User Manual
+#   by Jon L. Bentley, Lynn W. Jelinski, Brian W. Kernighan
+#   <http://cm.bell-labs.com/cm/cs/cstr/122.ps.gz>.
+
+# Copyright (C) 2006, 2009 Free Software Foundation, Inc.
+
+# Last update: 5 Jan 2009
+
+# This file is part of `chem', 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/>.
+
+########################################################################
+
+    bond 120 dotted
+    bond 120 length .3 ; BP
+    back bond -120 length .25 from BP ; H
+    front bond 120 length .25 from BP ; CH3
+    bond 60 length .5 from BP ; BP
+    bond -60 length .25 from BP ; H
+# note the pic move command to position the text
+    move left .35 ; "(ANTI)"
+    front bond 60 length .25 from BP ; H
+# another positioning of text
+    move right .35 ; "(SYN)"
+    bond 120 length .4 from BP ; BP
+    back bond -120 length .25 from BP ; H
+    front bond 120 length .25 from BP ; CH3
+    bond 60 length .5 from BP
+    bond 60 dotted
+
+########################################################################
+### Emacs settings
+# Local Variables:
+# mode: Nroff
+# End:
+.cend

Index: ch5a_size.chem
===================================================================
RCS file: ch5a_size.chem
diff -N ch5a_size.chem
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ ch5a_size.chem	11 Aug 2013 08:29:36 -0000	1.6
@@ -0,0 +1,47 @@
+ch5a_size.chem:
+.br
+.cstart
+
+# Example file for `chem':
+
+# This originates from Computing Science Technical Report No. 122
+#   CHEM - A Program for Typesetting Chemical Diagrams: User Manual
+#   by Jon L. Bentley, Lynn W. Jelinski, Brian W. Kernighan
+#   <http://cm.bell-labs.com/cm/cs/cstr/122.ps.gz>.
+
+# Copyright (C) 2006, 2009 Free Software Foundation, Inc.
+
+# Last update: 5 Jan 2009
+
+# This file is part of `chem', 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/>.
+
+########################################################################
+
+.ps 14
+size 16
+R: ring6 put O at 1 put C at 2 put O at 3 put C at 4 put O at 5 put C at 6
+   double bond 60 from R.V2 ; NH
+   double bond down from R.V4 ; NH
+   double bond -60 from R.V6 ; HN
+size 10 # if you are doing more than one
+.ps 10
+
+########################################################################
+### Emacs settings
+# Local Variables:
+# mode: Nroff
+# End:
+.cend

Index: ch6a_pic.chem
===================================================================
RCS file: ch6a_pic.chem
diff -N ch6a_pic.chem
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ ch6a_pic.chem	11 Aug 2013 08:29:36 -0000	1.7
@@ -0,0 +1,45 @@
+ch6a_pic.chem:
+.br
+.cstart
+
+# Example file for `chem':
+
+# This originates from Computing Science Technical Report No. 122
+#   CHEM - A Program for Typesetting Chemical Diagrams: User Manual
+#   by Jon L. Bentley, Lynn W. Jelinski, Brian W. Kernighan
+#   <http://cm.bell-labs.com/cm/cs/cstr/122.ps.gz>.
+
+# Copyright (C) 2006, 2009 Free Software Foundation, Inc.
+
+# Last update: 5 Jan 2009
+
+# This file is part of `chem', 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/>.
+
+########################################################################
+
+R:	ring double 2,3
+	line from R.V6 to R.C
+	line from R.C to R.V4
+	X1: 1/2 <R.V5,R.C>
+	X2: 1/2 <R.C,R.V2>
+	bond from X1 to X2
+
+########################################################################
+### Emacs settings
+# Local Variables:
+# mode: Nroff
+# End:
+.cend

Index: ch6b_dna.chem
===================================================================
RCS file: ch6b_dna.chem
diff -N ch6b_dna.chem
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ ch6b_dna.chem	11 Aug 2013 08:29:36 -0000	1.7
@@ -0,0 +1,61 @@
+ch6b_dna.chem:
+.br
+.cstart
+
+# Example file for `chem':
+
+# This originates from Computing Science Technical Report No. 122
+#   CHEM - A Program for Typesetting Chemical Diagrams: User Manual
+#   by Jon L. Bentley, Lynn W. Jelinski, Brian W. Kernighan
+#   <http://cm.bell-labs.com/cm/cs/cstr/122.ps.gz>.
+
+# Copyright (C) 2006, 2009 Free Software Foundation, Inc.
+
+# Last update: 5 Jan 2009
+
+# This file is part of `chem', 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/>.
+
+########################################################################
+
+P: [
+R1:  flatring pointing up put N at 1 put N at 4 double 5,1
+     bond -135 from R1.V4 ; BP
+     "deoxyribose" rjust with .e at BP.w
+R2:  ring6 put N at 2 put N at 4 double 1,2 3,4 5,6 with .V6 at R1.V2
+     pic Conn: R2.V2.ne #because naming is too restricted in pic
+     bond up from R2.V1 ; N
+     bond -60 from N ; H
+     bond 60 from N ; H
+]
+     # thymine
+Q: [
+R3:  ring6 put N at 3 put N at 5 double 1,2
+     bond up from R3.V1 ; CH3
+     bond 120 from R3.V3 ; BP
+     "deoxyribose" ljust with .w at BP.e
+     double bond down from R3.V4 ; O
+     double bond -60 from R3.V6 ; O
+     bond -120 from R3.V5 ; H
+] with .O at P.H + (.3,.3)
+     bond from Q.O.sw to P.H.ne dotted
+     bond from Q.H.sw to P.Conn dotted
+
+########################################################################
+### Emacs settings
+# Local Variables:
+# mode: Nroff
+# End:
+.cend

Index: chAa_polymer.chem
===================================================================
RCS file: chAa_polymer.chem
diff -N chAa_polymer.chem
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ chAa_polymer.chem	11 Aug 2013 08:29:37 -0000	1.6
@@ -0,0 +1,74 @@
+chAa_polymer.chem:
+.br
+.cstart
+
+# Example file for `chem':
+
+# This originates from Computing Science Technical Report No. 122
+#   CHEM - A Program for Typesetting Chemical Diagrams: User Manual
+#   by Jon L. Bentley, Lynn W. Jelinski, Brian W. Kernighan
+#   <http://cm.bell-labs.com/cm/cs/cstr/122.ps.gz>.
+
+# Copyright (C) 2006, 2009 Free Software Foundation, Inc.
+
+# Last update: 5 Jan 2009
+
+# This file is part of `chem', 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/>.
+
+########################################################################
+
+# epoxy based on the m-phenyldiamine cured bisphenol-A
+     size 8
+     bond dotted
+     bond ; N
+     bond ; CH2
+     bond down from N
+R1:  benzene
+     bond 120 length .1 from R1.V3 ; N
+     bond right length .1 from N
+     bond down length .1 from N
+# back to the CH2
+     bond right from CH2 ; CH
+     bond down from CH ; OH
+     bond right from CH ; CH2
+     bond right ; O
+     bond right
+     benzene pointing right
+     bond right ; C
+     bond up from C ; CH3
+     bond down from C ; CH3
+     bond right from C
+     benzene pointing right
+     bond right ; O
+     bond right from O ; CH2
+     bond right ; CH
+     bond down from CH ; OH
+     bond right from CH ; CH2
+     bond right ; N
+     bond right from N
+     bond dotted
+     bond down from N
+R2:  benzene
+     bond 120 length .1 from R2.V3 ; N
+     bond right length .1 from N
+     bond down length .1 from N
+
+########################################################################
+### Emacs settings
+# Local Variables:
+# mode: Nroff
+# End:
+.cend

Index: chAb_vinyl_chloro.chem
===================================================================
RCS file: chAb_vinyl_chloro.chem
diff -N chAb_vinyl_chloro.chem
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ chAb_vinyl_chloro.chem	11 Aug 2013 08:29:37 -0000	1.6
@@ -0,0 +1,64 @@
+chAb_vinyl_chloro.chem:
+.br
+.cstart
+
+# Example file for `chem':
+
+# This originates from Computing Science Technical Report No. 122
+#   CHEM - A Program for Typesetting Chemical Diagrams: User Manual
+#   by Jon L. Bentley, Lynn W. Jelinski, Brian W. Kernighan
+#   <http://cm.bell-labs.com/cm/cs/cstr/122.ps.gz>.
+
+# Copyright (C) 2006, 2009 Free Software Foundation, Inc.
+
+# Last update: 5 Jan 2009
+
+# This file is part of `chem', 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/>.
+
+########################################################################
+
+    Cl
+    bond 120 length .25 ; BP
+    bond 60 length .25 from BP ; Cl
+B1: double bond down length .3 from BP
+    bond 120 length .35 ; BP
+# now comes the ring
+R1: ring6 double 1,2 3,4 5,6 with .V6 at BP
+    bond up length .1 from R1.V1 ; H
+    bond 60 length .1 from R1.V2 ; H
+    bond 120 from R1.V3 ; O
+    bond 60 from O ; C
+    double bond up from C ; O
+    bond 120 from C
+# continue decorating the ring
+    bond down length .1 from R1.V4 ; H
+    bond -120 length .1 from R1.V5 ; H
+# now go back and do the left hand ring
+    bond -120 length .35 from B1.end ; BP
+R2: ring6 double 1,2 3,4 5,6 with .V2 at BP
+    bond up length .1 from R2.V1 ; H
+    bond -60 length .1 from R2.V6 ; H
+    bond -120 from R2.V5 ; O
+    bond -60 from O
+    bond down length .1 from R2.V4 ; H
+    bond 120 length .1 from R2.V3 ; H
+
+########################################################################
+### Emacs settings
+# Local Variables:
+# mode: Nroff
+# End:
+.cend

Index: chAc_morphine.chem
===================================================================
RCS file: chAc_morphine.chem
diff -N chAc_morphine.chem
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ chAc_morphine.chem	11 Aug 2013 08:29:37 -0000	1.6
@@ -0,0 +1,54 @@
+chAc_morphine.chem:
+.br
+.cstart
+
+# Example file for `chem':
+
+# This originates from Computing Science Technical Report No. 122
+#   CHEM - A Program for Typesetting Chemical Diagrams: User Manual
+#   by Jon L. Bentley, Lynn W. Jelinski, Brian W. Kernighan
+#   <http://cm.bell-labs.com/cm/cs/cstr/122.ps.gz>.
+
+# Copyright (C) 2006, 2009 Free Software Foundation, Inc.
+
+# Last update: 5 Jan 2009
+
+# This file is part of `chem', 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/>.
+
+########################################################################
+
+R1:  ring6 double 1,2
+     bond -60 from R1.V6 ; HO
+R2:  ring6 with .V1 at R1.V3
+     bond 60 from R2.V2 ; N
+     bond right from N ; CH3
+R3:  benzene with .V1 at R2.V5
+     bond -120 from R3.V5 ; HO
+# this is the furan ring
+     bond -135 length .33 from R1.V5 ; O
+     bond -45 length .33 from R3.V6
+# this is the odd ring
+     bond up length .1 from N ; BP
+B1:  bond up length .33 from R1.V4
+     bond to BP
+
+
+########################################################################
+### Emacs settings
+# Local Variables:
+# mode: Nroff
+# End:
+.cend

Index: chAd_chlorophyll.chem
===================================================================
RCS file: chAd_chlorophyll.chem
diff -N chAd_chlorophyll.chem
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ chAd_chlorophyll.chem	11 Aug 2013 08:29:37 -0000	1.6
@@ -0,0 +1,71 @@
+chAd_chlorophyll.chem:
+.br
+.cstart
+
+# Example file for `chem':
+
+# This originates from Computing Science Technical Report No. 122
+#   CHEM - A Program for Typesetting Chemical Diagrams: User Manual
+#   by Jon L. Bentley, Lynn W. Jelinski, Brian W. Kernighan
+#   <http://cm.bell-labs.com/cm/cs/cstr/122.ps.gz>.
+
+# Copyright (C) 2006, 2009 Free Software Foundation, Inc.
+
+# Last update: 5 Jan 2009
+
+# This file is part of `chem', 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/>.
+
+########################################################################
+
+    Mg
+    bond 45 ; N
+R1: ring5 pointing up put N at 4 double 1,2 4,5 with .V4 at N
+         bond up from R1.V1 ; CH3
+         bond right from R1.V2 ; CH2CH3
+    bond 135 from Mg ; N
+R2: ring5 pointing down put N at 3 double 1,2 4,5 with .V3 at N
+         bond right from R2.V5 ; CH3
+    bond 225 from Mg ; N
+R3: ring5 pointing down put N at 4 double 3,4 with .V4 at N
+    bond -45 from Mg ; N
+R4: ring5 pointing up put N at 3 double 1,5 with .V3 at N
+         bond left from R4.V5 ; H3C
+         bond up from R4.V1 ; CH
+         double bond right length .1 from CH ; CH2
+    double bond 150 length .3 from R1.V3
+    bond to R2.V4
+R5: ring5 pointing 72 with .V5 at R2.V2
+         double bond 135 from R5.V2 ; O
+         bond down from R5.V3 ; C
+         double bond left length .1 from C ; O
+         bond down from C ; O
+         CH3 left of O
+    double bond -25 from R5.V4
+    bond down from R3.V1 ; CH2
+    CH2 left of CH2
+    bond left ; C
+    double bond -45 ; O
+    bond -135 from C ; C20H39O
+    bond left from R3.V2 ; H3C
+    double bond -150 length .3 from R4.V4
+    bond to R3.V3
+
+########################################################################
+### Emacs settings
+# Local Variables:
+# mode: Nroff
+# End:
+.cend

Index: chAe_chair.chem
===================================================================
RCS file: chAe_chair.chem
diff -N chAe_chair.chem
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ chAe_chair.chem	11 Aug 2013 08:29:37 -0000	1.6
@@ -0,0 +1,51 @@
+chAe_chair.chem:
+.br
+.cstart
+
+# Example file for `chem':
+
+# This originates from Computing Science Technical Report No. 122
+#   CHEM - A Program for Typesetting Chemical Diagrams: User Manual
+#   by Jon L. Bentley, Lynn W. Jelinski, Brian W. Kernighan
+#   <http://cm.bell-labs.com/cm/cs/cstr/122.ps.gz>.
+
+# Copyright (C) 2006, 2009 Free Software Foundation, Inc.
+
+# Last update: 5 Jan 2009
+
+# This file is part of `chem', 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/>.
+
+########################################################################
+
+pic define chair { [
+    V1: bond 120 length .25
+    V2: bond right length .35
+    V3: bond 150 length .35
+    V4: bond -60 length .25
+    V5: bond left length .35
+    V6: bond to V1.start
+pic ] }
+R1: chair
+R2: chair with .V1 at R1.V4.start
+bond 60 from R2.V4.start ; CH3
+bond down from R2.V4.start ; OH
+
+########################################################################
+### Emacs settings
+# Local Variables:
+# mode: Nroff
+# End:
+.cend

Index: chAf_arrow.chem
===================================================================
RCS file: chAf_arrow.chem
diff -N chAf_arrow.chem
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ chAf_arrow.chem	11 Aug 2013 08:29:37 -0000	1.6
@@ -0,0 +1,70 @@
+chAf_arrow.chem:
+.br
+.EQ
+delim $$
+.EN
+.cstart
+
+# Example file for `chem':
+
+# This originates from Computing Science Technical Report No. 122
+#   CHEM - A Program for Typesetting Chemical Diagrams: User Manual
+#   by Jon L. Bentley, Lynn W. Jelinski, Brian W. Kernighan
+#   <http://cm.bell-labs.com/cm/cs/cstr/122.ps.gz>.
+
+# Copyright (C) 2006, 2009 Free Software Foundation, Inc.
+
+# Last update: 5 Jan 2009
+
+# This file is part of `chem', 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/>.
+
+########################################################################
+
+    bond length .1 ; BP
+    bond up length .5
+    bond right
+    bond down length .5 from BP
+    bond right
+    bond right from BP ; C
+    double bond up ; O
+    bond right from C
+    benzene pointing right
+    bond right ; C
+    double bond up from C ; O
+    bond right from C ; O
+    bond right ; CH2
+# this is the statement to make the arrow
+    line <- from CH2.s down
+    move down .1 ; "0.085"
+    CH2CH2CH2 right of CH2
+    bond right ; O
+    bond right length .1 ; BP
+    bond up length .5 from BP
+    bond left
+    bond right length .1 from BP
+    bond down length .5 from BP ; BP
+    bond left
+    "$n$" with .w at BP.se
+
+########################################################################
+### Emacs settings
+# Local Variables:
+# mode: Nroff
+# End:
+.cend
+.EQ
+delim off
+.EN

Index: chAg_circle.chem
===================================================================
RCS file: chAg_circle.chem
diff -N chAg_circle.chem
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ chAg_circle.chem	11 Aug 2013 08:29:37 -0000	1.7
@@ -0,0 +1,56 @@
+chAg_circle.chem:
+.br
+.cstart
+
+# Example file for `chem':
+
+# This originates from Computing Science Technical Report No. 122
+#   CHEM - A Program for Typesetting Chemical Diagrams: User Manual
+#   by Jon L. Bentley, Lynn W. Jelinski, Brian W. Kernighan
+#   <http://cm.bell-labs.com/cm/cs/cstr/122.ps.gz>.
+
+# Copyright (C) 2006, 2009 Free Software Foundation, Inc.
+
+# Last update: 5 Jan 2009
+
+# This file is part of `chem', 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/>.
+
+########################################################################
+
+bond 120 ; C
+bond 60 ; C
+bond up ; Cl
+double bond 120 from C ; C
+bond 60 ; C
+bond 120 ; C
+bond 60 ; C
+bond up ; Cl
+double bond 120 from C ; C
+circle at C rad .08
+bond 60 from C ; C
+bond 120 ; C
+bond 60 ; C
+double bond 120 ; C
+bond down ; Cl
+bond 60 from C ; C
+bond 120
+
+########################################################################
+### Emacs settings
+# Local Variables:
+# mode: Nroff
+# End:
+.cend

Index: chAh_brackets.chem
===================================================================
RCS file: chAh_brackets.chem
diff -N chAh_brackets.chem
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ chAh_brackets.chem	11 Aug 2013 08:29:37 -0000	1.6
@@ -0,0 +1,62 @@
+chAh_brackets.chem:
+.br
+.EQ
+delim $$
+.EN
+.cstart
+
+# Example file for `chem':
+
+# This originates from Computing Science Technical Report No. 122
+#   CHEM - A Program for Typesetting Chemical Diagrams: User Manual
+#   by Jon L. Bentley, Lynn W. Jelinski, Brian W. Kernighan
+#   <http://cm.bell-labs.com/cm/cs/cstr/122.ps.gz>.
+
+# Copyright (C) 2006, 2009 Free Software Foundation, Inc.
+
+# Last update: 5 Jan 2009
+
+# This file is part of `chem', 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/>.
+
+########################################################################
+
+[
+    bond right ; CH2
+    bond 120 ; (CH2)
+    "$nothing sub n$"
+    bond 60 ; .CH2
+]
+# now put the arrow in
+    move right .3
+    arrow .5
+    move right .3
+# begin second structure
+[
+    bond right ; CH.
+    bond 120 ; (CH2)
+    "$nothing sub n$"
+    bond 60 ; CH3
+]
+
+########################################################################
+### Emacs settings
+# Local Variables:
+# mode: Nroff
+# End:
+.cend
+.EQ
+delim $$
+.EN

Index: chAi_poly_vinyl_chloride.chem
===================================================================
RCS file: chAi_poly_vinyl_chloride.chem
diff -N chAi_poly_vinyl_chloride.chem
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ chAi_poly_vinyl_chloride.chem	11 Aug 2013 08:29:38 -0000	1.7
@@ -0,0 +1,143 @@
+chAi_poly_vinyl_chloride.chem:
+.br
+.ps -2
+.cstart
+
+# Example file for `chem':
+
+# This originates from Computing Science Technical Report No. 122
+#   CHEM - A Program for Typesetting Chemical Diagrams: User Manual
+#   by Jon L. Bentley, Lynn W. Jelinski, Brian W. Kernighan
+#   <http://cm.bell-labs.com/cm/cs/cstr/122.ps.gz>.
+
+# Copyright (C) 2006, 2009 Free Software Foundation, Inc.
+
+# Last update: 5 Jan 2009
+
+# This file is part of `chem', 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/>.
+
+########################################################################
+
+db = .12
+cwid = .095
+A: [
+      bond dotted
+      bond right ; CH
+      bond down ; Cl
+      bond right from CH ; CH2
+      bond ; CH
+      bond down ; Cl
+      bond right from CH ; CH2
+      bond ; C.
+      bond down ; Cl
+      bond right from C ; CH2
+      bond ; CH2
+      bond down ; Cl
+]
+"     (6.13a)" ljust at A.e
+arrow down .5 from A.s
+[
+      CH2
+      double bond right ; CHCl
+] with .w at last arrow.c
+B: [
+      bond dotted
+      bond right ; CH
+      bond down ; Cl
+      bond right from CH ; CH2
+      bond ; CH
+      bond down ; Cl
+      bond right from CH ; CH2
+      bond ; C
+      bond up ; Cl
+      bond down from C ; CH2
+      bond ; CH2Cl
+      bond right from C ; CH2
+      bond ; CH
+      bond down ; Cl
+      bond right from CH
+      bond dotted
+] with .n at end of last arrow
+"     (6.13b)" ljust at B.e
+C: [
+      bond dotted
+      bond right ; CH
+      bond down ; Cl
+      bond right from CH ; CH2
+      bond ; C.
+      bond down ; Cl
+      bond right from C ; CH2
+      bond ; CH
+      bond down ; Cl
+      bond right from CH ; CH2
+      bond ; CH2
+      bond down ; Cl
+] with .n at B.s - (0,.5)
+"     (6.14a)" ljust at C.e
+arrow down .3 from C.s
+[
+      CH2
+      double bond right
+      CHCl
+] with .w at last arrow.s
+arrow down .3 from last arrow.s
+
+D: [
+      bond dotted
+      bond right ; CH
+      bond down ; Cl
+      bond right from CH ; CH2
+      bond ; C
+      bond up ; Cl
+      bond down from C ; CH2
+      bond ; CHCl
+      bond ; CH2
+      bond ; CH2Cl
+      bond right from C ; CH2
+      bond ; CH
+      bond down ; Cl
+      bond right from CH ; CH2
+      bond ; CH
+      bond down ; Cl
+      bond right from CH
+      bond dotted
+] with .n at last arrow.s
+"     (6.14b)" ljust at D.e
+E: [
+      bond dotted
+      bond ; CH
+      bond down ; Cl
+      bond right from CH ; CH2
+      bond ; CH
+      bond down ; Cl
+      bond right from CH ; CH2
+      bond ; CH
+      bond down ; Cl
+      bond right from CH ; CH2
+      bond ; CH
+      bond down ; Cl
+] with .e at B.w - (.5,0)
+
+arrow from E.ne to A.sw
+arrow from E.se to C.nw
+
+########################################################################
+### Emacs settings
+# Local Variables:
+# mode: Nroff
+# End:
+.cend
+.ps +2

Index: chBa_jump.chem
===================================================================
RCS file: chBa_jump.chem
diff -N chBa_jump.chem
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ chBa_jump.chem	11 Aug 2013 08:29:38 -0000	1.6
@@ -0,0 +1,43 @@
+chBa_jump.chem:
+.br
+.cstart
+
+# Example file for `chem':
+
+# This originates from Computing Science Technical Report No. 122
+#   CHEM - A Program for Typesetting Chemical Diagrams: User Manual
+#   by Jon L. Bentley, Lynn W. Jelinski, Brian W. Kernighan
+#   <http://cm.bell-labs.com/cm/cs/cstr/122.ps.gz>.
+
+# Copyright (C) 2006, 2009 Free Software Foundation, Inc.
+
+# Last update: 5 Jan 2009
+
+# This file is part of `chem', 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/>.
+
+########################################################################
+
+SiO2          # name = SiO2
+move right 1
+CH3CH2NH2.HCl # name = CH3CH2NH2HCl
+
+
+########################################################################
+### Emacs settings
+# Local Variables:
+# mode: Nroff
+# End:
+.cend

Index: chBb_bonds.chem
===================================================================
RCS file: chBb_bonds.chem
diff -N chBb_bonds.chem
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ chBb_bonds.chem	11 Aug 2013 08:29:38 -0000	1.6
@@ -0,0 +1,44 @@
+chBb_bonds.chem:
+.br
+.cstart
+
+# Example file for `chem':
+
+# This originates from Computing Science Technical Report No. 122
+#   CHEM - A Program for Typesetting Chemical Diagrams: User Manual
+#   by Jon L. Bentley, Lynn W. Jelinski, Brian W. Kernighan
+#   <http://cm.bell-labs.com/cm/cs/cstr/122.ps.gz>.
+
+# Copyright (C) 2006, 2009 Free Software Foundation, Inc.
+
+# Last update: 5 Jan 2009
+
+# This file is part of `chem', 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/>.
+
+########################################################################
+
+C
+frontbond -170 from C ; H
+backbond 10 from C ; CO2H
+bond left length .15 from C ; H2N
+bond right from C ; CH3
+
+########################################################################
+### Emacs settings
+# Local Variables:
+# mode: Nroff
+# End:
+.cend

Index: chBc_rings.chem
===================================================================
RCS file: chBc_rings.chem
diff -N chBc_rings.chem
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ chBc_rings.chem	11 Aug 2013 08:29:38 -0000	1.6
@@ -0,0 +1,45 @@
+chBc_rings.chem:
+.br
+.cstart
+
+# Example file for `chem':
+
+# This originates from Computing Science Technical Report No. 122
+#   CHEM - A Program for Typesetting Chemical Diagrams: User Manual
+#   by Jon L. Bentley, Lynn W. Jelinski, Brian W. Kernighan
+#   <http://cm.bell-labs.com/cm/cs/cstr/122.ps.gz>.
+
+# Copyright (C) 2006, 2009 Free Software Foundation, Inc.
+
+# Last update: 5 Jan 2009
+
+# This file is part of `chem', 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/>.
+
+########################################################################
+
+R1: benzene
+    bond -120 from R1.V5 ; CH3O
+R2: ring4 pointing 45 with .V4 at R1.V2
+R3: aromatic ring6 put N at 4 put S at 2 at R2 + (.75,0)
+R4: ring5 pointing left at R3 + (.75,0)
+    label R4
+
+########################################################################
+### Emacs settings
+# Local Variables:
+# mode: Nroff
+# End:
+.cend


From MAILER-DAEMON Sun Aug 11 04:30:31 2013
Received: from list by lists.gnu.org with archive (Exim 4.71)
	id 1V8R2l-0006R8-1h
	for mharc-groff-commit@gnu.org; Sun, 11 Aug 2013 04:30:31 -0400
Received: from eggs.gnu.org ([2001:4830:134:3::10]:52110)
	by lists.gnu.org with esmtp (Exim 4.71) (envelope-from <wl@gnu.org>)
	id 1V8R2b-0006BK-69
	for groff-commit@gnu.org; Sun, 11 Aug 2013 04:30:29 -0400
Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71)
	(envelope-from <wl@gnu.org>) id 1V8R2T-0003Jt-MM
	for groff-commit@gnu.org; Sun, 11 Aug 2013 04:30:21 -0400
Received: from vcs.savannah.gnu.org ([140.186.70.72]:59785)
	by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from <wl@gnu.org>)
	id 1V8R2T-0003Jo-I2
	for groff-commit@gnu.org; Sun, 11 Aug 2013 04:30:13 -0400
Received: from wl by vcs.savannah.gnu.org with local (Exim 4.72)
	(envelope-from <wl@gnu.org>) id 1V8R2S-0002lG-Ne
	for groff-commit@gnu.org; Sun, 11 Aug 2013 08:30:13 +0000
Date: Sun, 11 Aug 2013 08:30:12 +0000
Message-Id: <E1V8R2S-0002lG-Ne@vcs.savannah.gnu.org>
To: groff-commit@gnu.org
From: Werner LEMBERG <wl@gnu.org>
X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6.x
X-Received-From: 140.186.70.72
Subject: [Groff-commit] groff/contrib/glilypond ChangeLog ChangeLog.0x ...
X-BeenThere: groff-commit@gnu.org
X-Mailman-Version: 2.1.14
Precedence: list
List-Id: <groff-commit.gnu.org>
List-Unsubscribe: <https://lists.gnu.org/mailman/options/groff-commit>,
	<mailto:groff-commit-request@gnu.org?subject=unsubscribe>
List-Archive: <http://lists.gnu.org/archive/html/groff-commit>
List-Post: <mailto:groff-commit@gnu.org>
List-Help: <mailto:groff-commit-request@gnu.org?subject=help>
List-Subscribe: <https://lists.gnu.org/mailman/listinfo/groff-commit>,
	<mailto:groff-commit-request@gnu.org?subject=subscribe>
X-List-Received-Date: Sun, 11 Aug 2013 08:30:29 -0000

CVSROOT:	/sources/groff
Module name:	groff
Changes by:	Werner LEMBERG <wl>	13/08/11 08:30:12

Added files:
	contrib/glilypond: ChangeLog ChangeLog.0x Makefile.sub 
	                   README.txt args.pl glilypond.man glilypond.pl 
	                   oop_fh.pl subs.pl 

Log message:
	Revert accidental removal of previous files.

CVSWeb URLs:
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/glilypond/ChangeLog?cvsroot=groff&rev=1.14
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/glilypond/ChangeLog.0x?cvsroot=groff&rev=1.5
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/glilypond/Makefile.sub?cvsroot=groff&rev=1.8
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/glilypond/README.txt?cvsroot=groff&rev=1.4
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/glilypond/args.pl?cvsroot=groff&rev=1.6
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/glilypond/glilypond.man?cvsroot=groff&rev=1.4
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/glilypond/glilypond.pl?cvsroot=groff&rev=1.9
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/glilypond/oop_fh.pl?cvsroot=groff&rev=1.6
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/glilypond/subs.pl?cvsroot=groff&rev=1.8

Patches:
Index: ChangeLog
===================================================================
RCS file: ChangeLog
diff -N ChangeLog
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ ChangeLog	11 Aug 2013 08:30:04 -0000	1.14
@@ -0,0 +1,141 @@
+2013-05-10  Bernd Warken  <groff-bernd.warken-72@web.de>
+
+	* glilypond.pl: Correct position information.  Add debug code.
+
+	* args.pl, oop_fh.pl, subs.pl: Correct position information.
+
+2013-04-25  Bernd Warken  <groff-bernd.warken-72@web.de>
+
+	* Makefile.sub: minor corrections.
+
+2013-04-24  Bernd Warken  <groff-bernd.warken-72@web.de>
+
+	Public `glilypond' version `v1.1'.
+
+	* args.pl, sub.pl, glilypond.man: Change option `-v' to mean
+	`--verbose' instead of former `--version' such as many GNU
+	programs do.  Correct sub `&usage()' and man-page.
+
+	* args.pl, glilypond.pl, oop_fh.pl, subs.pl: Remove spaces in
+	` -> ', some `( ... )', and some `{ ... }' places for better
+	readability of the Perl source code.
+
+2013-04-24  Bernd Warken  <groff-bernd.warken-72@web.de>
+
+	* args.pl, oop_fh.pl: Remove 1st line calling `perl'.
+
+	* subs.pl: Remove 1st line calling `perl'.  Remove sub
+	`&perl_version()'.  Adjust sub `&usage()'.
+
+	* glilypond.pl: Keep 1st line, which will be reset by running
+	`make'.  Remove all parts of Perl testing.
+
+	* perl_test.pl: Remove this file.
+
+	* README.txt: Add information about needed Perl version.
+
+	* Makefile.sub: Corrections for removing Perl test.  Use `$<'.
+
+2013-04-24  Bernd Warken  <groff-bernd.warken-72@web.de>
+
+	* Makefile.sub: Remove Perl test.
+
+2013-04-12  Bernd Warken  <groff-bernd.warken-72@web.de>
+
+	* glilypond.pl: Fix END for early exit of `--version'.
+
+2013-04-12  Bernd Warken  <groff-bernd.warken-72@web.de>
+
+	* subs.pl: Replace `state' by global variable.  So the Perl
+	version can be older.
+
+	* perl_test.pl: Replace the Perl version by `v5.6', analogously to
+	`groffer'.
+
+2013-04-11  Bernd Warken  <groff-bernd.warken-72@web.de>
+
+	* Makefile.sub: Corrections for Emacs.
+
+2013-04-11  Bernd Warken  <groff-bernd.warken-72@web.de>
+
+	* old groff_lilypond: There is now a free `git' package containing
+	all old versions of the former name `groff_lilypond v0.*'.  They
+	work with `lilypond' parts in `roff' files, but were not
+	installed.  This package can be got at:
+
+	$ git clone git@github.com:RUNOFF/groff_lilypond.git
+
+	The new versions `glilypond 1.*' are not included there.
+
+2013-03-29  Bernd Warken  <groff-bernd.warken-72@web.de>
+
+	Published version is `v1.0'.
+
+	Run `autoconf' again.
+
+2013-03-29  Bernd Warken  <groff-bernd.warken-72@web.de>
+
+	* <groff_src_dir>/m4/groff.m4, <groff_src_dir>/configure.ac: Add
+	libdir information for `glilypond'.
+
+	* <groff_src_dir>/Makefile.in: Add
+	`<groff_src_dir>/contrib/glilypond'.
+
+	Run `autoconf'.
+
+	`glilypond' can now be installed to the system.
+
+2013-03-29  Bernd Warken  <groff-bernd.warken-72@web.de>
+
+	Rename `groff_lilypond' to `glilypond'.  So remove the former
+	source directory `<groff_src_dir>/contrib/lilypond' and newly
+	install `<groff_src_dir>/contrib/glilypond', which now has many
+	files.  The new version starts at `v1.0'.
+
+	Version will now be v1.*.  All former files of versions v0.*
+	vanished or were renamed.  This is not yet an information about
+	publishing.
+
+	* ChangeLog.0x: old `ChangeLog' file for the old `groff_lilypond'
+	versions v0.*.  In the future, this file won't be changed any
+	more.
+
+	* ChangeLog: New file.  It is this file.  It displays the history
+	of `glilypond' versions v1.* or later.
+
+	* glilypond.pl: New main Perl file written from
+	`groff_lilypond.pl' in a totally different way.  It is split now
+	into 4 Perl files.
+
+	* args.pl: New Perl file.  It handles the command line options for
+	a run of `glilypond.pl'.
+
+	* oop_fh.pl: New Perl file.  OOP handling of file handles.
+
+	* perl_test.pl: Test whether the actual Perl program has a
+	suitable versions.  For `Makefile.sub' and `glilypond.pl'.
+
+	* subs.pl: New Perl file.  Defines the global subs for
+	`glilypond.pl'.
+
+	* Makefile.sub: Newly written `Makefile' for this subdirectory of
+	`groff'.  `glilypond' should be able to be installed by `make'
+	with this file.
+
+	* glilypond.man: Newly written man-page for `glilypond'.
+
+	* README.txt: New file about the installation.
+
+########################################################################
+
+Copyright 2013
+  Free Software Foundation, Inc.
+
+Copying and distribution of this file, with or without modification,
+are permitted in any medium without royalty provided the copyright
+notice and this notice are preserved.
+
+Local Variables:
+version-control: never
+coding: utf-8
+End:

Index: ChangeLog.0x
===================================================================
RCS file: ChangeLog.0x
diff -N ChangeLog.0x
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ ChangeLog.0x	11 Aug 2013 08:30:05 -0000	1.5
@@ -0,0 +1,103 @@
+2013-04-11  Bernd Warken  <groff-bernd.warken-72@web.de>
+
+	* old groff_lilypond: There is now a free `git' package containing
+	all old versions of the former name `groff_lilypond v0.*'.  They
+	work with `lilypond' parts in `roff' files, but were not
+	installed.  This package can be got at:
+
+	$ git clone git@github.com:RUNOFF/groff_lilypond.git
+
+	The new versions `glilypond 1.*' are not included there.
+
+2013-03-28  Bernd Warken  <groff-bernd.warken-72@web.de>
+
+	Rename `groff_lilypond' to `glilypond' for *.pl and *.man files.
+	Split the single Perl script into several minor *.pl files.
+	Construct `Makefile.sub' in order to have installed `glilypond'.
+	Public versions will be v1.x.
+	Rename `ChangeLog' to `ChangeLog.0x' for the old versions of
+	`groff_lilypond' v0.*.  New `ChangeLog' for the new versions
+	`glilypond' 1.*.
+
+	* groff_lilypond.pl: Vanished.  Renamed to `glilypond.pl'.
+	* groff_lilypond.man: Vanished.  Renamed to `glilypond.man'.
+	* ChangeLog.0x: Moved from `ChangeLog'.  It is this file.  It
+	describes only the old `groff_lilypond' versions v0.*.  See file
+	`ChangeLog' for the files of the new `glilypond' v1.*.
+
+2013-03-11  Bernd Warken  <groff-bernd.warken-72@web.de>
+
+	* groff_lilypond.pl: Publishing groff_lilypond version v0.6.
+	New options: -e|--eps_dir, -l|--license, -k|--keep_files,
+	-p|--prefix=..., -t|--temp_dir=...
+	Install --eps_dir as directory for the useful EPS files.
+	* groff_lilypond.man: Include the new options.  Add section
+	SEE ALSO.
+
+2013-03-03  Bernd Warken  <groff-bernd.warken-72@web.de>
+
+	* groff_lilypond.pl: New code with Perl references.
+	Publishing groff_lilypond version v0.5.
+	New options: --usage, -V|--Verbose|--verbose, --file_prefix=...,
+	-o|--output=..., --temp_dir=...
+	Perl >=5.10.0 needed.
+	* groff_lilypond.man: Include the new options.
+
+2013-02-23  Bernd Warken  <groff-bernd.warken-72@web.de>
+
+	* groff_lilypond_pl: Remove `.lilypond include' for lilypond
+	regions.  Within `groff' mode. it is still allowed.
+	* groff_lilypond.man: Update `.lilypond include'.
+
+2013-02-23  Bernd Warken  <groff-bernd.warken-72@web.de>
+
+	New version v0.4 of groff_lilypond.
+	* groff_lilypond_pl: Major rewrite.
+	New options: --file_prefix, --temp_dir, and --license. 
+	* groff_lilypond.man: documents the new features.
+
+2013-02-16  Bernd Warken  <groff-bernd.warken-72@web.de>
+
+	* groff_lilypond.man: Minor corrections.
+
+2013-02-12  Bernd Warken  <groff-bernd.warken-72@web.de>
+
+	* groff_lilypond.pl: Add deletion of unused temporary files.
+
+2013-02-12  Bernd Warken  <groff-bernd.warken-72@web.de>
+
+	* contrib/lilypond: Version v0.3 for groff_lilypond
+	* groff_lilypond.pl: A new request was added for importing
+	lilypond files:
+	.lilypond include ...
+	The argument handling was improved.
+
+2013-02-11  Bernd Warken  <groff-bernd.warken-72@web.de>
+
+	* contrib/lilypond: Version v0.2 for groff_lilypond
+	* groff_lilypond.pl: Now there are 2 modes for generationg the EPS
+	files: --ly2eps (the default) and --pdf2eps (that's the old mode
+	from version v0.1 with pdf to ps to eps).  With ly2eps mode,
+	lilypond generates the EPS files itself, for each page one EPS
+	file.
+	* groff_lilypond.man: Corresponding updated man-page
+
+2013-02-10  Bernd Warken  <groff-bernd.warken-72@web.de>
+
+	* contrib/lilypond: New files for adding lilypond parts into groff
+	files.  These files will not yet be installed.
+	* groff_lilypond.pl: Program written in Perl, version v0.1
+	* groff_lilypond.man: Corresponding man-page
+
+Copyright 2013
+  Free Software Foundation, Inc.
+
+Copying and distribution of this file, with or without modification,
+are permitted in any medium without royalty provided the copyright
+notice and this notice are preserved.
+
+Local Variables:
+version-control: never
+mode: change-log-mode
+coding: utf-8
+End:

Index: Makefile.sub
===================================================================
RCS file: Makefile.sub
diff -N Makefile.sub
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ Makefile.sub	11 Aug 2013 08:30:06 -0000	1.8
@@ -0,0 +1,86 @@
+# Makefile.sub for `glilypond' (integration into the `groff' source tree)
+
+# File position: <groff-source>/contrib/lilypond/Makefile.sub
+
+# Copyright (C) 2013
+#   Free Software Foundation, Inc.
+# Written by Werner Lemberg <wl@gnu.org> and
+# Bernd Warken <groff-bernd.warken-72@web.de>.
+
+# Last update: 25 Apr 2013
+
+# This file is part of `glilypond' 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/>.
+
+########################################################################
+
+MAN1=glilypond.n
+
+MOSTLYCLEANADD=glilypond $(MAN1)
+
+# not all make programs have $(RM) predefined.
+RM=rm -f
+
+all: glilypond
+
+
+# files going to lib directory `$(glilypond_dir)'
+
+GLILYPOND_LIB=$(srcdir)/subs.pl \
+	$(srcdir)/oop_fh.pl \
+	$(srcdir)/args.pl
+
+GLILYPOND_LIB_=`echo $(GLILYPOND_LIB) | sed 's|$(srcdir)/||g'`
+
+
+# create perl executable `glilypond', being stored into `bindir'
+
+glilypond: $(srcdir)/glilypond.pl
+	sed -f "$(SH_DEPS_SED_SCRIPT)" \
+		-e "s|@g@|$(g)|g" \
+		-e "s|@BINDIR@|$(DESTDIR)$(bindir)|g" \
+		-e "s|@glilypond_dir@|$(DESTDIR)$(glilypond_dir)|g" \
+		-e "s|@VERSION@|$(version)$(revision)|g" \
+		$(srcdir)/glilypond.pl >$@
+	chmod +x $@
+
+
+install_data: glilypond $(GLILYPOND_LIB)
+	-test -d $(DESTDIR)$(bindir) \
+		|| $(mkinstalldirs) $(DESTDIR)$(bindir)
+	$(RM) $(DESTDIR)$(bindir)/$<
+	$(INSTALL_SCRIPT) glilypond $(DESTDIR)$(bindir)/$<
+	-test -d $(DESTDIR)$(glilypond_dir) \
+		|| $(mkinstalldirs) $(DESTDIR)$(glilypond_dir)
+	for f in $(GLILYPOND_); do \
+		$(RM) $(DESTDIR)$(glilypond_dir)/$$f; \
+		$(INSTALL_SCRIPT) $(srcdir)/$$f $(DESTDIR)$(glilypond_dir)/$$f; \
+	done
+
+
+uninstall_sub:
+	$(RM) $(DESTDIR)$(bindir)/glilypond;
+	for f in $(GLILYPOND_); do \
+		$(RM) $(DESTDIR)$(glilypond_dir)/$$f; \
+	done
+	-rmdir $(DESTDIR)$(glilypond_dir)
+
+########################################################################
+# Emacs settings
+########################################################################
+#
+# Local Variables:
+# mode: makefile
+# End:

Index: README.txt
===================================================================
RCS file: README.txt
diff -N README.txt
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ README.txt	11 Aug 2013 08:30:07 -0000	1.4
@@ -0,0 +1,39 @@
+    Copyright (C) 2013
+      Free Software Foundation, Inc.
+
+    Written by Bernd Warken <groff-bernd.warken-72@web.de>
+
+    Last update: 24 Apr 2013
+
+    Copying and distribution of this file, with or without modification,
+    are permitted in any medium without royalty provided the copyright
+    notice and this notice are preserved.
+
+    This file is part of `glilypond', which is part of `groff'.
+
+
+########################################################################
+
+In order to run `glilypond', your system must have installed Perl of at
+least version `v5.6'.
+
+
+########################################################################
+
+In order to have this program installed by `make', the creation of a
+libdir (library directory) must be programmed in some system files.
+The following actions must be taken:
+
+1) <groff_src_dir>/m4/groff.m4:
+Add `AC_DEFUN([GROFF_GROFFERDIR_DEFAULT])'.
+
+2) <groff_src_dir>/configure.ac:
+Add `GROFF_GROFFERDIR_DEFAULT'.
+
+3) <groff_src_dir>/Makefile.in:
+Add several informations of `glilypond_dir'
+
+With that, the program `autoconf' can be run in order to update the
+configure files and Makefile's.
+
+Now `$glilypond_dir' can be used as libdir.

Index: args.pl
===================================================================
RCS file: args.pl
diff -N args.pl
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ args.pl	11 Aug 2013 08:30:08 -0000	1.6
@@ -0,0 +1,504 @@
+########################################################################
+# Legalese
+########################################################################
+
+my $License = q*
+groff_lilypond - integrate `lilypond' into `groff' files
+
+Source file position: `<groff-source>/contrib/glilypond/args.pl'
+Installed position: `<prefix>/lib/groff/glilypond'
+
+Copyright (C) 2013 Free Software Foundation, Inc.
+  Written by Bernd Warken <groff-bernd.warken-72@web.de>
+
+Last update: 10 May 2013
+
+This file is part of `GNU groff'.
+
+  `GNU 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.
+
+  `GNU 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 package.  If not, see
+<http://www.gnu.org/licenses/>.
+*;
+
+##### end legalese
+
+
+# use strict;
+# use warnings;
+# use diagnostics;
+
+use integer;
+
+our ( $Globals, $Args, $stderr, $v, $out );
+
+# ----------
+# subs for second run, for remaining long options after splitting and
+# transfer
+# ----------
+
+my %opts_with_arg =
+  (
+
+   '--eps_dir' => sub {
+     $Args->{'eps_dir'} = shift;
+   },
+
+   '--output' => sub {
+     $Args->{'output'} = shift;
+   },
+
+   '--prefix' => sub {
+     $Args->{'prefix'} = shift;
+   },
+
+   '--temp_dir' => sub {
+     $Args->{'temp_dir'} = shift;
+   },
+
+  );				# end of %opts_with_arg
+
+
+my %opts_noarg =
+  (
+
+   '--help' => sub {
+     &usage;
+     exit;
+   },
+
+   '--keep_all' => sub {
+     $Args->{'keep_all'} = TRUE;
+   },
+
+   '--license' => sub {
+     &license;
+     exit;
+   },
+
+   '--ly2eps' => sub {
+     $Args->{'eps_func'} = 'ly';
+   },
+
+   '--pdf2eps' => sub {
+     $Args->{'eps_func'} = 'pdf';
+   },
+
+   '--verbose' => sub {
+     $Args->{'verbose'} = TRUE;
+   },
+
+   '--version' => sub {
+     &version;
+     exit;
+   },
+
+  );				# end of %opts_noarg
+
+
+# used variables in both runs
+
+my @files = EMPTYARRAY;
+
+
+#----------
+# first run for command line arguments
+#----------
+
+# global variables for first run
+
+my @splitted_args;
+my $double_minus = FALSE;
+my $arg = EMPTYSTRING;
+my $has_arg = FALSE;
+
+
+# Split short option collections and transfer these to suitable long
+# options from above.  Note that `-v' now means `--verbose' in version
+# `v1.1', earlier versions had `--version' for `-v'.
+
+my %short_opts =
+  (
+   '?' => '--help',
+   'e' => '--eps_dir',
+   'h' => '--help',
+   'l' => '--license',
+   'k' => '--keep_all',
+   'o' => '--output',
+   'p' => '--prefix',
+   't' => '--temp_dir',
+   'v' => '--verbose',
+   'V' => '--verbose',
+  );
+
+
+# transfer long option abbreviations to the long options from above
+
+my @long_opts;
+
+$long_opts[3] =
+  {				# option abbreviations of 3 characters
+   '--e' => '--eps_dir',
+   '--f' => '--prefix',		# --f for --file_prefix
+   '--h' => '--help',
+   '--k' => '--keep_all',	# and --keep_files
+   '--o' => '--output',
+   '--p' => '--prefix',		# and --file_prefix
+   '--t' => '--temp_dir',
+   '--u' => '--help',		# '--usage' is mapped to `--help'
+  };
+
+$long_opts[4] =
+  {				# option abbreviations of 4 characters
+   '--li' => '--license',
+   '--ly' => '--ly2eps',
+   '--pd' => '--pdf2eps',
+   '--pr' => '--prefix',
+  };
+
+$long_opts[6] =
+  {				# option abbreviations of 6 characters
+   '--verb' => '--verbose',
+   '--vers' => '--version',
+  };
+
+
+# subs for short splitting and replacing long abbreviations
+
+my $split_short = sub {
+
+  my @chars = split //, $1;	# omit leading dash
+
+     # if result is TRUE: run `next SPLIT' afterwards
+
+   CHARS: while ( @chars ) {
+       my $c = shift @chars;
+
+       unless ( exists $short_opts{$c} ) {
+	 $stderr->print( "Unknown short option `-$c'." );
+	 next CHARS;
+       }
+
+       # short option exists
+
+       # map or transfer to special long option from above
+       my $transopt = $short_opts{$c};
+
+       if ( exists $opts_noarg{$transopt} ) {
+	 push @splitted_args, $transopt;
+	 $Args->{'verbose'}  = TRUE if ( $transopt eq '--verbose' );
+	 next CHARS;
+       }
+
+       if ( exists $opts_with_arg{$transopt} ) {
+	 push @splitted_args, $transopt;
+
+	 if ( @chars ) {
+	   # if @chars is not empty, option $transopt has argument
+	   # in this arg, the rest of characters in @chars
+	   push @splitted_args, join "", @chars;
+	   @chars = EMPTYARRAY;
+	   return TRUE;		# use `next SPLIT' afterwards
+	 }
+
+	 # optarg is the next argument
+	 $has_arg = $transopt;
+	 return TRUE;		# use `next SPLIT' afterwards
+       }			# end of if %opts_with_arg
+     }				# end of while CHARS
+     return FALSE;		# do not do anything
+};				# end of sub for short_opt_collection
+
+
+my $split_long = sub {
+  my $from_arg = shift;
+  $from_arg =~ /^([^=]+)/;
+  my $opt_part = lc($1);
+  my $optarg = undef;
+  if ( $from_arg =~ /=(.*)$/ ) {
+    $optarg = $1;
+  }
+
+ N: for my $n ( qw/6 4 3/ ) {
+    $opt_part =~ / # match $n characters
+		   ^
+		   (
+		     .{$n}
+		   )
+		 /x;
+    my $argn = $1;		# get the first $n characters
+
+    # no match, so luck for fewer number of chars
+    next N unless ( $argn );
+
+    next N unless ( exists $long_opts[$n]->{$argn} );
+    # not in $n hash, so go on to next loop for $n
+
+    # now $n-hash has arg
+
+    # map or transfer to special long opt from above
+    my $transopt = $long_opts[$n]->{$argn};
+
+    # test on option without arg
+    if ( exists $opts_noarg{$transopt} ) { # opt has no arg
+      $stderr->print( 'Option ' . $transopt . 'has no argument: ' .
+		      $from_arg . '.' ) if ( defined($optarg) );
+      push @splitted_args, $transopt;
+      $Args->{'verbose'} = TRUE if ( $transopt eq '--verbose' );
+      return TRUE;		# use `next SPLIT' afterwards
+    }				# end of if %opts_noarg
+
+    # test on option with arg
+    if ( exists $opts_with_arg{$transopt} ) { # opt has arg
+      push @splitted_args, $transopt;
+
+      # test on optarg in arg
+      if ( defined($optarg) ) {
+	push @splitted_args, $1;
+	return TRUE; # use `next SPLIT' afterwards
+      } # end of if optarg in arg
+
+      # has optarg in next arg
+      $has_arg = $transopt;
+      return TRUE; # use `next SPLIT' afterwards
+    } # end of if %opts_with_arg
+
+    # not with and without option, so is not permitted
+    $stderr->print( "`" . $transopt .
+		    "' is unknown long option from `" . $from_arg . "'" );
+    return TRUE; # use `next SPLIT' afterwards
+  } # end of for N
+  return FALSE; # do nothing
+}; # end of split_long()
+
+
+#----------
+# do split and transfer arguments
+#----------
+sub run_first {
+
+ SPLIT: foreach (@ARGV) {
+    # Transform long and short options into some given long options.
+    # Split long opts with arg into 2 args (no `=').
+    # Transform short option collections into given long options.
+    chomp;
+
+    if ( $has_arg ) {
+      push @splitted_args, $_;
+      $has_arg = EMPTYSTRING;
+      next SPLIT;
+    }
+
+    if ( $double_minus ) {
+      push @files, $_;
+      next SPLIT;
+    }
+
+    if ( $_ eq '-' ) {		# file arg `-'
+      push @files, $_;
+      next SPLIT;
+    }
+
+    if ( $_ eq '--' ) {		# POSIX arg `--'
+      push @splitted_args, $_;
+      $double_minus = TRUE;
+      next SPLIT;
+    }
+
+    if ( / # short option or collection of short options
+	   ^
+	   -
+	   (
+	     [^-]
+	     .*
+	   )
+	   $
+	 /x ) {
+      $split_short->($1);
+      next SPLIT;
+    }				# end of short option
+
+    if ( /^--/ ) {		# starts with 2 dashes, a long option
+      $split_long->($_);
+      next SPLIT;
+    }				# end of long option
+
+    # unknown option without leading dash is a file name
+    push @files, $_;
+    next SPLIT;
+  }				# end of foreach SPLIT
+
+				# all args are considered
+  $stderr->print( "Option `$has_arg' needs an argument." )
+    if ( $has_arg );
+
+
+  push @files, '-' unless ( @files );
+  @ARGV = @splitted_args;
+
+};		    # end of first run, splitting with map or transfer
+
+
+#----------
+# open or ignore verbose output
+#----------
+sub install_verbose {
+  if ( $Args->{'verbose'} ) { # `--verbose' was used
+    # make verbose output into $v
+    my $s = $v->get(); # get content of string so far as array ref, close
+
+    $v = new FH_STDERR(); # make verbose output into STDERR
+    if ( $s ) {
+      for ( @$s ) {
+	# print the file content into new verbose output
+	$v->print($_);
+      }
+    }
+    # verbose output is now active (into STDERR)
+    $v->print( "Option `-v' means `--verbose'." );
+    $v->print( "Version information is printed by option `--version'." );
+    $v->print( "#" x 72 );
+
+  } else { # `--verbose' was not used
+    # do not be verbose, make verbose invisible
+
+    $v->close(); # close and ignore the string content
+
+    $v = new FH_NULL();
+    # this is either into /dev/null or in an ignored string
+
+  } # end if-else about verbose
+  # `$v->print' works now in any case
+
+  $v->print( "Verbose output was chosen." );
+
+  my $s = $Globals->{'prog_is_installed'} ? '' : ' not';
+  $v->print( $Globals->{'prog'} . " is" . $s .
+	     " installed." );
+
+  $v->print( 'The command line options are:' );
+
+  $s = "  options:";
+  $s .= " `" . $_ . "'" for ( @ARGV );
+  $v->print( $s );
+
+  $s = "  file names:";
+  $s .= " `" . $_ . "'\n" for ( @files );
+  $v->print( $s );
+} # end install_verbose()
+
+
+#----------
+# second run of command line arguments
+#----------
+sub run_second {
+    # Second run of args with new @ARGV from the former splitting.
+    # Arguments are now splitted and transformed into special long options.
+
+    my $double_minus = FALSE;
+    my $has_arg = FALSE;
+
+  ARGS: for my $arg ( @ARGV ) {
+
+      # ignore `--', file names are handled later on
+      last ARGS if ( $arg eq '--' );
+
+      if ( $has_arg ) {
+	unless ( exists $opts_with_arg{$has_arg} ) {
+	  $stderr->print( "`\%opts_with_args' does not have key `" .
+			    $has_arg . "'." );
+	  next ARGS;
+	}
+
+	$opts_with_arg{$has_arg}->($arg);
+	$has_arg = FALSE;
+	next ARGS;
+      } # end of $has_arg
+
+      if ( exists $opts_with_arg{$arg} ) {
+	$has_arg = $arg;
+	next ARGS;
+      }
+
+      if ( exists $opts_noarg{$arg} ) {
+	$opts_noarg{$arg}->();
+	next ARGS;
+      }
+
+      # not a suitable option
+      $stderr->print( "Wrong option `" . $arg . "'." );
+      next ARGS;
+
+    } # end of for ARGS:
+
+
+    if ( $has_arg ) { # after last argument
+      die "Option `$has_arg' needs an argument.";
+    }
+
+  }; # end of second run
+
+
+sub handle_args {
+  # handling the output of args
+
+  if ( $Args->{'output'} ) { # `--output' was set in the arguments
+    my $out_path = &path2abs($Args->{'output'});
+    die "Output file name $Args->{'output'} cannot be used."
+      unless ( $out_path );
+
+    my ( $file, $dir );
+    ( $file, $dir ) = File::Basename::fileparse($out_path)
+      or die "Could not handle output file path `" . $out_path . "': " .
+	"directory name `" . $dir . "' and file name `" . $file . "'.";
+
+    die "Could not find output directory for `" . $Args->{'output'} . "'"
+      unless ( $dir );
+    die "Could not find output file: `" . $Args->{'output'} .
+      "'" unless ( $file );
+
+    if ( -d $dir ) {
+      die "Could not write to output directory `" . $dir . "'."
+	unless ( -w $dir );
+    } else {
+      $dir = &make_dir($dir);
+      die "Could not create output directory in: `" . $out_path . "'."
+	unless ( $dir );
+    }
+
+    # now $dir is a writable directory
+
+    if ( -e $out_path ) {
+      die "Could not write to output file `" . $out_path . "'."
+	unless ( -w $out_path );
+    }
+
+    $out = new FH_FILE( $out_path );
+    $v->print( "Output goes to file `" . $out_path . "'." );
+  } else { # `--output' was not set
+    $out = new FH_STDOUT();
+  }
+  # no $out is the right behavior for standard output
+
+#  $Args->{'prefix'} .= '_' . $Args->{'eps_func'} . '2eps';
+
+  @ARGV = @files;
+}
+
+
+1;
+########################################################################
+### Emacs settings
+# Local Variables:
+# mode: CPerl
+# End:

Index: glilypond.man
===================================================================
RCS file: glilypond.man
diff -N glilypond.man
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ glilypond.man	11 Aug 2013 08:30:09 -0000	1.4
@@ -0,0 +1,916 @@
+.TH glilypond @MAN1EXT@ "@MDATE@" "Groff Version @VERSION@"
+.SH NAME
+glilypond \[em] integrate \f[CI]lilypond\f[P] parts into \f[CI]groff\f[]
+.
+.\" This .SH was moved to this place in order to appease `apropos'.
+.
+.\" --------------------------------------------------------------------
+.\" Legalese
+.\" --------------------------------------------------------------------
+.
+.de authors
+This file was written by Bernd Warken
+.MT groff\-bernd.warken\-72@web.de
+.ME .
+.
+Last update: 25 Apr 2013
+..
+.
+.
+.\" The following macro .copying contains the license information for this file.
+.de copying
+.nh
+.nf
+glilypond - integrate lilypond into groff files
+
+Source file position: <groff-source>/contrib/lilypond/glilypond.man
+Installed position: <prefix>/share/man/man1/glilypond.1
+
+Copyright \(co 2013
+          Free Software Foundation, Inc.
+
+This file is part of GNU groff.
+
+GNU 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.
+
+GNU 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 package.
+
+.hy
+.fi
+If not, see the GNU licenses at
+.UR http://www.gnu.org/licenses/
+.UE .
+..
+.
+.
+.\" --------------------------------------------------------------------
+.\" Setup
+.\" --------------------------------------------------------------------
+.
+.ds Ellipsis "\&.\|.\|.\&\"
+.
+.
+.\" --------------------------------------------------------------------
+.\" Macro definitions
+.\" --------------------------------------------------------------------
+.
+.\" --------------------------------------------------------------------
+.\" .FONT (<font name> <text> [<font name> <text> ...])
+.\"
+.\" Print in different fonts: R, I, B, CR, CI, CB
+.\"
+.de1 FONT
+.  if (\\n[.$] = 0) \{\
+.	nop \&\f[P]\&
+.	return
+.  \}
+.  ds result \&
+.  while (\\n[.$] >= 2) \{\
+.	as result \,\f[\\$1]\\$2
+.	if !"\\$1"P" .as result \f[P]
+.	shift 2
+.  \}
+.  if (\\n[.$] = 1) .as result \,\f[\\$1]
+.  nh
+.  nop \\*[result]\&
+.  hy
+..
+.
+.
+.\" --------------------------------------------------------------------
+.\" .OP+ (<option> [ [ | option] ...] [<optarg> [<end>] ])
+.\"
+.\" like .OP, but with 1st arg split and and optional final character
+.\" Example: `.OP+ -p | --prefix ly .' gets `[-t|--prefix ly].'
+.\" Example: `.OP+ -h | --help | --usage' gets `[-h|--help|--usage]'
+.\" Example: `.OP+ -v | --verbose "" ,' gets `[-v|--verbose],'
+.\"
+.de1 OP+
+.  if ( \\n[.$] == 0 ) \{\
+.	nop \&\f[CR][]\fR\&
+.	return
+.  \}
+.  nh
+.  ds result \&\f[CR][\f[CB]\\$1
+.  shift
+.  while (\\n[.$] >= 2) \{\
+.	ie '\\$1'|' .as result \f[CR]|\f[CB]\\$2
+.	el \{\
+.		ie '\\$1'' .as result \f[CR]]\fR\\$2
+.		el .as result \fI\ \\$1\f[CR]]\fR\\$2
+.		nop \\*[result]\&
+.		hy
+.		return
+.	\}
+.	shift 2
+.  \}
+.  as result \fI\ \\$1\f[CR]]\fR
+.  nop \\*[result]\&
+.  hy
+..
+.
+.\" --------------------------------------------------------------------
+.SH "SYNOPSIS"
+.\" --------------------------------------------------------------------
+.
+.SY glilypond
+.OP+ options
+.OP+ -
+.OP+ --
+.OP+ \%filespec \*[Ellipsis]
+.YS
+.
+.
+.\" --------------------------------------------------------------------
+.SH DESCRIPTION
+.\" --------------------------------------------------------------------
+.
+.FONT CB glilypond
+transforms sheet music written in the
+.FONT CI lilypond
+language into the
+.BR groff (@MAN7EXT@)
+language using the
+.FONT CB .PSPIC
+request, such that
+.BR groff (@MAN1EXT@)
+can transform it into a format that can be displayed directly.
+.
+.
+.P
+Files in
+.FONT CI groff
+language and
+.FONT CI "standard input"
+can be provided as arguments.
+.
+.
+.\" --------------------------------------------------------------------
+.SH "OPTION OVERVIEW"
+.\" --------------------------------------------------------------------
+.
+.\" --------------------------------------------------------------------
+.SS "Breaking Options"
+.\" --------------------------------------------------------------------
+.
+.SY
+.OP+ -? | -h | --help | --usage
+.YS
+.SY
+.OP+ --version
+.YS
+.SY
+.OP+ -l | --license
+.YS
+.
+.
+.\" --------------------------------------------------------------------
+.SS "Options for building EPS Files"
+.\" --------------------------------------------------------------------
+.
+.TP
+.OP+ --ly2eps
+Here the
+.FONT CB lilypond
+program creates
+.FONT CI eps
+files directly.
+.
+This is the default.
+.
+.
+.TP
+.OP+ --pdf2eps
+The program
+.FONT CB glilypond
+generates a
+.FONT CI pdf
+file using
+.FONT CB lilypond R .
+.
+Then the
+.FONT CI eps
+file is generated by
+.FONT CB pdf2ps
+and
+.FONT CB ps2eps R .
+.
+.
+.\" --------------------------------------------------------------------
+.SS "Directories and Files"
+.\" --------------------------------------------------------------------
+.
+.TP
+.OP+ -e | --eps_dir directory_name
+Normally all
+.FONT CI EPS
+files are sent to the temporary directory.
+.
+With this option, you can generate your own directory, in which all useful
+.FONT CI EPS
+files are send.
+.
+So at last, the temporary directory can be removed.
+.
+.
+.TP
+.OP+ -p | --prefix begin_of_name
+Normally all temporary files get names that start with the
+.FONT CB ly CI \*[Ellipsis]
+prefix.
+.
+With this option, you can freely change this prefix.
+.
+.
+.TP
+.OP+ -k | --keep_all
+Normally all temporary files without the
+.FONT CI eps
+files are deleted.
+.
+With this opton, all generated files either by the
+.FONT CB lilypond
+program or other format transposers are kept.
+.
+.
+.TP
+.OP+ -t | --temp_dir dir
+With this option, you call a directory that is the base for the
+temporary directory.
+.
+This directory name is used as is without any extensions.
+.
+If this directory does not exist it is be created.
+.
+The temporary directory is created by Perl's security operations
+directly under this directory.
+.
+In this temporary directory, the temporary files are stored.
+.
+.
+.\" --------------------------------------------------------------------
+.SS "Output"
+.\" --------------------------------------------------------------------
+.
+.TP
+.OP+ -o | --output file_name
+Normally all
+.FONT CI groff
+output of this program is sent to
+.FONT CB STDOUT R .
+.
+With this option, that can be changed, such that the output is stored
+into a file named in the option argument
+.IR file_name .
+.
+.
+.TP
+.OP+ -v | -V | --verbose
+A lot more of information is sent to STDERR.
+.
+.
+.\" --------------------------------------------------------------------
+.SS "Short Option Collections"
+.\" --------------------------------------------------------------------
+.
+The argument handling of options 
+.
+.
+.P
+.FONT CI "Short options"
+are arguments that start with a single dash
+.FONT CB \- R .
+.
+Such an argument can consist of arbitrary many options without option
+argument, composed as a collection of option characters following the
+single dash.
+.
+.
+.P
+Such a collection can be terminated by an option character that
+expects an option argument.
+.
+If this option character is not the last character of the argument,
+the follwing final part of the argument is the option argument.
+.
+If it is the last character of the argument, the next argument is
+taken as the option argument. 
+.
+.
+.P
+This is the standard for
+.FONT CI POSIX
+and
+.FONT CI GNU
+option management.
+.
+.
+.P
+For example,
+.
+.TP
+.FONT CB \-kVesome_dir
+is a collection of the short options
+.FONT CB \-k
+and
+.FONT CB \-V
+without option argument, followed by the short option
+.FONT CB \-e
+with option argument that is the following part of the argument
+.FONT CB some_dir R .
+.
+So this argument could also be written as several arguments
+.FONT CB "\-k \-V \-e some_dir" R .
+.
+.
+.\" --------------------------------------------------------------------
+.SS "Handling of Long Options"
+.\" --------------------------------------------------------------------
+.
+Arguments that start with a double dash
+.FONT CB \-\-
+are so-called
+.FONT CI "long options" R .
+.
+Each double dash argument can only have a single long option.
+.
+.
+.P
+.FONT CI "Long options"
+have or have not an option argument.
+.
+An option argument can be the next argument or can be appended with an
+equal sign
+.FONT CB =
+to the same argument as the long option.
+.
+.
+.TP
+.FONT CB \-\-help
+is a long option without an option argument.
+.
+.TP
+.FONT CB "\-\-eps_dir some_dir"
+.TQ
+.FONT CB "\-\-eps_dir=some_dir"
+is the long option
+.FONT CB "\-\-eps_dir
+with the option argument
+.FONT CB some_dir R .
+.
+.
+.P
+Moreover the program allows abbreviations of long options, as much as
+possible.
+.
+.
+.P
+The
+.FONT CI "long option"
+.FONT CB \-\-keep_all
+can be abbreviated from
+.FONT CB \-\-keep_al
+up to
+.FONT CB \-\-k
+because the program does not have another
+.FONT CI "long option"
+whose name starts with the character
+.FONT CB k R .
+.
+.
+.P
+On the other hand, the option
+.FONT CB \-\-version
+cannot be abbreviated further than
+.FONT CB \-\-vers
+because there is also the
+.FONT CI "long option " CB \-\-verbose
+that can be abbreviated up to
+.FONT CB \-\-verb R .
+.
+.
+.P
+An option argument can also be appended to an abbreviation.
+.
+So is
+.FONT CB \-\-e=some_dir
+the same as
+.FONT CB "\-\-eps_dir some_dir" R .
+.
+.
+.P
+Moreover the program allows an arbitrary usage of upper and lower case
+in the option name.
+.
+This is
+.FONT CI Perl
+style.
+.
+.
+.P
+For example, the
+.FONT CI "long option"
+.FONT CB \-\-keep_all
+can as well be written as
+.FONT CB \-\-Keep_All
+or even as an abbreviation like
+.FONT CB \-\-KeE R .
+.
+.
+.\" --------------------------------------------------------------------
+.SH FILESPEC ARGUMENTS
+.\" --------------------------------------------------------------------
+.
+An argument that is not an option or an option argument is called a
+.FONT CI filespec
+argument. 
+.
+.
+.P
+Without any
+.I filespec
+argument,
+.FONT CI "standard input"
+is read.
+.
+.
+.P
+Each
+.I filespec
+argument must either be the name of a readable file or a dash
+.FONT CB -
+for
+.FONT CI "standard input" R .
+.
+Each input must be written in the
+.FONT CI roff
+or
+.FONT CI groff
+language and can include
+.FONT CI lilypond
+parts.
+.
+.
+.P
+Normally arguments starting with a dash
+.FONT CB \-
+are interpreted as an option.
+.
+But if you use an argument that consists only of a doubled dash
+.FONT CB \-\- R ,
+all following arguments are taken as
+.FONT CI filespec
+argument, even if such an argument starts with a dash.
+.
+This is handled according to the
+.FONT CI GNU
+standard.
+.
+.
+.\" --------------------------------------------------------------------
+.SH "THE LILYPOND PARTS IN ROFF INPUT"
+.\" --------------------------------------------------------------------
+.
+.\" --------------------------------------------------------------------
+.SS "Integrated Lilypond Codes"
+.\" --------------------------------------------------------------------
+.
+A
+.FONT CI lilypond
+part within a structure written in the
+.FONT CI groff
+language is the whole part between the marks
+.EX
+.FONT CB ".lilypond start"
+.EE
+and
+.EX
+.FONT CB ".lilypond end"
+.EE
+.
+.
+.P
+A
+.FONT CI groff
+input can have several of these
+.FONT CI lilypond
+parts.
+.
+.
+.P
+When processing such a
+.FONT CI lilypond
+part between
+.FONT CB ".lilypond start"
+and
+.FONT CB ".lilypond end"
+we say that the
+.FONT CB glilypond
+program is in
+.FONT CI "lilypond mode" R .
+.
+.
+.P
+These
+.FONT CI lilypond
+parts are sent into temporary
+.FONT CI lilypond
+files with the file name extension
+.FONT CB .ly R .
+.
+These files are transformed later on into
+.FONT CI EPS
+files.
+.
+.
+.\" --------------------------------------------------------------------
+.SS "Inclusion of ly-Files"
+.\" --------------------------------------------------------------------
+.
+An additional command line for file inclusion of
+.FONT CI lilypond
+files is given by
+.EX
+.FONT CB ".lilypond include" I " file_name"
+.EE
+in
+.FONT CI groff
+input.
+.
+For each such
+.FONT CI include
+command, one file of
+.FONT CI lilypond
+code can be included into the
+.FONT CI groff
+code.
+.
+Arbitrarily many of these commands can be included in the
+.FONT CI groff
+input.
+.
+.
+.P
+These include commands can only be used outside the
+.FONT CI lilypond
+parts.
+.
+Within the
+.FONT CI "lilypond mode" R ,
+this inclusion is not possible.
+.
+So
+.FONT CB ".lilypond include"
+may not be used in
+.FONT CI "lilypond mode" R ,
+i.e. between
+.FONT CB ".lilypond start"
+and
+.FONT CB ".lilypond end" R .
+.
+.
+These included
+.FONT CI ly R -files
+are also transformed into
+.FONT CI EPS
+files.
+.
+.
+.\" --------------------------------------------------------------------
+.SH "GENERATED FILES"
+.\" --------------------------------------------------------------------
+.
+By the transformation process of
+.FONT CI lilypond
+parts into
+.FONT CI EPS
+files, there are many files generated.
+.
+By default, these files are regarded as temporary files and as such
+stored in a temporary directory.
+.
+.
+.P
+This process can be changed by command line options.
+.
+.
+.\" --------------------------------------------------------------------
+.SS "Command Line Options for Directories"
+.\" --------------------------------------------------------------------
+.
+The temporary directory for this program is either created
+automatically or can be named by the option
+.OP+ -t | --temp_dir dir .
+.
+.
+.P
+Moreover, the
+.FONT CI EPS
+files that are later on referred by
+.FONT CB .PSPIC
+command in the final
+.FONT CI groff
+output can be stored in a different directory that can be set by the
+command line option
+.OP+ -e | --eps_dir directory_name .
+.
+With this option, the temporary directory can be removed completely at
+the end of the program.
+.
+.
+.P
+The beginning of the names of the temporary files can be set by the
+command line option
+.OP+ -p | --prefix begin_of_name .
+.
+.
+.P
+All of the temporary files except the
+.FONT CI EPS
+files are deleted finally.
+.
+This can be changed by setting the command line option
+.OP+ -k | --keep_files
+.
+With this, all temporary files and directories are kept, not deleted.
+.
+.
+.P
+These
+.FONT CI EPS
+files are stored in a temporary or
+.FONT CI EPS
+directory.
+.
+But they cannot be deleted by the transformation process because they
+are needed for the display which can take a long time.
+.
+.
+.\" --------------------------------------------------------------------
+.SH "TRANSFORMATION PROCESSES FOR GENERATING EPS FILES"
+.\" --------------------------------------------------------------------
+.
+.\" --------------------------------------------------------------------
+.SS "Mode ly2eps"
+.\" --------------------------------------------------------------------
+.
+This mode is the default.
+.
+It can also be chosen by the option
+.FONT CB --ly2eps R .
+.
+.
+.P
+In this mode, the
+.FONT CB .ly
+files are transformed by the
+.FONT CB lilypond
+program into many files of different formats, including
+.FONT CI eps
+files, using
+.EX
+.FONT CB "$ lilypond \-\-ps \-dbackend=eps \-dgs\-load\-fonts \-\-output=" I file\-name
+.EE
+for each
+.FONT CB .ly
+file.
+.
+The output
+.I file\-name
+must be provided without an extension, its directory is temporary..
+.
+.
+.P
+There are many
+.FONT CI EPS
+files created.
+.
+One having the complete transformed
+.FONT CB ly
+file, named
+.FONT I file\-name CB .eps R .
+.
+.
+.P
+Moreover there are
+.FONT CI EPS
+files for each page, named
+.FONT I file\-name CB \- I digit CB .eps R .
+.
+.
+.P
+The last step to be done is replacing all
+.FONT CI lilypond
+parts by the collection of the corresponding
+.FONT CI EPS
+page files.
+.
+This is done by
+.FONT CI groff
+commands
+.EX
+.FONT CB ".PSPIC " CI file-name CB \- I digit CB .eps 
+.EE
+.
+.
+.\" --------------------------------------------------------------------
+.SS "Mode pdf2eps"
+.\" --------------------------------------------------------------------
+.
+This mode can be chosen by the option
+.FONT CB --pdf2eps R .
+.
+.
+.P
+In this mode, the
+.FONT CB .ly
+files are transformed by the
+.BR lilypond (1)
+program into
+.FONT CI pdf
+files, using
+.EX
+.FONT CB "lilypond \-\-pdf \-\-output=" I file-name
+.EE
+for each
+.FONT CB .ly
+file.
+.
+The
+.I file-name
+must be provided without the extension
+.FONT CB .pdf R .
+.
+By this process, a file
+.FONT CI file-name CB .pdf
+is generated.
+.
+.
+.P
+The next step is to transform these
+.FONT CI PDF
+files into a
+.FONT CI PS
+file.
+.
+This is done by the
+.BR pdf2ps (1)
+program using
+.EX
+.FONT R "$ " CB "pdf2ps " CI file-name CB ".pdf " CI file-name CB ".ps"
+.EE
+.
+.
+The next step creates an
+.FONT CI EPS
+file from the
+.FONT CI PS
+file.
+.
+This is done by the
+.BR ps2eps (1)
+program using
+.EX
+.FONT R "$ " CB "ps2eps " CI file-name CB ".ps"
+.EE
+.
+.
+.P
+By that, a file
+.FONT CI file-name CB .eps
+is created for each
+.FONT CI lilypond
+part in the
+.FONT CI groff
+file or standard input.
+.
+.
+.P
+The last step to be done is replacing all
+.FONT CI lilypond
+parts by the
+.FONT CI groff
+command
+.EX
+.FONT CB ".PSPIC " CI file-name CB .eps 
+.EE
+.
+.
+.\" --------------------------------------------------------------------
+.SH "THE GENERATED NEW ROFF STRUCTURE"
+.\" --------------------------------------------------------------------
+.
+The new
+.BR groff (@MAN7EXT@)
+structure generated by
+.FONT CB glilypond
+is either
+.
+.TP
+1)
+sent to standard output and can there be saved into a file or piped into
+.BR groff (@MAN1EXT@)
+or
+.BR groffer (@MAN1EXT@)
+or
+.
+.TP
+2)
+stored into a file by given the option
+.OP -o\fR|\fB\~--output file_name
+.
+.
+.\" --------------------------------------------------------------------
+.SH "SEE ALSO"
+.\" --------------------------------------------------------------------
+.
+.TP
+.BR groff (@MAN1EXT@)
+the usage of the groff program and pointers to the documentation and
+availability of the
+.FONT CI groff
+system.
+.
+The main source of information for the
+.FONT CI groff
+szstem is the
+.FONT CB groff
+.BR info (1)
+file.
+.
+.
+.TP
+.BR groff (@MAN7EXT@)
+documents the
+.FONT CI groff
+language.
+.
+.
+.TP
+.BR groff_tmac (@MAN5EXT@)
+contains documentation of the
+.FONT CB .PSPIC
+request.
+.
+.
+.TP
+.BR lilypond (1)
+The documentation of the
+.FONT CB lilypond
+program.
+.
+The main source of information for the
+.FONT CI lilypond
+language is the
+.FONT CB lilypond
+.BR info (1)
+file.
+.
+.
+.TP
+.BR pdf2ps (1)
+transform a
+.FONT CI PDF
+file into a
+.FONT CI Postscript
+format.
+.
+.
+.TP
+.BR ps2eps (1)
+transform a
+.FONT CI PS
+file into an
+.FONT CI EPS
+format.
+.
+.
+.\" --------------------------------------------------------------------
+.SH "AUTHORS"
+.\" --------------------------------------------------------------------
+.authors
+.
+.
+.\" --------------------------------------------------------------------
+.SH "COPYING"
+.\" --------------------------------------------------------------------
+.copying
+.
+.
+.\" --------------------------------------------------------------------
+.\" Emacs settings
+.\" --------------------------------------------------------------------
+.
+.\" Local Variables:
+.\" mode: nroff
+.\" End:

Index: glilypond.pl
===================================================================
RCS file: glilypond.pl
diff -N glilypond.pl
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ glilypond.pl	11 Aug 2013 08:30:10 -0000	1.9
@@ -0,0 +1,763 @@
+#! /usr/bin/env perl
+
+package main;
+
+########################################################################
+# debugging
+########################################################################
+
+# See `Mastering Perl', chapter 4.
+
+# use strict;
+# use warnings;
+# use diagnostics;
+
+use Carp;
+$SIG[__DIE__] = sub { &Carp::croak; };
+
+use Data::Dumper;
+
+########################################################################
+# Legalese
+########################################################################
+
+our $Legalese;
+
+{
+  use constant VERSION => 'v1.1'; # version of glilypond
+  use constant LASTUPDATE => '10 May 2013'; # date of last update
+
+### This constant `LICENSE' is the license for this file `GPL' >= 3
+  use constant LICENSE => q*
+glilypond - integrate `lilypond' into `groff' files
+
+Source file position: `<groff-source>/contrib/glilypond/glilypond.pl'
+Installed position: `<prefix>/bin/glilypond'
+
+Copyright (C) 2013 Free Software Foundation, Inc.
+  Written by Bernd Warken <groff-bernd.warken-72@web.de>
+
+This file is part of `GNU groff'.
+
+  `GNU 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.
+
+  `GNU 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 package.  If not, see
+<http://www.gnu.org/licenses/>.
+*;
+
+
+  $Legalese =
+    {
+     'version' => VERSION,
+     'last_update' => LASTUPDATE,
+     'license' => LICENSE,
+    }
+
+}
+
+##### end legalese
+
+
+########################################################################
+# global variables and BEGIN
+########################################################################
+
+use integer;
+use utf8;
+
+use Cwd qw[];
+use File::Basename qw[];
+use File::Copy qw[];
+use File::HomeDir qw[];
+use File::Spec qw[];
+use File::Path qw[];
+use File::Temp qw[];
+use FindBin qw[];
+use POSIX qw[];
+
+
+BEGIN {
+
+  use constant FALSE => 0;
+  use constant TRUE => 1;
+  use constant EMPTYSTRING => '';
+  use constant EMPTYARRAY => ();
+  use constant EMPTYHASH => ();
+
+  our $Globals =
+    {
+     'before_make' => FALSE,
+     'groff_version' => EMPTYSTRING,
+     'prog' => EMPTYSTRING,
+    };
+
+  {
+    ( my $volume, my $directory, $Globals->{'prog'} ) =
+      File::Spec->splitpath($0);
+    # $Globals->{'prog'} is `glilypond' when installed,
+    # `glilypond.pl' when not
+  }
+
+
+  $\ = "\n";	# adds newline at each print
+  $/ = "\n";	# newline separates input
+  $| = 1;       # flush after each print or write command
+
+
+  {
+    {
+      # script before run of `make'
+      my $at = '@';
+      $Globals->{'before_make'} = TRUE if '@VERSION@' eq "${at}VERSION${at}";
+    }
+
+    my $file_test_pl;
+    my $glilypond_libdir;
+
+    if ( $Globals->{'before_make'} ) { # in source, not yet installed
+      my $glilypond_dir = $FindBin::Bin;
+      $glilypond_dir = Cwd::realpath($glilypond_dir);
+      $glilypond_libdir = $glilypond_dir;
+
+    } else {			# already installed
+      $Globals->{'groff_version'} = '@VERSION@';
+      $glilypond_libdir = '@glilypond_dir@';
+    }
+
+    unshift(@INC, $glilypond_libdir);
+
+    umask 0077; # octal output: `printf "%03o", umask;'
+  }
+
+  require 'subs.pl';
+}
+
+die "test: ";
+########################################################################
+# OOP declarations for some file handles
+########################################################################
+
+require 'oop_fh.pl';
+
+our $stdout = new FH_STDOUT();
+our $stderr = new FH_STDERR();
+
+# verbose printing, not clear wether this will be set by `--verbose',
+# so store this now into a string, which can be gotten later on, when
+# it will become either STDERR or /dev/null
+our $v = new FH_STRING();
+
+# for standard output, either STDOUT or output file
+our $out;
+
+# end of FH
+
+
+########################################################################
+# Args: command line arguments
+########################################################################
+
+# command line arguments are handled in 2 runs:
+# 1) split short option collections, `=' optargs, and transfer abbrevs
+# 2) handle the transferred options with subs
+
+our $Args =
+  {
+   'eps_dir' => EMPTYSTRING, # can be overwritten by `--eps_dir'
+
+   # `eps-func' has 2 possible values:
+   # 1) `ly' from `--ly2eps' (default)
+   # 2) `pdf' `--pdf2eps'
+   'eps_func' => 'ly',
+
+   # files names of temporary files start with this string,
+   # can be overwritten by `--prefix'
+   'prefix' => 'ly',
+
+   # delete or do not delete temporary files
+   'keep_all' => FALSE,
+
+   # the roff output goes normally to STDOUT, can be a file with `--output'
+   'output' => EMPTYSTRING,
+
+   # temporary directory, can be overwritten by `--temp_dir',
+   # empty for default of the program
+   'temp_dir' => EMPTYSTRING,
+
+   # regulates verbose output (on STDERR), overwritten by `--verbose'
+   'verbose' => FALSE,
+  };
+
+{ # `Args'
+  require 'args.pl';
+  &run_first();
+  &install_verbose();
+  &run_second();
+  &handle_args();
+}
+
+# end `Args'
+
+
+########################################################################
+# temporary directory .../tmp/groff/USER/lilypond/TIME
+########################################################################
+
+our $Temp =
+  {
+   # store the current directory
+   'cwd' => Cwd::getcwd(),
+
+   # directory for EPS files
+   'eps_dir' => EMPTYSTRING,
+
+   # temporary directory
+   'temp_dir' => EMPTYSTRING,
+  };
+
+{ # `Temp'
+
+  if ( $Args->{'temp_dir'} ) {
+
+    #----------
+    # temporary directory was set by `--temp_dir'
+    #----------
+
+    my $dir = $Args->{'temp_dir'};
+
+    $dir = &path2abs($dir);
+    $dir = &make_dir($dir) or
+      die "The directory `$dir' cannot be used temporarily: $!";
+
+
+    # now `$dir' is a writable directory
+
+    opendir( my $dh, $dir ) or
+      die "Could not open temporary directory `$dir': $!";
+    my $file_name;
+    my $found = FALSE;
+    my $prefix = $Args->{'prefix'};
+    my $re = qr<
+		 ^
+		 $prefix
+		 _
+	       >x;
+
+  READDIR: while ( defined($file_name = readdir($dh)) ) {
+      chomp $file_name;
+      if ( $file_name =~ /$re/ ) { # file name starts with $prefix_
+	$found = TRUE;
+	last READDIR;
+      }
+      next;
+    }
+
+    $Temp->{'temp_dir'} = $dir;
+    my $n = 0;
+    while ( $found ) {
+      $dir = File::Spec->catdir( $Temp->{'temp_dir'}, ++$n );
+      next if ( -e $dir );
+
+      $dir = &make_dir($dir) or next;
+
+      $found = FALSE;
+      last;
+    }
+
+    $Temp->{'temp_dir'} = $dir;
+
+
+  } else { # $Args->{'temp_dir'} not given by `--temp_dir'
+
+    #----------
+    # temporary directory was not set
+    #----------
+
+    { # search for or create a temporary directory
+
+      my @tempdirs = EMPTYARRAY;
+      {
+	my $tmpdir = File::Spec->tmpdir();
+	push @tempdirs, $tmpdir if ( $tmpdir && -d $tmpdir && -w $tmpdir );
+
+	my $root_dir = File::Spec->rootdir(); # `/' in Unix
+	my $root_tmp = File::Spec->catdir($root_dir, 'tmp');
+	push @tempdirs, $root_tmp
+	  if ( $root_tmp ne $tmpdir && -d $root_tmp && -w $root_tmp );
+
+	# home directory of the actual user
+	my $home = File::HomeDir->my_home;
+	my $home_tmp = File::Spec->catdir($home, 'tmp');
+	push @tempdirs, $home_tmp if ( -d $home_tmp && -w $home_tmp );
+
+	# `/var/tmp' in Unix
+	my $var_tmp = File::Spec->catdir('', 'var', 'tmp');
+	push @tempdirs, $var_tmp if ( -d $var_tmp && -w $var_tmp );
+      }
+
+
+      my @path_extension = qw( groff ); # TEMPDIR/groff/USER/lilypond/<NUMBER>
+      {
+	# `$<' is UID of actual user,
+	# `getpwuid' gets user name in scalar context
+	my $user = getpwuid($<);
+	push @path_extension, $user if ( $user );
+
+	push @path_extension, qw( lilypond );
+      }
+
+
+    TEMPS: foreach ( @tempdirs ) {
+
+	my $dir; # final directory name in `while' loop
+	$dir = &path2abs($_);
+	next TEMPS unless ( $dir );
+
+	# beginning of directory name
+	my @dir_begin =
+	  ( File::Spec->splitdir($dir), @path_extension );
+
+
+	my $n = 0;
+	my $dir_blocked = TRUE;
+      BLOCK: while ( $dir_blocked ) {
+	  # should become the final dir name
+	  $dir = File::Spec->catdir(@dir_begin, ++$n);
+	  next BLOCK if ( -d $dir );
+
+	  # dir name is now free, create it, and end the blocking
+	  my $res = &make_dir( $dir );
+	  die "Could not create directory: $dir" unless ( $res );
+
+	  $dir = $res;
+	  $dir_blocked = FALSE;
+	}
+
+	next TEMPS unless ( -d $dir && -w $dir  );
+
+	# $dir is now a writable directory
+	$Temp->{'temp_dir'} = $dir; # tmp/groff/USER/lilypond/TIME
+	last TEMPS;
+      } # end foreach tmp directories
+    } # end to create a temporary directory
+
+    die "Could not find a temporary directory" unless
+      ( $Temp->{'temp_dir'} && -d $Temp->{'temp_dir'} &&
+	-w $Temp->{'temp_dir'} );
+
+  } # end temporary directory
+
+  $v->print( "Temporary directory: `" . $Temp->{'temp_dir'} . "'\n" );
+  $v->print( "file_prefix: `" . $Args->{'prefix'} . "'" );
+
+
+  #----------
+  # EPS directory
+  #----------
+
+  my $make_dir = FALSE;
+  if ( $Args->{'eps_dir'} ) { # set by `--eps_dir'
+    my $dir = $Args->{'eps_dir'};
+
+    $dir = &path2abs($dir);
+
+    if ( -e $dir ) {
+      goto EMPTY unless ( -w $dir );
+
+      # `$dir' is writable
+      if ( -d $dir ) {
+	my $upper_dir = $dir;
+
+	my $found = FALSE;
+	opendir( my $dh, $upper_dir ) or $found = TRUE;
+	my $prefix = $Args->{'prefix'};
+	my $re = qr<
+		     ^
+		     $prefix
+		     _
+		   >x;
+	while ( not $found ) {
+	  my $file_name = readdir($dh);
+	  if ( $file_name =~ /$re/ ) { # file name starts with $prefix_
+	    $found = TRUE;
+	    last;
+	  }
+	  next;
+	}
+
+	my $n = 0;
+	while ( $found ) {
+	  $dir = File::Spec->catdir($upper_dir, ++$n);
+	  next if ( -d $dir );
+	  $found = FALSE;
+	}
+	$make_dir = TRUE;
+	$Temp->{'eps_dir'} = $dir;
+      } else { # `$dir' is not a dir, so unlink it to create it as dir
+	if ( unlink $dir ) { # could remove `$dir'
+	  $Temp->{'eps_dir'} = $dir;
+	  $make_dir = TRUE;
+	} else { # could not remove
+	  stderr->print(  "Could not use EPS dir `" . $dir .
+			  "', use temp dir." );
+	} # end of unlink
+      } # end test of -d $dir
+    } else {
+      $make_dir = TRUE;
+    } # end of if -e $dir
+
+
+    if ( $make_dir ) { # make directory `$dir'
+      my $made = FALSE;
+      $dir = &make_dir($dir) and $made = TRUE;
+
+      if ( $made ) {
+	$Temp->{'eps_dir'} = $dir;
+	$v->print( "Directory for useful EPS files is `" . $dir . "'." );
+      } else {
+	$v->print( "The EPS directory `" . $dir . "' cannot be used: $!" );
+      }
+    } else { # `--eps_dir' was not set, so take the temporary directory
+      $Temp->{'eps_dir'} = $Args->{'temp_dir'};
+    } # end of make dir
+  }
+
+ EMPTY: unless ( $Temp->{'eps_dir'} ) {
+    # EPS-dir not set or available, use temp dir,
+    # but leave $Temp->{'}eps_dir'} empty
+    $v->print( "Directory for useful EPS files is the " .
+      "temporary directory `" . $Temp->{'temp_dir'} . "'." );
+  }
+
+} # end `Temp'
+
+
+########################################################################
+# Read: read files or stdin
+########################################################################
+
+our $Read =
+  {
+   'file_numbered' => EMPTYSTRING,
+   'file_ly' => EMPTYSTRING, # `$file_numbered.ly'
+  };
+
+{ # read files or stdin
+
+  my $ly_number = 0; # number of lilypond file
+
+  # `$Args->{'prefix'}_[0-9]'
+
+  my $lilypond_mode = FALSE;
+
+  my $arg1; # first argument for `.lilypond'
+  my $arg2; # argument for `.lilypond include'
+
+  my $path_ly; # path of ly-file
+
+
+  my $check_file = sub { # for argument of `.lilypond include'
+    my $file = shift; # argument is a file name
+    $file = &path2abs($file);
+    unless ( $file ) {
+      die "Line `.lilypond include' without argument";
+      return '';
+    }
+    unless ( -f $file && -r $file ) {
+      die "Argument `$file' in `.lilypond include' is not a readable file";
+    }
+
+    return $file;
+  }; # end sub &$check_file()
+
+
+  my $increase_ly_number = sub {
+    ++$ly_number;
+    $Read->{'file_numbered'} = $Args->{'prefix'} . '_' . $ly_number;
+    $Read->{'file_ly'} =  $Read->{'file_numbered'} . '.ly';
+    $path_ly = File::Spec->catdir($Temp->{'temp_dir'}, $Read->{'file_ly'} );
+  };
+
+
+  my %eps_subs =
+    (
+     'ly' => \&create_ly2eps,   # lilypond creates EPS files
+     'pdf' => \&create_pdf2eps, # lilypond creates PDF file
+    );
+
+  # about lines starting with `.lilypond'
+
+  my $ly;
+  my $fh_include_file;
+  my %lilypond_args =
+    (
+
+     'start' => sub {
+       $v->print( "\nline: `.lilypond start'" );
+       die "Line `.lilypond stop' expected." if ( $lilypond_mode );
+
+       $lilypond_mode = TRUE;
+       &$increase_ly_number;
+
+       $v->print( "ly-file: `" . $path_ly . "'" );
+
+       $ly = new FH_FILE($path_ly);
+     },
+
+
+     'end' => sub {
+       $v->print( "line: `.lilypond end'\n" );
+       die "Expected line `.lilypond start'." unless ( $lilypond_mode );
+
+       $lilypond_mode = FALSE;
+       $ly->close();
+
+       if ( exists $eps_subs{ $Args->{'eps_func'} } ) {
+	 $eps_subs{ $Args->{'eps_func'} }->();
+       } else {
+	 die "Wrong argument for \%eps_subs: " . $Args->{'eps_func'} . "'";
+       }
+     },
+
+
+     'include' => sub { # `.lilypond include file...'
+
+       # this may not be used within lilypond mode
+       next LILYPOND if ( $lilypond_mode );
+
+       my $file_arg = shift;
+
+       my $file = &$check_file($file_arg);
+       next LILYPOND unless ( $file );
+       # file can be read now
+
+
+       # `$fh_write_ly' must be opened
+       &$increase_ly_number;
+
+       $ly = new FH_FILE($path_ly);
+
+       my $include = new FH_READ_FILE($file);
+       my $res = $include->read-all(); # is a refernce to an array
+       foreach ( @$res ) {
+	 chomp;
+	 $ly->print($_);
+       }
+       $ly->close();
+
+       if ( exists $eps_subs{ $Args->{'eps_func'} } ) {
+	 $eps_subs{ $Args->{'eps_func'} }->();
+       } else {
+	 die "Wrong argument for \$eps_subs: `" . $Args->{'eps_func'} . "'";
+       }
+     }, # end `.lilypond include'
+
+    ); # end definition %lilypond_args
+
+
+ LILYPOND: foreach (<>) {
+    chomp;
+    my $line = $_;
+
+
+    # now the lines with '.lilypond ...'
+
+    if ( /
+	   ^
+	   [.']
+	   \s*
+	   lilypond
+	   (
+	     .*
+	   )
+	   $
+	 /x ) { # .lilypond ...
+      my $args = $1;
+      $args =~ s/
+		  ^
+		  \s*
+		//x;
+      $args =~ s/
+		  \s*
+		  $
+		//x;
+      $args =~ s/
+		  ^
+		  (
+		    \S*
+		  )
+		  \s*
+		//x;
+      my $arg1 = $1; # `start', `end' or `include'
+      $args =~ s/["'`]//g;
+      my $arg2 = $args; # file argument for `.lilypond include'
+
+      if ( exists $lilypond_args{$arg1} ) {
+	$lilypond_args{$arg1}->($arg2);
+	next;
+      } else {
+	# not a suitable argument of `.lilypond'
+	$stderr->print( "Unknown command: `$arg1' `$arg2':  `$line'" );
+      }
+
+      next LILYPOND;
+    } # end if for .lilypond
+
+
+    if ( $lilypond_mode ) { # do lilypond-mode
+      # see `.lilypond start'
+      $ly->print( $line );
+      next LILYPOND;
+    } # do lilypond-mode
+
+    # unknown line without lilypond
+    unless ( /
+	       ^
+	       [.']
+	       \s*
+	       lilypond
+	     /x ) { # not a `.lilypond' line
+      $out->print($line);
+      next LILYPOND;
+    }
+
+  } # end foreach <>
+} # end Read
+
+
+########################################################################
+# clean up
+########################################################################
+
+END {
+
+  exit unless ( defined($Temp->{'temp_dir'}) );
+
+  if ( $Args->{'keep_all'} ) {
+    # With --keep_all, no temporary files are removed.
+    $v->print( "keep_all: `TRUE'" );
+    $v->print( "No temporary files will be deleted:" );
+
+    opendir my $dh_temp, $Temp->{'temp_dir'} or
+      die "Cannot open " . $Temp->{'temp_dir'} . ": $!";
+    for ( sort readdir $dh_temp ) {
+      next if ( /         # omit files starting with a dot
+		  ^
+		  \.
+		/x );
+      if ( /
+	     ^
+	     $Args->{'prefix'}
+	     _
+	   /x ) {
+	my $file = File::Spec->catfile( $Temp->{'temp_dir'}, $_ );
+	$v->print( "- " . $file );
+	next;
+      }
+      next;
+    } # end for sort readdir
+    closedir $dh_temp;
+
+  } else { # keep_all is not set
+    # Remove all temporary files except the eps files.
+
+    $v->print( "keep_all: `FALSE'" );
+    $v->print( "All temporary files except *.eps will be deleted" );
+
+
+    if ( $Temp->{'eps_dir'} ) {
+      # EPS files are in another dir, remove temp dir
+
+      if ( &is_subdir( $Temp->{'eps_dir'}, $Temp->{'temp_dir'} ) ) {
+	$v->print( "EPS dir is subdir of temp dir, so keep both." );
+      } else { # remove temp dir
+	$v->print( "Try to remove temporary directory `" .
+	  $Temp->{'temp_dir'} ."':" );
+	if ( File::Path::remove_tree($Temp->{'temp_dir'}) ) {
+	  # remove succeeds
+	  $v->print( "...done." );
+	} else { # did not remove
+	  $v->print( "Failure to remove temporary directory." );
+	} # end test on remove
+      } # end is subdir
+
+    } else { # no EPS dir, so keep EPS files
+
+      opendir my $dh_temp, $Temp->{'temp_dir'} or
+	die "Cannot open " . $Temp->{'temp_dir'} . ": $!";
+      for ( sort readdir $dh_temp ) {
+	next if ( /          # omit files starting with a dot
+		    ^
+		    \.
+		  /x );
+	next if ( /          # omit EPS-files
+		    \.eps
+		    $
+		  /x );
+	if ( /
+	       ^
+	       $Args->{'prefix'}
+	       _
+	     /x ) { # this includes `PREFIX_temp*'
+	  my $file = File::Spec->catfile( $Temp->{'temp_dir'},  $_ );
+	  $v->print( "Remove `" . $file . "'" );
+	  unlink $file or $stderr->print( "Could not remove `$file': $!" );
+	  next;
+	} # end if prefix
+	next;
+      } # end for readdir temp dir
+      closedir $dh_temp;
+    } # end if-else EPS files
+  } # end if-else keep files
+
+
+  if ( $Temp->{'eps_dir'} ) {
+    # EPS files in $Temp->{'eps_dir'} are always kept
+    $v->print( "As EPS directrory is set as `" .
+      $Temp->{'eps_dir'} . "', no EPS files there will be deleted." );
+
+    opendir my $dh_temp, $Temp->{'eps_dir'} or
+      die "Cannot open `" . $Temp->{'eps_dir'} . ": $!";
+    for ( sort readdir $dh_temp ) {
+      next if ( /         # omit files starting with a dot
+		  ^
+		  \.
+		/x );
+      if ( /
+	     ^
+	     $Args->{'prefix'}
+	     _
+	     .*
+	     \.eps
+	     $
+	   /x ) {
+	my $file = File::Spec->catfile( $Temp->{'eps_dir'}, $_ );
+	$v->print( "- " . $file );
+	next;
+      } # end if *.eps
+      next;
+    } # end for sort readdir
+    closedir $dh_temp;
+
+  }
+
+  1;
+} # end package Clean
+
+
+1;
+########################################################################
+### Emacs settings
+# Local Variables:
+# mode: CPerl
+# End:

Index: oop_fh.pl
===================================================================
RCS file: oop_fh.pl
diff -N oop_fh.pl
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ oop_fh.pl	11 Aug 2013 08:30:11 -0000	1.6
@@ -0,0 +1,311 @@
+my $License = q*
+########################################################################
+# Legalese
+########################################################################
+
+Source file position: `<groff-source>/contrib/glilypond/oop_fh.pl'
+Installed position: `<prefix>/lib/groff/glilypond/oop_fh.pl'
+
+Copyright (C) 2013 Free Software Foundation, Inc.
+  Written by Bernd Warken <groff-bernd.warken-72@web.de>
+
+Last update: 10 May 2013
+
+This file is part of `glilypond', which is part of `GNU groff'.
+
+glilypond - integrate `lilypond' into `groff' files
+
+  `GNU 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.
+
+  `GNU 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 package.  If not, see
+<http://www.gnu.org/licenses/>.
+*;
+
+##### end legalese
+
+
+# use strict;
+# use warnings;
+# use diagnostics;
+
+use integer;
+
+########################################################################
+# OOP for writing file handles that are open by default, like STD*
+########################################################################
+
+# -------------------------- _FH_WRITE_OPENED --------------------------
+
+{	# FH_OPENED: base class for all opened file handles, like $TD*
+
+  package _FH_WRITE_OPENED;
+  use strict;
+
+  sub new {
+    my ( $pkg, $std ) = @_;
+    bless {
+	   'fh' => $std,
+	  }
+  }
+
+  sub open {
+  }
+
+  sub close {
+  }
+
+  sub print {
+    my $self = shift;
+    for ( @_ ) {
+      print { $self->{'fh'} } $_;
+    }
+  }
+
+}
+
+
+# ------------------------------ FH_STDOUT ----------------------------
+
+{			     # FH_STDOUT: print to noral output STDOUT
+
+  package FH_STDOUT;
+  use strict;
+  @FH_STDOUT::ISA = qw( _FH_WRITE_OPENED );
+
+  sub new {
+    &_FH_WRITE_OPENED::new( '_FH_WRITE_OPENED', *STDOUT );
+  }
+
+}				# end FH_STDOUT
+
+
+# ------------------------------ FH_STDERR -----------------------------
+
+{				# FH_STDERR: print to STDERR
+
+  package FH_STDERR;
+  use strict;
+  @FH_STDERR::ISA = qw( _FH_WRITE_OPENED );
+
+  sub new {
+    &_FH_WRITE_OPENED::new( 'FH_OPENED', *STDERR );
+  }
+
+}				# end FH_STDERR
+
+
+########################################################################
+# OOP for file handles that write into a file or string
+########################################################################
+
+# ------------------------------- FH_FILE ------------------------------
+
+{	       # FH_FILE: base class for writing into a file or string
+
+  package FH_FILE;
+  use strict;
+
+  sub new {
+    my ( $pkg, $file ) = @_;
+    bless {
+	   'fh' => undef,
+	   'file' => $file,
+	   'opened' => main::FALSE,
+	  }
+  }
+
+  sub DESTROY {
+    my $self = shift;
+    $self->close();
+  }
+
+  sub open {
+    my $self = shift;
+    my $file = $self->{'file'};
+    if ( $file && -e $file ) {
+      die "file $file is not writable" unless ( -w $file );
+      die "$file is a directory" if ( -d $file );
+    }
+    open $self->{'fh'}, ">", $self->{'file'}
+      or die "could not open file `$file' for writing: $!";
+    $self->{'opened'} = main::TRUE;
+  }
+
+  sub close {
+    my $self = shift;
+    close $self->{'fh'} if ( $self->{'opened'} );
+    $self->{'opened'} = main::FALSE;
+  }
+
+  sub print {
+    my $self = shift;
+    $self->open() unless ( $self->{'opened'} );
+    for ( @_ ) {
+      print { $self->{'fh'} } $_;
+    }
+  }
+
+}				# end FH_FILE
+
+
+# ------------------------------ FH_STRING -----------------------------
+
+{				# FH_STRING: write into a string
+
+  package FH_STRING;		# write to \string
+  use strict;
+  @FH_STRING::ISA = qw( FH_FILE );
+
+  sub new {
+    my $pkg = shift;		# string is a reference to scalar
+    bless
+      {
+       'fh' => undef,
+       'string' => '',
+       'opened' => main::FALSE,
+      }
+    }
+
+  sub open {
+    my $self = shift;
+    open $self->{'fh'}, ">", \ $self->{'string'}
+      or die "could not open string for writing: $!";
+    $self->{'opened'} = main::TRUE;
+  }
+
+  sub get { # get string, move to array ref, close, and return array ref
+    my $self = shift;
+    return '' unless ( $self->{'opened'} );
+    my $a = &string2array( $self->{'string'} );
+    $self->close();
+    return $a;
+  }
+
+}				# end FH_STRING
+
+
+# -------------------------------- FH_NULL -----------------------------
+
+{				# FH_NULL: write to null device
+
+  package FH_NULL;
+  use strict;
+  @FH_NULL::ISA = qw( FH_FILE FH_STRING );
+
+  use File::Spec;
+
+  my $devnull = File::Spec->devnull();
+  $devnull = '' unless ( -e $devnull && -w $devnull );
+
+  sub new {
+    my $pkg = shift;
+    if ( $devnull ) {
+      &FH_FILE::new( $pkg, $devnull );
+    } else {
+      &FH_STRING::new( $pkg );
+    }
+  } # end new()
+
+}				# end FH_NULL
+
+
+########################################################################
+# OOP for reading file handles
+########################################################################
+
+# ---------------------------- FH_READ_FILE ----------------------------
+
+{ # FH_READ_FILE: read a file
+
+  package FH_READ_FILE;
+  use strict;
+
+  sub new {
+    my ( $pkg, $file ) = @_;
+    die "File `$file' cannot be read." unless ( -f $file && -r $file );
+    bless {
+	   'fh' => undef,
+	   'file' => $file,
+	   'opened' => main::FALSE,
+	  }
+  }
+
+  sub DESTROY {
+    my $self = shift;
+    $self->close();
+  }
+
+  sub open {
+    my $self = shift;
+    my $file = $self->{'file'};
+    if ( $file && -e $file ) {
+      die "file $file is not writable" unless ( -r $file );
+      die "$file is a directory" if ( -d $file );
+    }
+    open $self->{'fh'}, "<", $self->{'file'}
+      or die "could not read file `$file': $!";
+    $self->{'opened'} = main::TRUE;
+  }
+
+  sub close {
+    my $self = shift;
+    close $self->{'fh'} if ( $self->{'opened'} );
+    $self->{'opened'} = main::FALSE;
+  }
+
+  sub read_line {
+    # Read 1 line of the file into a chomped string.
+    # Do not close the read handle at the end.
+    my $self = shift;
+    $self->open() unless ( $self->{'opened'} );
+
+    my $res;
+    if ( defined($res = CORE::readline($self->{'fh'}) ) ) {
+      chomp $res;
+      return $res;
+    } else {
+      $self->close();
+      return undef;
+    }
+  }
+
+  sub read_all {
+    # Read the complete file into an array reference.
+    # Close the read handle at the end.
+    # Return array reference.
+    my $self = shift;
+    $self->open() unless ( $self->{'opened'} );
+
+    my $res = [];
+    my $line;
+    while ( defined ( $line = CORE::readline $self->{'fh'} ) ) {
+      chomp $line;
+      push @$res, $line;
+    }
+    $self->close();
+    $self->{'opened'} = main::FALSE;
+    return $res;
+  }
+
+}
+
+# end of OOP definitions
+
+package main;
+
+1;
+########################################################################
+### Emacs settings
+# Local Variables:
+# mode: CPerl
+# End:

Index: subs.pl
===================================================================
RCS file: subs.pl
diff -N subs.pl
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ subs.pl	11 Aug 2013 08:30:12 -0000	1.8
@@ -0,0 +1,469 @@
+my $License = q*
+########################################################################
+# Legalese
+########################################################################
+
+Subroutines for `glilypond'.
+
+Source file position: `<groff-source>/contrib/glilypond/subs.pl'
+Installed position: `<prefix>/lib/groff/glilypond/subs.pl'
+
+Copyright (C) 2013 Free Software Foundation, Inc.
+  Written by Bernd Warken <groff-bernd.warken-72@web.de>
+
+  Last update: 10 May 2013
+
+This file is part of `glilypond', which is part of `GNU groff'.
+
+  `GNU 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.
+
+  `GNU 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 package.  If not, see
+<http://www.gnu.org/licenses/>.
+*;
+
+##### end legalese
+
+
+# use strict;
+# use warnings;
+# use diagnostics;
+
+use integer;
+use utf8;
+use feature 'state';
+
+
+########################################################################
+# subs for using several times
+########################################################################
+
+sub create_ly2eps {		       # `--ly2eps' default
+  our ( $out, $Read, $Temp );
+
+  my $prefix = $Read->{'file_numbered'};   # with dir change to temp dir
+
+  # `$ lilypond --ps -dbackend=eps -dgs-load-fonts \
+  #      output=file_without_extension file.ly'
+  # extensions are added automatically
+  my $opts = '--ps -dbackend=eps -dinclude-eps-fonts -dgs-load-fonts ' .
+    "--output=$prefix $prefix";
+  &run_lilypond("$opts");
+
+  Cwd::chdir $Temp->{'cwd'} or
+      die "Could not change to former directory `" .
+	$Temp->{'cwd'} . "': $!";
+
+  my $eps_dir = $Temp->{'eps_dir'};
+  my $dir = $Temp->{'temp_dir'};
+  opendir( my $dh, $dir ) or
+    die "could not open temporary directory `$dir': $!";
+
+  my $re = qr<
+	       ^
+	       $prefix
+	       -
+	       .*
+	       \.eps
+	       $
+	     >x;
+  my $file;
+  while ( readdir( $dh ) ) {
+    chomp;
+    $file = $_;
+    if ( /$re/ ) {
+      my $file_path = File::Spec->catfile($dir, $file);
+      if ( $eps_dir ) {
+	my $could_copy = FALSE;
+	File::Copy::copy($file_path, $eps_dir)
+	    and $could_copy = TRUE;
+	if ( $could_copy ) {
+	  unlink $file_path;
+	  $file_path = File::Spec->catfile($eps_dir, $_);
+	}
+      }
+      $out->print( '.PSPIC ' . $file_path );
+    }
+  }				# end while readdir
+  closedir( $dh );
+}				# end sub create_ly2eps()
+
+
+sub create_pdf2eps {		       # `--pdf2eps'
+  our ( $v, $stdout, $stderr, $out, $Read, $Temp );
+
+  my $prefix = $Read->{'file_numbered'};   # with dir change to temp dir
+
+  &run_lilypond("--pdf --output=$prefix $prefix");
+
+  my $file_pdf = $prefix . '.pdf';
+  my $file_ps = $prefix . '.ps';
+
+  # pdf2ps in temp dir
+  my $temp_file = &next_temp_file;
+  $v->print( "\n##### run of `pdf2ps'" );
+  # `$ pdf2ps file.pdf file.ps'
+  my $output = `pdf2ps $file_pdf $file_ps 2> $temp_file`;
+  die 'Program pdf2ps does not work.' if ( $? );
+  &shell_handling($output, $temp_file);
+  $v->print( "##### end run of `pdf2ps'\n" );
+
+  # ps2eps in temp dir
+  $temp_file = &next_temp_file;
+  $v->print( "\n##### run of `ps2eps'" );
+  # `$ ps2eps file.ps'
+  $output = `ps2eps $file_ps 2> $temp_file`;
+  die 'Program ps2eps does not work.' if ( $? );
+  &shell_handling($output, $temp_file);
+  $v->print( "##### end run of `ps2eps'\n" );
+
+  # change back to former dir
+  Cwd::chdir $Temp->{'cwd'} or
+      die "Could not change to former directory `" .
+	$Temp->{'cwd'} . "': $!";
+
+  # handling of .eps file
+  my $file_eps = $prefix . '.eps';
+  my $eps_path = File::Spec->catfile($Temp->{'temp_dir'}, $file_eps);
+  if ( $Temp->{'eps_dir'} ) {
+    my $has_copied = FALSE;
+    File::Copy::copy( $eps_path, $Temp->{'eps_dir'} )
+	and $has_copied = TRUE;
+    if ( $has_copied ) {
+      unlink $eps_path;
+      $eps_path = File::Spec->catfile( $Temp->{'eps_dir'}, $file_eps );
+    } else {
+      $stderr->print( "Could not use EPS-directory." );
+    } # end Temp->{'eps_dir'}
+  }
+  # print into groff output
+  $out->print( '.PSPIC ' . $eps_path );
+}				# end sub create_pdf2eps()
+
+
+sub is_subdir {			# arg1 is subdir of arg2 (is longer)
+  my ( $dir1, $dir2 ) = @_;
+  $dir1 = &path2abs( $dir1 );;
+  $dir2 = &path2abs( $dir2 );;
+  my @split1 = File::Spec->splitdir($dir1);
+  my @split2 = File::Spec->splitdir($dir2);
+  for ( @split2 ) {
+    next if ( $_ eq shift @split1 );
+    return FALSE;
+  }
+  return TRUE;
+}
+
+
+sub license {
+  our ( $Legalese, $stdout );
+  &version;
+  $stdout->print( $Legalese->{'license'} );
+} # end sub license()
+
+
+sub make_dir {			# make directory or check if it exists
+  our ( $v, $Args );
+
+  my $dir_arg = shift;
+  chomp $dir_arg;
+  $dir_arg =~ s/^\s*(.*)\s*$/$1/;
+
+  unless ( $dir_arg ) {
+    $v->print( "make_dir(): empty argument" );
+    return FALSE;
+  }
+
+  unless ( File::Spec->file_name_is_absolute($dir_arg) ) {
+    my $res = Cwd::realpath($dir_arg);
+    $res = File::Spec->canonpath($dir_arg) unless ( $res );
+    $dir_arg = $res if ( $res );
+  }
+
+  return $dir_arg if ( -d $dir_arg && -w $dir_arg );
+
+
+  # search thru the dir parts
+  my @dir_parts = File::Spec->splitdir($dir_arg);
+  my @dir_grow;
+  my $dir_grow;
+  my $can_create = FALSE;	# dir could be created if TRUE
+
+ DIRPARTS: for ( @dir_parts ) {
+    push @dir_grow, $_;
+    next DIRPARTS unless ( $_ ); # empty string for root directory
+
+    # from array to path dir string
+    $dir_grow = File::Spec->catdir(@dir_grow);
+
+    next DIRPARTS if ( -d $dir_grow );
+
+    if ( -e $dir_grow ) {  # exists, but not a dir, so must be removed
+      die "Couldn't create dir `$dir_arg', it is blocked by `$dir_grow'."
+	unless ( -w $dir_grow );
+
+      # now it's writable, but not a dir, so it can be removed
+      unlink ( $dir_grow ) or
+	die "Couldn't remove `$dir_grow', " .
+	  "so I cannot create dir `$dir_arg': $!";
+    }
+
+    # $dir_grow does no longer exist, so the former dir must be writable
+    # in order to create the directory
+    pop @dir_grow;
+    $dir_grow = File::Spec->catdir(@dir_grow);
+
+    die "`$dir_grow' is not writable, " .
+      "so directory `$dir_arg' can't be createdd."
+	unless ( -w $dir_grow );
+
+    # former directory is writable, so `$dir_arg' can be created
+
+    File::Path::make_path( $dir_arg,
+			   {
+			    mask => oct('0700'),
+			    verbose => $Args->{'verbose'},
+			   }
+			 )	#  `mkdir -P'
+	or die "Could not create directory `$dir_arg': $!";
+
+    last DIRPARTS;
+  }
+
+  die "`$dir_arg' is not a writable directory"
+    unless ( -d $dir_arg && -w $dir_arg );
+
+  return $dir_arg;
+
+} # end sub make_dir()
+
+
+my $number = 0;
+sub next_temp_file {
+  our ( $Temp, $v, $Args );
+  ++$number;
+  my $temp_basename = $Args->{'prefix'} . '_temp_' . $number;
+  my $temp_file = File::Spec->catfile( $Temp->{'temp_dir'} ,
+				       $temp_basename );
+  $v->print( "next temporary file: `$temp_file'" );
+  return $temp_file;
+}				# end sub next_temp_file()
+
+
+sub path2abs {
+  our ( $Temp, $Args );
+
+  my $path = shift;
+  $path =~ s/
+	      ^
+	      \s*
+	      (
+		.*
+	      )
+	      \s*
+	      $
+	    /$1/x;
+
+  die "path2abs(): argument is empty." unless ( $path );
+
+  # Perl does not support shell `~' for home dir
+  if ( $path =~ /
+		  ^
+		  ~
+		/x ) {
+    if ( $path eq '~' ) {	# only own home
+      $path = File::HomeDir->my_home;
+    } elsif ( $path =~ m<
+			  ^
+			  ~ /
+			  (
+			    .*
+			  )
+			  $
+			>x ) {	# subdir of own home
+      $path = File::Spec->catdir( $Temp->{'cwd'}, $1 );
+    } elsif ( $path =~ m<
+			  ^
+			  ~
+			  (
+			    [^/]+
+			  )
+			  $
+			>x ) {	# home of other user
+      $path = File::HomeDir->users_home($1);
+    } elsif ( $path =~ m<
+			  ^
+			  ~
+			  (
+			    [^/]+
+			  )
+			  /+
+			  (
+			    .*
+			  )
+			  $
+			>x ) {	# subdir of other home
+      $path = File::Spec->
+	catdir( File::HomeDir->users_home($1), $2 );
+    }
+  }
+
+  $path = File::Spec->rel2abs($path);
+
+  # now $path is absolute
+  return $path;
+} # end sub path2abs()
+
+
+sub run_lilypond {
+  # arg is the options collection for `lilypond' to run
+  # either from ly or pdf
+
+  our ( $Temp, $v );
+
+  my $opts = shift;
+  chomp $opts;
+
+  my $temp_file = &next_temp_file;
+  my $output = EMPTYSTRING;
+
+  # change to temp dir
+  Cwd::chdir $Temp->{'temp_dir'} or
+      die "Could not change to temporary directory `" .
+	$Temp->{'temp_dir'} . "': $!";
+
+  $v->print( "\n##### run of `lilypond " . $opts . "'" );
+  $output = `lilypond $opts 2>$temp_file`;
+  die "Program lilypond does not work, see `$temp_file': $?"
+    if ( $? );
+  chomp $output;
+  &shell_handling($output, $temp_file);
+  $v->print( "##### end run of `lilypond'\n" );
+
+  # stay in temp dir
+} # end sub run_lilypond()
+
+
+sub shell_handling {
+  # Handle ``-shell-command output in a string (arg1).
+  # stderr goes to temporary file $TempFile.
+
+  our ( $out, $v, $Args );
+
+  my $out_string = shift;
+  my $temp_file = shift;
+
+  my $a = &string2array($out_string); # array ref
+  for ( @$a ) {
+    $out->print( $_ );
+  }
+
+  $temp_file && -f $temp_file && -r $temp_file ||
+    die "shell_handling(): $temp_file is not a readable file.";
+  my $temp = new FH_READ_FILE($temp_file);
+  my $res = $temp->read_all();
+  for ( @$res ) {
+    chomp;
+    $v->print($_);
+  }
+
+  unlink $temp_file unless ( $Args->{'keep_all'} );
+} # end sub shell_handling()
+
+
+sub string2array {
+  my $s = shift;
+  my @a = ();
+  for ( split "\n", $s ) {
+    chomp;
+    push @a, $_;
+  }
+  return \@a;
+} # end string2array()
+
+
+sub usage {			# for `--help'
+  our ( $Globals, $Args );
+
+  my $p = $Globals->{'prog'};
+  my $usage = EMPTYSTRING;
+  $usage = '###### usage:' . "\n" if ( $Args->{'verbose'} );
+  $usage .= qq*Options for $p:
+Read a `roff' file or standard input and transform `lilypond' parts
+(everything between `.lilypond start' and `.lilypond end') into
+`EPS'-files that can be read by groff using `.PSPIC'.
+
+There is also a command `.lilypond include <file_name>' that can
+include a complete `lilypond' file into the `groff' document.
+
+
+# Breaking options:
+$p -?|-h|--help|--usage    # usage
+$p --version               # version information
+$p --license               # the license is GPL >= 3
+
+
+# Normal options:
+$p [options] [--] [filename ...]
+
+There are 2 options for influencing the way how the `EPS' files for the
+`roff' display are generated:
+--ly2eps           `lilypond' generates `EPS' files directly (default)
+--pdf2eps          `lilypond' generates a `PDF' file that is transformed
+
+-k|--keep_all      do not delete any temporary files
+-v|--verbose       print much information to STDERR
+
+Options with an argument:
+-e|--eps_dir=...   use a directory for the EPS files
+-o|--output=...    sent output in the groff language into file ...
+-p|--prefix=...    start for the names of temporary files
+-t|--temp_dir=...  provide the directory for temporary files.
+
+The directories set are created when they do not exist.
+*;
+
+  # old options:
+  # --keep_files       -k: do not delete any temporary files
+  # --file_prefix=...  -p: start for the names of temporary files
+
+  $main::stdout->print( $usage );
+} # end sub usage()
+
+
+sub version { # for `--version'
+  our ( $Globals, $Legalese, $stdout, $Args );
+  my $end;
+  if ( $Globals->{'groff_version'} ) {
+    $end = " version $Globals->{'groff_version'}";
+  } else {
+    $end = '.';
+  }
+
+  my $output = EMPTYSTRING;
+  $output = "###### version:\n" if ( $Args->{'verbose'} );
+  $output .= "`" . $Globals->{'prog'} . "' version `" .
+    $Legalese->{'version'} . "' of `" .
+      $Legalese->{'last_update'} . "' is part of `GNU groff'" . $end;
+
+  $stdout->print($output);
+} # end sub version()
+
+
+# end of subs
+
+1;
+########################################################################
+### Emacs settings
+# Local Variables:
+# mode: CPerl
+# End:


From MAILER-DAEMON Sun Aug 11 04:32:32 2013
Received: from list by lists.gnu.org with archive (Exim 4.71)
	id 1V8R4i-0006pW-Gl
	for mharc-groff-commit@gnu.org; Sun, 11 Aug 2013 04:32:32 -0400
Received: from eggs.gnu.org ([2001:4830:134:3::10]:51849)
	by lists.gnu.org with esmtp (Exim 4.71) (envelope-from <wl@gnu.org>)
	id 1V8R1C-0004mY-S3
	for groff-commit@gnu.org; Sun, 11 Aug 2013 04:29:27 -0400
Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71)
	(envelope-from <wl@gnu.org>) id 1V8R0j-0002Ni-DG
	for groff-commit@gnu.org; Sun, 11 Aug 2013 04:28:54 -0400
Received: from vcs.savannah.gnu.org ([140.186.70.72]:59744)
	by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from <wl@gnu.org>)
	id 1V8R0i-0002Nb-T2
	for groff-commit@gnu.org; Sun, 11 Aug 2013 04:28:25 -0400
Received: from wl by vcs.savannah.gnu.org with local (Exim 4.72)
	(envelope-from <wl@gnu.org>) id 1V8R0i-0002V9-JK
	for groff-commit@gnu.org; Sun, 11 Aug 2013 08:28:24 +0000
Date: Sun, 11 Aug 2013 08:28:24 +0000
Message-Id: <E1V8R0i-0002V9-JK@vcs.savannah.gnu.org>
To: groff-commit@gnu.org
From: Werner LEMBERG <wl@gnu.org>
X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6.x
X-Received-From: 140.186.70.72
X-Mailman-Approved-At: Sun, 11 Aug 2013 04:32:30 -0400
Subject: [Groff-commit] groff/contrib/groffer/shell ChangeLog.0 README_...
X-BeenThere: groff-commit@gnu.org
X-Mailman-Version: 2.1.14
Precedence: list
List-Id: <groff-commit.gnu.org>
List-Unsubscribe: <https://lists.gnu.org/mailman/options/groff-commit>,
	<mailto:groff-commit-request@gnu.org?subject=unsubscribe>
List-Archive: <http://lists.gnu.org/archive/html/groff-commit>
List-Post: <mailto:groff-commit@gnu.org>
List-Help: <mailto:groff-commit-request@gnu.org?subject=help>
List-Subscribe: <https://lists.gnu.org/mailman/listinfo/groff-commit>,
	<mailto:groff-commit-request@gnu.org?subject=subscribe>
X-List-Received-Date: Sun, 11 Aug 2013 08:29:28 -0000

CVSROOT:	/sources/groff
Module name:	groff
Changes by:	Werner LEMBERG <wl>	13/08/11 08:28:24

Added files:
	contrib/groffer/shell: ChangeLog.0 README_SH groffer.man 
	                       groffer.sh groffer2.sh roff2.sh 

Log message:
	Revert accidental removal in previous commit.

CVSWeb URLs:
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/groffer/shell/ChangeLog.0?cvsroot=groff&rev=1.5
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/groffer/shell/README_SH?cvsroot=groff&rev=1.9
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/groffer/shell/groffer.man?cvsroot=groff&rev=1.20
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/groffer/shell/groffer.sh?cvsroot=groff&rev=1.7
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/groffer/shell/groffer2.sh?cvsroot=groff&rev=1.9
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/groffer/shell/roff2.sh?cvsroot=groff&rev=1.7

Patches:
Index: ChangeLog.0
===================================================================
RCS file: ChangeLog.0
diff -N ChangeLog.0
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ ChangeLog.0	11 Aug 2013 08:28:23 -0000	1.5
@@ -0,0 +1,2122 @@
+2006-10-10  Bernd Warken <groff-bernd.warken-72@web.de>
+
+	* ChangeLog.0: This file is the former ChangeLog file of the
+	`groffer' versions 0.* consisting of a shell version only.  Since
+	then the files have been moved to the subdirectory `shell' of the
+	`groffer' main directory.
+
+2006-10-05  Bernd Warken <groff-bernd.warken-72@web.de>
+	________________________________________________________________
+	* release of groffer 0.9.31
+
+	* groffer2.sh:
+	- _make_pdf(): Fix argument of `obj'.
+	- to_tmp(): Add option -r to soelim to omit the .lf request.  The
+	new global variable $_SOELIM_R stores the option if it is
+	available.  Use numbers for the names of the `file' and `so'
+	temporary files, such that the information for each filespec
+	argument is kept for debug.  New global variable $_FILE_NR.
+	- main_set_resources(): Remove `man' temporary files except for
+	debug
+	- man_get(): Change name in $_TMP_MANSPEC.
+	- man_is_man(): Change name in $_TMP_MANSPEC.  Remove file in
+	$_TMP_MANPEC if empty.
+	- _do_display() of main_display(): Add check on empty mode file.
+
+	* groffer.man: Filespec: Add information on the argument
+	handling of apropos.
+
+	Remove the space characters at the end of line in all files.
+
+2006-10-03  Bernd Warken <groff-bernd.warken-72@web.de>
+	________________________________________________________________
+	* release of groffer 0.9.30
+
+	* groffer2.sh:
+	- Correct spacing.
+        - main_do_fileargs(): Distribute special_filespec() in order to
+        get a better heading for `whatis'.
+
+2006-10-03  Bernd Warken <groff-bernd.warken-72@web.de>
+	________________________________________________________________
+	* release of groffer 0.9.29
+
+	* groffer2.sh:
+	- --to-stdtout: New option to display the generated mode file
+	without graphical display.
+	- _get_prog_args() of main_set_mode(): Make argument upper case.
+	- usage(): Add --to-stdout, remove -Q, reorder --source.
+
+	* groffer.man:
+	- Reorder the default viewers.
+	- Move `--source' to `groffer' options.
+	- Remove `-Q'.
+	- Add `--to-stdout'.
+	- Reconfigure the sections on filespec arguments.
+	- Remove information on wildcards.
+
+2006-10-01  Bernd Warken <groff-bernd.warken-72@web.de>
+	________________________________________________________________
+	* release of groffer 0.9.28
+
+	* groffer.sh:
+	- Change all directories to end with `/'.
+	- In the state before the run of `make', make the script runnable
+	from each directory using $0 and `pwd'.
+
+	* groffer2.sh:
+	- main_init(): Change the umask to 0077 to allow only access for
+	the file owner for the temporary files.  This is done for security
+	reasons.
+	- version(): Put the whole output under `<<EOF'.
+	- usage(): Add information on filespec arguments.
+	- main_do_fileargs(): Rewrite the handling of filespec
+	parameters.  Fix filespec man:name.section.
+
+2006-09-26  Bernd Warken <groff-bernd.warken-72@web.de>
+	________________________________________________________________
+	* release of groffer 0.9.27
+
+	* Makefile.sub: Add Emacs setting at the end of the file.
+
+	* TODO: Remove this file because it does not contain any actual
+	entries.
+
+	* groffer2.sh:
+	- main_set_mode(): Remove too early test of modes on X.  Fix pdf
+	mode.
+	- where_is_prog(): Fix this function to detect files in the
+	current directory.
+	- _get_prog_args() of main_set_mode(): Fix return;
+	- _get_first_prog() of main_set_mode(): Fix call of exit_test().
+	- cat_z(): Make it a single function and add file test.
+	- whatis_setup(): Rename whatis_header().  Fix display title to
+	`whatis'.
+	- apropos_setup(): Fix display title to `apropos'.
+	- Globals: Fix this section in the description of several
+	functions.
+	- apropos_filespec(): Fix variable $s and the corresponding sed
+	call.
+	- man_setup(): Add $EXTENSION.
+	- _do_man_so() of to_tmp(): Fix variables.
+	- $_ALL_EXIT: Remove unused variable.
+	- $_TITLE_ELT: Remove unused variable.
+	- man_set_resources(): Fix setting of $_DISPLAY_ARGS.
+	- main_display(): Fix description.  Remove $md_options.  Let
+	$MANOPT override system variables.
+
+2006-09-16  Bernd Warken <groff-bernd.warken-72@web.de>
+	________________________________________________________________
+	* release of groffer 0.9.26
+
+	### Simplification of main_set_mode()
+
+	* groffer2.sh:
+	- _get_first_prog() of main_set_mode(): Rewrite this function
+	such that it does not have an output, but set the variables
+	$_DISPLAY_PROG and $_DISPLAY_ARGS.
+	- _check_prog_on_list() of main_set_mode(): Rename and rewrite
+	_check_X_prog().  Suitable for being called for $_VIEWER_<mode>_X
+	and $_VIEWER_<mode>_TTY.  No output, but set the variables
+	$_DISPLAY_PROG and $_DISPLAY_ARGS.
+	- _obj_set_vars() of main_set_mode(): Remove this function.  It is
+	no longer necessary because its variables are set by the other
+	functions.
+	- _get_prog_args() of main_set_mode(): New function that
+	simplifies the loop in main_set_mode() and handles both
+	$_VIEWER_<mode>_X and $_VIEWER_<mode>_TTY.
+	- _process_mode() of main_set_mode(): Remove this function.
+	- main_set_mode(): Remove case for calling _process_mode().  In
+	the loop, use _get_prog_args() for simplification.
+	- main_parse_args(): Make --<mode>-viewer equivalent to
+	--<mode>-viewer-tty to make _process_mode() unnecessary.
+	- $_VIEWER_BACKGROUND: Start with `no'.
+
+	### Extend the documentation
+
+	* groffer2.sh:
+	- Environment Variables: Add information on the naming of
+	variables in functions.
+	- $_ADDOPTS_POST, $_ADDOPTS_X: Remove these unused variables.
+	- apropos_setup(), apropos_setup (), base_name(), dir_name(),
+	echo1(), echo2(), func_check(), func_pop(), func_push(),
+	is_greater_than(), list_append(), list_from_split(),
+	_manpath_add_sys() of manpath_add_lang_sys(), rm_tree(),
+	special_filespec(), special_setup(), tmp_create(), to_tmp_line(),
+	usage(), version(), where_is_prog(), main_set_mode():
+	Fix and extend the description.  Many other function descriptions
+	were just fixed without being mentioned.
+	- landmark 7: man_*(): Add information on the search of `man'
+	pages.
+
+	* groffer.man:
+	- GNU `man' option overview: Add --location, --no-location, and
+	--where.
+	- GNU `man' options: Add the GNU `man' long options that are
+	accepted by `groffer', but just ignored.
+	- MAN PAGE SEARCHING: Correct and extend this section.
+
+	* TODO:
+	- Remove entry on function headers.
+	- Remove entry on GNU `man' options.
+	- Remove entry on search algorithm for `man' pages.
+
+	### Other fixes
+
+	* groffer2.sh:
+	- man_get(): On `man' page search with given name and section
+	handle also files with extension when no files without extension
+	are found.
+
+2006-09-11  Bernd Warken <groff-bernd.warken-72@web.de>
+	________________________________________________________________
+	* release of groffer 0.9.25
+
+	### Version information
+
+	* groffer2.sh:
+	- version(): Add groffer to the version information; replace the
+	call of `groff --version'.
+
+	### Configuration Files
+
+	* groffer.sh: Fix the configuration handling by removing all
+	quotes.  Arguments are ended by the end of the line.
+
+	* groffer.man: Fix the section on the configuration files.
+
+	### Options
+
+	* groffer2.sh:
+	- $_OPTS_GROFF_SHORT_NA: Add `-k' as new groff option.
+	- main_pars_args(): Add X options `--ft', `--bordercolor',
+	`--borderwidth'.
+	- usage(): Add `--debug-filenames'.  Remove `*-viewer-tty'.
+	Correct first line after call of version().
+	- main_parse_MANOPT(): Fix `-h', `-t', and `-u' as options without
+	argument.
+
+	* groffer.man:
+	- Add documentation to `--fn', `--ft', `--bordercolor',
+	`--borderwidth'.
+	- Remove the `--*-viewer-tty' options.  These options are still
+	supported by the groffer program, but they aren't needed any
+	more.
+
+	### soelim: Allow manpath and compressed files in .so requests, as
+	### man does.
+
+	* groffer2.sh:
+	- $_FILESPEC_IS_MAN: New variable for storing if a filespec is for
+	searching a man page.
+	- to_tmp(): Rewrite. For existing file as filespec argument, add
+	call of `soelim' with the corresponding `-I dir' before the call
+	of `grog'.  For man paged, uncompress and store the files from .so
+	requests; replace the requests with the stored file names.
+	- _do_man_so() of to_tmp(): New function to handle the file of a
+	.so request.
+	- man_get(): For man pages without extension, add special search
+	strategy.
+
+	* README: Add the .so handling to the Compatiblity section.
+
+	### Print file names debug
+
+	* groffer2.sh:
+	- $_OPT_LOCATION: Replace this variable by
+	$_DEBUG_PRINT_FILENAMES.
+	- register_file(): Move file name printing and call to basename to
+	register_title().
+	- _do_man_so() of to_tmp(): Add file name printing for man pages.
+
+	### modes
+
+	* groffer2.sh:
+	- $_DEFAULT_MODES: New set of default modes in the sequence 'pdf',
+	'html', 'ps', 'x', 'dvi', and 'tty'.  That is done because the `x'
+	mode viewers `gxditview' and `xditview' are very bad programs.
+	- _make_pdf() of main_display(): If pdf format can not be
+	generated use Postscript mode (ps) instead for display.
+	- $_PDF_DID_NOT_WORK, $_PDF_HAS_PS2PDF, $_PDF_HAS_GS: New
+	variables for pdf mode to avoid several runs.
+	- $_VIEWER_TTY_TTY, $_VIEWER_TTY_X: Add these variables for the
+	viewers in tty mode.
+	- main_display(): Rewrite tty mode by using where_is_prog() to add
+	options to `less' from the command line.
+
+	* groffer.man:
+	- Add this information.
+	- Adjust the viewers in `SEE ALSO'.
+
+	### Check viewer option for programs running in X Window
+
+	* groffer2.sh:
+	- _check_X_prog() of main_set_mode(): New function for checking if
+	a program of a command line argument is in the list for X for this
+	mode.
+	- _get_first_prog() of main_set_mode(): Use where_is_prog();
+	change the output to the same 3-element list as _check_X_prog().
+	- _obj_set_vars() of main_set_mode(): New function for setting
+	some variables in several modes.  Argument is the 3-element list
+	from _check_X_prog() or _get_first_prog().
+	- _process_mode() of main_set_mode(): Remove part with
+	list_has_not_prog().  This is better done by _check_X_prog().
+	- main_set_mode(): Use _check_X_prog() in different modes.
+	Correct several modes.  Add reset of $_VIEWER_BACKGROUND at the
+	beginning of the loop of default modes.
+
+	### Allow man pages with space characters
+
+	* groffer2.sh:
+	- man_is_man(): Fix grep calls.
+	- list_from_file(): New function that reads the lines of a file as
+	list elements.
+	- man_get(): Fix `case' applications by double-quoting all
+	variables.  Use list_from_file() instead of setting with `cat'.
+	Add further tests.
+	- _do_man_so() of to_tmp(): Use list_from_file() instead of
+	setting with `cat'.
+
+	### Allow program names with space
+
+	* groffer2.sh:
+	- is_prog(), is_not_program(): Change to exactly one argument with
+	possible spaces and arguments.	Fix all calls.
+	- where_is_prog(): Change to exactly one argument.  Change
+	variable prefix to `wip'.  Rewrite it to support programs with
+	spaces and arguments.  Return a list with 3 elements: the
+	program's directory, the program name, and the given arguments.
+	- main_display(): Correct tty mode.
+
+	### Further fixes
+
+	* groffer2.sh:
+	- main_setup(): Fix func_check.
+	- clean_up(): Add variable to avoid several prints.
+	- where_is_prog(): Remove possible arguments from program
+	argument.
+	- obj_from_output(): As return value take the return value of the
+	called function.
+	- is_not_empty(): Rename of is_non_emtpy().
+	- $_VIEWER_BACKGROUND: Rename $_VIEWER_TERMINAL and reverse its
+	values.
+	- list_has_prog(), list_has_not_prog(): Remove these functions,
+	they are no longer needed.
+
+	* groffer.man:
+	- Add `--print' in OPTION OVERVIEW.
+	- Correct many entries with the non-breaking `\%' construct.
+
+2006-07-28  Bernd Warken <groff-bernd.warken-72@web.de>
+	________________________________________________________________
+	* release of groffer 0.9.24
+
+	### Extent long option abbreviation to abbreviations before each `-'.
+
+	* groffer2.sh:
+	- list_from_cmdline_with_minus(): New function, the same as
+	list_from_cmdline() with multiple abbreviations around `-'.
+	- _search_abbrev(): Subfunction of list_from_cmdline_with_minus().
+	- main_parse_args(): Use list_from_cmdline_with_minus() for
+	getting the double abbreviation, but keep main_parse_MANOPT()
+	to list_from_cmdline() for simple abbreviation of long options.
+	- For the debug test at the beginning, add the double abbreviation
+	functionality.
+
+	* README_SH, groffer.man: Document the multiple set of
+	abbreviations by `-'.
+
+	### Fix handling of `--apropos*' and `--whatis'
+
+	* groffer2.sh:
+	- apropos_filespec(): Fix handling of `/' and `.' in sed; add `\&'
+	at the beginning of each non-macro groff line in sed.
+	- main_parse_args(): Set $_MAN_OPT to `yes' if --whatis is called.
+	- main_do_fileargs(): Fix dealing with `apropos' for several
+	cases.
+	- apropos_*(), special_*(), whatis_*(): Add two different return
+	values.
+	- $_SPECIAL_SETUP: New variable to test whether apropos_setup() or
+	whatis_header() had been run.
+	- Add language locale to --whatis, the `whatis' program does not
+	support this.
+
+	### Handle several macro packages
+
+	* groffer2.sh:
+	- $_MACROS: New variable to store the actual macro package.
+	- $_MACRO_PACKAGES: New variable for the full macro packages of
+	groff (man, mdoc, me, mm, mom, ms).
+	- to_tmp(): Add test for different macro packages.  Ignore files
+	with a different one.
+	- main_do_fileargs(): Add different macro check before doing man
+	pages.
+
+	### Rewrite the man page search
+
+	* groffer2.sh:
+	- $_MAN_SEC_CHARS, $_MAN_SEC_LIST: New variables from $_MAN_SEC.
+	Add these to man_setup().
+	- man_get(): New function that finally gets the man page or man
+	pages for a filespec.  Avoid double files.
+	- man_is_man(): New function that checks whether a name goes as
+	man page.
+	- manpath_add_lang_sys(): Fix handling of language addition for
+	short language names.
+	- main_parse_args(): Move handling of `-' to main_do_fileargs().
+	- do_filearg(), man_do_filespec(), man_register_file(),
+	man_search_section(): Remove these functions.
+	- main_do_fileargs(): Rewrite this function together with
+	the removed functions.
+	- list_uniq(): New function to remove the multiple elements from a
+	list.
+
+	### Version handling.
+
+	* version.sh: New file for $_PROGRAM_VERSION, $_LAST_UPDATE, and
+	$_GROFF_VERSION_PRESET.
+
+	* groffer.sh:
+	- Add running of version.sh with `.'.
+	- Remove $_PROGRAM_VERSION and $_LAST_UPDATE.
+	- Run groffer2.sh with `.' instead of `exec'.  This allows to have
+	groffer2.sh without executive access permission.
+	- Determine $_BEFORE_MAKE by @VERSION@, use this variable on more
+	places.
+
+	* groffer2.sh:
+	- Remove executive access permission.
+	- version(): Write a version information without calling groff.
+
+	* Makefile.sub:
+	- Add version.sh.  Use $(INSTALL_DATA) instead of
+	$(INSTALL_SCRIPT) for version.sh and groffer2.sh.
+	- Add $(DESTDIR) to some elements of `sed' call in `groffer:'.
+
+	### viewers for different modes
+
+	* groffer2.sh:
+	- $_VIEWER_HTML_X: Add `epiphany' as browser.
+	- $_VIEWER_PDF_X: Add `kpdf' and `evince' as pdf viewer for X.
+	Make `kpdf', `acroread', `evince', and `xpdf' the first automatic
+	pdf viewers for X because they support searching.  Add `gpdf'.
+	- $_VIEWER_PS_X: Add `kpdf' and `evince' as ps viewer for X; make
+	`kpdf' the first automatic ps viewer for X because it supports
+	searching even for Postscript.
+
+	### pdf mode
+
+	* groffer2.sh:
+	- _make_pdf() of main_display(): add `ps2pdf' as secondary
+	transformer.
+	- main_set_resources(): Allow setting of resolution for `xpdf'
+	only if option -z is not set for `xpdf'.
+
+	### Revise $_VIEWER_*
+
+	* groffer2.sh:
+	- $_VIEWER_<mode>_TTY: Add this variable to each mode even if it
+	is only empty.
+	- $_VIEWER_<mode>_X: Rename $_VIEWER_<mode> to this for each
+	mode.
+
+	### Other fixes
+
+	* groffer2.sh:
+	- is_empty_file(): New function.
+	- obj_from_output(): Quote arguments by building a list.
+	- path_list(): Output path list with unique elements.
+	- where_is_prog(): Rename where_is().  Handle all file names
+	having a slash somewhere instead of only those that start with a
+	slash.
+	- $_REG_TITLE_LIST: Replace $_REGISTERED_TITLE and make it a
+	list.
+	- $_OPT_TITLE: Make it a list with at most 1 element.
+	- Remove double quotes in case patterns.
+	- _func_test(): For the function test at the beginning, add this
+	function for output check with $() construct.
+	- usage(): Add --shell.
+	- $_VIEWER_HTML_X: Add `firefox' and `mosaic'.
+	- list_get(): Remove this unused function.
+	- Fix func_check() calls in all functions.
+
+	* groffer.sh: Adjust groff version to 19.3.
+
+	* README: Add information list of the source files.
+
+2006-02-26  Claudio Fontana  <claudio@gnu.org>
+
+        * Makefile.sub: Add DESTDIR to install and uninstall targets
+        to support staged installations.
+
+2005-09-14  Bernd Warken <groff-bernd.warken-72@web.de>
+	________________________________________________________________
+	* release of groffer 0.9.23
+
+	### Increase the speed for the search of man pages
+
+	Run `find' on all man directories and ask this with `grep' instead
+	of scanning through many `ls'.
+
+	* groffer2.sh:
+	- $_TMP_MAN: New variable with the name of the file that stores
+	the `find' of the man path.
+	- $_TMP_MANSPEC: New variable with the name of the file that
+	stores the man page file names for each filespec.
+	- man_setup(): Do the `find' of the man path with $_TMP_MAN.
+	- man_do_filespec(): Add creation of $_TMP_MANSPEC.
+	- man_search_section(): Rewrite it to use $_TMP_MANSPEC.
+
+	* TODO: The demand on the increase of speed for man pages is now
+	removed.
+
+	### Increase speed by enhancement of debug
+
+	* groffer.sh: $_BEFORE_MAKE: New variable that stores whether the
+	@...@ constructs are still available or already transformed by
+	`make'.
+
+	* groffer2.sh:
+	- $_DEBUG_FUNC_CHECK: New debug variable that regulates the check
+	calls at the beginning and end of most functions done by the
+	functions func_<name>().  By default, this is enabled before the
+	run of `make', and disabled after.  $_DEBUG_STACKS and
+	$_DEBUG_USER_WITH_STACK enable this variable automatically.
+	- --debug-func: New option for setting $_DEBUG_FUNC_CHECK.
+	- usage(), main_parse_args(): Add information for --debug-func.
+	- func_<name>(): Disable these functions if $_DEBUG_FUNC_CHECK is
+	not `yes'.
+
+	* groffer.man:
+	- Add information on --debug-func.
+	- Move the sections on options for development to the end of
+	option processing.
+
+	### Fixes of man page search
+
+	- man_search_section(): Repair it such that extensions do not
+	occur in the directory name.
+	- manpath_set_from_path(): Rewrite it.  Add `.../MAN/...'
+	subdirectories additionally to `.../man/...'.
+	- manpath_add_lang_sys(): Rewrite it to overwrite _MAN_PATH by
+	systems parameter if any.  Then _MAN_PATH is prepended by the
+	language part.
+	- _manpath_add_sys(): New subfunction of manpath_add_lang_sys() to
+	handle the systems part.
+	- man_search_section: Fix it to handle section names that have
+	more than one character (an extension).
+	- $_MAN_PATH: Now stores man path as a list.  This is done in
+	man_setup() and manpath_set_from_path(), and used in
+	manpath_add_lang_sys().
+	- $_MAN_SYS: Now stores man systems parameter as a list.  This is
+	done in man_setup() and used in manpath_add_lang_sys().
+	- $_MAN_SEC_DONE, $_MAN_SYS_DONE, $_MAN_LANG_DONE: Remove these
+	variables.
+
+	### Reorder the beginning of groffer2.sh
+
+	* groffer2.sh:
+	- func_<name>(): Move these functions to the functions in
+	alphabetical order.
+	- main_init(): Move "Test for compression" to this function.
+	- Move the "System Test" and function landmark() to the beginning
+	"Test of rudimentary shell functionality".  Change landmarks 1 and
+	2 to new positions.
+
+	### Fix the mode when not in X
+
+	* groffer2.sh:
+	- main_parse_args(): Accept modes even when not in X, hoping for a
+	program given by option.  Add $_OPT_VIEWER_<MODE>_TTY.  Remove
+	$_VIEWER_TERMINAL.
+	- main_set_mode(): Add a section to set $_VIEWER_TERMINAL and move
+	the value of $_OPT_VIEWER_<MODE>_TTY to $_OPT_VIEWER_<MODE>.  When
+	not in X and no terminal programs are set remove $_OPT_MODE.  All
+	unknown programs are treated as terminal programs.
+	- usage(): Comment out options --<mode>-viewer-tty.  They exist
+	and are handled by `groffer', but they are no longer documented.
+	- $_OPT_VIEWER_<MODE>_TTY: New variables for option
+	--<mode>-viewer-tty.
+	- $_DEFAULT_MODE, $_VIEWER_<MODE>: Change it from , separation to
+	a list.  Rewrite _get_first_prog() of main_set_mode() to get
+	around with this.
+
+	* groffer.man: Remove information on --<mode>-viewer-tty.
+
+	### Debug
+
+	* groffer2.sh:
+	- $_DEBUG_PRINT_FILENAMES: New variable for printing the file
+	names that are displayed by `groffer'.
+	- --debug-filenames: The corresponding option.  It is used in
+	man_register_file(), register_file(), and main_parse_args().
+
+	* groffer.man: Add information on --debug-filenames.
+
+	### Other changements
+
+	* groffer2.sh:
+	- is_greater_than(): New function.  Use it where suitable.
+	- lists_combine(): New function to combine several lists to a
+	single list.
+	- list_from_split(): Rewrite it to output a list with quoted
+	elements.
+	- list_has_prog(), list_has_not_prog(): New functions to check the
+	list on an element that starts with a given word.
+	- obj_from_output(): Use this function at many places instead of
+	`var="$(...)"'; this makes the usage of exit_test() unnecessary.
+	- path_clean(): Fix assignment.
+	- path_list(): Rename path_split().
+	- tmp_create(): Add check of temporary file.
+	- usage(): Fix.
+
+	* README_SH:
+	- Fix section `Error handling'.
+	- Add section `Speed'.
+
+2005-08-22  Bernd Warken <groff-bernd.warken-72@web.de>
+	________________________________________________________________
+	* release of groffer 0.9.22
+
+	### `--whatis'
+
+	Produce a `groff' output and allow wild cards on filespec
+	parameters for `--whatis'.
+
+	* groffer2.sh:
+	- $_FILESPEC_ARG: New variable for storing the actual filespec
+	parameter.
+	- main_do_fileargs(): Set $_FILESPEC_ARG and add
+	what_is_filespec().
+        - main_parse_args(): Add --all to --whatis.
+	- to_tmp_line(): New function to write the arguments to the
+	temorary cat file.
+	- whatis_filename(): Rename of what_is().  Construct a better
+	printout using $_FILESPEC_ARG.  Repair the sed sequneces.
+	- whatis_filespec(): New function to print the filespec once
+	during the `whatis' process.
+	- whatis_header(): New funtion for printing the header of the
+	`whatis' output.
+
+	* groffer.man: Revise the documentation of --whatis.
+
+	### `--apropos*'
+
+	Produce `groff' for `--apropos*'.  Allow `--sections' for
+	`--apropos', ignore it  with `--apropos-*'.
+
+	* groffer2.sh:
+	- --apropos*: Make these options without argument.
+	- $_APROPOS_PROG: New variable for the program that is is used for
+	`apropos'.
+	- $_APROPOS_SECTIONS: New variable to determine the sections that
+	are filtered out of `apropos' output depending on `--apropos-*'.
+	- apropos_filespec(): Handling of apropos at the filespec level.
+	- apropos_run(): Remove it.
+	- apropos_setup(): New function.
+	- main_set_mode(): Remove handling of $_OPT_APROPOS*.
+
+	* groffer.man:
+	- Revise the documentation of `--apropos*'.
+	- Split section 'options for GNU man' into two sections `options
+	for man pages' and `long options taken over from GNU man'.
+	- Move `--apropos*', `--whatis', `--man', and `--no-man' to
+	section `options for man pages'.
+
+	### special display (apropos and whatis)
+
+	* groffer2.sh:
+	- special_setup(): New function that chooses the setup between
+	apropos and whatis.
+	- special_filespec(): New function that does the output at the
+	filespec level for apropos or whatis.
+
+	### handle `--sections' for man page searching
+
+	* groffer2.sh:
+	- man_do_filespec(): Use $_OPT_SECTIONS of --sections instead of
+	$_MAN_AUTO_SEC if non-empty.  If a section was given on the
+	filespec parameter $_OPT_SECTIONS is ignored.  This differs from
+	`man' which always uses the restricted sections of --sections.
+	This function works for both normal man page search and whatis.
+	- apropos_filespec(): Use --sections for --apropos, but not for
+	--apropos-* because these provide already their own sections.
+
+	### wildcards in filespec arguments
+
+	* groffer2.sh: Wildcards are now accepted.  In `--apropos*' and
+	`--whatis' they are interpreted as wildcard search elements; but
+	in normal display they are only handled as their own character.
+
+	### development; new option
+
+	* groffer2.sh:
+	- --print: New option that prints just its argument for parameter
+	check.
+	- usage(): Add new option.
+	- $_OPT_DO_NOTHING: New variable for do_nothing().  Handle it at
+	the end of main_parse_Args().
+
+	* groffer.man: Add information on --print.
+
+	### safe exit
+
+	* groffer2.sh:
+	- error(): Always exit with $_ERROR.
+	- exit_test(): New function to exit when first exit was hidden by
+	().  Call it after each $().
+
+	### automatic shell determination
+
+	* groffer.sh:
+	- If no option --shell is given perform a test of several shells
+	to automatically start some shell for groffer2.sh.  `ksh' is used
+	first because it can be safely terminated by Ctrl-C.
+	- This can be cancelled by providing --shell=''.
+	- Add test on `sed' program.
+
+	* groffer.man: Revise information on --shell.
+
+	### trap
+
+	* groffer2.sh:
+	- trap_set(): Remove argument.  Instead of $_ALL_EXIT use only
+	signal 0.
+	- trap_unset(): Rename trap_clean().  Instead of $_ALL_EXIT use
+	only signal 0.
+	- $_ALL_EXIT: Remove this variable.
+	- Replace all direct `trap' calls by trap_set().
+
+	* README_SH: New section `Bugs' on `trap'..
+
+	### user errors, error output without function stack
+
+	* groffer2.sh:
+	- error_user(): New function for user errors.
+	- error(): Remove call of clean_up() because the trap will do it
+	with the exit.  Remove the `kill' commands.  Create a temporary
+	file `.error' that can be tested by exit_test() for a better exit
+	test (especially for shell `ksh').
+	- $_DEBUG_USER_WITH_STACK: New variable to enable function stack
+	output in error_user().
+	- list_from_cmdline(), list_single_from_abbrev(), main_set_mode():
+	Use error_user().
+
+	### test modes on X and tty
+
+	* groffer2,sh:
+	- is_X(), is_not_X(): New functions for checking on X Window.
+	- $_VIEWER_HTML_TTY, $_VIEWER_HTML_X: New variables that split
+	$_VIEWER_HTML.  Add `galeon'.
+	- main_parse_args(): Allow mode change for graphical modes only
+	when in X Window.
+	- _do_display() of main_display(): Create a special run for
+	viewers that run on the terminal; `lynx' is the only one so far.
+
+	### add $GROFFER_MODE to command line
+
+	* groffer.sh:
+	- After the handling of the configuration files integrate
+	$GROFFER_OPT to the command line.
+	- This makes a `set' in the shell determination unnecessary.
+
+	* groffer2.sh:
+	- The debug test gets simpler because quotes are vanished without
+	$GROFFER_OPT.
+	- main_parse_MANOPT(): Prepend $mpm_list to the command line.
+	- main_parse_args(): `set' is unnecessary.
+
+	### debug; new options
+
+	* groffer2.sh:
+	- --debug-all, --debug-lm, --debug-params, --debug-shell,
+	--debug-stacks, --debug-tmpdir, --debug-user: New options.
+	- --debug: Enable all debug variables except $_DEBUG_STACKS and
+	$_DEBUG_LM.  By the new options the smallest abbreviation is now
+	`--debug'.
+	- $_DEBUG_STACKS: Rename $_DEBUG.
+	- $_DEBUG_PRINT_TMPDIR: New debug variable for printing the name
+	of the temporary directory in main_init().
+	- $_OPT_DEBUG: Remove this variable because debug is handled at
+	the early part of the script.
+	- clean_up(): Enlarge $_DEBUG_KEEP_FILES to not deleting the
+	temporary directory.
+	- usage(): Move all development options on a section of its own.
+	- Move the test of rudimentary shell functionality at the
+	beginning of the script.  Add test on `sed'.
+	- Follow this by the debug section.  The determination of all
+	--debug* options can be done without a function.
+
+	* groffer.man: Revise information on --debug and add new options.
+
+	### variables
+
+	* groffer.sh:
+	- $_ERROR: Move the definition of this variable here.
+	- $_GROFF_VERSION: New variable, is set over @...@ construct.
+	- $_OUTPUT_FILE_NAME: Move this variable to groffer2.sh.
+
+	* groffer2.sh:
+	- $_MAN_AUTO_SEC_LIST: Rename $_MAN_AUTO_SEC because it represents
+	a list.
+	- $_MAN_AUTO_SEC_CHARS: New read-only variable for storing
+	$_MAN_AUTO_SEC_LIST in [] construct.  Use it in man_do_filespec()
+	and whatis_filename().
+	- $_SPACE_CASE: New read-only variable with [] on space characters
+	with \ for `case' patterns.  Use it in several functions.
+	- $_SPACE_SED: New read-only variable with [] on space characters
+	for `sed'.  Use it in several functions.
+
+	### options and display
+
+	* groffer2.sh:
+	- list_from_cmdline(): Add test whether the same abbreviation is
+	part of long options with and without arguments.  Give handling of
+	`=' a `case' pattern of its own.
+	- main_display(): Remove unnecessary calls of `clean_up' in order
+	to use `mozilla' without problems.  In _do_display(): Fix -X by
+	providing a different process when $_DISPLAY_PROG is empty.
+	- main_set_mode(): Accept options for viewers as is, without check
+	for program.  Add test whether no program is given for a mode.
+	This avoids unnecessary empty $_DISPLAY_PROG in main_display().
+
+	### viewer programs that run on the terminal (tty); new options
+
+	* groffer2.sh:
+	- $_VIEWER_TERMINAL: New variable that stores whether a viewer was
+	supposed to run on tty.
+	- --dvi-viewer-tty, --html-viewer-tty, --pdf-viewer-tty,
+	--ps-viewer-tty, --tty-viewer-tty, --X-viewer-tty, --x-viewer-tty,
+	--www-viewer-tty: New options for viewers that run on a terminal.
+	- main_parse_args(), _do_display() of main_display(): Use the new
+	options and the new variable.
+	- usage(): Add the new options.
+
+	* groffer.man: Add information on options --*-viewer-tty.
+
+	### other fixes
+
+	* groffer2.sh:
+	- _do_display() of main_display(): Bear errors of `groff' run.
+	- is_not_file: Fix to have exactly one argument.
+	- is_not_prog(): Handle no arguments.
+	- list_has_not(): Fix.
+	- main_do_fileargs(): Remove $mdfa_exitcode.
+	- register_title(): Limit title to 4 elements.
+	- version(): Print the version information to standard output just
+	like `groff' does.
+	- --no-special: New option to disable former calls of `--all',
+	`--apropos*', and `whatis.
+	- --title: Make it an option with argument.
+
+2005-08-07  Keith Marshall  <keith.d.marshall@ntlworld.com>
+
+	* contrib/groffer/Makefile.sub (install): Reference groffer2.sh
+	as $(srcdir)/groffer2.sh, so it will install when building in a
+	different directory from the source.
+
+2005-08-02  Bernd Warken <groff-bernd.warken-72@web.de>
+	________________________________________________________________
+	* 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 that	it 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.
+
+2005-07-30  Bernd Warken <groff-bernd.warken-72@web.de>
+	________________________________________________________________
+	* release of groffer 0.9.20
+
+	### Split groffer.sh into two files groffer.sh and groffer2.sh.
+
+	* groffer.sh:
+	- Remove the second part of this script.  It is now in
+	groffer2.sh.
+	- $_GROFFER2_SH: New variable to point to the installed position
+	of `groffer2.sh'.  This position is presented using @libdir@.
+
+	* groffer2.sh: New script containing the second part of
+	groffer.sh. This script will be installed in the groffer library
+	directory @libdir@/groff/groffer, this might be
+	/usr/local/lib/groff/groffer/groffer2.sh for example.
+
+	* Makefile.sub:
+	- `groffer': Add replacement of @libdir@.
+	- `install_data': Add the installation of the groffer library
+	directory and groffer2.sh.
+	- `uninstall_sub': Delete the installed `groffer2.sh' and the
+	groffer library directory.
+
+	* README_SH:
+	- Remove the function list.
+	- Add argument options to the list of used commands.
+	- Documentation of the splitting of the script.
+	- Document the possible abbreviation of options.
+
+2005-07-07  Bernd Warken <groff-bernd.warken-72@web.de>
+	________________________________________________________________
+	* release of groffer 0.9.19
+
+	* groffer.sh: extensions
+	- `mode x': Mode for the equivalent options `--x', `--mode x',
+	`--X' `--mode X', and the default mode.  The default assumes a
+	resolution of 75 dpi.  The default device for a resolution of 75
+	dpi is `X75-12', the default device for a resolution of 100 dpi is
+	`X100'.  The default geometry for the resolution of 100 dpi is set
+	to the width 800 dpi.
+	- `mode X': New mode for option -X only.
+	- `-V': Extent the `groff' output of -V by `groffer' specific
+	information (in main_display()).
+	- register_file(): Replace title `-' by `stdin'.
+	- $_DEBUG_KEEP_FILES: If set to `yes' the files in the temporary
+	directory are not deleted before the end trap.
+
+	* groffer.sh: get `zsh' to work as well
+	- tmp_create(): Use `: >file' for generating an empty file.
+	- rmdir: Replace `rmdir' by `rm -f -r'.
+	- eval: Add `eval' to many commands with variable arguments.
+
+	* groffer.sh: repair `debug'
+	- Print all debug output to stderr.
+	- $_FUNC_STACK: Built function call stack even when $_DEBUG is not
+	set.  Now the arguments are not added.
+	- $_DEBUG: If set to `yes' print 3 call stack events: the function
+	that is added with its arguments is printed with `+++ '
+	(func_push()); the call stack after the addition is printed with
+	`>>> ' (func_push()); the call stack after the removing is printed
+	with `<<< ' (func_pop()).
+	- error(): Always print the function call stack on errors.
+
+	* groffer.sh: Corrections
+	- $_groffer_run: Rename to $_GROFFER_RUN.
+	- $unset: Rename to $_UNSET.
+	- Repair test of `unset'.
+	- Repair test for `--shell'.  The script is now rerun under the
+	shell specified in the option argument.  This can increase the
+	speed.
+
+	* README_SH: `zsh' now works.
+
+	* groffer.man:
+	- Reformulate the information for the `groffer' specific details
+	of option `-V'.
+	- Add information on the debug process.
+	- Add information on the default devices in `x mode'.
+	- Minor corrections.
+
+2005-07-01  Bernd Warken <groff-bernd.warken-72@web.de>
+	________________________________________________________________
+	* 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 choosing 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@'.
+
+2005-06-23  Bernd Warken <groff-bernd.warken-72@web.de>
+	________________________________________________________________
+	* release of groffer 0.9.17
+
+	* groffer.sh: get rid of `local' in functions (it is not POSIX)
+	- Replace local variables by variable names with a special prefix
+	that is an abbreviation of the corresponding function name (quasi-
+	local variables).
+	- Unset the quasi-local function variables before returning.
+	- _t_e_s_t_f_u_n_c_(): Remove tests for local and global
+	variables.
+	- Add quasi-local variables for saving the content of
+	single-character variables.
+	- Remove some unused local and global variables.
+	- Several variables were forgotten to make local.  They are now
+	made quasi-local.
+
+	* groffer.sh: other corrections
+	- $return_var: New function (after `eval') for an arbitrary
+	return value.
+	- obj*(): Add return modes.
+	- Rewrite tests for `true' and `false'.
+	- Add function names to error calls where it was forgotten.
+	- `for': Replace `for x in "$@"' by `for x'.
+	- `set': Replace `set -- ...' by `set x ...; shift'.
+	- `sed': Replace `\|.*|s|...|...|' by `s|...|...|'.
+
+	* README_SH:
+	- Add information on the removing of `local'.
+	- New section for non-POSIX shell restrictions.
+
+2005-06-20 Keith Marshall
+
+	* README-SH: Information of `Portable shells' in info autoconf.
+
+2005-06-19  Bernd Warken <groff-bernd.warken-72@web.de>
+	________________________________________________________________
+	* release of groffer 0.9.16
+
+	* groffer.sh: Place each `then', `else', and `do' on a line of its
+	own because some shells do not support the mixture mode.
+
+	* groffer.man: Add section `BUGS'.
+
+	* README_SH:
+	- Add compatibility information.
+	- Correct documentation for function arguments.
+
+2005-06-18  Keith Marshall
+
+	* groffer.sh: $_NULL_DEV: Replace /dev/null by $_NULL_DEV which is
+	either /dev/null or NUL if /dev/null does not exist.
+
+2005-06-17  Zvezdan Petkovic
+
+	* Makefile.sub: $(RM): Define it to `rm -f' because not all `make'
+	programs have it predefined.
+
+2005-06-16  Bernd Warken <groff-bernd.warken-72@web.de>
+	________________________________________________________________
+	* release of groffer 0.9.15
+
+	* Makefile.sub:
+	- Use `$(RM)'.
+	- Use `sed -f $(SH_DEPS_SED_SCRIPT)'.
+
+2005-05-20  Bernd Warken <groff-bernd.warken-72@web.de>
+	________________________________________________________________
+	* release of groffer 0.9.14
+
+	* groffer.man: correction of non-hyphenation
+
+2005-05-17  Bernd Warken <groff-bernd.warken-72@web.de>
+	________________________________________________________________
+	* release of groffer 0.9.13
+
+	* groffer.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
+
+2005-05-14  Keith Marshall
+
+	* groffer.sh:
+	- first line: Add space to `#! /bin/sh'.
+
+2004-11-15  Bernd Warken <groff-bernd.warken-72@web.de>
+	________________________________________________________________
+	* release of groffer 0.9.12
+
+	* groffer.sh:
+	- main_init(): Rewriting of the creation of the temporary
+	directory to ensure that it cannot be made writable apart from the
+	user.  If the directory already exists and cannot be removed then
+	append `X' to the directory name.
+	- is_non_empty_file(): fix it to use POSIX `test -s'.
+	- is_existing(): new function.
+	- POSIX `rm -f -r': use this in `clean_up()' and `main_init()'.
+	- `--macro-file': remove this unused long option.
+	- `-V', `--source', `--device': move these from groff options
+	to groffer options.
+	- `$_TMP_DIR_SUB': remove this unused variable.
+
+2004-06-15  Bernd Warken <groff-bernd.warken-72@web.de>
+	________________________________________________________________
+	* release of groffer 0.9.11
+
+	* groffer.sh:
+	- To the search of the `--apropos-*' options, add man pages with a
+	subsection in their apropos output.
+
+2004-06-02  Bernd Warken <groff-bernd.warken-72@web.de>
+	________________________________________________________________
+	* 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.
+
+2004-05-29  Bernd Warken <groff-bernd.warken-72@web.de>
+	________________________________________________________________
+	* release of groffer 0.9.9
+
+	* groffer.sh:
+	Fix first run section to allow the starting shell to go on if
+	`ash' is not available.
+
+	* groffer.man:
+	Remove unnecessary information on groffer version.
+
+2004-05-12  Bernd Warken <groff-bernd.warken-72@web.de>
+	________________________________________________________________
+	* release of groffer 0.9.8
+
+	* groffer.sh:
+	Fix problems of `test' by adding subs to arguments.
+
+	* groffer.man:
+	Write the file license as macros that are called in sections
+	AUTHOR and COPYING.
+
+	* .cvsignore:
+	Restore this file.
+
+2004-04-30  Bernd Warken <groff-bernd.warken-72@web.de>
+	________________________________________________________________
+	* release of groffer 0.9.7
+
+	* groffer.sh:
+	- obj(), obj_data(), obj_from_output(), obj_set(): New object
+	oriented functions to minimize complicated `eval' commands.
+	- list_*(): Corrections.
+	- usage(): Streamlining.
+
+	* groffer.man, README_SH:
+	Corrections.
+
+2004-04-27  Bernd Warken <groff-bernd.warken-72@web.de>
+	________________________________________________________________
+	* release of groffer 0.9.6
+
+	This version replaces the license of all files except ChangeLog of
+	the groffer source to the GNU General Public License (GPL) of the
+	version described in files COPYING and LICENSE in the groff top
+	source directory.
+
+	* groffer.man:
+	Changement from the GNU Free Documentation License (FDL) to
+	the GNU General Public License (GPL).
+
+	* README, README_SH, TODO:
+	Add license GNU General Public License (GPL).
+
+	* Makefile.sub, groffer.sh:
+	Keep the GNU General Public License (GPL), but refer to the
+	COPYING and LICENSE files.
+
+	* ChangeLog: Add a license in the style of Emacs ChangeLog file,
+	which is weaker than the GPL, but has its flavor.
+
+2004-04-24  Bernd Warken <groff-bernd.warken-72@web.de>
+	________________________________________________________________
+	* release of groffer 0.9.5
+
+	This version is a rewrite of groffer in many parts, but it is kept
+	in the old single script style.
+
+	Overview of new options:
+	--text, --mode text, --tty-viewer,
+	--X, --mode X, --X-viewer, --html, --mode html, --html-view,
+	--apropos-data, --apropos-devel, --apropos-progs
+
+	New file:
+	<groffer-source>/README_SH
+
+
+	******* Extension of the `apropos' handling
+
+        The output of man's `apropos' has grown immensely meanwhile, so it
+	has become inefficient.  Now `groffer' provides new options to get
+	the a selected information from this output.
+
+	* groffer.sh:
+        `--apropos-progs': new option for displaying only information
+        on programs (man page sections 1, 6, and 8)
+        `--apropos-data': new option for displaying only information
+        on documented data (man page sections 4, 5 and 7)
+        `--apropos-devel': new option for displaying only information
+        on development documentation (man page sections 2, 3 and 9)
+        `--apropos': still displays just the output of man's `apropos'
+	program.
+	- Specify all of these options as a single argument option; that
+	makes groffer's `--apropos' option slightly different because
+	the corresponding `man' option does not have arguments,	but takes
+	all file arguments as apropos targets.  So just ignore the `man'
+	options `-k' and `--apropos' in the parsing of $MANOPT.
+	- Exit after processing one `apropos' call.
+
+
+	******* Quasi object oriented function arguments
+
+	An object is the name of an environment variable.  The value of
+	this variable contains the object's content.  This allows to
+	specify function arguments and the calling syntax in a simpler way
+	by letting the first argument be a variable name, usable for input
+	or output.
+
+	Such an object type is `list', the string value of a shell
+	variable arranged in space-separated single-quoted elements, such
+	as $GROFFER_OPT internally.
+
+	* groffer.sh:
+	- Remove list_from_args(), list_element_from_arg()
+	list_from_lists(), list_length(), and list_prepend().
+	They can be replaced by list_append().
+	- All list*() functions are rearranged such that the first
+	argument is a list object, the name of a variable.
+
+
+	******* Simplification of configuration files
+
+	The new syntax of the groffer configuration files is
+	- all lines starting with a `-' character are interpreted as
+	command line options for all calls of groffer; they are collected
+	and prepended to the actual value of $GROFFER_OPT; optional
+	spaces at the beginning.of the line are omitted.
+	- all other lines are interpreted as a shell command and executed
+	in the current shell of the groffer call.
+
+	Precedence:
+	- The command line and the external environment variables such as
+	$GROFFER_OPT of the groffer call have the highest precedence.
+	- This is overwritten by the configuration file in the user's home
+	directory.
+	- The system configuration file in /etc has the lowest
+	precedence.
+
+	* groffer.sh:
+	The configuration files are now called after the determination of
+	the temporary files in main_init().
+
+
+	******* Script file name
+
+	The file name of the script is needed for the several calls during
+	the search for the optimal shell.
+
+	* groffer.sh:
+	- $_GROFFER_SH: replace $_this by $_GROFFER_SH and use $0 for
+	determining the file name of the script for the following calls,
+	instead of the cumbersome @BINDIR@ construction.
+	- Force the script to be called as an executable file, so $0 must
+	contain the program name.
+
+
+	******* Improved temporary file names
+
+	Just like groff, groffer mixes all file parameters into a single
+	output file.  Its name is now constructed as a comma-separated
+	list built from the file name arguments without a leading comma.
+	So a leading comma can be used for the internal temporary file
+	names.
+
+	* groffer.sh:
+	- $_OUTPUT_FILE_NAME: new global variable as basis for the output
+	file name; it is set in main_set_resources().
+        - tmp_create(): use `,name' for temporary files different from
+	output file because the output file name does not start with a
+	comma.  `$$' is not needed anymore.
+	- main_display(): simplification of $_modefile in _do_display()
+	and single display modes.
+	- Add extension `.html' to output file name in html mode.
+	- base_name(): correction for strange positions of `/'.
+
+
+	******* Mode fixes
+
+	* groffer.sh:
+	- Set the main default mode to `x' with groff's	X Window viewer
+	`gxditview'.
+	- Allow 'x' and 'X' in `--mode' for the X Window mode; the same
+	for `--x' and `X', `--x-viewer' and `--X-viewer'.
+	- Make groff's `-X' equivalent to `mode X'.
+	- Fix `--auto', `--mode auto',  and `--default-modes'.
+	- `html' mode: new mode equivalent to `www', add `konqueror' and
+	`lynx' as viewers.
+	- `pdf' mode: fix zoom options for pdf-viewer `xpdf' in
+	main_set_resources(); in main_display() fix the display structure.
+	- Set default X Window resolution to 75dpi.  This is not optimal,
+	but with a higher value the options and resources for some viewers
+	must be optimized.
+	`--text' and `--mode text': new option for text output without a
+	pager.
+	- `--tty-viewer': new option equivalent to `--pager'.
+	- Correct the pagers for `tty' mode.
+	- Fix `groff' mode in main_set_resources() and main_display().
+	- Harmonize `--mode arg' with the equivalent options `--arg'.
+
+
+	******* Fixes for command line options
+
+	* groffer.sh:
+	- list_from_cmdline(): fix the parsing of options with arguments.
+	- Rename $_OPT_TTY_DEVICE to $_OPT_TEXT_DEVICE.
+	- $_OPTS_X_*: new variables for the inhereted X Window variables.
+	- Improve the distribution of the command line options into
+	$_OPTS_GROFFER_*, $_OPTS_GROFF_*, $_OPTS_X_*, and $_OPTS_MAN_*.
+	- $_OPTS_MANOPT_*: new variables for the parsing of $MANOPT.
+	- Correct $_OPTS_CMDLINE_*.
+	- Remove some unused $_OPTS_*.
+	- `--iconic': new option from `-iconic' of the X Window toolkit.
+	- Correct `--rv' to an option without argument.
+	- Minor fixes of other  X Window toolkit options.
+
+
+	******* Other fixes
+
+	* groffer.sh:
+	- is_prog(): allow 0 arguments.
+	- is_not_writable(): new function.
+	- is_*(): fix trailing return codes.
+        - Replace most `test' calls by is_*() functions.
+	- man_setup(): due to bugs in `manpath', prefer
+	manpath_set_from_path() for the determination of the man page path.
+	- man_search_section(): correction of some `for' loops.
+	- Remove export of external non-groffer variables.
+
+
+	******* Documentation
+
+	* groffer.man:
+	- Reorder the option details according to the option origin as
+	groffer, groff, X, and man options.
+	- Add the programming changes information mentioned above.
+	- Support man pages with a dot in their name
+
+	* README_SH: new file
+	Move large parts of the documentation in `groffer.sh' into this
+	file.
+
+	* groffer.sh: usage():
+	- Change the output for `--help' to standard output.
+	- Restructure the information for this help output.
+
+
+	******* Removement of the author's email address
+
+	Because of the extreme spam attacks, the author removed all
+	occurencies of his email address in every file of the groffer
+	source.
+
+2003-01-22  Bernd Warken <groff-bernd.warken-72@web.de>
+	________________________________________________________________
+	* release of groffer 0.9.4
+
+	* groffer.sh: corrections for some restrictive shells
+	- Possible exit codes in actual `ash' are between 0 and 63.  To
+	handle even deeper restrictions, use 7 as maximal code instead
+	of 255 as replacement for error -1.
+	- Remove variables $_BAD2 and $_BAD3.
+	- Replace `trap' argument `EXIT' by 0 and write new fuctions
+	`trap_clean' and `trap_set' to handle the restrictions of `trap'
+	for some shells.
+	- Correct wrong $MANPATH to $_MAN_PATH in function
+	`man_do_filespec'.
+	- Test existence of directory before deleting it in the
+	`clean_up' definitions.
+	- Correct help output in `usage' (called by `--help').
+
+	* TODO:
+	Remove mention of `shoop' and `apropos'.
+
+2002-10-21  Bernd Warken <groff-bernd.warken-72@web.de>
+	________________________________________________________________
+	* release of groffer 0.9.3
+
+	* groffer.sh: new temporary subdirectory
+	- Generate temporary subdirectory for storing temporary files
+	with better names in future groffer versions (name:
+	"groffer$$" in usual temporary directory).
+	- Use `umask 000' for temporary files to allow cleaning up
+	for everyone after a system break.
+	- Change both clean_up() functions (for normal shell and
+	for main_display() subshell) to handle the new subdirectory.
+	- clean_up_secondary() and $_TMP_PREFIX are unnecessary now, so
+	they were removed.
+
+	* Makefile.sub: `sed' commands for "groffer:"
+	- Remove "@g@" entry (not used in "groffer.sh").
+	- Add global replace for "@BINDIR@" and "@VERSION@" for future
+	usage.
+
+	* TODO: think about...
+	- writing part of groffer in C/C++.
+	- handling several files with different macro packages.
+
+2002-10-17  Bernd Warken <groff-bernd.warken-72@web.de>
+	________________________________________________________________
+	* 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.
+
+2002-10-14  Bernd Warken <groff-bernd.warken-72@web.de>
+
+	* Makefile.sub:
+	add replacement "@BINDIR@" to "$(bindir)" for "groffer:"
+
+	* groffer.sh:
+	Define $_this as "@BINDIR@/${_PROGRAM_NAME}" to save the right
+	installation position of groffer for the special shell calling.
+
+	* groffer.man:
+	Remove double definition of filespec parameters.
+
+2002-10-13  Bernd Warken <groff-bernd.warken-72@web.de>
+	________________________________________________________________
+	* release of groffer 0.9.2
+
+	* groffer.sh: fixes
+	- Fix some 'sed' functions: two in func_stack_dump(), one in
+	  base_name(), add 'sed' command in list_from_cmdline().
+	- Finish main_parse_MANOPT() if $MANOPT is empty.
+	- Sort $_OPTS_GROFF_SHORT_NA like groff short options (but
+	  unchanged).
+	- Fix some comments.
+
+	* groffer.man: make it more readable (but no additions)
+	- A shortened section "SYNOPSIS" is followed by a simplified
+	  section "DESCRIPTION".
+	- The options from "SYNOPSIS" go to new section "OPTION
+	  OVERVIEW" with all groffer options in a single subsection.
+	- The details of all groffer options are described in section
+	  "GROFFER OPTIONS".
+	- New macro for file names ".File_name".
+	- "Option Parsing" is moved to section "COMPATIBILITY".
+	- Fix some "EXAMPLES".
+
+2002-09-30  Bernd Warken <groff-bernd.warken-72@web.de>
+	________________________________________________________________
+	* release of groffer 0.9.1
+
+	* TODO: remove done entries
+	- Remove request for different shells.
+	- Remove the 'sed' complaints.
+
+2002-07-15  Bernd Warken <groff-bernd.warken-72@web.de>
+
+	* groffer.sh: replace `sed' interface by direct `sed'
+	- This improves the performance of the shell programming parts
+	  and shortens the groffer script by about 5%.
+	- Remove functions: string_del_append(), string_del_leading(),
+	  string_del_trailing(), string_flatten(), string_get_before(),
+	  string_get_leading(), string_replace_all(), string_sed_s(),
+	  and their auxiliary functions.
+	- Replace all calls of these functions by direct `sed' commands.
+	- Define variables for special characters to ease `sed' calls.
+	- Remove `$APPEND'.
+	- Restrict list_from_string() to single character separators.
+	- Correct list_check() and base_name().
+	- Add comments to all calls of `sed'.
+
+	* groffer.sh: add run-time support for several shells
+	- New option `--shell': stop execution and rerun groffer under
+	  the shell specified in the argument of `--shell'.
+	- If no shell was specified at run-time, `ash' is tried first;
+	  if `ash' is not available continue with the shell with which
+	  groffer was called from the command line, or with the shell
+	  name in the first line of the script, actually `/bin/sh'.
+
+2002-07-12  Bernd Warken <groff-bernd.warken-72@web.de>
+	________________________________________________________________
+	* fixes for groffer 0.9.0
+
+	* groffer.sh: enhance version information
+	`groffer -v|--version' now print:
+	- groffer's version number and date
+	- the string `is part of '
+	- groff's version information (version number and copyright),
+	  but not groff's `called subprograms' information.
+
+	* groffer.sh: minor fixes
+	- Fix the argument parser to process argument `-' correctly.
+	- Some display programs have trouble with empty input; feed a
+	  line consisting of a single space character in this case for
+	  all display modes (not for source or groff modes).
+
+	* TODO:
+	fix entry `shoop' (not 'shopt').
+
+2002-06-28  Bernd Warken <groff-bernd.warken-72@web.de>
+	________________________________________________________________
+	* release of groffer 0.9.0
+
+	* groffer.sh: new mode `pdf'
+	- PDF (Portable Document Format):
+	  -> Transform groff `ps' output into pdf using `gs'.
+	  -> Pro: PDF viewers provide text searching (!).
+	  -> Con: the transformation is quite slow.
+	  -> Not suitable as an auto mode.
+	- New options `--pdf', `--pdf-viewer', `--mode pdf'.
+	- Standard pdf viewers `xpdf' and `acroread'.
+	- For `xpdf', choose zoom `z 3' for 100 dpi, `z 2' for 75 dpi.
+
+	* groffer.sh: support bzip2 decompression
+	- add test for `bzip2' with necessary options
+	- extend functions `catz()' and `save_stdin()'.
+
+	* TODO
+	remove entry on `bzip' decompression (done).
+
+	* groffer.man:
+	- Document new `pdf' features.
+	- Document new `bzip2' decompression.
+	- Fix documentation for `--auto-modes'.
+
+	* groffer.sh: minor fixes
+	- Improve device tests in `tty' and `dvi' modes.
+	- Internally, map mode `auto' to '' to facilitate tests.
+	- Fix auto mode sequence to: `ps,x,tty' as was intended.
+
+2002-06-25  Bernd Warken <groff-bernd.warken-72@web.de>
+
+	* groffer.sh:
+	Fix `source' mode.
+
+	* groffer.man:
+	Fix some indentations.
+
+2002-06-23  Bernd Warken <groff-bernd.warken-72@web.de>
+	________________________________________________________________
+	* release of groffer 0.8
+
+	* Makefile.sub: add copyright section
+
+	* groffer.man:
+	- Document the new options.
+	- Revise the documentation of the modes.
+	- Document the configuration files in new section `FILES'.
+	- Redesign section `EXAMPLES'.
+	- Remove documentation for `-W'.
+
+	* groffer.sh: new debugging features
+	- Disabled by default; enabled by environment variables.
+	- Add landmark() to catch typos with quotes.
+	- Add a function call stack for suitable functions; implemented
+	  as within the argument checker func_check().
+	- This implies the need to provide `return' with some clean-up
+	  facility; implemented as `eval "$_return_..."'.
+	- Add option `--debug' to enable debugging at run-time.
+	- Actually, the groffer script uses only shell builtins found
+	  in `ash' (a subset of POSIX) and POSIX `sed' as the only
+	  external shell utility.
+
+	* groffer.sh: customization of viewers
+	- In `groff' mode, the groffer viewing facilities are disabled.
+	- The postprocessor option `-P' costumizes the viewer only in
+	  some situations in the `groff' mode, so a new infrastructure
+	  for viewer customization is necessary.
+	- Allow to specify arguments to the viewer programs specified
+	  in `--*-viewer()'.
+	- Implement some of the essential X Toolkit resource options in
+	  groffer, but with use a leading double minus.
+	  -> `--bd': set border color.
+	  -> `--bg', `--background': set background color.
+	  -> `--bw': set border width.
+	  -> `--display': set X display.
+	  -> `--geometry': set size and position of viewer window.
+	  -> `--fg', `--foreground': set foreground color.
+	  -> `--ft', `--font': set font.
+	  -> `--resolution': set X resolution in dpi.
+	  -> `--title': set viewer window title.
+	  -> `--xrm': set X resource.
+	- Remove misnamed option `--xrdb'.
+
+	* groffer.sh: new mode structure
+	- New Postcript mode `ps' (`--ps'):
+	  -> default viewers: gv,ghostview,gs_x11,gs;
+	  -> `--ps-viewer' sets the Postscript viewer.
+	- New mode `www' (`--www') for displaying in a web browser:
+	  -> default browsers: mozilla,netscape,opera,amaya,arena;
+	  -> `--www-viewer' sets the web browser.
+	- New dvi mode (`--dvi'); default viewer `xdvi':
+	  -> default viewers: xdvi,dvilx;
+	  -> `--dvi-viewer' sets the dvi viewer.
+	- New mode `auto':
+	  -> active if no other mode is given or by new option `--auto';
+	  -> selects from a sequence of modes that are tested until one
+	    of them succeeds.
+	  -> the default mode sequence is actually `ps', `x', `tty'.
+	  -> `--default-modes' sets this mode sequence as a comma
+	     separated string of program names, optionally each one
+	     with arguments).
+	- New mode `groff':
+	  -> process input like groff, ignore viewing options.
+	  -> activated by new option `--groff'.
+	  -> automatically active with one of `-V', `-X', `-Z'.
+	- Revise `tty' mode:
+	  -> allow several text devices.
+	  ->
+	- Reorganize the mode management:
+	  -> new mode setting option `--mode'.
+	  -> logically separate source, groff, and display modes.
+	  -> intermediate output mode is now part of mode groff; remove
+	     any special features around `-Z'.
+	- Update usage() to reflect the new option structure.
+
+	* groffer.sh: add configuration files
+	- `/etc/groff/groffer.conf' system-wide configuration.
+	- `${HOME}/.groff/groffer.conf' user configuration.
+	- The configuration file are shell scripts for now; later
+	  implementations can identify this from the `#! /bin/sh' line.
+
+	* groffer.sh: new data structure `list':
+	- Implement a `list' data structure as a string consisting of
+	  single-quoted elements, separated by a space character;
+	  embedded single-quotes are escaped.
+
+	* groffer.sh: new option parser based on `list':
+	- Write new option parser based on `list', compatible to both
+	  POSIX getopts() and GNU getopt().
+	- Long options are now available on GNU and non-GNU systems.
+	- Get rid of POSIX getopts() and GNU getopt().
+	- the `-W--longopt' construct is now obsolete; remove it.
+	- add test/function for `unset'.
+	- Option strings are now implemented as `list's in order to
+	  allow unusual characters in options.
+	- Parse $MANOPT first; translate essential arguments into
+	  groffer options.
+
+	* groffer.man:
+	- determine prompt length for `.Shell_cmd'* dynamically.
+	- naming scheme for static strings and registers changed to
+	  `namespace:macro.variable'.
+
+
+2002-06-16  Werner Lemberg  <wl@gnu.org>
+
+	* groffer.sh:
+	Implement man option `--ascii' by `-mtty-char'.
+
+
+2002-05-31  Werner LEMBERG  <wl@gnu.org>
+
+        * groffer.man (@.Shell_cmd_width):
+	Increase to 4m (we use `sh#' as the prompt).
+
+
+2002-05-31  Bernd Warken <groff-bernd.warken-72@web.de>
+	________________________________________________________________
+	* release of groffer 0.7
+
+	* groffer.sh: remove incompatibilities with the `ash' shell:
+	- do not use `!command':
+          -> use `else'
+	  -> write `_not_' equivalents for some functions
+	- do not use `[^]' in `case':
+	  ->  restructure some functions.
+	- only single-character names for loop variables:
+	  -> spoils the paradigm of leading `_' for local variables.
+	- spurious trouble with `for i in ${var}':
+	  -> use `eval set -- ${var}' and `for i in "$@"'
+	- do not change or use $IFS:
+	  -> define new functions string_split() and `path_split()'.
+	  -> result must be processed by `eval set --'.
+	  -> solve conflicts with existing positional parameters.
+	- trouble with exporting external `$GROFF_*' variables:
+	  -> hope that they were exported in the calling shell.
+	- not smart about additional blanks:
+	  -> remove unnecessary white space.
+
+	* groffer.sh: improve run-time speed:
+	- `ash' more than doubles the speed of `bash'.
+	- speed-up `man_setup()'.
+
+
+2002-05-30  Werner Lemberg  <wl@gnu.org>
+
+	* groffer.man:
+	- remove some wrong `\:'.
+	- rename macro names that start with a `[' (clashes with refer).
+	- fix TP_header.
+
+
+2002-05-28  Bernd Warken <groff-bernd.warken-72@web.de>
+	________________________________________________________________
+	* release of groffer 0.6
+
+	This is almost a complete rewrite since groffer 0.5 .
+	________________________________________________________________
+	* Documentation
+
+	* groffer.man:
+   	- Apply the changes done in www.tmac (.URL and .MTO)
+	- Replace \fP by \f[].
+	- Redesign and rewrite most macros.
+	- Include the documentation for the new features.
+	- Greatly enlarge section ENVIRONMENT
+	- Add examples.
+
+	* TODO:
+	- Start a TODO file with several sections.
+
+	* ChangeLog:
+	Due to the many changes, shorten and rearrange the entries
+	since groffer 0.5 .
+	________________________________________________________________
+	* Shell compatibility
+
+	* groffer.sh:
+	- Due to possible conflicts in old BSD versions, `[]' was
+	  replaced by `test'; the `test' options `-a' and `-o' were
+	  replaced by multiple calls of `test'.
+	- Write interface to the `sed' command `s' to become
+	  independent of the delimiter character.  Rewrite all text
+	  manipulating function to use this new scheme.  The new
+	  functions are named `string_*'.
+	- `tr' is not needed any longer, replaced by `sed'.
+	- `grep' is not needed any longer, mostly replaced by `case'.
+	- Revision of test for `getopt'.
+	- Remove `set -a'; explicitly export variables.
+	- The only external programs used are POSIX `sed' and the
+	  fallback to `apropos'.  All other program calls were
+	  replaced by shell builtins and functions.
+
+	________________________________________________________________
+	* Cosmetics
+
+	* groffer.sh:
+	- Implement a prefix based naming scheme for local variables
+	  and functions (OOP-like).
+	- Introduce variables for white space (better readability with
+	  $IFS).
+	- Store the names of the processed filespecs into a variable
+	  instead of a temporary file.
+	- Error-prone shell constructions were replaced by functions
+	  with a simple interface.
+	- To avoid too long pipes, replace supercat() by do_fileargs();
+	  every input file is handled independently.
+
+	________________________________________________________________
+	* New features:
+	- Add support for more X devices (e.g. X75-12 and X100-12).
+	- Add long option `--intermediate_output' to `-Z'.
+	- Make the options for mode selection clobber each other.
+	- Add option `--mode' with an argument having the following
+	  values:
+	  `X': force displaying in X, same as options `-X';
+	  `tty': display with a pager on text terminal; same as `--tty';
+	  `source', `default', `auto', etc.
+	- Make the handling of the X mode like in groff (e.g. -X -Tps).
+	- Make resolution for gxditview behave like groff (default
+	  75 dpi).
+	- Add environment variable $GROFFER_OPT to preset groffer
+	  options.
+
+	________________________________________________________________
+	* implement most of the functionality of GNU `man'.
+
+	- Add all `man' long options to groffer.
+	- Add all `man' environment variables.
+	- Parse and use content of `$MANOPT'.
+	- The precedence of the options and environment variables
+	  is regulated like in GNU `man'.
+	- Force the option `--manpath' to have a colon-separated
+	  argument like GNU `man'.
+	- Support `man section name' calling convention.
+	- Remove all dependencies on `man -w'.
+
+	* groffer.sh:
+	- Add the new features above.
+	- Rewrite the search algorithm for man pages.
+	- Remove searching with `man -w' (problems with space
+	  characters in file names).
+	- Fix and complement usage().
+	- The filespec parsers gets a function of its own do_manpage().
+
+
+2002-01-08  Bernd Warken <groff-bernd.warken-72@web.de>
+
+	* groffer 0.5 (beta) released
+
+	* groffer.man:
+	- Fix hyphenation problems with macros describing options.
+	- Fix the handling of some `-' characters.
+	- Examples of shell commands now print in font CR instead of CB.
+	- Remove documentation for option `-X'.
+	- Add documentation for option `--dpi'.
+
+	* groffer.sh:
+	- New method for creating temporary files, based on process
+	  IDs.  This is reliable enough and suitable for GNU and POSIX.
+	- Run gxditview in a new shell instantiation for having a clean
+    	  handling of the temporary files when running in the
+	  background.
+	- Revision of the retrieving method for the window title.
+	- Empty input is now tolerated.
+	- Export the variables that are set before the call of `set -a'.
+	- Function usage() corrected and updated.
+	- Unnecessary stuff removed.
+	- Comments adjusted.
+	- Pass option `-X' to groff, i.e. force X output with 75 dpi.
+	- Implement option `--dpi' for setting the resolution for the X
+	  viewer, which had already been documented in earlier versions.
+
+2002-01-07  Bernd Warken <groff-bernd.warken-72@web.de> 
+
+	* groffer 0.4 (beta) released (as groff `contrib')
+
+	* groffer.man:
+	- New features documented.
+	- Macros stream-lined.
+	- Section EXAMPLES added.
+
+	* groffer.sh:
+	- System tests added/optimized.
+	- Speed/memory optimizations by defining some shell functions
+	  alternatively depending on the text results.
+	- Use `gzip' for decompression instead of `zcat'.
+	- Signal handling added for clean exiting by `trap'.
+	- Temporary files exist only as long as necessary.
+	- Setup of path for man-pages moved after the option parsing.
+	- Fixed a bug in determining the path for man-pages.
+	- Fixed a bug in the handling of non-groffer options.
+
+	* New features:
+	- New option --tty for forcing paging on text terminal.
+	- New option --no-man for disabling the man-page feature.
+	- Implement reserved POSIX -W feature to simulate long options.
+	- gxditview is now run as a background process.
+
+2002-01-05  Werner LEMBERG  <wl@gnu.org>
+
+        * Integrate groffer into groff's `contrib' tree.
+
+        * Makefile: Replaced by...
+        Makefile.sub: New file.
+
+        * groffer: Replaced by...
+        groffer.sh: New file.
+
+        * groffer.man (OptDef): Add missing backslashes.
+        Update copyright.
+
+2001-12-15  Bernd Warken <groff-bernd.warken-72@web.de>
+
+	* groffer 0.3 (alpha) released (still stand-alone package).
+
+	* GNU and POSIX are supported (POSIX without long options).
+
+	* New options : --man, --mandb, --title, --xrdb
+
+	* Support for command line arguments with embedded single space
+	characters (GNU only) .
+
+	* Several search methods for man-pages when no `man -w' is
+	available ($MANPATH, mandb, a default path).
+
+	* Language support for man-pages.
+
+	* Recognize the following filespecs as man-page parameters:
+	  man:name(section), man:name, name.section, name.
+
+2001-12-03  Bernd Warken <groff-bernd.warken-72@web.de>
+
+	* Stand-alone package for groffer 0.2 (alpha) created
+	Files: groffer, groffer.man, Makefile, TODO, ChangeLog
+
+2001-12-02  Bernd Warken <groff-bernd.warken-72@web.de>
+
+	* groffer 0.2 (alpha) program released.
+
+	* Name changed from `groffview' to `groffer'.
+
+	* Comments added.
+
+	* Name changed from `groffview' to `groffer'.
+
+	* Options harmonized with groff.
+	New options : -Q --source, -T --device, -X .
+	Other options known from groff are passed unchanged.
+
+	* 100 dpi as default, 75 dpi only in emergency situations.
+
+	* Bugs with temporary files fixed.
+
+	* Code restructured and comments added.
+
+2001-11-28  Bernd Warken <groff-bernd.warken-72@web.de>
+
+	***** groffview 0.1 (experimental) and groffview.man released
+	(predecessor of groffer, shell script)
+
+	* Options : -h --help, -v --version
+
+	* Search for man-pages based on $MANPATH
+
+	* development of `groffview' shell script started
+
+2001-11-28  Bernd Warken <groff-bernd.warken-72@web.de>
+
+	________________________________________________________________
+	License
+
+	Copyright (C) 2001,2002,2003,2004,2005,2006
+	Free Software Foundation, Inc.
+	Written by Bernd Warken <groff-bernd.warken-72@web.de>.
+
+	Copying and distribution of this file, with or without
+	modification, are permitted provided the copyright notice and this
+	notice are preserved.
+
+	This file is part of `groffer', which is part of the `groff'
+	project.
+
+
+	Emacs settings
+
+	Local Variables:
+	mode: change-log
+	End:

Index: README_SH
===================================================================
RCS file: README_SH
diff -N README_SH
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ README_SH	11 Aug 2013 08:28:23 -0000	1.9
@@ -0,0 +1,297 @@
+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 function in groffer2.sh has a description that starts with the
+function name and symbols for its arguments in parentheses `()'.  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 on 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.
+
+For shell compatibility, see also Autobook, chapter 22.
+
+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: 7 Feb 2011
+
+Copyright (C) 2003-2006, 2009, 2011
+  Free Software Foundation, Inc.
+Written by Bernd Warken <groff-bernd.warken-72@web.de>
+
+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:

Index: groffer.man
===================================================================
RCS file: groffer.man
diff -N groffer.man
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ groffer.man	11 Aug 2013 08:28:23 -0000	1.20
@@ -0,0 +1,4124 @@
+.TH GROFFER @MAN1EXT@ "@MDATE@" "Groff Version @VERSION@"
+.SH NAME
+groffer \- display groff files and man\~pages on X and tty
+.
+.SH "SYNOPSIS"
+.\" The .SH was moved to this place in order to appease `apropos'.
+.
+.\" --------------------------------------------------------------------
+.\" Legalese
+.\" --------------------------------------------------------------------
+.
+.de author
+This file was written by Bernd Warken <groff-bernd.warken-72@web.de>.
+..
+.de copyleft
+Copyright (C) 2001, 2002, 2004-2012
+ Free Software Foundation, Inc.
+.
+.P
+This file is part of
+.IR \%groffer ,
+which is part of
+.IR \%groff ,
+a free software project.
+.
+You can redistribute it and/or modify it under the terms of the
+.nh
+.B GNU General Public License
+.hy
+as published by the
+.nh
+.BR "Free Software Foundation" ,
+.hy
+either version 3 of the License, or (at your option) any later version.
+.
+.P
+You should have received a copy of the \f[CR]GNU General Public
+License\f[] along with
+.IR groff ,
+see the files \%\f[CB]COPYING\f[] and \%\f[CB]LICENSE\f[] in the top
+directory of the
+.I groff
+source package.
+.
+Or read the
+.I man\~page
+.BR gpl (1).
+You can also visit
+.nh
+.B <http://www.gnu.org/licenses/>.
+.hy
+..
+.
+.\" --------------------------------------------------------------------
+.\" Setup
+.\" --------------------------------------------------------------------
+.
+.ds Ellipsis "\&.\|.\|.\&\"
+.
+.\" --------------------------------------------------------------------
+.\" Macro definitions
+.
+.\" --------------------------------------------------------------------
+.\" .CB  (<text>...)
+.\"
+.\" Print in constant-width bold font.
+.\"
+.de CB
+.  ft CB
+.  Text \\$*
+.  ft
+..
+.\" --------------------------------------------------------------------
+.\" .CI  (<text>...)
+.\"
+.\" Print in constant-width italic font.
+.\"
+.de CI
+.  ft CI
+.  Text \\$*
+.  ft
+..
+.\" --------------------------------------------------------------------
+.\" .CR  (<text>...)
+.\"
+.\" Print in constant-width roman font.
+.\"
+.de CR
+.  ft CR
+.  Text \\$*
+.  ft
+..
+.\" --------------------------------------------------------------------
+.\" .Error  (<text>...)
+.\"
+.\" Print error message to terminal and abort.
+.\"
+.de Error
+.  tm \\$*
+.  ab
+..
+.\" --------------------------------------------------------------------
+.\" .Env_var  (<env_var_name> [<punct>])
+.\"
+.\" Display an environment variable, with optional punctuation.
+.\"
+.de Env_var
+.  nh
+.  SM
+.  Text \f[CB]\\$1\f[]\\$2
+.  hy
+..
+.\" --------------------------------------------------------------------
+.\" .File_name  (<path_name>)
+.\"
+.\" Display a file or directory name in CB font.
+.\"
+.de File_name
+.  Header_CB \\$@
+..
+.\" --------------------------------------------------------------------
+.\" .Header_CB  (<path_name>)
+.\"
+.\" Display a line in CB font, for example after .TP
+.\"
+.de Header_CB
+.  nh
+.  Text \f[CB]\\$1\f[]\\$2
+.  hy
+..
+.\"  --------------------------------------------------------------------
+.\" .Text  (<text>...)
+.\"
+.\" Treat the arguments as text, no matter how they look.
+.\"
+.de Text
+.  if \\n[.$]=0 \
+.    return
+.  nh
+.  nop \)\\$*\)
+.  hy
+..
+.\" --------------------------------------------------------------------
+.\" .Topic  ([<indent>])
+.\"
+.\" A bulleted paragraph
+.\"
+.de Topic
+.  ie \\n[.$]=0 \
+.    ds @indent 2m\"
+.  el \
+.    ds @indent \\$1\"
+.  IP \[bu] \\*[@indent]
+.  rm @indent
+..
+
+.\" End of macro definitions
+.
+.
+.\" --------------------------------------------------------------------
+.\" SH "SYNOPSIS"
+.\" --------------------------------------------------------------------
+.
+.SY groffer
+.OP option \*[Ellipsis]
+.OP --
+.OP \%filespec \*[Ellipsis]
+.YS
+.
+.SY groffer
+.BR -h | --help
+.YS
+.
+.SY groffer
+.BR -v | --version
+.YS
+.
+.
+.\" --------------------------------------------------------------------
+.SH DESCRIPTION
+.\" --------------------------------------------------------------------
+.
+The
+.B \%groffer
+program is the easiest way to use
+.BR \%groff (@MAN1EXT@).
+It can display arbitrary documents written in the
+.I \%groff
+language, see
+.BR \%groff (@MAN7EXT@),
+or other
+.I \%roff
+languages, see
+.BR \%roff (@MAN7EXT@),
+that are compatible to the original
+.I \%troff
+language.
+.
+It finds and runs all necessary
+.I groff
+preprocessors, such as
+.BR @g@chem .
+.
+.
+.P
+The
+.B \%groffer
+program also includes many of the features for finding and displaying
+the \%\f[CR]Unix\f[] manual pages
+.nh
+.RI ( man\~pages ),
+.hy
+such that it can be used as a replacement for a
+.BR \%man (1)
+program.
+.
+Moreover, compressed files that can be handled by
+.BR \%gzip (1)
+or
+.BR \%bzip2 (1)
+are decompressed on-the-fly.
+.
+.
+.P
+The normal usage is quite simple by supplying a file name or name of a
+.I \%man\~page
+without further options.
+.
+But the option handling has many possibilities for creating special
+behaviors.
+.
+This can be done either in configuration files, with the shell
+environment variable
+.Env_var \%$GROFFER_OPT ,
+or on the command line.
+.
+.
+.P
+The output can be generated and viewed in several different ways
+available for
+.IR \%groff .
+.
+This includes the
+.I \%groff
+native \%\f[CR]X\~Window\f[] viewer
+.BR \%gxditview (@MAN1EXT@),
+each
+.IR \%Postcript ,
+.IR \%pdf ,
+or
+.I \%dvi
+display program, a web browser by generating
+.I \%html
+in
+.IR \%www\~mode ,
+or several
+.I \%text\~modes
+in text terminals.
+.
+.
+.P
+Most of the options that must be named when running
+.B \%groff
+directly are determined automatically for
+.BR \%groffer ,
+due to the internal usage of the
+.BR \%grog (@MAN1EXT@)
+program.
+.
+But all parts can also be controlled manually by arguments.
+.
+.
+.P
+Several file names can be specified on the command line arguments.
+.
+They are transformed into a single document in the normal way of
+.BR \%groff .
+.
+.
+.P
+Option handling is done in \f[CR]GNU\f[] style.
+.
+Options and file names can be mixed freely.
+.
+The option
+.RB ` \-\- '
+closes the option handling, all following arguments are treated as
+file names.
+.
+Long options can be abbreviated in several ways.
+.
+.
+.\" --------------------------------------------------------------------
+.SH "OPTION OVERVIEW"
+.\" --------------------------------------------------------------------
+.
+.TP
+.I breaking options
+.RS
+.P
+.SY
+.OP -h\~\fR|\fB\~--help
+.OP -v\~\fR|\fB\~--version
+.YS
+.RE
+.
+.
+.TP
+.I \%groffer mode options
+.RS
+.P
+.SY
+.OP --auto
+.OP --default
+.OP --default\-modes mode1,mode2,\*[Ellipsis]
+.OP --dvi
+.OP --dvi\-viewer prog
+.OP --groff
+.OP --html
+.OP --html\-viewer prog
+.OP --mode display_mode
+.OP --pdf
+.OP --pdf\-viewer prog
+.OP --ps
+.OP --ps\-viewer prog
+.OP --source
+.OP --text
+.OP --to\-stdout
+.OP --tty
+.OP --tty\-viewer prog
+.OP --www
+.OP --www\-viewer prog
+.OP --x\~\fR|\fB\~--X
+.OP --x\-viewer\~\fR|\fB\~--X\-viewer prog
+.YS
+.RE
+.
+.
+.TP
+.I options related to \%groff
+.RS
+.P
+.SY
+.OP -T\~\fR|\fB\~--device device
+.OP -Z\~\fR|\fB\~--intermediate\-output\~\fR|\fB\~--ditroff
+.YS
+.P
+All further
+.B \%groff
+short options are accepted.
+.RE
+.
+.
+.TP
+.I options for man\~pages
+.RS
+.P
+.SY
+.OP --apropos
+.OP --apropos\-data
+.OP --apropos\-devel
+.OP --apropos\-progs
+.OP --man
+.OP --no\-man
+.OP --no\-special
+.OP --whatis
+.YS
+.RE
+.
+.
+.TP
+.I long options taken over from GNU man
+.RS
+.P
+.SY
+.OP --all
+.OP --ascii
+.OP --ditroff
+.OP --extension suffix
+.OP --locale language
+.OP --local\-file
+.OP --location\~\fR|\fB\~--where
+.OP --manpath dir1:dir2:\*[Ellipsis]
+.OP --no\-location
+.OP --pager program
+.OP --sections sec1:sec2:\*[Ellipsis]
+.OP --systems sys1,sys2,\*[Ellipsis]
+.OP --troff\-device device
+.YS
+.P
+Further long options of \f[CR]GNU\f[]
+.B man
+are accepted as well.
+.RE
+.
+.
+.TP
+.I X Window Toolkit options
+.RS
+.P
+.SY
+.OP --bd\~\fR|\fB\~--bordercolor pixels
+.OP --bg\~\fR|\fB\~--background color
+.OP --bw\~\fR|\fB\~--borderwidth pixels
+.OP --display X-display
+.OP --fg\~\fR|\fB\~--foreground color
+.OP --fn\~\fR|\fB\~--ft\~\fR|\fB\~--font font_name
+.OP --geometry size_pos
+.OP --resolution value
+.OP --rv
+.OP --title string
+.OP --xrm X\-resource
+.YS
+.RE
+.
+.
+.TP
+.I options for development
+.RS
+.P
+.SY
+.OP --debug
+.OP --debug\-all
+.OP --debug\-filenames
+.OP --debug\-func
+.OP --debug\-grog
+.OP --debug\-keep
+.OP --debug\-lm
+.OP --debug\-params
+.OP --debug\-shell
+.OP --debug\-stacks
+.OP --debug\-tmpdir
+.OP --debug\-user
+.OP --do\-nothing
+.OP --print text
+.OP --shell prog
+.OP -V
+.YS
+.RE
+.
+.
+.TP
+.I \%filespec arguments
+.RS
+.P
+The
+.I \%filespec
+parameters are all arguments that are neither an option nor an option
+argument.
+.
+They usually mean a file name or a
+.I man page
+searching scheme.
+.
+.
+.P
+In the following, the term
+.I section_extension
+is used.
+.
+It means a word that consists of a
+.I man section
+that is optionally followed by an
+.IR extension .
+.
+The name of a
+.I man section
+is a single character from
+.BR \%[1-9on] ,
+the
+.I extension
+is some word.
+.
+The
+.I extension
+is mostly lacking.
+.
+.
+.P
+No
+.I \%filespec
+parameters means standard input.
+.
+.
+.TP 10m
+.B -
+stands for standard input (can occur several times).
+.
+.
+.TP
+.I filename
+the path name of an existing file.
+.
+.
+.TP
+.BI man: name ( section_extension )
+.TQ
+.BI man: name . section_extension
+.TQ
+.IB name ( section_extension )
+.TQ
+.IB name . section_extension
+.TQ
+.I "section_extension name"
+search the \%man\~page
+.I \%name
+in the section with optional extension
+.IR section_extension .
+.
+.
+.TP
+.BI man: name
+\%man\~page in the lowest
+.I \%man\~section
+that has
+.IR \%name .
+.
+.
+.TP
+.I name
+if
+.I \%name
+is not an existing file search for the man\~page
+.I \%name
+in the lowest man\~section.
+.
+.RE
+.
+.
+.\" --------------------------------------------------------------------
+.SH "OPTION DETAILS"
+.\" --------------------------------------------------------------------
+.
+The
+.B \%groffer
+program can usually be run with very few options.
+.
+But for special purposes, it supports many options.
+.
+These can be classified in 5 option classes.
+.
+.
+.P
+All short options of
+.B \%groffer
+are compatible with the short options of
+.BR \%groff (@MAN1EXT@).
+.
+All long options of
+.B \%groffer
+are compatible with the long options of
+.BR \%man (1).
+.
+.
+.P
+Arguments for long option names can be abbreviated in several ways.
+.
+First, the argument is checked whether it can be prolonged as is.
+.
+Furthermore, each minus sign
+.B -
+is considered as a starting point for a new abbreviation.
+.
+This leads to a set of multiple abbreviations for a single argument.
+.
+For example,
+.B --de\-n\-f
+can be used as an abbreviation for
+.BR --debug\-not\-func ,
+but
+.B --de\-n
+works as well.
+.
+If the abbreviation of the argument leads to several resulting options
+an error is raised.
+.
+.
+.P
+These abbreviations are only allowed in the environment variable
+.Env_var \%$GROFFER_OPT ,
+but not in the configuration files.
+.
+In configuration, all long options must be exact.
+.
+.
+.\" --------------------------------------------------------------------
+.SS "groffer breaking Options"
+.\" --------------------------------------------------------------------
+.
+As soon as one of these options is found on the command line it is
+executed, printed to standard output, and the running
+.B \%groffer
+is terminated thereafter.
+.
+All other arguments are ignored.
+.
+.
+.TP
+.B -h\~\fR|\fB\~--help
+Print help information with a short explanation of options to
+standard output.
+.
+.
+.TP
+.B -v\~\fR|\fB\~--version
+Print version information to standard output.
+.
+.
+.\" --------------------------------------------------------------------
+.SS "groffer Mode Options"
+.\" --------------------------------------------------------------------
+.
+The display mode and the viewer programs are determined by these
+options.
+.
+If none of these mode and viewer options is specified
+.B \%groffer
+tries to find a suitable display mode automatically.
+.
+The default modes are
+.IR "mode pdf" ,
+.IR "mode ps" ,
+.IR "mode html" ,
+.IR "mode x" ,
+and
+.I "mode dvi"
+in \%\f[CR]X\~Window\f[] with different viewers and
+.I mode tty
+with device
+.I latin1
+under
+.B less
+on a terminal; other modes are tested if the programs for the main
+default mode do not exist.
+.
+.
+.P
+In \%\f[CR]X\~Window\f[],
+many programs create their own window when called.
+.B \%groffer
+can run these viewers as an independent program in the background.
+.
+As this does not work in text mode on a terminal (tty) there must be a
+way to know which viewers are \%\f[CR]X\~Window\f[] graphical
+programs.
+.
+The
+.B \%groffer
+script has a small set of information on some viewer names.
+.
+If a viewer argument of the command\-line chooses an element that is
+kept as \%\f[CR]X\~Window\f[] program in this list it is treated as a
+viewer that can run in the background.
+.
+All other, unknown viewer calls are not run in the background.
+.
+.
+.P
+For each mode, you are free to choose whatever viewer you want.
+.
+That need not be some graphical viewer suitable for this mode.
+.
+There is a chance to view the output source; for example, the
+combination of the options
+.B --mode=ps
+and
+.B --ps\-viewer=less
+shows the content of the
+.I Postscript
+output, the source code, with the pager
+.BR less .
+.
+.
+.TP
+.B --auto
+Equivalent to
+.BR --mode=auto .
+.
+.
+.TP
+.B --default
+Reset all configuration from previously processed command line options
+to the default values.
+.
+This is useful to wipe out all former options of the configuration, in
+.Env_var \%$GROFFER_OPT ,
+and restart option processing using only the rest of the command line.
+.
+.
+.TP
+.BI --default\-modes \ mode1,mode2,\*[Ellipsis]
+Set the sequence of modes for
+.I \%auto\~mode
+to the comma separated list given in the argument.
+.
+See
+.B --mode
+for details on modes.  Display in the default manner; actually, this
+means to try the modes
+.IR x ,
+.IR ps ,
+and
+.I \%tty
+in this sequence.
+.
+.
+.
+.TP
+.B --dvi
+Equivalent to
+.BR --mode=\%dvi .
+.
+.
+.TP
+.BI --dvi\-viewer \ prog
+Choose a viewer program for
+.IR \%dvi\~mode .
+.
+This can be a file name or a program to be searched in
+.Env_var $PATH .
+.
+Known \%\f[CR]X\~Window\f[]
+.I \%dvi
+viewers include
+.BR \%xdvi (1)
+and
+.BR \%dvilx (1).
+.
+In each case, arguments can be provided additionally.
+.
+.
+.TP
+.B --groff
+Equivalent to
+.BR --mode=groff .
+.
+.
+.TP
+.B --html
+Equivalent to
+.BR --mode=html .
+.
+.
+.TP
+.B --html\-viewer
+Choose a web browser program for viewing in
+.IR \%html\~mode .
+.
+It can be the path name of an executable file or a program in
+.Env_var $PATH .
+.
+In each case, arguments can be provided additionally.
+.
+.
+.TP
+.BI --mode \ value
+.
+Set the display mode.
+.
+The following mode values are recognized:
+.
+.RS
+.
+.TP
+.Header_CB auto
+Select the automatic determination of the display mode.
+.
+The sequence of modes that are tried can be set with the
+.B --default\-modes
+option.
+.
+Useful for restoring the
+.I \%default\~mode
+when a different mode was specified before.
+.
+.
+.TP
+.Header_CB dvi
+Display formatted input in a
+.I \%dvi
+viewer program.
+.
+By default, the formatted input is displayed with the
+.BR \%xdvi (1)
+program.
+.
+.
+.TP
+.Header_CB groff
+After the file determination, switch
+.B \%groffer
+to process the input like
+.BR \%groff (@MAN1EXT@)
+would do.
+.
+This disables the
+.I \%groffer
+viewing features.
+.
+.
+.TP
+.Header_CB html
+Translate the input into html format and display the result in a web
+browser program.
+.
+By default, the existence of a sequence of standard web browsers is
+tested, starting with
+.BR \%konqueror (1)
+and
+.BR \%mozilla (1).
+The text html viewer is
+.BR \%lynx (1).
+.
+.
+.TP
+.Header_CB pdf
+Display formatted input in a
+.I \%PDF
+(Portable Document Format) viewer
+program.
+.
+By default, the input is formatted by
+.B \%groff
+using the Postscript device, then it is transformed into the PDF file
+format using
+.BR \%gs (1),
+or
+.BR ps2pdf (1).
+If that's not possible, the
+.I Postscript mode (ps)
+is used instead.
+.
+Finally it is displayed using different viewer programs.
+.
+.I \%pdf
+has a big advantage because the text is displayed graphically and
+is searchable as well.
+.
+.
+.TP
+.Header_CB ps
+Display formatted input in a Postscript viewer program.
+.
+By default, the formatted input is displayed in one of many viewer
+programs.
+.
+.
+.TP
+.Header_CB text
+Format in a
+.I \%groff\~text\~mode
+and write the result to standard output without a pager or viewer
+program.
+.
+The text device,
+.I \%latin1
+by default, can be chosen with option
+.BR -T .
+.
+.
+.TP
+.Header_CB tty
+Format in a
+.I \%groff\~text\~mode
+and write the result to standard output using a text pager program,
+even when in \%\f[CR]X\~Window\f[].
+.
+.
+.TP
+.Header_CB www
+Equivalent to
+.BR --mode=html .
+.
+.
+.TP
+.Header_CB x
+Display the formatted input in a native
+.I roff
+viewer.
+.
+By default, the formatted input is displayed with the
+.BR \%gxditview (@MAN1EXT@)
+program being distributed together with
+.BR \%groff .
+But the standard \%\f[CR]X\~Window\f[] tool
+.BR \%xditview (1)
+can also be chosen with the option
+.BR --x\-viewer .
+The default resolution is
+.BR 75dpi ,
+but
+.B 100dpi
+are also possible.
+.
+The default
+.I groff
+device
+for the resolution of
+.B 75dpi
+is
+.BR X75\-12 ,
+for
+.B 100dpi
+it is
+.BR X100 .
+.
+The corresponding
+.I "groff intermediate output"
+for the actual device is generated and the result is displayed.
+.
+For a resolution of
+.BR 100dpi ,
+the default width of the geometry of the display program is chosen to
+.BR 850dpi .
+.
+.
+.TP
+.Header_CB X
+Equivalent to
+.BR --mode=x .
+.
+.
+.P
+The following modes do not use the
+.I \%groffer
+viewing features.
+.
+They are only interesting for advanced applications.
+.
+.
+.TP
+.Header_CB groff
+Generate device output with plain
+.I \%groff
+without using the special viewing features of
+.IR \%groffer .
+If no device was specified by option
+.B -T
+the
+.I \%groff
+default
+.B \%ps
+is assumed.
+.
+.
+.TP
+.Header_CB source
+Output the roff source code of the input files without further
+processing.
+.
+.
+.RE
+.
+.
+.TP
+.B --pdf
+Equivalent to
+.BR --mode=pdf .
+.
+.
+.TP
+.BI --pdf\-viewer \ prog
+Choose a viewer program for
+.IR \%pdf\~mode .
+.
+This can be a file name or a program to be searched in
+.Env_var $PATH ;
+arguments can be provided additionally.
+.
+.
+.TP
+.B --ps
+Equivalent to
+.BR --mode=ps .
+.
+.
+.TP
+.BI --ps\-viewer \ prog
+Choose a viewer program for
+.IR \%ps\~mode .
+.
+This can be a file name or a program to be searched in
+.Env_var $PATH .
+.
+Common Postscript viewers include
+.BR \%gv (1),
+.BR \%ghostview (1),
+and
+.BR \%gs (1),
+.
+In each case, arguments can be provided additionally.
+.
+.
+.TP
+.B --source
+Equivalent to
+.BR --mode=source .
+.
+.
+.TP
+.B --text
+Equivalent to
+.BR --mode=text .
+.
+.
+.TP
+.B --to\-stdout
+The file for the chosen mode is generated and its content is printed
+to standard output.
+.
+It will not be displayed in graphical mode.
+.
+.
+.TP
+.B --tty
+Equivalent to
+.BR --mode=tty .
+.
+.
+.TP
+.BI --tty\-viewer \ prog
+Choose a text pager for mode
+.IR tty .
+The standard pager is
+.BR less (1).
+This option is equivalent to
+.I man
+option
+.BR --pager=\fIprog\fP .
+The option argument can be a file name or a program to be searched in
+.Env_var $PATH ;
+arguments can be provided additionally.
+.
+.
+.TP
+.B --www
+Equivalent to
+.BR --mode=html .
+.
+.
+.TP
+.BI --www\-viewer \ prog
+Equivalent to
+.BR --html\-viewer .
+.
+.
+.TP
+.B --X\~\fR|\fB\~--x
+Equivalent to
+.BR --mode=x .
+.
+.
+.TP
+.BI --X\-viewer\~\fR|\fB\~--x\-viewer \ prog
+Choose a viewer program for
+.IR \%x\~mode .
+Suitable viewer programs are
+.BR \%gxditview (@MAN1EXT@)
+which is the default and
+.BR \%xditview (1).
+The argument can be any executable file or a program in
+.Env_var $PATH ;
+arguments can be provided additionally.
+.
+.
+.TP
+.B --
+Signals the end of option processing; all remaining arguments are
+interpreted as
+.I \%filespec
+parameters.
+.
+.
+.P
+Besides these,
+.B \%groffer
+accepts all short options that are valid for the
+.BR \%groff (@MAN1EXT@)
+program.
+.
+All
+.RB \%non- groffer
+options are sent unmodified via
+.B \%grog
+to
+.BR \%groff .
+.
+So postprocessors, macro packages, compatibility with
+.I classical
+.IR \%troff ,
+and much more can be manually specified.
+.
+.
+.\" --------------------------------------------------------------------
+.SS "Options related to groff"
+.\" --------------------------------------------------------------------
+.
+All short options of
+.B \%groffer
+are compatible with the short options of
+.BR \%groff (@MAN1EXT@).
+.
+The following of
+.B \%groff
+options have either an additional special meaning within
+.B \%groffer
+or make sense for normal usage.
+.
+.
+.P
+Because of the special outputting behavior of the
+.B \%groff
+option
+.B -Z
+.B \%groffer
+was designed to be switched into
+.IR \%groff\~mode ;
+the
+.I \%groffer
+viewing features are disabled there.
+.
+The other
+.B \%groff
+options do not switch the mode, but allow to customize the formatting
+process.
+.
+.
+.TP
+.B --a
+This generates an ascii approximation of output in the
+.IR \%text\~modes .
+.
+That could be important when the text pager has problems with control
+sequences in
+.IR "tty mode" .
+.
+.
+.TP
+.BI --m \ file
+Add
+.I \%file
+as a
+.I \%groff
+macro file.
+.
+This is useful in case it cannot be recognized automatically.
+.
+.
+.TP
+.BI --P \ opt_or_arg
+Send the argument
+.I \%opt_or_arg
+as an option or option argument to the actual
+.B \%groff
+postprocessor.
+.
+.
+.TP
+.B --T \fIdevname\fR\~\fR|\fB\~--device \fIdevname\fR
+.
+This option determines
+.BR \%groff 's
+output device.
+.
+The most important devices are the text output devices for referring
+to the different character sets, such as
+.BR \%ascii ,
+.BR \%utf8 ,
+.BR \%latin1 ,
+and others.
+.
+Each of these arguments switches
+.B \%groffer
+into a
+.I \%text\~mode
+using this device, to
+.I \%mode\~tty
+if the actual mode is not a
+.IR \%text\~mode .
+.
+The following
+.I \%devname
+arguments are mapped to the corresponding
+.B \%groffer
+.B --mode=\fIdevname\fR
+option:
+.BR \%dvi ,
+.BR \%html ,
+and
+.BR \%ps .
+All
+.B \%X*
+arguments are mapped to
+.IR \%mode\~x .
+Each other
+.I \%devname
+argument switches to
+.I \%mode\~groff
+using this device.
+.
+.
+.TP
+.B --X
+is equivalent to
+.BR "groff \-X" .
+It displays the
+.I groff intermediate output
+with
+.BR gxditview .
+As the quality is relatively bad this option is deprecated; use
+.B --X
+instead because the
+.I \%x\~mode
+uses an
+.IR X *
+device for a better display.
+.
+.
+.TP
+.B -Z\~\fR|\fB\~--intermediate-output\~\fR|\fB\~--ditroff
+Switch into
+.I \%groff\~mode
+and format the input with the
+.I \%groff intermediate output
+without postprocessing; see
+.BR \%groff_out (@MAN5EXT@).
+This is equivalent to option
+.B --ditroff
+of
+.IR \%man ,
+which can be used as well.
+.
+.
+.P
+All other
+.B \%groff
+options are supported by
+.BR \%groffer ,
+but they are just transparently transferred to
+.B \%groff
+without any intervention.
+.
+The options that are not explicitly handled by
+.B \%groffer
+are transparently passed to
+.BR \%groff .
+.
+Therefore these transparent options are not documented here, but in
+.BR \%groff (@MAN1EXT@).
+Due to the automatism in
+.BR \%groffer ,
+none of these
+.B \%groff
+options should be needed, except for advanced usage.
+.
+.
+.\" --------------------------------------------------------------------
+.SS "Options for man\~pages"
+.\" --------------------------------------------------------------------
+.
+.TP
+.B --apropos
+Start the
+.BR \%apropos (1)
+command or facility of
+.BR \%man (1)
+for searching the
+.I \%filespec
+arguments within all
+.I \%man\~page
+descriptions.
+.
+Each
+.I \%filespec
+argument is taken for search as it is;
+.I section
+specific parts are not handled, such that
+.B 7 groff
+searches for the two arguments
+.B 7
+and
+.BR groff ,
+with a large result; for the
+.I \%filespec
+.B groff.7
+nothing will be found.
+.
+The
+.I language
+locale is handled only when the called programs do support this; the
+GNU
+.B apropos
+and
+.B man \-k
+do not.
+.
+The display differs from the
+.B \%apropos
+program by the following concepts:
+.RS
+.Topic
+Construct a
+.I \%groff
+frame similar to a
+.I \%man\~page
+to the output of
+.BR \%apropos ,
+.Topic
+each
+.I \%filespec
+argument is searched on its own.
+.Topic
+The restriction by
+.B --sections
+is handled as well,
+.Topic
+wildcard characters are allowed and handled without a further option.
+.RE
+.
+.
+.TP
+.B --apropos\-data
+Show only the
+.B \%apropos
+descriptions for data documents, these are the
+.BR \%man (7)
+.IR sections\~4 ", " 5 ", and " 7 .
+.
+Direct
+.I section
+declarations are ignored, wildcards are accepted.
+.
+.
+.TP
+.B --apropos\-devel
+Show only the
+.B \%apropos
+descriptions for development documents, these are the
+.BR man (7)
+.IR sections\~2 ", " 3 ", and " 9 .
+.
+Direct
+.I section
+declarations are ignored, wildcards are accepted.
+.
+.
+.TP
+.B --apropos\-progs
+Show only the
+.B \%apropos
+descriptions for documents on programs, these are the
+.BR \%man (7)
+.IR sections\~1 ", " 6 ", and " 8 .
+.
+Direct
+.I section
+declarations are ignored, wildcards are accepted.
+.
+.
+.TP
+.B --whatis
+For each
+.I \%filespec
+argument search all
+.I \%man\~pages
+and display their description \[em] or say that it is not a
+.IR \%man\~page .
+This is written from anew, so it differs from
+.IR man 's
+.B whatis
+output by the following concepts
+.RS
+.Topic
+each retrieved file name is added,
+.Topic
+local files are handled as well,
+.Topic
+the \fIlanguage\fP and \fIsystem\fP locale is supported,
+.Topic
+the display is framed by a
+.I groff
+output format similar to a
+.IR \%man\~page ,
+.Topic
+wildcard characters are allowed without a further option.
+.RE
+.
+.
+.P
+The following options were added to
+.B \%groffer
+for choosing whether the file name arguments are interpreted as names
+for local files or as a search pattern for
+.IR \%man\~pages .
+.
+The default is looking up for local files.
+.
+.
+.TP
+.B --man
+Check the non-option command line arguments
+.nh
+.RI ( filespecs )
+.hy
+first on being
+.IR \%man\~pages ,
+then whether they represent an existing file.
+.
+By default, a
+.I \%filespec
+is first tested whether it is an existing file.
+.
+.
+.TP
+.B --no-man\~\fR|\fB\~--local-file
+Do not check for
+.IR \%man\~pages .
+.
+.B --local-file
+is the corresponding
+.B man
+option.
+.
+.
+.TP
+.B --no-special
+Disable former calls of
+.BR --all ,
+.BR --apropos* ,
+and
+.BR --whatis .
+.
+.
+.\" --------------------------------------------------------------------
+.SS "Long options taken over from GNU man"
+.\" --------------------------------------------------------------------
+.
+The long options of
+.B \%groffer
+were synchronized with the long options of \f[CR]GNU\f[]
+.BR man .
+.
+All long options of \f[CR]GNU\f[]
+.B man
+are recognized, but not all of these options are important to
+.BR \%groffer ,
+so most of them are just ignored.
+.
+These ignored
+.B man
+options are
+.BR --catman ,
+.BR --troff ,
+and
+.BR --update .
+.
+.
+.P
+In the following, the
+.B man
+options that have a special meaning for
+.B \%groffer
+are documented.
+.
+.
+.P
+If your system has \f[CR]GNU\f[]
+.B man
+installed the full set of long and short options of the \f[CR]GNU\f[]
+.B man
+program can be passed via the environment variable
+.Env_var \%$MANOPT ;
+see
+.BR \%man (1).
+.
+.
+.TP
+.B --all
+In searching
+.IR \%man\~pages ,
+retrieve all suitable documents instead of only one.
+.
+.
+.TP
+.B -7\~\fR|\fB\~--ascii
+In
+.IR \%text\~modes ,
+display ASCII translation of special characters for critical environment.
+.
+This is equivalent to
+.BR "groff \%-mtty_char" ;
+see
+.BR groff_tmac (@MAN5EXT@).
+.
+.
+.TP
+.B --ditroff
+Produce
+.IR "groff intermediate output" .
+This is equivalent to
+.B \%groffer
+.BR -Z .
+.
+.
+.TP
+.BI --extension \ suffix
+Restrict
+.I \%man\~page
+search to file names that have
+.I \%suffix
+appended to their section element.
+.
+For example, in the file name
+.I \%/usr/share/man/man3/terminfo.3ncurses.gz
+the
+.I \%man\~page
+extension is
+.IR \%ncurses .
+.
+.
+.TP
+.BI --locale \ language
+.
+Set the language for
+.IR \%man\~pages .
+.
+This has the same effect, but overwrites
+.Env_var $LANG .
+.
+.
+.TP
+.B --location
+Print the location of the retrieved files to standard error.
+.
+.
+.TP
+.B --no-location
+Do not display the location of retrieved files; this resets a former
+call to
+.BR --location .
+.
+This was added by
+.BR \%groffer .
+.
+.
+.TP
+.BI --manpath \ 'dir1:dir2:\*[Ellipsis]'
+Use the specified search path for retrieving
+.I \%man\~pages
+instead of the program defaults.
+.
+If the argument is set to the empty string "" the search for
+.I \%man\~page
+is disabled.
+.
+.
+.TP
+.B --pager
+Set the pager program in
+.IR \%tty\~mode ;
+default is
+.BR \%less .
+This is equivalent to
+.BR --tty\-viewer .
+.
+.
+.TP
+.BI --sections \ sec1:sec2:\*[Ellipsis]
+Restrict searching for
+.I \%man\~pages
+to the given
+.IR sections ,
+a colon-separated list.
+.
+.
+.TP
+.BI --systems \ sys1,sys2,\*[Ellipsis]
+Search for
+.I \%man\~pages
+for the given operating systems; the argument
+.I \%systems
+is a comma-separated list.
+.
+.
+.TP
+.B --where
+Equivalent to
+.BR --location .
+.
+.
+.\" --------------------------------------------------------------------
+.SS "X\~\%Window\~\%Toolkit Options"
+.\" --------------------------------------------------------------------
+.
+The following long options were adapted from the corresponding
+\%\f[CR]X\~Window\~Toolkit\f[] options.
+.
+.B \%groffer
+will pass them to the actual viewer program if it is an
+\%\f[CR]X\~Window\f[] program.
+.
+Otherwise these options are ignored.
+.
+.
+.P
+Unfortunately these options use the old style of a single minus for
+long options.
+.
+For
+.B \%groffer
+that was changed to the standard with using a double minus for long
+options, for example,
+.B \%groffer
+uses the option
+.B --font
+for the \%\f[CR]X\~Window\f[] option
+.BR -font .
+.
+.
+.P
+See
+.BR X (7)
+and the documentation on the \%\f[CR]X\~Window\~Toolkit\f[] options
+for more details on these options and their arguments.
+.
+.
+.TP
+.BI --background \ color
+Set the background color of the viewer window.
+.
+.
+.TP
+.BI --bd \ pixels
+This is equivalent to
+.BR --bordercolor .
+.
+.
+.TP
+.BI --bg \ color
+This is equivalent to
+.BR --background .
+.
+.
+.TP
+.BI --bw \ pixels
+This is equivalent to
+.BR --borderwidth .
+.
+.
+.TP
+.BI --bordercolor \ pixels
+Specifies the color of the border surrounding the viewer window.
+.
+.
+.TP
+.BI --borderwidth \ pixels
+Specifies the width in pixels of the border surrounding the viewer
+window.
+.
+.
+.TP
+.BI --display \ X-display
+Set the \%\f[CR]X\~Window\f[] display on which the viewer program
+shall be started, see the \%\f[CR]X\~Window\f[] documentation for the
+syntax of the argument.
+.
+.
+.TP
+.BI --foreground \ color
+Set the foreground color of the viewer window.
+.
+.
+.TP
+.BI --fg \ color
+This is equivalent to
+.BR -foreground .
+.
+.
+.TP
+.BI --fn \ font_name
+This is equivalent to
+.BR --font .
+.
+.
+.TP
+.BI --font \ font_name
+Set the font used by the viewer window.
+.
+The argument is an \%\f[CR]X\~Window\f[] font name.
+.
+.
+.TP
+.BI --ft \ font_name
+This is equivalent to
+.BR --font .
+.
+.
+.TP
+.BI --geometry \ size_pos
+Set the geometry of the display window, that means its size and its
+starting position.
+.
+See
+.BR \%X (7)
+for the syntax of the argument.
+.
+.
+.TP
+.BI --resolution \ value
+Set \%\f[CR]X\~Window\f[] resolution in dpi (dots per inch) in some
+viewer programs.
+.
+The only supported dpi values are
+.B 75
+and
+.BR 100 .
+.
+Actually, the default resolution for
+.B \%groffer
+is set to
+.BR 75dpi .
+The resolution also sets the default device in
+.IR "mode x" .
+.
+.
+.TP
+.B --rv
+Reverse foreground and background color of the viewer window.
+.
+.
+.TP
+.BI --title "\ 'some text'"
+Set the title for the viewer window.
+.
+.
+.TP
+.BI --xrm \ 'resource'
+Set \f[CR]\%X\~Window\f[] resource.
+.
+.
+.\" --------------------------------------------------------------------
+.SS "Options for Development"
+.\" --------------------------------------------------------------------
+.
+.TP
+.B --debug
+Enable eight debugging informations.
+.
+The temporary files are kept and not deleted, the name of the
+temporary directory and the shell name for
+.File_name groffer2.sh
+are printed, the displayed file names are printed, the
+.B grog
+output is printed, the parameters are printed at several steps of
+development, and a function stack is output with function
+\f[CR]error_user()\f[] as well.
+.
+Neither the function call stack at the opening and closing of each
+function call nor the landmark information to determine how far the
+program is running are printed.
+.
+These seem to be the most useful parts among all debugging options.
+.
+.
+.TP
+.B --debug\-all
+Enable all ten debugging informations including the function call
+stack and the landmark information.
+.
+.
+.TP
+.B --debug\-filenames
+Print the names of the files and
+.I \%man\~pages
+that are displayed by
+.BR \&groffer .
+.
+.
+.TP
+.B --debug\-func
+Enable the basic debugging information for checking the functions on
+the beginning and end of each call.
+.
+The options
+.B --debug\-stacks
+and
+.B --debug\-user
+enable this option automatically.
+.
+This option is important for the development, but it decreases the
+speed of
+.B groffer
+by large amounts.
+.
+.
+.TP
+.B --debug\-grog
+Print the output of all
+.B grog
+commands.
+.
+.
+.TP
+.B --debug\-keep
+Enable two debugging informations, the printing of the name of the
+temporary directory and the keeping of the temporary files.
+.
+.
+.TP
+.B --debug\-lm
+Enable one debugging information, the landmark information.
+.
+.
+.TP
+.B --debug\-params
+Enable one debugging information, the parameters at several steps.
+.
+.
+.TP
+.B --debug\-shell
+Enable one debugging information, the shell name for
+.File_name groffer2.sh .
+.
+.
+.TP
+.B --debug\-stacks
+Enable one debugging information, the function call stack.
+.
+.
+.TP
+.B --debug\-tmpdir
+Enable one debugging information, the name of the temporary directory.
+.
+.
+.TP
+.B --debug\-user
+Enable one debugging information, the function stack with
+\f[CR]error_user()\f[].
+.
+.
+.TP
+.B --do-nothing
+This is like
+.BR --version ,
+but without the output; no viewer is started.
+.
+This makes only sense in development.
+.
+.
+.TP
+.B --print=\fItext\fR
+Just print the argument to standard error.
+.
+This is good for parameter check.
+.
+.
+.TP
+.B --shell \fIshell_program\fR
+Specify the shell under which the
+.File_name \%groffer2.sh
+script should be run.
+.
+This option overwrites the automatic shell determination of the
+program.
+.
+If the argument
+.I shell_program
+is empty a former shell option and the automatic shell determination
+is cancelled and the default shell is restored.
+.
+Some shells run considerably faster than the standard shell.
+.
+.
+.TP
+.B -V
+This is an advanced option for debugging only.
+.
+Instead of displaying the formatted input, a lot of
+.I \%groffer
+specific information is printed to standard output:
+.
+.RS
+.Topic
+the output file name in the temporary directory,
+.
+.Topic
+the display mode of the actual
+.B \%groffer
+run,
+.
+.Topic
+the display program for viewing the output with its arguments,
+.
+.Topic
+the active parameters from the config files, the arguments in
+.Env_var \%$GROFFER_OPT ,
+and the arguments of the command line,
+.
+.Topic
+the pipeline that would be run by the
+.B \%groff
+program, but without executing it.
+.RE
+.
+.
+.P
+Other useful debugging options are the
+.B \%groff
+option
+.B -Z
+and
+.BR --mode=groff .
+.
+.
+.\" --------------------------------------------------------------------
+.SS "Filespec Arguments"
+.\" --------------------------------------------------------------------
+.
+A
+.I \%filespec
+parameter is an argument that is not an option or option argument.
+.
+In
+.BR \%groffer ,
+.I \%filespec
+parameters are a file name or a template for searching
+.IR \%man\~pages .
+.
+These input sources are collected and composed into a single output
+file such as
+.B \%groff
+does.
+.
+.
+.P
+The strange \%\f[CR]POSIX\f[] behavior to regard all arguments behind
+the first non-option argument as
+.I \%filespec
+arguments is ignored.
+.
+The \f[CR]GNU\f[] behavior to recognize options even when mixed with
+.I \%filespec
+arguments is used throughout.
+.
+But, as usual, the double minus argument
+.B --
+ends the option handling and interprets all following arguments as
+.I \%filespec
+arguments; so the \%\f[CR]POSIX\f[] behavior can be easily adopted.
+.
+.
+.P
+The options
+.B --apropos*
+have a special handling of
+.I filespec
+arguments.
+.
+Each argument is taken as a search scheme of its own.
+.
+Also a regexp (regular expression) can be used in the filespec.
+.
+For example,
+.B groffer --apropos '^gro.f$'
+searches
+.B groff
+in the
+.I man\~page
+name, while
+.B groffer --apropos groff
+searches
+.B groff
+somewhere in the name or description of the
+.IR man\~pages .
+.
+.
+.P
+All other parts of
+.IR groffer ,
+such as the normal display or the output with
+.B --whatis
+have a different scheme for
+.IR filespecs .
+No regular expressions are used for the arguments.
+.
+The
+.I filespec
+arguments are handled by the following scheme.
+.
+.
+.P
+It is necessary to know that on each system the
+.I \%man\~pages
+are sorted according to their content into several sections.
+.
+The
+.I classical man sections
+have a single-character name, either a digit from
+.B 1
+to
+.B 9
+or one of the characters
+.B n
+or
+.BR o .
+.
+.
+.P
+This can optionally be followed by a string, the so-called
+.IR extension .
+The
+.I extension
+allows to store several
+.I man\~pages
+with the same name in the same
+.IR section .
+But the
+.I extension
+is only rarely used, usually it is omitted.
+.
+Then the
+.I extensions
+are searched automatically by alphabet.
+.
+.
+.P
+In the following, we use the name
+.I section_extension
+for a word that consists of a single character
+.I section
+name or a
+.I section
+character that is followed by an
+.IR extension .
+.
+Each
+.I \%filespec
+parameter can have one of the following forms in decreasing sequence.
+.
+.
+.Topic
+No
+.I \%filespec
+parameters means that
+.B \%groffer
+waits for standard input.
+.
+The minus option
+.B -
+always stands for standard input; it can occur several times.
+.
+If you want to look up a
+.I \%man\~page
+called
+.B -
+use the argument
+.BR man:\- .
+.
+.
+.Topic
+Next a
+.I \%filespec
+is tested whether it is the path name of an existing file.
+.
+Otherwise it is assumed to be a searching pattern for a
+.IR \%man\~page .
+.
+.
+.Topic
+.BI \%man: name ( section_extension ) ,
+.BI \%man: name . section_extension,
+.IB \%name ( section_extension ) ,
+or
+.IB \%name . section_extension
+search the \%man\~page
+.I \%name
+in \%man\~section and possibly extension of
+.IR \%section_extension .
+.
+.
+.Topic
+Now
+.BI \%man: name
+searches for a
+.I \%man\~page
+in the lowest
+.I \%man\~section
+that has a document called
+.IR \%name .
+.
+.
+.Topic
+.I \%section_extension\~name
+is a pattern of 2 arguments that originates from a strange argument
+parsing of the
+.B man
+program.
+.
+Again, this searches the man page
+.I name
+with
+.IR \%section_extension ,
+a combination of a
+.I section
+character optionally followed by an
+.IR extension .
+.
+.
+.Topic
+We are left with the argument
+.I \%name
+which is not an existing file.
+.
+So this searches for the
+.I \%man\~page
+called
+.I \%name
+in the lowest
+.I \%man\~section
+that has a document for this name.
+.
+.
+.P
+Several file name arguments can be supplied.
+.
+They are mixed by
+.B \%groff
+into a single document.
+.
+Note that the set of option arguments must fit to all of these file
+arguments.
+.
+So they should have at least the same style of the
+.I \%groff
+language.
+.
+.
+.\" --------------------------------------------------------------------
+.SH "OUTPUT MODES"
+.\" --------------------------------------------------------------------
+.
+By default, the
+.B \%groffer
+program collects all input into a single file, formats it with the
+.B \%groff
+program for a certain device, and then chooses a suitable viewer
+program.
+.
+The device and viewer process in
+.B \%groffer
+is called a
+.IR \%mode .
+.
+The mode and viewer of a running
+.B \%groffer
+program is selected automatically, but the user can also choose it
+with options.
+.
+.
+The modes are selected by option the arguments of
+.BR --mode=\fIanymode .
+Additionally, each of this argument can be specified as an option of
+its own, such as
+.BR anymode .
+Most of these modes have a viewer program, which can be chosen by an
+option that is constructed like
+.BR --\fIanymode\fR\-viewer .
+.
+.
+.P
+Several different modes are offered, graphical modes for
+\f[CR]\%X\~Window\f[],
+.IR \%text\~modes ,
+and some direct
+.I \%groff\~modes
+for debugging and development.
+.
+.
+.P
+By default,
+.B \%groffer
+first tries whether
+.I \%x\~mode
+is possible, then
+.IR \%ps\~mode ,
+and finally
+.IR \%tty\~mode .
+.
+This mode testing sequence for
+.I \%auto\~mode
+can be changed by specifying a comma separated list of modes with the
+option
+.B --default\-modes.
+.
+.
+.P
+The searching for
+.I \%man\~pages
+and the decompression of the input are active in every mode.
+.
+.
+.\" --------------------------------------------------------------------
+.SS "Graphical Display Modes"
+.\" --------------------------------------------------------------------
+.
+The graphical display modes work mostly in the \%\f[CR]X\~Window\f[]
+environment (or similar implementations within other windowing
+environments).
+.
+The environment variable
+.Env_var \%$DISPLAY
+and the option
+.B --display
+are used for specifying the \%\f[CR]X\~Window\f[] display to be used.
+.
+If this environment variable is empty
+.B \%groffer
+assumes that no \%\f[CR]X\~Window\f[] is running and changes to a
+.IR \%text\~mode .
+.
+You can change this automatic behavior by the option
+.BR --default\-modes .
+.
+.
+.P
+Known viewers for the graphical display modes and their standard
+\%\f[CR]X\~Window\f[] viewer programs are
+.
+.Topic
+in a PDF viewer
+.nh
+.RI ( \%pdf\~mode )
+.hy
+.
+.Topic
+in a web browser
+.nh
+.RI ( html
+or
+.IR \%www\~mode )
+.hy
+.RE
+.
+.Topic
+in a Postscript viewer
+.nh
+.RI ( \%ps\~mode )
+.hy
+.
+.Topic
+\%\f[CR]X\~Window\f[]
+.I roff
+viewers such as
+.BR \%gxditview (@MAN1EXT@)
+or
+.BR \%xditview (1)
+(in
+.IR \%x\~mode )
+.
+.Topic
+in a dvi viewer program
+.nh
+.RI ( \%dvi\~mode )
+.hy
+.
+.
+.P
+The
+.I \%pdf\~mode
+has a major advantage \[em] it is the only graphical display mode that
+allows to search for text within the viewer; this can be a really
+important feature.
+.
+Unfortunately, it takes some time to transform the input into the PDF
+format, so it was not chosen as the major mode.
+.
+.
+.P
+These graphical viewers can be customized by options of the
+\%\f[CR]X\~Window\~Toolkit\f[].
+.
+But the
+.B \%groffer
+options use a leading double minus instead of the single minus used by
+the \%\f[CR]X\~Window\~Toolkit\f[].
+.
+.
+.\" --------------------------------------------------------------------
+.SS "Text modes"
+.\" --------------------------------------------------------------------
+.
+There are two modes for text output,
+.I \%mode\~text
+for plain output without a pager and
+.I \%mode\~tty
+for a text output on a text terminal using some pager program.
+.
+.
+.P
+If the variable
+.Env_var \%$DISPLAY
+is not set or empty,
+.B \%groffer
+assumes that it should use
+.IR \%tty\~\%mode .
+.
+.
+.P
+In the actual implementation, the
+.I groff
+output device
+.I \%latin1
+is chosen for
+.IR \%text\~modes .
+.
+This can be changed by specifying option
+.B -T
+or
+.BR \%--device .
+.
+.
+.P
+The pager to be used can be specified by one of the options
+.B --pager
+and
+.BR --tty\-viewer ,
+or by the environment variable
+.Env_var \%$PAGER .
+If all of this is not used the
+.BR \%less (1)
+program with the option
+.B -r
+for correctly displaying control sequences is used as the default
+pager.
+.
+.
+.\" --------------------------------------------------------------------
+.SS "Special Modes for Debugging and Development"
+.\" --------------------------------------------------------------------
+.
+These modes use the
+.I \%groffer
+file determination and decompression.
+.
+This is combined into a single input file that is fed directly into
+.B \%groff
+with different strategy without the
+.I \%groffer
+viewing facilities.
+.
+These modes are regarded as advanced, they are useful for debugging
+and development purposes.
+.
+.
+.P
+The
+.I \%source\~mode
+with option
+.B --source
+just displays the decompressed input.
+.
+.
+.P
+Otion
+.B --to\-stdout
+does not display in a graphical mode.
+.
+It just generates the file for the chosen mode and then prints its
+content to standard output.
+.
+.
+.P
+The
+.I \%groff\~mode
+passes the input to
+.B \%groff
+using only some suitable options provided to
+.BR \%groffer .
+.
+This enables the user to save the generated output into a file or pipe
+it into another program.
+.
+.
+.P
+In
+.IR \%groff\~\%mode ,
+the option
+.B -Z
+disables post-processing, thus producing the
+.nh
+.I groff intermediate
+.IR output .
+.hy
+.
+In this mode, the input is formatted, but not postprocessed; see
+.BR \%groff_out (@MAN5EXT@)
+for details.
+.
+.
+.P
+All
+.B \%groff
+short options are supported by
+.BR \%groffer .
+.
+.
+.\" --------------------------------------------------------------------
+.SH "MAN PAGE SEARCHING"
+.\" --------------------------------------------------------------------
+.
+The default behavior of
+.B \%groffer
+is to first test whether a file parameter represents a local file; if
+it is not an existing file name, it is assumed to represent the name
+of a
+.IR \%man\~page .
+The following options can be used to determine whether the arguments
+should be handled as file name or
+.I \%man\~page
+arguments.
+.
+.TP
+.B --man
+forces to interpret all file parameters as
+.I \%filespecs
+for searching
+.IR \%man\~pages .
+.
+.TP
+.B --no\-man
+.TQ
+.B --local\-file
+disable the
+.I man
+searching; so only local files are displayed.
+.
+.
+.P
+If neither a local file nor a
+.I \%man\~page
+was retrieved for some file parameter a warning is issued on standard
+error, but processing is continued.
+.
+.
+.\" --------------------------------------------------------------------
+.SS "Search Algorithm"
+.\" --------------------------------------------------------------------
+.
+Let us now assume that a
+.I \%man\~page
+should be searched.
+.
+The
+.B \%groffer
+program provides a search facility for
+.IR \%man\~pages .
+.
+All long options, all environment variables, and most of the
+functionality of the \f[CR]GNU\fP
+.BR \%man (1)
+program were implemented.
+.
+The search algorithm shall determine which file is displayed for a given
+.IR \%man\~page .
+The process can be modified by options and environment variables.
+.
+.
+.P
+The only
+.I man
+action that is omitted in
+.B \%groffer
+are the preformatted
+.IR \%man\~pages ,
+also called
+.IR cat\~pages .
+.
+With the excellent performance of the actual computers, the
+preformatted
+.I \%man\~pages
+aren't necessary any longer.
+.
+Additionally,
+.B \%groffer
+is a
+.I roff
+program; it wants to read
+.I roff
+source files and format them itself.
+.
+.
+.P
+The algorithm for retrieving the file for a
+.I \%man\~page
+needs first a set of directories.
+.
+This set starts with the so-called
+.I man\~path
+that is modified later on by adding names of
+.I operating system
+and
+.IR language .
+.
+This arising set is used for adding the section directories which
+contain the
+.I \%man\~page
+files.
+.
+.
+.P
+The
+.I man\~path
+is a list of directories that are separated by colon.
+.
+It is generated by the following methods.
+.
+.Topic
+The environment variable
+.Env_var \%$MANPATH
+can be set.
+.
+.Topic
+It can be read from the arguments of the environment variable
+.Env_var \%$MANOPT .
+.
+.Topic
+The
+.I man\~path
+can be manually specified by using the option
+.BR --manpath .
+An empty argument disables the
+.I \%man\~page
+searching.
+.
+.Topic
+When no
+.I man\~path
+was set the
+.BR \%manpath (1)
+program is tried to determine one.
+.
+.Topic
+If this does not work a reasonable default path from
+.Env_var $PATH
+is determined.
+.
+.
+.P
+We now have a starting set of directories.
+.
+The first way to change this set is by adding names of
+.I operating
+.IR systems .
+.
+This assumes that
+.I \%man\~pages
+for several
+.I operating systems
+are installed.
+.
+This is not always true.
+.
+The names of such
+.I operating systems
+can be provided by 3 methods.
+.
+.Topic
+The environment variable
+.Env_var \%$SYSTEM
+has the lowest precedence.
+.
+.Topic
+This can be overridden by an option in
+.Env_var \%$MANOPT .
+.
+.Topic
+This again is overridden by the command line option
+.BR --systems .
+.
+.
+.P
+Several names of
+.I operating systems
+can be given by appending their names, separated by a comma.
+.
+.
+.P
+The
+.I man\~path
+is changed by appending each
+.I system
+name as subdirectory at the end of each directory of the set.
+.
+No directory of the
+.I man\~path
+set is kept.
+.
+But if no
+.I system
+name is specified the
+.I man\~path
+is left unchanged.
+.
+.
+.P
+After this, the actual set of directories can be changed by
+.I language
+information.
+.
+This assumes that there exist
+.I man\~pages
+in different languages.
+.
+The wanted
+.I language
+can be chosen by several methods.
+.
+.Topic
+Environment variable
+.Env_var $LANG .
+.
+.Topic
+This is overridden by
+.Env_var \%$LC_MESSAGES .
+.
+.Topic
+This is overridden by
+.Env_var $LC_ALL .
+.
+.Topic
+This can be overridden by providing an option in
+.Env_var \%$MANOPT .
+.
+.Topic
+All these environment variables are overridden by the command line
+option
+.BR --locale .
+.
+.
+.P
+The
+.I default language
+can be specified by specifying one of the pseudo-language parameters
+\f[CR]C\fP or \f[CR]\%POSIX\fP.
+.
+This is like deleting a formerly given
+.I language
+information.
+.
+The
+.I \%man\~pages
+in the
+.I default language
+are usually in English.
+.
+.
+.P
+Of course, the
+.I language
+name is determined by
+.BR man .
+In \f[CR]GNU\fP
+.BR man ,
+it is specified in the \%\f[CR]POSIX\~1003.1\fP based format:
+.P
+.nh
+\f[I]<language>\f[][\f[CB]_\f[]\f[I]<territory>\f[][\f[CB].\fP\
+\f[I]<character-set>\f[][\f[CB],\fP\f[I]<version>\fP]]],
+.hy
+.P
+but the two-letter code in
+.nh
+.I <language>
+.hy
+is sufficient for most purposes.
+.
+If for a complicated
+.I language
+formulation no
+.I \%man\~pages
+are found
+.B \%groffer
+searches the country part consisting of these first two characters as
+well.
+.
+.
+.P
+The actual directory set is copied thrice.
+.
+The
+.I language
+name is appended as subdirectory to each directory in the first copy
+of the actual directory set (this is only done when a language
+information is given).
+.
+Then the 2-letter abbreviation of the
+.I language
+name is appended as subdirectories to the second copy of the directory
+set (this is only done when the given language name has more than 2
+letters).
+.
+The third copy of the directory set is kept unchanged (if no
+.I language
+information is given this is the kept directory set).
+.
+These maximally 3 copies are appended to get the new directory set.
+.
+.
+.P
+We now have a complete set of directories to work with.
+.
+In each of these directories, the
+.I man
+files are separated in
+.IR sections .
+.
+The name of a
+.I section
+is represented by a single character, a digit between
+.I 1
+and
+.IR 9 ,
+or the character
+.I o
+or
+.IR n ,
+in this order.
+.
+.
+.P
+For each available
+.IR section ,
+a subdirectory
+.File_name man \fI<section>\fP
+exists containing all
+.I man
+files for this
+.IR section ,
+where
+.I <section>
+is a single character as described before.
+.
+Each
+.I man
+file in a
+.I section
+directory has the form
+.IR \%\f[CB]man\fP<section>\f[CB]/\fP<name>\f[CB].\fP<section>\
+[<extension>][\f[CB].\fP<compression>] ,
+where
+.I \%<extension>
+and
+.I \%<compression>
+are optional.
+.
+.I \%<name>
+is the name of the
+.I \%man\~page
+that is also specified as filespec argument on the command line.
+.
+.
+.P
+The
+.I extension
+is an addition to the section.
+.
+This postfix acts like a subsection.
+.
+An
+.I extension
+occurs only in the file name, not in name of the
+.I section
+subdirectory.
+.
+It can be specified on the command line.
+.
+.
+.P
+On the other hand, the
+.I compression
+is just an information on how the file is compressed.
+.
+This is not important for the user, such that it cannot be specified
+on the command line.
+.
+.
+.P
+There are 4 methods to specify a
+.I section
+on the command line:
+.
+.Topic
+Environment variable
+.Env_var \%$MANSECT
+.
+.Topic
+Command line option
+.B --sections
+.
+.Topic
+Appendix to the
+.I name
+argument in the form
+.I <name>.<section>
+.
+.Topic
+Preargument before the
+.I name
+argument in the form
+.I <section> <name>
+.
+.
+.P
+It is also possible to specify several
+.I sections
+by appending the single characters separated by colons.
+.
+One can imagine that this means to restrict the
+.I \%man\~page
+search to only some
+.IR sections .
+.
+The multiple
+.I sections
+are only possible for
+.Env_var \%$MANSECT
+and
+.BR --sections .
+.
+.
+.P
+If no
+.I section
+is specified all
+.I sections
+are searched one after the other in the given order, starting with
+.IR section\~1 ,
+until a suitable file is found.
+.
+.
+.P
+There are 4 methods to specify an
+.I extension
+on the command line.
+.
+But it is not necessary to provide the whole extension name, some
+abbreviation is good enough in most cases.
+.
+.Topic
+Environment variable
+.Env_var \%$EXTENSION
+.
+.Topic
+Command line option
+.B --extension
+.
+.Topic
+Appendix to the
+.I <name>.<section>
+argument in the form
+.I <name>.<section><extension>
+.
+.Topic
+Preargument before the
+.I name
+argument in the form
+.I <section><extension> <name>
+.
+.
+.P
+For further details on
+.I \%man\~page
+searching, see
+.BR \%man (1).
+.
+.
+.\" --------------------------------------------------------------------
+.SS "Examples of man files"
+.\" --------------------------------------------------------------------
+.
+.TP
+.File_name /usr/share/man/man1/groff.1
+This is an uncompressed file for the
+.I \%man\~page
+\f[CR]groff\fP in
+.IR section\~1 .
+.
+It can be called by
+.EX
+\fIsh#\fR groffer\~groff
+.EE
+No
+.I section
+is specified here, so all
+.I sections
+should be searched, but as
+.I section\~1
+is searched first this file will be found first.
+.
+The file name is composed of the following components.
+.File_name /usr/share/man
+must be part of the
+.IR \%man\~path ;
+the subdirectory
+.File_name man1/
+and the part
+.File_name .1
+stand for the
+.IR section ;
+.File_name groff
+is the name of the
+.IR \%man\~page .
+.
+.
+.TP
+.File_name /usr/local/share/man/man7/groff.7.gz
+The file name is composed of the following components.
+.File_name /usr/local/share/man
+must be part of the
+.IR \%man\~path ;
+the subdirectory
+.File_name man7/
+and the part
+.File_name .7
+stand for the
+.IR section ;
+.File_name groff
+is the name of the
+.IR \%man\~page ;
+the final part
+.File_name .gz
+stands for a compression with
+.BR gzip (1).
+As the
+.I section
+is not the first one it must be specified as well.
+.
+This can be done by one of the following commands.
+.EX
+\fIsh#\fR\~groffer\~groff.7
+\fIsh#\fR\~groffer\~7\~groff
+\fIsh#\fR\~groffer\~\-\-sections=7\~groff
+.EE
+.
+.TP
+.File_name /usr/local/man/man1/ctags.1emacs21.bz2
+Here
+.File_name /usr/local/man
+must be in
+.IR \%man\~path ;
+the subdirectory
+.File_name man1/
+and the file name part
+.File_name .1
+stand for
+.IR section\~1 ;
+the name of the
+.I \%man\~page
+is
+.File_name ctags ;
+the section has an extension
+.File_name emacs21 ;
+and the file is compressed as
+.File_name .bz2
+with
+.BR bzip2 (1).
+The file can be viewed with one of the following commands
+.EX
+\fIsh#\fR\~groffer\~ctags.1e
+\fIsh#\fR\~groffer\~1e\~ctags
+\fIsh#\fR\~groffer\~\-\-extension=e\~\-\-sections=1\~ctags
+.EE
+where \f[CR]e\fP works as an abbreviation for the extension
+\f[CR]emacs21\fP.
+.
+.
+.TP
+.File_name /usr/man/linux/de/man7/man.7.Z
+The directory
+.File_name /usr/man
+is now part of the
+.IR \%man\~path ;
+then there is a subdirectory for an
+.I operating system
+name
+.File_name linux/ ;
+next comes  a subdirectory
+.File_name de/
+for the German
+.IR language ;
+the
+.I section
+names
+.File_name man7
+and
+.File_name .7
+are known so far;
+.File_name man
+is the name of the
+.IR \%man\~page ;
+and
+.File_name .Z
+signifies the compression that can be handled by
+.BR gzip (1).
+We want now show how to provide several values for some options.
+.
+That is possible for
+.I sections
+and
+.I operating system
+names.
+.
+So we use as
+.I sections\~5
+and
+.I 7
+and as
+.I system
+names
+.I linux
+and
+.IR aix .
+The command is then
+.sp
+.EX
+\fIsh#\fR groffer\~\-\-locale=de\~\-\-sections=5:7\~\-\-systems=linux,aix\~man
+\fIsh#\fR LANG=de\~MANSECT=5:7\~SYSTEM=linux,aix\~groffer\~man
+.EE
+.
+.
+.\" --------------------------------------------------------------------
+.SH DECOMPRESSION
+.\" --------------------------------------------------------------------
+.
+The program has a decompression facility.
+.
+If standard input or a file that was retrieved from the command line
+parameters is compressed with a format that is supported by either
+.BR \%gzip (1)
+or
+.BR \%bzip2 (1)
+it is decompressed on-the-fly.
+.
+This includes the \f[CR]GNU\fP
+.BR \%.gz ,
+.BR \%.bz2 ,
+and the traditional
+.B \%.Z
+compression.
+.
+The program displays the concatenation of all decompressed input in
+the sequence that was specified on the command line.
+.
+.
+.\" --------------------------------------------------------------------
+.SH "ENVIRONMENT"
+.\" --------------------------------------------------------------------
+.
+The
+.B \%groffer
+program supports many system variables, most of them by courtesy of
+other programs.
+.
+All environment variables of
+.BR \%groff (@MAN1EXT@)
+and \f[CR]GNU\fP
+.BR \%man (1)
+and some standard system variables are honored.
+.
+.
+.\" --------------------------------------------------------------------
+.SS "Native groffer Variables"
+.\" --------------------------------------------------------------------
+.
+.TP
+.Env_var \%$GROFFER_OPT
+Store options for a run of
+.BR \%groffer .
+.
+The options specified in this variable are overridden by the options
+given on the command line.
+.
+The content of this variable is run through the shell builtin `eval';
+so arguments containing white-space or special shell characters should
+be quoted.
+.
+Do not forget to export this variable, otherwise it does not exist
+during the run of
+.BR groffer .
+.
+.
+.\" --------------------------------------------------------------------
+.SS "System Variables"
+.\" --------------------------------------------------------------------
+.
+The
+.B \%groffer
+program is a shell script that is run through
+.File_name /bin/sh ,
+which can be internally linked to programs like
+.BR \%bash (1).
+The corresponding system environment is automatically effective.
+.
+The following variables have a special meaning for
+.BR \%groffer .
+.
+.
+.TP
+.Env_var \%$DISPLAY
+If this variable is set this indicates that the \%\f[CR]X\~Window\fP
+system is running.
+.
+Testing this variable decides on whether graphical or text output is
+generated.
+.
+This variable should not be changed by the user carelessly, but it can
+be used to start the graphical
+.B \%groffer
+on a remote \%\f[CR]X\~Window\fP terminal.
+.
+For example, depending on your system,
+.B \%groffer
+can be started on the second monitor by the command
+.sp
+.EX
+\fIsh#\fR DISPLAY=:0.1\~groffer\~what.ever &
+.EE
+.
+.
+.TP
+.Env_var \%$LC_ALL
+.TQ
+.Env_var \%$LC_MESSAGES
+.TQ
+.Env_var $LANG
+If one of these variables is set (in the above sequence), its content
+is interpreted as the locale, the language to be used, especially when
+retrieving
+.IR \%man\~pages .
+.
+A locale name is typically of the form
+.nh
+.IR language [\c
+.B _\c
+.IR territory [\c
+.B .\c
+.IR codeset [\c
+.B @\c
+.IR modifier ]]],
+.hy
+where
+.I \%language
+is an ISO 639 language code,
+.I \%territory
+is an ISO 3166 country code, and
+.I \%codeset
+is a character set or encoding identifier like ISO-8859-1 or UTF-8;
+see
+.BR \%setlocale (3).
+.
+The locale values \f[CR]C\fP and \%\f[CR]POSIX\fP
+stand for the default, i.e. the
+.I \%man\~page
+directories without a language prefix.
+.
+This is the same behavior as when all 3\~variables are unset.
+.
+.
+.TP
+.Env_var \%$PAGER
+This variable can be used to set the pager for the tty output.
+.
+For example, to disable the use of a pager completely set this
+variable to the
+.BR \%cat (1)
+program
+.sp
+.EX
+\fIsh#\fR PAGER=cat\~groffer\~anything
+.EE
+.sp
+.
+.TP
+.Env_var $PATH
+All programs within the
+.B \%groffer
+shell script are called without a fixed path.
+.
+Thus this environment variable determines the set of programs used
+within the run of
+.BR \%groffer .
+.
+.
+.\" --------------------------------------------------------------------
+.SS "Groff Variables"
+.\" --------------------------------------------------------------------
+.
+The
+.B \%groffer
+program internally calls
+.BR \%groff ,
+so all environment variables documented in
+.BR \%groff (@MAN1EXT@)
+are internally used within
+.B \%groffer
+as well.
+.
+The following variable has a direct meaning for the
+.B \%groffer
+program.
+.
+.TP
+.Env_var \%$GROFF_TMPDIR
+If the value of this variable is an existing, writable directory,
+.B \%groffer
+uses it for storing its temporary files, just as
+.B groff
+does.
+.
+See the
+.BR \%groff (@MAN1EXT@)
+man page for more details on the location of temporary files.
+.
+.
+.\" --------------------------------------------------------------------
+.SS "Man Variables"
+.\" --------------------------------------------------------------------
+.
+Parts of the functionality of the
+.B man
+program were implemented in
+.BR \%groffer ;
+support for all environment variables documented in
+.BR \%man (1)
+was added to
+.BR \%groffer ,
+but the meaning was slightly modified due to the different approach in
+.BR \%groffer ;
+but the user interface is the same.
+.
+The
+.B man
+environment variables can be overwritten by options provided with
+.Env_var \%$MANOPT ,
+which in turn is overwritten by the command line.
+.
+.
+.TP
+.Env_var \%$EXTENSION
+Restrict the search for
+.I \%man\~pages
+to files having this extension.
+.
+This is overridden by option
+.BR --extension ;
+see there for details.
+.
+.
+.TP
+.Env_var \%$MANOPT
+This variable contains options as a preset for
+.BR \%man (1).
+As not all of these are relevant for
+.B \%groffer
+only the essential parts of its value are extracted.
+.
+The options specified in this variable overwrite the values of the
+other environment variables that are specific to
+.IR man .
+.
+All options specified in this variable are overridden by the options
+given on the command line.
+.
+.
+.TP
+.Env_var \%$MANPATH
+If set, this variable contains the directories in which the
+.I \%man\~page
+trees are stored.
+.
+This is overridden by option
+.BR \%--manpath .
+.
+.
+.TP
+.Env_var \%$MANSECT
+If this is a colon separated list of section names, the search for
+.I \%man\~pages
+is restricted to those manual sections in that order.
+.
+This is overridden by option
+.BR --sections .
+.
+.
+.TP
+.Env_var \%$SYSTEM
+If this is set to a comma separated list of names these are interpreted
+as
+.I \%man\~page
+trees for different operating systems.
+.
+This variable can be overwritten by option
+.BR --systems ;
+see there for details.
+.
+.
+.P
+The environment variable
+.Env_var \%$MANROFFSEQ
+is ignored by
+.B \%groffer
+because the necessary preprocessors are determined automatically.
+.
+.
+.\" --------------------------------------------------------------------
+.SH "CONFIGURATION FILES"
+.\" --------------------------------------------------------------------
+.
+The
+.B \%groffer
+program can be preconfigured by two configuration files.
+.
+.
+.TP
+.File_name \%/etc/groff/groffer.conf
+System-wide configuration file for
+.BR \%groffer .
+.
+.
+.TP
+.File_name \%$HOME/.groff/groffer.conf
+User-specific configuration file for
+.BR \%groffer ,
+where
+.Env_var \%$HOME
+denotes the user's home directory.
+.
+This file is called after the system-wide configuration file to enable
+overriding by the user.
+.
+.
+.P
+Both files are handled for the configuration, but the configuration
+file in
+.File_name /etc
+comes first; it is overwritten by the configuration file in the home
+directory; both configuration files are overwritten by the environment
+variable
+.Env_var \%$GROFFER_OPT ;
+everything is overwritten by the command line arguments.
+.
+.
+.P
+In the configuration files, arbitrary spaces are allowed at the
+beginning of each line, they are just ignored.
+.
+Apart from that, the lines of the configuration lines either start
+with a minus character, all other lines are interpreted as shell
+commands.
+.
+.
+.P
+The lines with the beginning minus are interpreted as
+.B groffer
+options.
+.
+This easily allows to set general
+.B \%groffer
+options that should be used with any call of
+.BR \%groffer .
+.
+.
+.P
+If a lines starts with a double minus it represents a
+.B \%groffer
+long option; everything behind the first equal sign
+.RB ` = '
+or space character up to the end of the line is interpreted as its
+argument.
+.
+A line starting with a single minus represents a short options cluster
+with or without a final argument.
+.
+It is not necessary to use quotes in these lines; quotes are just
+ignored.
+.
+.
+.P
+The lines starting with a minus are changed into a prepend to the
+existing value of
+.Env_var \%$GROFFER_OPT .
+.
+So the configuration files will be transferred into a shell script
+that is called within
+.BR \%groffer .
+.
+.
+.P
+It makes sense to use these configuration files for the following
+tasks:
+.
+.Topic
+Preset command line options, such as choosing a
+.I \%mode
+or a viewer.
+.
+These are written into lines starting with a single or double minus
+sign, followed by the option name.
+.
+.Topic
+Preset environment variables recognized by
+.BR \%groffer ;
+but do not forget to export them.
+.
+.Topic
+You can also write a shell function for calling, for example a viewer
+program for some
+.IR \%mode .
+Such a function can be fed into a corresponding
+.B --\f[I]mode\fP\-viewer
+option.
+.
+.Topic
+Enter
+.B --shell
+to specify a shell for the run of
+.File_name groffer2.sh .
+Some shells run much faster than the standard shell.
+.
+.
+.P
+As an example, consider the following configuration file that can be
+used either in
+.File_name \%/etc/groff/groffer.conf
+or
+.File_name \%~/.groff/groffer.conf .
+.
+.
+.P
+.ft CR
+.nh
+.nf
+# groffer configuration file
+#
+# groffer options that are used in each call of groffer
+\-\-shell=ksh
+\-\-foreground=DarkBlue
+\-\-resolution=100
+\-\-x\-viewer=gxditview \-geometry 900x1200
+#
+# some shell commands
+if test "$DISPLAY" = ""; then
+  export DISPLAY='localhost:0.0'
+fi
+date >>~/mygroffer.log
+.fi
+.hy
+.ft
+.
+.
+.P
+The lines starting with
+.B #
+are just ignored, so they act as command lines.
+.
+This configuration sets four
+.B \%groffer
+options (the lines starting with `\-') and runs two shell commands (the
+rest of the script).
+.
+This has the following effects:
+.
+.
+.Topic
+Use
+.B ksh
+as the shell to run the
+.B \%groffer
+script; if it works it should be faster than the usual
+.BR sh .
+.
+.
+.Topic
+Use a text color of
+.B \%DarkBlue
+in all viewers that support this, such as
+.BR \%gxditview .
+.
+.
+.Topic
+Use a resolution of
+.B 100dpi
+in all viewers that support this, such as
+.BR \%gxditview .
+.
+By this, the default device in
+.I x mode
+is set to
+.BR X100 .
+.
+.
+.Topic
+Force
+.BR \%gxditview (@MAN1EXT@)
+as the
+.I \%x-mode
+viewer using the geometry option for setting the width to
+.B 900px
+and the height to
+.BR 1200px .
+This geometry is suitable for a resolution of
+.BR 100dpi .
+.
+.
+.Topic
+If the environment variable
+.Env_var \%$DISPLAY
+is empty set it to
+.IR localhost:0.0 .
+.
+That allows to start
+.B \%groffer
+in the standard \%\f[CR]X\~Window\fP display, even when the program
+is called from a text console.
+.
+.
+.Topic
+Just for fun, the date of each
+.B \%groffer
+start is written to the file
+.File_name mygroffer.log
+in the home directory.
+.
+.
+.\" --------------------------------------------------------------------
+.SH "EXAMPLES"
+.\" --------------------------------------------------------------------
+.
+The usage of
+.B \%groffer
+is very easy.
+.
+Usually, it is just called with a file name or
+.IR \%man\~page .
+.
+The following examples, however, show that
+.B \%groffer
+has much more fancy capabilities.
+.
+.sp
+.EX
+\fIsh#\fR\~groffer\~/usr/local/share/doc/groff/meintro.ms.gz
+.EE
+.sp
+Decompress, format and display the compressed file
+.File_name meintro.ms.gz
+in the directory
+.File_name /usr/local/share/doc/groff ,
+using the standard viewer
+.B \%gxditview
+as graphical viewer when in \%\f[CR]X\~Window\fP, or the
+.BR \%less (1)
+pager program when not in \%\f[CR]X\~Window\fP.
+.
+.sp
+.EX
+\fIsh#\fR\~groffer\~groff
+.EE
+.sp
+If the file
+.File_name \%./groff
+exists use it as input.
+.
+Otherwise interpret the argument as a search for the
+.I \%man\~page
+named
+.B \%groff
+in the smallest possible
+.IR \%man\~section ,
+being section 1 in this case.
+.
+.sp
+.EX
+\fIsh#\fR\~groffer\~man:groff
+.EE
+.sp
+search for the
+.I \%man\~page
+of
+.B \%groff
+even when the file
+.File_name ./groff
+exists.
+.
+.sp
+.EX
+\fIsh#\fR\~groffer\~groff.7
+\fIsh#\fR\~groffer\~7\~groff
+.EE
+.sp
+search the
+.I \%man\~page
+of
+.B \%groff
+in
+.I \%man\~section
+.BR 7 .
+This section search works only for a digit or a single character from
+a small set.
+.
+.sp
+.EX
+\fIsh#\fR\~groffer\~fb.modes
+.EE
+.sp
+If the file
+.File_name ./fb.modes
+does not exist interpret this as a search for the
+.I \%man\~page
+of
+.BR fb.modes .
+As the extension
+.I \%modes
+is not a single character in classical section style the argument is
+not split to a search for
+.BR fb .
+.
+.sp
+.EX
+\fIsh#\fR\~groffer\~groff\~\[cq]troff(1)\[cq]\~man:roff
+.EE
+.sp
+The arguments that are not existing files are looked-up as the
+following
+.IR \%man\~pages :
+.B \%groff
+(automatic search, should be found in \fIman\fP\~section\~1),
+.B \%troff
+(in section\~1),
+and
+.B \%roff
+(in the section with the lowest number, being\~7 in this case).
+.
+The quotes around
+.nh
+.I \[cq]troff(1)\[cq]
+.hy
+are necessary because the parentheses are special shell characters;
+escaping them with a backslash character
+.I \[rs](
+and
+.I \[rs])
+would be possible, too.
+.
+The formatted files are concatenated and displayed in one piece.
+.
+.sp
+.EX
+\fIsh#\fR\~LANG=de\~groffer\~--man\~--www\~--www-viewer=galeon\~ls
+.EE
+.sp
+Retrieve the German
+.I \%man\~page
+(language
+.IR de )
+for the
+.B ls
+program, decompress it, format it to
+.I \%html
+format
+.nh
+.RI ( \%www\~mode )
+.hy
+and view the result in the web browser
+.BR \%galeon .
+The option
+.B --man
+guarantees that the
+.I \%man\~page
+is retrieved, even when a local file
+.File_name \%ls
+exists in the actual directory.
+.
+.
+.sp
+.EX
+\fIsh#\fR\~groffer\~--source\~'man:roff(7)'
+.EE
+.sp
+Get the
+.I \%man\~page
+called
+.I \%roff
+in \fIman\fP\~section 7, decompress it, and print its unformatted
+content, its source code.
+.
+.
+.sp
+.EX
+\fIsh#\fR\~groffer\~--de-p\~--in\~--ap
+.EE
+.sp
+This is a set of abbreviated arguments, it is determined as
+.br
+.sp
+.EX
+\fIsh#\fR\~groffer\~--debug-params\~--intermediate-output\~--apropos
+.EE
+.sp
+.
+.sp
+.EX
+\fIsh#\fR\~cat\~file.gz\~|\~groffer\~-Z\~-mfoo
+.EE
+.sp
+.
+The file
+.File_name file.gz
+is sent to standard input, this is decompressed, and then this is
+transported to the
+.I \%groff intermediate output mode
+without post-processing
+.RB ( groff
+option
+.BR -Z ),
+using macro package
+.I \%foo
+.RB ( groff
+option
+.BR -m ).
+.
+.
+.sp
+.EX
+\fIsh#\fR\~echo\~'\[rs]f[CB]WOW!'\~|
+> groffer --x --bg red --fg yellow --geometry 200x100 -
+.EX
+.sp
+.
+Display the word \f[CB]WOW!\fP in a small window in constant-width
+bold font, using color yellow on red background.
+.
+.
+.\" --------------------------------------------------------------------
+.SH "COMPATIBILITY"
+.\" --------------------------------------------------------------------
+.
+The
+.B \%groffer
+program consists of two shell scripts.
+.
+.
+.P
+The starting script is the file
+.File_name \%groffer
+that is installed in a
+.File_name bin
+directory.
+.
+It is generated from the source file
+.File_name \%groffer.sh .
+.
+It is just a short starting script without any functions such that it
+can run on very poor shells.
+.
+.
+.P
+The main part of the
+.B \%groffer
+program is the file
+.File_name groffer2.sh
+that is installed in the
+.I groff
+library directory.
+.
+This script can be run under a different shell by using the
+.B \%groffer
+option
+.BR --shell .
+.
+.
+.P
+Both scripts are compatible with both
+\f[CR]GNU\fP and \%\f[CR]POSIX\fP.
+.
+\%\f[CR]POSIX\fP compatibility refers to
+\%\f[CR]IEEE\~P1003.2/D11.2\fP of September 1991, a very early
+version of the \%\f[CR]POSIX\fP standard that is still freely
+available on the Internet at
+.UR http://\:www.funet.fi/\:pub/\:doc/\:posix/\:p1003.2/\:d11.2/\:all
+\%POSIX\~P1003.2\~draft\~11.2
+.UE .
+.
+.
+.P
+Only a restricted set of shell language elements and shell builtins is
+used to achieve even compatibility with some Bourne shells that are
+not fully \%\f[CR]POSIX\fP compatible.
+.
+The
+.B \%groffer
+shell scripts were tested on many shells, including the following
+Bourne shells:
+.BR \%ash (1),
+.BR \%bash (1),
+.BR \%dash (1),
+.BR \%ksh (1),
+.BR \%pdksh (1),
+.BR \%posh (1),
+and
+.BR \%zsh (1).
+So it should work on most actual free and commercial operating
+systems.
+.
+.
+.P
+The shell for the run of
+.File_name groffer2.sh
+can be chosen by the option
+.BR --shell
+on the command line or the environment variable
+.Env_var $GROFF_OPT .
+If you want to add it to one of the
+.B \%groffer
+configuration files you must write a line starting with
+.BR --shell .
+.
+.
+.P
+The
+.B \%groffer
+program provides its own parser for command line arguments that is
+compatible to both \%\f[CR]POSIX\fP
+.BR \%getopts (1)
+and \%\f[CR]GNU\fP
+.BR \%getopt (1).
+It can handle option arguments and file names containing white space
+and a large set of special characters.
+.
+The following standard types of options are supported.
+.
+.
+.Topic
+The option consisting of a single minus
+.B -
+refers to standard input.
+.
+.
+.Topic
+A single minus followed by characters refers to a single character
+option or a combination thereof; for example, the
+.B \%groffer
+short option combination
+.B -Qmfoo
+is equivalent to
+.BR -Q\~\-m\~foo .
+.
+.
+.Topic
+Long options are options with names longer than one character; they
+are always preceded by a double minus.
+.
+An option argument can either go to the next command line argument or
+be appended with an equal sign to the argument; for example,
+.B --long=arg
+is equivalent to
+.BR --long\~arg .
+.
+.
+.Topic
+An argument of
+.B --
+ends option parsing; all further command line arguments are
+interpreted as
+.I \%filespec
+parameters, i.e. file names or constructs for searching
+.IR \%man\~pages ).
+.
+.
+.Topic
+All command line arguments that are neither options nor option
+arguments are interpreted as
+.I \%filespec
+parameters and stored until option parsing has finished.
+.
+For example, the command line
+.sp
+.EX
+\fIsh#\fR\~groffer file1 -a -o arg file2
+.EE
+.sp
+is equivalent to
+.sp
+.EX
+\fIsh#\fR\~groffer -a -o arg -- file1 file2
+.EE
+.sp
+.
+.P
+The free mixing of options and
+.I \%filespec
+parameters follows the GNU principle.
+.
+That does not fulfill the strange option behavior of \%\f[CR]POSIX\fP
+that ends option processing as soon as the first non-option argument
+has been reached.
+.
+The end of option processing can be forced by the option
+.RB ` \-\- '
+anyway.
+.
+.
+.\" --------------------------------------------------------------------
+.SH "BUGS"
+.\" --------------------------------------------------------------------
+.
+Report bugs to the
+.MT bug-groff@gnu.org
+bug-groff mailing list 
+.ME .
+.
+Include a complete, self-contained example that will allow the bug to
+be reproduced, and say which version of
+.B \%groffer
+you are using.
+.
+.
+.P
+You can also use the
+.MT groff@gnu.org
+groff mailing list
+.ME ,
+but you must first subscribe to this list.
+.
+You can do that by visiting the
+.UR http://\:lists.gnu.org/\:mailman/\:listinfo/\:groff
+groff mailing list web page
+.UE .
+.
+.
+.P
+See
+.BR \%groff (@MAN1EXT@)
+for information on availability.
+.
+.
+.\" --------------------------------------------------------------------
+.SH "SEE ALSO"
+.\" --------------------------------------------------------------------
+.
+.P
+.BR \%groff (@MAN1EXT@),
+.BR \%@g@troff (@MAN1EXT@)
+.RS
+Details on the options and environment variables available in
+.BR \%groff ;
+all of them can be used with
+.BR \%groffer .
+.RE
+.
+.
+.TP
+.BR \%groff (@MAN7EXT@)
+Documentation of the
+.I \%groff
+language.
+.
+.
+.TP
+.BR \%grog (@MAN1EXT@)
+Internally,
+.B \%groffer
+tries to guess the
+.B \%groff
+command line options from the input using this program.
+.
+.
+.TP
+.BR groff_out (@MAN5EXT@)
+Documentation on the
+.I \%groff intermediate output
+.nh
+.RI ( ditroff
+output).
+.hy
+.
+.
+.TP
+.BR groff_tmac (@MAN5EXT@)
+Documentation on the
+.I \%groff
+macro files.
+.
+.
+.TP
+.BR \%man (1)
+The standard program to display
+.IR \%man\~pages .
+.
+The information there is only useful if it is the
+.I \%man\~page
+for GNU
+.BR man .
+Then it documents the options and environment variables that are
+supported by
+.BR \%groffer .
+.
+.
+.P
+.BR \%ash (1),
+.BR \%bash (1),
+.BR \%dash (1),
+.BR \%ksh (1),
+.BR \%pdksh (1),
+.BR \%posh (1),
+.BR \%sh (1),
+.BR \%zsh (1)
+.RS
+Bourne shells that were tested with
+.BR \%groffer .
+.RE
+.
+.
+.P
+.BR \%gxditview (@MAN1EXT@),
+.BR \%xditview (1x)
+.RS
+Viewers for
+.BR \%groffer 's
+.IR \%x\~mode .
+.RE
+.
+.
+.P
+.BR \%kpdf (1),
+.BR \%kghostview (1),
+.BR \%evince (1),
+.BR \%ggv (1),
+.BR \%gv (1),
+.BR \%ghostview (1),
+.BR \%gs (1)
+.RS
+Viewers for
+.BR \%groffer 's
+.IR \%ps\~mode .
+.RE
+.
+.
+.P
+.BR \%kpdf (1),
+.BR \%acroread (1),
+.BR \%evince (1),
+.BR \%xpdf (1),
+.BR \%gpdf (1),
+.BR \%kghostview (1),
+.BR \%ggv (1)
+.RS
+Viewers for
+.BR \%groffer 's
+.IR \%pdf\~mode .
+.RE
+.
+.
+.P
+.BR \%kdvi (1),
+.BR \%xdvi (1),
+.BR \%dvilx (1)
+.RS
+Viewers for
+.BR \%groffer 's
+.IR \%dvi\~mode .
+.RE
+.
+.
+.P
+.BR \%konqueror (1),
+.BR \%epiphany (1),
+.BR \%firefox (1),
+.BR \%mozilla (1),
+.BR \%netscape (1),
+.BR \%lynx (1)
+.RS
+Web-browsers for
+.BR \%groffer 's
+.I \%html
+or
+.IR \%www\~mode .
+.RE
+.
+.
+.TP
+.BR \%less (1)
+Standard pager program for the
+.IR \%tty\~mode .
+.
+.
+.P
+.BR \%gzip (1),
+.BR \%bzip2 (1)
+.RS
+The decompression programs supported by
+.BR \%groffer .
+.RE
+.
+.
+.\" --------------------------------------------------------------------
+.SH "AUTHOR"
+.\" --------------------------------------------------------------------
+.author
+.
+.
+.\" --------------------------------------------------------------------
+.SH "COPYING"
+.\" --------------------------------------------------------------------
+.copyleft
+.
+.
+.\" --------------------------------------------------------------------
+.\" Emacs settings
+.\" --------------------------------------------------------------------
+.
+.\" Local Variables:
+.\" mode: nroff
+.\" End:

Index: groffer.sh
===================================================================
RCS file: groffer.sh
diff -N groffer.sh
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ groffer.sh	11 Aug 2013 08:28:24 -0000	1.7
@@ -0,0 +1,384 @@
+#! /bin/sh
+
+# groffer - display groff files
+
+# Source file position: <groff-source>/contrib/groffer/groffer.sh
+# Installed position: <prefix>/bin/groffer
+
+# Copyright (C) 2001, 2002, 2003, 2004, 2005, 2006, 2009
+# Free Software Foundation, Inc.
+# Written by Bernd Warken <groff-bernd.warken-72@web.de>.
+
+# Last update: 5 Jan 2009
+
+# 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/>.
+
+########################################################################
+
+export GROFFER_OPT;		# option environment for groffer
+
+export _CONF_FILE_ETC;		# configuration file in /etc
+export _CONF_FILE_HOME;		# configuration file in $HOME
+export _CONF_FILES;		# configuration files
+_CONF_FILE_ETC='/etc/groff/groffer.conf';
+_CONF_FILE_HOME="${HOME}/.groff/groffer.conf";
+_CONF_FILES="${_CONF_FILE_ETC} ${_CONF_FILE_HOME}";
+
+# characters
+
+export _AT;
+export _SP;
+export _SQ;
+export _TAB;
+
+_AT='@';
+_SP=' ';
+_SQ="'";
+_TAB='	';
+
+export _ERROR;
+_ERROR='7';			# for syntax errors; no `-1' in `ash'
+
+# @...@ constructs
+
+export _BEFORE_MAKE;
+if test _@VERSION@_ = _${_AT}VERSION${_AT}_
+then
+  # script before `make'
+  _BEFORE_MAKE='yes';
+else
+  _BEFORE_MAKE='no';
+fi;
+
+export _AT_BINDIR_AT;
+export _AT_G_AT;
+export _AT_LIBDIR_AT;
+export _GROFFER_LIBDIR;
+case "${_BEFORE_MAKE}" in
+yes)
+  self="$0";
+  case "${self}" in
+  /*) :; ;;
+  *)
+    curdir="$(pwd)";
+    case "${curdir}" in
+    */)
+      self="${curdir}${self}";
+      ;;
+    *)
+      self="${curdir}/${self}";
+      ;;
+    esac;
+    ;;
+  esac;
+  groffer_shell_dir="$(dirname ${self})";
+  case "${groffer_shell_dir}" in
+  */) :; ;;
+  *) groffer_shell_dir="${groffer_shell_dir}/";
+  esac;
+  groffer_top_dir="${groffer_shell_dir}../";
+  _AT_G_AT='';
+  _AT_BINDIR_AT="${groffer_shell_dir}";
+  _AT_LIBDIR_AT="${groffer_shell_dir}";
+  _GROFFER_LIBDIR="${_AT_LIBDIR_AT}";
+  _VERSION_SH="${groffer_top_dir}version.sh";
+  ;;
+no)
+  _AT_G_AT='@g@';
+  _AT_BINDIR_AT='@BINDIR@';
+  case "${_AT_BINDIR_AT}" in
+  */) :; ;;
+  *) _AT_BINDIR_AT="${_AT_BINDIR_AT}/";
+  esac;
+  _AT_LIBDIR_AT='@libdir@';
+  case "${_AT_LIBDIR_AT}" in
+  */) :; ;;
+  *) _AT_LIBDIR_AT="${_AT_LIBDIR_AT}/";
+  esac;
+  _GROFFER_LIBDIR="${_AT_LIBDIR_AT}"'groff/groffer/';
+  _VERSION_SH="${_GROFFER_LIBDIR}"'version.sh';
+  ;;
+esac;
+
+if test -f "${_VERSION_SH}"
+then
+  . "${_VERSION_SH}";
+fi;
+
+export _GROFF_VERSION;
+case "${_BEFORE_MAKE}" in
+yes)
+  _GROFF_VERSION="${_GROFF_VERSION_PRESET}";
+  ;;
+no)
+  _GROFF_VERSION='@VERSION@';
+  ;;
+esac;
+
+export _GROFFER2_SH;		# file name of the script that follows up
+_GROFFER2_SH="${_GROFFER_LIBDIR}"'groffer2.sh';
+
+export _GROFFER_SH;		# file name of this shell script
+case "$0" in
+*groffer*)
+  _GROFFER_SH="$0";
+  ;;
+*)
+  echo 'The groffer script should be started directly.' >&2
+  exit 1;
+  ;;
+esac;
+
+export _NULL_DEV;
+if test -c /dev/null
+then
+  _NULL_DEV="/dev/null";
+else
+  _NULL_DEV="NUL";
+fi;
+
+
+# Test of the `$()' construct.
+if test _"$(echo "$(echo 'test')")"_ \
+     != _test_
+then
+  echo 'The "$()" construct did not work.' >&2;
+  exit "${_ERROR}";
+fi;
+
+# Test of sed program
+if test _"$(echo red | sed 's/r/s/')"_ != _sed_
+then
+  echo 'The sed program did not work.' >&2;
+  exit "${_ERROR}";
+fi;
+
+# for some systems it is necessary to set some unset variables to `C'
+# according to Autobook, ch. 22
+for var in LANG LC_ALL LC_MESSAGES LC_CTYPES LANGUAGES
+do
+  if eval test _"\${$var+set}"_ = _set_
+  then
+    eval ${var}='C';
+    eval export ${var};
+  fi;
+done;
+
+
+########################### configuration
+
+# read and transform the configuration files, execute the arising commands
+for f in "${_CONF_FILE_HOME}" "${_CONF_FILE_ETC}"
+do
+  if test -f "$f"
+  then
+    o="";			# $o means groffer option
+    # use "" quotes because of ksh and posh
+    eval "$(cat "$f" | sed -n '
+# Ignore comments
+/^['"${_SP}${_TAB}"']*#/d
+# Delete leading and final space
+s/^['"${_SP}${_TAB}"']*//
+s/['"${_SP}${_TAB}"']*$//
+# Print all lines with shell commands, those not starting with -
+/^[^-]/p
+# Remove all single and double quotes
+s/['"${_SQ}"'"]//g
+# Replace empty arguments
+s/^\(-[^ ]*\)=$/o="${o} \1 '"${_SQ}${_SQ}"'"/p
+# Replace division between option and argument by single space
+s/[='"${_SP}${_TAB}"']['"${_SP}${_TAB}"']*/'"${_SP}"'/
+# Handle lines without spaces
+s/^\(-[^'"${_SP}"']*\)$/o="${o} \1"/p
+# Encircle the remaining arguments with single quotes
+s/^\(-[^ ]*\) \(.*\)$/o="${o} \1 '"${_SQ}"'\2'"${_SQ}"'"/p
+')"
+
+    # Remove leading space
+    o="$(echo "$o" | sed 's/^ *//')";
+    if test _"${o}"_ != __
+    then
+      if test _"{GROFFER_OPT}"_ = __
+      then
+        GROFFER_OPT="${o}";
+      else
+        GROFFER_OPT="${o} ${GROFFER_OPT}";
+      fi;
+    fi;
+  fi;
+done;
+
+# integrate $GROFFER_OPT into the command line; it isn't needed any more
+if test _"${GROFFER_OPT}"_ != __
+then
+  eval set x "${GROFFER_OPT}" '"$@"';
+  shift;
+  GROFFER_OPT='';
+fi;
+
+
+########################### Determine the shell
+
+export _SHELL;
+
+supports_func=no;
+foo() { echo bar; } 2>${_NULL_DEV};
+if test _"$(foo)"_ = _bar_
+then
+  supports_func=yes;
+fi;
+
+# use "``" instead of "$()" for using the case ")" construct
+# do not use "" quotes because of ksh
+_SHELL=`
+  # $x means list.
+  # $s means shell.
+  # The command line arguments are taken over.
+  # Shifting herein does not have an effect outside.
+  export x;
+  case " $*" in
+  *\ --sh*)			# abbreviation for --shell
+    x='';
+    s='';
+    # determine all --shell arguments, store them in $x in reverse order
+    while test $# != 0
+    do
+      case "$1" in
+      --shell|--sh|--she|--shel)
+        if test "$#" -ge 2
+        then
+          s="$2";
+          shift;
+        fi;
+        ;;
+      --shell=*|--sh=*|--she=*|--shel=*)
+        # delete up to first "=" character
+        s="$(echo x"$1" | sed 's/^x[^=]*=//')";
+        ;;
+      *)
+        shift;
+        continue;
+      esac;
+      if test _"${x}"_ = __
+      then
+        x="'${s}'";
+      else
+        x="'${s}' ${x}";
+      fi;
+      shift;
+    done;
+
+    # from all possible shells in $x determine the first being a shell
+    # or being empty
+    s="$(
+      # "" quotes because of posh
+      eval set x "${x}";
+      shift;
+      if test $# != 0
+      then
+        for i
+        do
+          if test _"$i"_ = __
+          then
+            if test _"${supports_func}"_ = _yes_
+            then
+              # use the empty argument as the default shell
+              echo 'standard shell';
+              break;
+            else
+              echo groffer: standard shell does not support functions. >&2;
+              continue;
+            fi;
+          else
+            # test $i on being a shell program;
+            # use this kind of quoting for posh
+            if test _"$(eval "$i -c 'echo ok'" 2>${_NULL_DEV})"_ = _ok_ >&2
+            then
+              # test whether shell supports functions
+              if eval "$i -c 'foo () { exit 0; }; foo'" 2>${_NULL_DEV}
+              then
+                # shell with function support found
+                cat <<EOF
+${i}
+EOF
+                break;
+              else
+                # if not being a shell with function support go on searching
+                echo groffer: argument $i is not a shell \
+with function support. >&2
+                continue;
+              fi;
+            else
+              # if not being a shell go on searching
+              echo groffer: argument $i is not a shell. >&2
+              continue;
+            fi;
+          fi;
+        done;
+      fi;
+    )";
+    if test _"${s}"_ != __
+    then
+      cat <<EOF
+${s}
+EOF
+    fi;
+    ;;
+  esac;
+`
+
+########################### test fast shells for automatic run
+
+if test _"${_SHELL}"_ = __
+then
+  # shell sorted by speed, bash is very slow
+  for s in ksh ash dash pdksh zsh posh sh bash
+  do
+    # test on shell with function support
+    if eval "$s -c 'foo () { exit 0; }; foo'" 2>${_NULL_DEV}
+    then
+      _SHELL="$s";
+      break;
+    fi;
+  done;
+fi;
+
+
+########################### start groffer2.sh
+
+if test _"${_SHELL}"_ = _'standard shell'_
+then
+  _SHELL='';
+fi;
+
+if test _"${_SHELL}"_ = __
+then
+  # no shell found, so start groffer2.sh normally
+  if test _${supports_func}_ = _yes_
+  then
+    eval . "'${_GROFFER2_SH}'" '"$@"';
+    exit;
+  else
+    echo groffer: standard shell does not support functions; no shell works.\
+Get some free working shell such as bash. >&2
+    exit "${_ERROR}";
+  fi;
+else
+  # start groffer2.sh with the found $_SHELL
+  # do not quote $_SHELL to allow arguments
+  eval exec "${_SHELL} '${_GROFFER2_SH}'" '"$@"';
+  exit;
+fi;

Index: groffer2.sh
===================================================================
RCS file: groffer2.sh
diff -N groffer2.sh
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ groffer2.sh	11 Aug 2013 08:28:24 -0000	1.9
@@ -0,0 +1,7312 @@
+#! /bin/sh
+
+# groffer - display groff files
+
+# Source file position: <groff-source>/contrib/groffer/shell/groffer2.sh
+# Installed position: <prefix>/lib/groff/groffer/groffer2.sh
+
+# This file should not be run independently.  It is called by
+# `groffer.sh' in the source or by the installed `groffer' program.
+
+# Copyright (C) 2001, 2002, 2003, 2004, 2005, 2006, 2009
+# Free Software Foundation, Inc.
+# Written by Bernd Warken <groff-bernd.warken-72@web.de>.
+
+# Last update: 5 Jan 2009
+
+# 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/>.
+
+
+########################################################################
+#             Test of rudimentary shell functionality
+########################################################################
+
+# Zsh is not Bourne compatible without the following:
+if test -n "$ZSH_VERSION"; then
+  emulate sh
+  NULLCMD=:
+fi
+
+
+########################################################################
+# Test of `unset'
+#
+export _UNSET;
+export _foo;
+_foo=bar;
+_res="$(unset _foo 2>&1)";
+if unset _foo >${_NULL_DEV} 2>&1 && \
+   test _"${_res}"_ = __ && test _"${_foo}"_ = __
+then
+  _UNSET='unset';
+  eval "${_UNSET}" _foo;
+  eval "${_UNSET}" _res;
+else
+  _UNSET=':';
+fi;
+
+
+########################################################################
+# Test of `test'.
+#
+if test a = a && test a != b && test -f "${_GROFFER_SH}"
+then
+  :;
+else
+  echo '"test" did not work.' >&2;
+  exit "${_ERROR}";
+fi;
+
+
+########################################################################
+# Test of `echo' and the `$()' construct.
+#
+if echo '' >${_NULL_DEV}
+then
+  :;
+else
+  echo '"echo" did not work.' >&2;
+  exit "${_ERROR}";
+fi;
+if test _"$(t1="$(echo te)" &&
+            t2="$(echo '')" &&
+            t3="$(echo 'st')" &&
+            echo "${t1}${t2}${t3}")"_ \
+     != _test_
+then
+  echo 'The "$()" construct did not work' >&2;
+  exit "${_ERROR}";
+fi;
+
+
+########################################################################
+# Test of sed program; test in groffer.sh is not valid here.
+#
+if test _"$(echo xTesTx \
+           | sed -n 's/^.\([Tt]e*x*sTT*\).*$/\1/p' \
+           | sed 's|T|t|g')"_ != _test_
+then
+  echo 'The sed program did not work.' >&2;
+  exit "${_ERROR}";
+fi;
+
+
+########################################################################
+# Test of `cat'.
+#
+if test _"$(echo test | cat)"_ != _test_
+then
+  error 'Test of "cat" command failed.';
+fi;
+
+
+########################################################################
+# Test of function definitions.
+#
+_t_e_s_t_f_u_n_c_()
+{
+  return 0;
+}
+
+_test_func()
+{
+  echo test;
+}
+
+if _t_e_s_t_f_u_n_c_ 2>${_NULL_DEV} && \
+   test _"$(_test_func 2>${_NULL_DEV})"_ = _test_
+then
+  :;
+else
+  echo 'Shell '"${_SHELL}"' does not support function definitions.' >&2;
+  exit "${_ERROR}";
+fi;
+
+
+########################################################################
+# landmark (<text>)
+#
+# Print <text> to standard error as a debugging aid.
+#
+# Globals: $_DEBUG_LM
+#
+landmark()
+{
+  if test _"${_DEBUG_LM}"_ = _yes_
+  then
+    echo "LM: $*" >&2;
+  fi;
+} # landmark()
+
+
+########################################################################
+# test for compression.
+#
+export _HAS_COMPRESSION;
+export _HAS_BZIP;
+if test _"$(echo 'test' | gzip -c -d -f - 2>${_NULL_DEV})"_ = _test_
+then
+  _HAS_COMPRESSION='yes';
+  if echo 'test' | bzip2 -c 2>${_NULL_DEV} | bzip2 -t 2>${_NULL_DEV} \
+     && test _"$(echo 'test' | bzip2 -c 2>${_NULL_DEV} \
+                             | bzip2 -d -c 2>${_NULL_DEV})"_ \
+             = _test_
+  then
+    _HAS_BZIP='yes';
+  else
+    _HAS_BZIP='no';
+  fi;
+else
+  _HAS_COMPRESSION='no';
+  _HAS_BZIP='no';
+fi;
+
+
+########################################################################
+#                    debug - diagnostic messages
+########################################################################
+
+export _DEBUG_FUNC_CHECK;
+if test _"${_BEFORE_MAKE}"_ = _yes_
+then
+  _DEBUG_FUNC_CHECK='yes';
+else
+  _DEBUG_FUNC_CHECK='no';
+fi;
+_DEBUG_FUNC_CHECK='no';	# disable function checking
+#_DEBUG_FUNC_CHECK='yes';	# enable function checking
+
+export _DEBUG_STACKS;
+_DEBUG_STACKS='no';		# disable stack output in each function
+#_DEBUG_STACKS='yes';		# enable stack output in each function
+
+export _DEBUG_USER_WITH_STACK;
+_DEBUG_USER_WITH_STACK='no';	# disable stack dump in error_user()
+#_DEBUG_USER_WITH_STACK='yes';	# enable stack dump in error_user()
+
+export _DEBUG_LM;
+_DEBUG_LM='no';			# disable landmark messages
+#_DEBUG_LM='yes';		# enable landmark messages
+
+export _DEBUG_GROG;
+_DEBUG_GROG='no';		# disable grog output
+#_DEBUG_GROG='yes';		# enable grog output
+
+export _DEBUG_KEEP_FILES;
+_DEBUG_KEEP_FILES='no'		# disable file keeping in temporary dir
+#_DEBUG_KEEP_FILES='yes'	# enable file keeping in temporary dir
+
+export _DEBUG_PRINT_PARAMS;
+_DEBUG_PRINT_PARAMS='no';	# disable printing of all parameters
+#_DEBUG_PRINT_PARAMS='yes';	# enable printing of all parameters
+
+export _DEBUG_PRINT_SHELL;
+_DEBUG_PRINT_SHELL='no';	# disable printing of the shell name
+#_DEBUG_PRINT_SHELL='yes';	# enable printing of the shell name
+
+export _DEBUG_PRINT_TMPDIR;
+_DEBUG_PRINT_TMPDIR='no';	# disable printing of the temporary dir
+#_DEBUG_PRINT_TMPDIR='yes';	# enable printing of the temporary dir
+
+export _DEBUG_PRINT_FILENAMES;
+_DEBUG_PRINT_FILENAMES='no';	# disable printing of the found file names
+#_DEBUG_PRINT_FILENAMES='yes';	# enable printing of the found file names
+
+# determine all --debug* options
+case " $*" in
+*\ --deb*|*\ --d*-*)
+  # --debug-* options
+  d=' --debug-all --debug-filenames --debug-func --debug-grog '\
+'--debug-not-func --debug-keep --debug-lm --debug-params '\
+'--debug-shell --debug-stacks --debug-tmpdir --debug-user ';
+  # non-debug options with scheme --d*-*
+  n=' --do-nothing --default-modes --dvi-viewer --dvi-viewer-tty ';
+  for i
+  do
+    case "$i" in
+    --deb|--debu|--debug)
+      _DEBUG_FUNC_CHECK='yes';
+      # _DEBUG_STACKS='yes';
+      _DEBUG_USER_WITH_STACK='yes';
+      # _DEBUG_LM='yes';
+      _DEBUG_GROG='yes';
+      _DEBUG_KEEP_FILES='yes';
+      _DEBUG_PRINT_PARAMS='yes';
+      _DEBUG_PRINT_SHELL='yes';
+      _DEBUG_PRINT_TMPDIR='yes';
+      _DEBUG_PRINT_FILENAMES='yes';
+      continue;
+      ;;
+    --d*-*)
+      # before `-'
+      b="$(echo x"$i" | sed 's/^x--\([^-]*\)-.*$/\1/')";
+      # after `-'
+      a="$(echo x"$i" | sed 's/^x--[^-]*-\(.*\)$/\1/')";
+      ;;
+    *)
+      continue;
+      ;;
+    esac;
+    case "$n" in
+    *\ --$b*-$a*)
+      continue;
+      ;;
+    esac;
+    case "$d" in
+    *\ --$b*-$a*)
+      case "$a" in
+      f|s)			# double --debug-* options
+        continue;
+        ;;
+      esac;
+      # extract whole word of double abbreviation
+      s="$(cat <<EOF | sed -n 's/^.* \(--'"$b"'[^ -]*-'"$a"'[^ ]*\) .*/\1/p'
+$d
+EOF
+)"
+      case "$s" in
+      '') continue; ;;
+      --debug-all)
+        _DEBUG_FUNC_CHECK='yes';
+        _DEBUG_STACKS='yes';
+        _DEBUG_USER_WITH_STACK='yes';
+        _DEBUG_GROG='yes';
+        _DEBUG_LM='yes';
+        _DEBUG_KEEP_FILES='yes';
+        _DEBUG_PRINT_PARAMS='yes';
+        _DEBUG_PRINT_SHELL='yes';
+        _DEBUG_PRINT_TMPDIR='yes';
+        _DEBUG_PRINT_FILENAMES='yes';
+        _DEBUG_PRINT_FILENAMES='yes';
+        ;;
+      --debug-filenames)
+        _DEBUG_PRINT_FILENAMES='yes';
+        ;;
+      --debug-func)
+        _DEBUG_FUNC_CHECK='yes';
+	;;
+      --debug-not-func)
+        _DEBUG_FUNC_CHECK='no';
+        _DEBUG_STACKS='no';
+        _DEBUG_USER_WITH_STACK='no';
+	;;
+      --debug-grog)
+        _DEBUG_GROG='yes';
+	;;
+      --debug-keep)
+        _DEBUG_PRINT_TMPDIR='yes';
+        _DEBUG_KEEP_FILES='yes';
+        ;;
+      --debug-lm)
+        _DEBUG_LM='yes';
+        ;;
+      --debug-params)
+        _DEBUG_PRINT_PARAMS='yes';
+        ;;
+      --debug-shell)
+        _DEBUG_PRINT_SHELL='yes';
+        ;;
+      --debug-stacks)
+        _DEBUG_STACKS='yes';
+        ;;
+      --debug-tmpdir)
+        _DEBUG_PRINT_TMPDIR='yes';
+        ;;
+      --debug-user)
+        _DEBUG_USER_WITH_STACK='yes';
+        ;;
+      esac;
+      ;;
+    esac;
+  done
+  ;;
+esac;
+
+if test _"${_DEBUG_STACKS}"_ = _yes_ || \
+   test _"${_DEBUG_USER_WITH_STACK}"_ = _yes_
+then
+  _DEBUG_FUNC_CHECK='yes';
+fi
+
+if test _"${_DEBUG_PRINT_PARAMS}"_ = _yes_
+then
+  echo "parameters: $@" >&2;
+fi;
+
+if test _"${_DEBUG_PRINT_SHELL}"_ = _yes_
+then
+  if test _"${_SHELL}"_ = __
+  then
+    if test _"${POSIXLY_CORRECT}"_ = _y_
+    then
+      echo 'shell: bash as /bin/sh (none specified)' >&2;
+    else
+      echo 'shell: /bin/sh (none specified)' >&2;
+    fi;
+  else
+    echo "shell: ${_SHELL}" >&2;
+  fi;
+fi;
+
+
+########################################################################
+#                       Environment Variables
+########################################################################
+
+landmark "1: environment variables";
+
+# Environment variables that exist only for this file start with an
+# underscore letter.  Global variables to this file are written in
+# upper case letters, e.g. $_GLOBAL_VARIABLE; temporary variables
+# start with an underline and use only lower case letters and
+# underlines, e.g.  $_local_variable.
+
+#   [A-Z]*     system variables,      e.g. $MANPATH
+#   _[A-Z_]*   global file variables, e.g. $_MAN_PATH
+#   _[a-z_]*   temporary variables,   e.g. $_manpath
+
+# Due to incompatibilities of the `ash' shell, the name of loop
+# variables in `for' must be a single character.
+#   [a-z]      local loop variables,   e.g. $i
+
+# In functions, other writings are used for variables.  As some shells
+# do not support the `local' command a unique prefix in lower case is
+# constructed for each function, most are the abbreviation of the
+# function name.  All variable names start with this prefix.
+#   ${prefix}_[a-z_]*	variable name in a function, e.g. $msm_modes
+
+
+########################################################################
+# read-only variables (global to this file)
+########################################################################
+
+# function return values; `0' means ok; other values are error codes
+export _BAD;
+export _GOOD;
+export _NO;
+export _OK;
+export _YES;
+
+_GOOD='0';			# return ok
+_BAD='1';			# return negatively, error code `1'
+# $_ERROR was already defined as `7' in groffer.sh.
+
+_NO="${_BAD}";
+_YES="${_GOOD}";
+_OK="${_GOOD}";
+
+# quasi-functions, call with `eval', e.g `eval "${return_ok}"'
+export return_ok;
+export return_good;
+export return_bad;
+export return_yes;
+export return_no;
+export return_error;
+export return_var;
+return_ok="func_pop; return ${_OK}";
+return_good="func_pop; return ${_GOOD}";
+return_bad="func_pop; return ${_BAD}";
+return_yes="func_pop; return ${_YES}";
+return_no="func_pop; return ${_NO}";
+return_error="func_pop; return ${_ERROR}";
+return_var="func_pop; return";	# add number, e.g. `eval "${return_var} $n'
+
+
+export _DEFAULT_MODES;
+_DEFAULT_MODES="'pdf' 'html' 'ps' 'x' 'dvi' 'tty'";
+export _DEFAULT_RESOLUTION;
+_DEFAULT_RESOLUTION='75';
+
+export _DEFAULT_TTY_DEVICE;
+_DEFAULT_TTY_DEVICE='latin1';
+
+# _VIEWER_* viewer programs for different modes constructed as lists
+export _VIEWER_DVI_TTY;		# viewer program for dvi mode in tty
+export _VIEWER_DVI_X;		# viewer program for dvi mode in X
+export _VIEWER_HTML_TTY;	# viewer program for html mode in tty
+export _VIEWER_HTML_X;		# viewer program for html mode in X
+export _VIEWER_PDF_TTY;		# viewer program for pdf mode in tty
+export _VIEWER_PDF_X;		# viewer program for pdf mode in X
+export _VIEWER_PS_TTY;		# viewer program for ps mode in tty
+export _VIEWER_PS_X;		# viewer program for ps mode in X
+export _VIEWER_TTY_TTY;		# viewer program for X/x mode in tty
+export _VIEWER_TTY_X;		# viewer program for X/x mode in X
+export _VIEWER_X_TTY;		# viewer program for X/x mode in tty
+export _VIEWER_X_X;		# viewer program for X/x mode in X
+_VIEWER_DVI_TTY="";
+_VIEWER_DVI_X="'kdvi' 'xdvi' 'dvilx'";
+_VIEWER_HTML_TTY="'lynx' 'w3m'";
+_VIEWER_HTML_X="'konqueror' 'epiphany' 'mozilla-firefox' 'firefox' 'mozilla' \
+'netscape' 'galeon' 'opera' 'amaya' 'arena' 'mosaic'";
+_VIEWER_PDF_TTY="";
+_VIEWER_PDF_X="'kpdf' 'acroread' 'evince' 'xpdf -z 150' 'gpdf' \
+'kghostview --scale 1.45' 'ggv'";
+_VIEWER_PS_TTY="";
+_VIEWER_PS_X="'kpdf' 'kghostview --scale 1.45' 'evince' 'ggv' 'gv' \
+'ghostview' 'gs_x11,gs'";
+_VIEWER_TTY_TTY="'less -r -R' 'more' 'pager'";
+_VIEWER_TTY_X="'xless'";
+_VIEWER_X_TTY="";
+_VIEWER_X_X="'gxditview' 'xditview'";
+
+# Search automatically in standard sections `1' to `8', and in the
+# traditional sections `9', `n', and `o'.  On many systems, there
+# exist even more sections, mostly containing a set of man pages
+# special to a specific program package.  These aren't searched for
+# automatically, but must be specified on the command line.
+export _MAN_AUTO_SEC_LIST;
+_MAN_AUTO_SEC_LIST="'1' '2' '3' '4' '5' '6' '7' '8' '9' 'n' 'o'";
+export _MAN_AUTO_SEC_CHARS;
+_MAN_AUTO_SEC_CHARS='[123456789no]';
+
+export _SPACE_SED;
+_SPACE_SED='['"${_SP}${_TAB}"']';
+
+export _SPACE_CASE;
+_SPACE_CASE='[\'"${_SP}"'\'"${_TAB}"']';
+
+export _PROCESS_ID;		# for shutting down the program
+_PROCESS_ID="$$";
+
+export _START_DIR;		# directory at start time of the script
+_START_DIR="$(pwd)";
+
+
+############ the command line options of the involved programs
+#
+# The naming scheme for the options environment names is
+# $_OPTS_<prog>_<length>[_<argspec>]
+#
+# <prog>:    program name GROFFER, GROFF, or CMDLINE (for all
+#            command line options)
+# <length>:  LONG (long options) or SHORT (single character options)
+# <argspec>: ARG for options with argument, NA for no argument;
+#            without _<argspec> both the ones with and without arg.
+#
+# Each option that takes an argument must be specified with a
+# trailing : (colon).
+
+# exports
+export _OPTS_GROFFER_SHORT_NA;
+export _OPTS_GROFFER_SHORT_ARG;
+export _OPTS_GROFFER_LONG_NA;
+export _OPTS_GROFFER_LONG_ARG;
+export _OPTS_GROFF_SHORT_NA;
+export _OPTS_GROFF_SHORT_ARG;
+export _OPTS_GROFF_LONG_NA;
+export _OPTS_GROFF_LONG_ARG;
+export _OPTS_X_SHORT_ARG;
+export _OPTS_X_SHORT_NA;
+export _OPTS_X_LONG_ARG;
+export _OPTS_X_LONG_NA;
+export _OPTS_MAN_SHORT_ARG;
+export _OPTS_MAN_SHORT_NA;
+export _OPTS_MAN_LONG_ARG;
+export _OPTS_MAN_LONG_NA;
+export _OPTS_MANOPT_SHORT_ARG;
+export _OPTS_MANOPT_SHORT_NA;
+export _OPTS_MANOPT_LONG_ARG;
+export _OPTS_MANOPT_LONG_NA;
+export _OPTS_CMDLINE_SHORT_NA;
+export _OPTS_CMDLINE_SHORT_ARG;
+export _OPTS_CMDLINE_LONG_NA;
+export _OPTS_CMDLINE_LONG_ARG;
+
+###### groffer native options
+
+_OPTS_GROFFER_SHORT_NA="'h' 'Q' 'v' 'V' 'X' 'Z'";
+_OPTS_GROFFER_SHORT_ARG="'T'";
+
+_OPTS_GROFFER_LONG_NA="'auto' \
+'apropos' 'apropos-data' 'apropos-devel' 'apropos-progs' \
+'debug' 'debug-all' 'debug-filenames' \
+'debug-func' 'debug-not-func' 'debug-grog' 'debug-keep' 'debug-lm' \
+'debug-params' 'debug-shell' 'debug-stacks' 'debug-tmpdir' 'debug-user' \
+'default' 'do-nothing' 'dvi' 'groff' 'help' 'intermediate-output' 'html' \
+'man' 'no-location' 'no-man' 'no-special' 'pdf' 'ps' 'rv' 'source' \
+'text' 'to-stdout' 'text-device' 'tty' 'tty-device' \
+'version' 'whatis' 'www' 'x' 'X'";
+
+_OPTS_GROFFER_LONG_ARG="\
+'default-modes' 'device' 'dvi-viewer' 'dvi-viewer-tty' 'extension' 'fg' \
+'fn' 'font' 'foreground' 'html-viewer' 'html-viewer-tty' 'mode' \
+'pdf-viewer' 'pdf-viewer-tty' 'print' 'ps-viewer' 'ps-viewer-tty' 'shell' \
+'title' 'tty-viewer' 'tty-viewer-tty' 'www-viewer' 'www-viewer-tty' \
+'x-viewer' 'x-viewer-tty' 'X-viewer' 'X-viewer-tty'";
+
+##### groffer options inhereted from groff
+
+_OPTS_GROFF_SHORT_NA="'a' 'b' 'c' 'C' 'e' 'E' 'g' 'G' 'i' 'k' 'l' 'N' 'p' \
+'R' 's' 'S' 't' 'U' 'z'";
+_OPTS_GROFF_SHORT_ARG="'d' 'f' 'F' 'I' 'K' 'L' 'm' 'M' 'n' 'o' 'P' 'r' \
+'w' 'W'";
+_OPTS_GROFF_LONG_NA="";
+_OPTS_GROFF_LONG_ARG="";
+
+##### groffer options inhereted from the X Window toolkit
+
+_OPTS_X_SHORT_NA="";
+_OPTS_X_SHORT_ARG="";
+
+_OPTS_X_LONG_NA="'iconic' 'rv'";
+
+_OPTS_X_LONG_ARG="'background' 'bd' 'bg' 'bordercolor' 'borderwidth' \
+'bw' 'display' 'fg' 'fn' 'font' 'foreground' 'ft' 'geometry' \
+'resolution' 'title' 'xrm'";
+
+###### groffer options inherited from man
+
+_OPTS_MAN_SHORT_NA="";
+_OPTS_MAN_SHORT_ARG="";
+
+_OPTS_MAN_LONG_NA="'all' 'ascii' 'catman' 'ditroff' \
+'local-file' 'location' 'troff' 'update' 'where'";
+
+_OPTS_MAN_LONG_ARG="'locale' 'manpath' \
+'pager' 'preprocessor' 'prompt' 'sections' 'systems' 'troff-device'";
+
+###### additional options for parsing $MANOPT only
+
+_OPTS_MANOPT_SHORT_NA="'7' 'a' 'c' 'd' 'D' 'f' 'h' 'k' 'l' 't' 'u' \
+'V' 'w' 'Z'";
+_OPTS_MANOPT_SHORT_ARG="'e' 'L' 'm' 'M' 'p' 'P' 'r' 'S' 'T'";
+
+_OPTS_MANOPT_LONG_NA="${_OPTS_MAN_LONG_NA} \
+'apropos' 'debug' 'default' 'help' 'html' 'ignore-case' 'location-cat' \
+'match-case' 'troff' 'update' 'version' 'whatis' 'where' 'where-cat'";
+
+_OPTS_MANOPT_LONG_ARG="${_OPTS_MAN_LONG_NA} \
+'config_file' 'encoding' 'extension' 'locale'";
+
+###### collections of command line options
+
+_OPTS_CMDLINE_SHORT_NA="${_OPTS_GROFFER_SHORT_NA} \
+${_OPTS_GROFF_SHORT_NA} ${_OPTS_X_SHORT_NA} ${_OPTS_MAN_SHORT_NA}";
+_OPTS_CMDLINE_SHORT_ARG="${_OPTS_GROFFER_SHORT_ARG} \
+${_OPTS_GROFF_SHORT_ARG} ${_OPTS_X_SHORT_ARG} ${_OPTS_MAN_SHORT_ARG}";
+
+_OPTS_CMDLINE_LONG_NA="${_OPTS_GROFFER_LONG_NA} \
+${_OPTS_GROFF_LONG_NA} ${_OPTS_X_LONG_NA} ${_OPTS_MAN_LONG_NA}";
+_OPTS_CMDLINE_LONG_ARG="${_OPTS_GROFFER_LONG_ARG} \
+${_OPTS_GROFF_LONG_ARG} ${_OPTS_MAN_LONG_ARG} ${_OPTS_X_LONG_ARG}";
+
+
+########################################################################
+# read-write variables (global to this file)
+########################################################################
+
+export _ALL_PARAMS;		# All options and file name parameters
+export _ADDOPTS_GROFF;		# Transp. options for groff (`eval').
+export _APROPOS_PROG;		# Program to run apropos.
+export _APROPOS_SECTIONS;	# Sections for different --apropos-*.
+export _DISPLAY_MODE;		# Display mode.
+export _DISPLAY_PROG;		# Viewer program to be used for display.
+export _DISPLAY_ARGS;		# X resources for the viewer program.
+export _FILE_NR;		# number for temporary `,file,*'
+export _FILEARGS;		# Stores filespec parameters.
+export _FILESPEC_ARG;		# Stores the actual filespec parameter.
+export _FILESPEC_IS_MAN;	# filespec is for searching a man page
+export _FUNC_STACK;		# Store debugging information.
+export _MACRO_PACKAGES;		# groff's macro packages.
+export _MACRO_PKG;		# Macro package for each found file.
+export _NO_FILESPECS;		# Yes, if there are no filespec arguments.
+export _OUTPUT_FILE_NAME;	# output generated, see main_set_res..()
+export _REG_TITLE_LIST;		# Processed file names.
+export _SOELIM_R;		# option -r for soelim
+export _SPECIAL_FILESPEC;	# Filespec ran for apropos or whatis.
+export _SPECIAL_SETUP;		# Test on setup for apropos or whatis.
+export _VIEWER_BACKGROUND;	# viewer shall be run in the background or not
+# _MAN_* finally used configuration of man searching
+export _MAN_ALL;		# search all man pages per filespec
+export _MAN_ENABLE;		# enable search for man pages
+export _MAN_EXT;		# extension for man pages
+export _MAN_FORCE;		# force file parameter to be man pages
+export _MAN_IS_SETUP;		# setup man variables only once
+export _MAN_LANG;		# language for man pages
+export _MAN_LANG2;		# language for man pages
+export _MAN_PATH;		# search path for man pages as a list
+export _MAN_SEC;		# sections for man pages; sep. `:'
+export _MAN_SEC_CHARS;		# sections for man pages as [] construct
+export _MAN_SEC_LIST;		# sections for man pages as a list
+export _MAN_SYS;		# system names for man pages as a list
+# _MANOPT_* as parsed from $MANOPT
+export _MANOPT_ALL;		# $MANOPT --all
+export _MANOPT_EXTENSION;	# $MANOPT --extension
+export _MANOPT_LANG;		# $MANOPT --locale
+export _MANOPT_PATH;		# $MANOPT --manpath
+export _MANOPT_PAGER;		# $MANOPT --pager
+export _MANOPT_SEC;		# $MANOPT --sections
+export _MANOPT_SYS;		# $MANOPT --systems
+# variables for mode pdf
+export _PDF_DID_NOT_WORK;
+export _PDF_HAS_GS;
+export _PDF_HAS_PS2PDF;
+# _OPT_* as parsed from groffer command line
+export _OPT_ALL;		# display all suitable man pages
+export _OPT_APROPOS;		# call `apropos' program
+export _OPT_BD;			# set border color in some modes
+export _OPT_BG;			# set background color in some modes
+export _OPT_BW;			# set border width in some modes
+export _OPT_DEFAULT_MODES;	# `,'-list of modes when no mode given
+export _OPT_DEVICE;		# device option
+export _OPT_DO_NOTHING;		# do nothing in main_display()
+export _OPT_DISPLAY;		# set X display
+export _OPT_EXTENSION;		# set extension for man page search
+export _OPT_FG;			# set foreground color in some modes
+export _OPT_FN;			# set font in some modes
+export _OPT_GEOMETRY;		# set size and position of viewer in X
+export _OPT_ICONIC;		# -iconic option for X viewers
+export _OPT_LANG;		# set language for man pages
+export _OPT_MODE;		# values: X, tty, Q, Z, ""
+export _OPT_MANPATH;		# manual setting of path for man-pages
+export _OPT_PAGER;		# specify paging program for tty mode
+export _OPT_RESOLUTION;		# set X resolution in dpi
+export _OPT_RV;			# reverse fore- and background colors
+export _OPT_SECTIONS;		# sections for man page search
+export _OPT_STDOUT;		# print mode file to standard output
+export _OPT_SYSTEMS;		# man pages of different OS's
+export _OPT_TITLE;		# title for gxditview window
+export _OPT_TEXT_DEVICE;	# set device for tty mode
+export _OPT_V;			# groff option -V
+export _OPT_VIEWER_DVI;		# viewer program for dvi mode
+export _OPT_VIEWER_HTML;	# viewer program for html mode
+export _OPT_VIEWER_PDF;		# viewer program for pdf mode
+export _OPT_VIEWER_PS;		# viewer program for ps mode
+export _OPT_VIEWER_X;		# viewer program for x mode
+export _OPT_WHATIS;		# print the man description
+export _OPT_XRM;		# specify X resource
+export _OPT_Z;			# groff option -Z
+# _TMP_* temporary directory and files
+export _TMP_DIR;		# groffer directory for temporary files
+export _TMP_CAT;		# stores concatenation of everything
+export _TMP_MAN;		# stores find of man path
+export _TMP_MANSPEC;		# filters man pages with filespec
+export _TMP_STDIN;		# stores stdin, if any
+
+# these variables are preset in section `Preset' after the rudim. test
+
+
+########################################################################
+# Preset and reset of read-write global variables
+########################################################################
+
+# For variables that can be reset by option `--default', see reset().
+
+_FILE_NR=0;
+_FILEARGS='';
+_MACRO_PACKAGES="'-man' '-mdoc' '-me' '-mm' '-mom' '-ms'";
+_SPECIAL_FILESPEC='no';
+_SPECIAL_SETUP='no';
+
+# _TMP_* temporary files
+_TMP_DIR='';
+_TMP_CAT='';
+_TMP_MAN='';
+_TMP_CONF='';
+_TMP_STDIN='';
+
+# variables for mode pdf
+_PDF_DID_NOT_WORK='no';
+_PDF_HAS_GS='no';
+_PDF_HAS_PS2PDF='no';
+
+# option -r for soelim
+if : | soelim -r 2>${_NULL_DEV} >${_NULL_DEV}
+then
+  _SOELIM_R='-r';
+else
+  _SOELIM_R='';
+fi;
+
+########################################################################
+# reset ()
+#
+# Reset the variables that can be affected by options to their default.
+#
+reset()
+{
+  if test "$#" -ne 0
+  then
+    error "reset() does not have arguments.";
+  fi;
+
+  _ADDOPTS_GROFF='';
+  _APROPOS_PROG='';
+  _APROPOS_SECTIONS='';
+  _DISPLAY_ARGS='';
+  _DISPLAY_MODE='';
+  _DISPLAY_PROG='';
+  _MACRO_PKG='';
+  _NO_FILESPECS='';
+  _REG_TITLE_LIST='';
+
+  # _MAN_* finally used configuration of man searching
+  _MAN_ALL='no';
+  _MAN_ENABLE='yes';		# do search for man-pages
+  _MAN_EXT='';
+  _MAN_FORCE='no';		# first local file, then search man page
+  _MAN_IS_SETUP='no';
+  _MAN_LANG='';
+  _MAN_LANG2='';
+  _MAN_PATH='';
+  _MAN_SEC='';
+  _MAN_SEC_CHARS='';
+  _MAN_SEC_LIST='';
+  _MAN_SYS='';
+
+  # _MANOPT_* as parsed from $MANOPT
+  _MANOPT_ALL='no';
+  _MANOPT_EXTENSION='';
+  _MANOPT_LANG='';
+  _MANOPT_PATH='';
+  _MANOPT_PAGER='';
+  _MANOPT_SEC='';
+  _MANOPT_SYS='';
+
+  # _OPT_* as parsed from groffer command line
+  _OPT_ALL='no';
+  _OPT_APROPOS='no';
+  _OPT_BD='';
+  _OPT_BG='';
+  _OPT_BW='';
+  _OPT_DEFAULT_MODES='';
+  _OPT_DEVICE='';
+  _OPT_DISPLAY='';
+  _OPT_DO_NOTHING='no';
+  _OPT_EXTENSION='';
+  _OPT_FG='';
+  _OPT_FN='';
+  _OPT_GEOMETRY='';
+  _OPT_ICONIC='no';
+  _OPT_LANG='';
+  _OPT_MODE='';
+  _OPT_MANPATH='';
+  _OPT_PAGER='';
+  _OPT_RESOLUTION='';
+  _OPT_RV='no';
+  _OPT_SECTIONS='';
+  _OPT_SYSTEMS='';
+  _OPT_STDOUT='no';
+  _OPT_TITLE='';
+  _OPT_TEXT_DEVICE='';
+  _OPT_V='no';
+  _OPT_VIEWER_DVI='';
+  _OPT_VIEWER_PDF='';
+  _OPT_VIEWER_PS='';
+  _OPT_VIEWER_HTML='';
+  _OPT_VIEWER_X='';
+  _OPT_WHATIS='no';
+  _OPT_XRM='';
+  _OPT_Z='no';
+  _VIEWER_BACKGROUND='no';
+}
+
+reset;
+
+
+########################################################################
+#              Preliminary functions for error handling
+########################################################################
+
+landmark "2: preliminary functions";
+
+# These functions do not have a func-check frame.  Basically they could be
+# moved to the functions in alphabetical order.
+
+##############
+# echo1 (<text>*)
+#
+# Output to stdout with final line break.
+#
+# Arguments : arbitrary text including `-'.
+#
+echo1()
+{
+  cat <<EOF
+$@
+EOF
+} # echo1()
+
+
+##############
+# echo2 (<text>*)
+#
+# Output to stderr with final line break.
+#
+# Arguments : arbitrary text including `-'.
+#
+echo2()
+{
+  cat >&2 <<EOF
+$@
+EOF
+} # echo2()
+
+
+
+
+##############
+# clean_up ()
+#
+# Clean up at exit.
+#
+cu_already='no';
+clean_up()
+{
+  cd "${_START_DIR}" >"${_NULL_DEV}" 2>&1;
+  if test _${_DEBUG_KEEP_FILES}_ = _yes_
+  then
+    if test _"$cu_already"_ = _yes_
+    then
+      eval "${return_ok}";
+    fi;
+    cu_already=yes;
+    echo2 "Kept temporary directory ${_TMP_DIR}."
+  else
+    if test _"${_TMP_DIR}"_ != __
+    then
+      if test -e "${_TMP_DIR}"
+      then
+        rm -f -r "${_TMP_DIR}" >${_NULL_DEV} 2>&1;
+      fi;
+    fi;
+  fi;
+  eval "${return_ok}";
+} # clean_up()
+
+
+#############
+# diag (text>*)
+#
+# Output a diagnostic message to stderr.
+#
+diag()
+{
+  echo2 '>>>>>'"$*";
+} # diag()
+
+
+#############
+# error (<text>*)
+#
+# Print an error message to standard error, print the function stack,
+# exit with an error condition.  The argument should contain the name
+# of the function from which it was called.  This is for system errors.
+#
+error()
+{
+  case "$#" in
+    1) echo2 'groffer error: '"$1"; ;;
+    *) echo2 'groffer error: wrong number of arguments in error().'; ;;
+  esac;
+  func_stack_dump;
+  if test _"${_TMP_DIR}"_ != __ && test -d "${_TMP_DIR}"
+  then
+    : >"${_TMP_DIR}"/,error;
+  fi;
+  exit "${_ERROR}";
+} # error()
+
+
+#############
+# error_user (<text>*)
+#
+# Print an error message to standard error; exit with an error condition.
+# The error is supposed to be produced by the user.  So the funtion stack
+# is omitted.
+#
+error_user()
+{
+  case "$#" in
+    1)
+      echo2 'groffer error: '"$1";
+       ;;
+    *)
+      echo2 'groffer error: wrong number of arguments in error_user().';
+      ;;
+  esac;
+  if test _"${_DEBUG_USER_WITH_STACK}"_ = _yes_
+  then
+    func_stack_dump;
+  fi;
+  if test _"${_TMP_DIR}"_ != __ && test -d "${_TMP_DIR}"
+  then
+    : >"${_TMP_DIR}"/,error;
+  fi;
+  exit "${_ERROR}";
+} # error_user()
+
+
+
+#############
+# exit_test ()
+#
+# Test whether the former command ended with error().  Exit again.
+#
+# Globals: $_ERROR
+#
+exit_test()
+{
+  if test "$?" = "${_ERROR}"
+  then
+    exit ${_ERROR};
+  fi;
+  if test _"${_TMP_DIR}"_ != __ && test -f "${_TMP_DIR}"/,error
+  then
+    exit ${_ERROR};
+  fi;
+} # exit_test()
+
+
+########################################################################
+#       Definition of normal Functions in alphabetical order
+########################################################################
+
+landmark "3: functions";
+
+########################################################################
+# apropos_filespec ()
+#
+# Compose temporary file for filspec.
+#
+# Globals:  in: $_OPT_APROPOS, $_SPECIAL_SETUP, $_FILESPEC_ARG,
+#               $_APROPOS_PROG, $_APROPOS_SECTIONS, $_OPT_SECTIONS
+#          out: $_SPECIAL_FILESPEC
+#
+# Variable prefix: af
+#
+apropos_filespec()
+{
+
+  func_check apropos_filespec '=' 0 "$@";
+  if obj _OPT_APROPOS is_yes
+  then
+    if obj _SPECIAL_SETUP is_not_yes
+    then
+      error 'apropos_filespec(): apropos_setup() must be run first.';
+    fi;
+    _SPECIAL_FILESPEC='yes';
+    if obj _NO_FILESPECS is_yes
+    then
+      to_tmp_line '.SH no filespec';
+      eval "${_APROPOS_PROG}" | sed 's/^/\\\&/' >>"${_TMP_CAT}";
+      eval "${return_ok}";
+    fi;
+    eval to_tmp_line \
+      "'.SH $(echo1 "${_FILESPEC_ARG}" | sed 's/[^\\]-/\\-/g')'";
+    exit_test;
+    if obj _APROPOS_SECTIONS is_empty
+    then
+      if obj _OPT_SECTIONS is_empty
+      then
+        s='^.*(..*).*$';
+      else
+        s='^.*(['"$(echo1 "${_OPT_SECTIONS}" | sed 's/://g')"']';
+      fi;
+    else
+      s='^.*(['"${_APROPOS_SECTIONS}"']';
+    fi;
+### apropos_filespec()
+    af_filespec="$(echo1 "${_FILESPEC_ARG}" | sed '
+s,/,\\/,g
+s/\./\\./g
+')";
+    eval "${_APROPOS_PROG}" "'${_FILESPEC_ARG}'" | \
+      sed -n '
+/^'"${af_filespec}"': /s/^\(.*\)$/\\\&\1/p
+/'"$s"'/p
+' | \
+      sort |\
+      sed '
+s/^\(.*(..*).*\)  *-  *\(.*\)$/\.br\n\.TP 15\n\.BR \"\1\"\n\\\&\2/
+' >>"${_TMP_CAT}";
+    eval ${_UNSET} af_filespec;
+    eval "${return_ok}";
+  else
+    eval "${return_bad}";
+  fi;
+} # apropos_filespec()
+
+
+########################################################################
+# apropos_setup ()
+#
+# Setup for the --apropos* options, just 2 global variables are set.
+#
+# Globals:  in: $_OPT_APROPOS
+#          out: $_SPECIAL_SETUP, $_APROPOS_PROG
+#
+apropos_setup()
+{
+  func_check apropos_setup '=' 0 "$@";
+  if obj _OPT_APROPOS is_yes
+  then
+    if is_prog apropos
+    then
+      _APROPOS_PROG='apropos';
+    elif is_prog man
+    then
+      if man --apropos man >${_NULL_DEV} 2>${_NULL_DEV}
+      then
+        _APROPOS_PROG='man --apropos';
+      elif man -k man >${_NULL_DEV} 2>${_NULL_DEV}
+      then
+        _APROPOS_PROG='man -k';
+      fi;
+    fi;
+    if obj _APROPOS_PROG is_empty
+    then
+      error 'apropos_setup(): no apropos program available.';
+    fi;
+    to_tmp_line '.TH GROFFER APROPOS';
+    _SPECIAL_SETUP='yes';
+    if obj _OPT_TITLE is_empty
+    then
+      _OPT_TITLE='apropos';
+    fi;
+    eval "${return_ok}";
+  else
+    eval "${return_bad}";
+  fi;
+} # apropos_setup()
+
+
+########################################################################
+# base_name (<path>)
+#
+# Get the file name part of <path>, i.e. delete everything up to last
+# `/' from the beginning of <path>.  Remove final slashes, too, to get
+# a non-empty output.  The output is constructed according the shell
+# program `basename'.
+#
+# Arguments : 1
+# Output    : the file name part (without slashes)
+#
+# Variable prefix: bn
+#
+base_name()
+{
+  func_check base_name = 1 "$@";
+  bn_name="$1";
+  case "${bn_name}" in
+    */)
+      # delete all final slashes
+      bn_name="$(echo1 "${bn_name}" | sed 's|//*$||')";
+      exit_test;
+      ;;
+  esac;
+  case "${bn_name}" in
+    '')
+      eval ${_UNSET} bn_name;
+      eval "${return_bad}";
+      ;;
+    /)
+      # this is like `basename' does
+      echo1 '/';
+      ;;
+    */*)
+      # delete everything before and including the last slash `/'.
+      echo1 "${bn_name}" | sed 's|^.*//*\([^/]*\)$|\1|';
+      ;;
+    *)
+      obj bn_name echo1;
+      ;;
+  esac;
+  eval ${_UNSET} bn_name;
+  eval "${return_ok}";
+} # base_name()
+
+
+########################################################################
+# cat_z (<file>)
+#
+# Decompress if possible or just print <file> to standard output.
+# gzip, bzip2, and .Z decompression is supported.
+#
+# Arguments: 1, a file name.
+# Output: the content of <file>, possibly decompressed.
+#
+cat_z()
+{
+  func_check cat_z = 1 "$@";
+  case "$1" in
+  '')
+    error 'cat_z(): empty file name.';
+    ;;
+  '-')
+    error 'cat_z(): for standard input use save_stdin().';
+    ;;
+  esac;
+  if is_file "$1"
+  then
+    :;
+  else
+    error 'cat_z(): argument $1 is not a file.';
+  fi;
+  if test -s "$1"
+  then
+    :;
+  else
+    eval "${return_ok}";
+  fi;
+  if obj _HAS_COMPRESSION is_yes
+  then
+    if obj _HAS_BZIP is_yes
+    then
+      # test whether being compressed with bz2
+      if bzip2 -t "$1" 2>${_NULL_DEV}
+      then
+        bzip2 -c -d "$1" 2>${_NULL_DEV};
+        eval "${return_ok}";
+      fi;
+    fi;
+    # if not compressed gzip acts like `cat'
+    gzip -c -d -f "$1" 2>${_NULL_DEV};
+  else
+    cat "$1";
+  fi;
+  eval "${return_ok}";
+} # cat_z()
+
+
+########################################################################
+# clean_up ()
+#
+# Do the final cleaning up before exiting; used by the trap calls.
+#
+# defined above
+
+
+########################################################################
+# diag (<text>*)
+#
+# Print marked message to standard error; useful for debugging.
+#
+# defined above
+
+
+########################################################################
+landmark '4: dir_name()*';
+########################################################################
+
+#######################################################################
+# dir_name (<name>)
+#
+# Get the directory name of <name>.  The output is constructed
+# according to the shell program `dirname'.
+#
+# Arguments : 1
+# Output    : the directory part of <name>
+#
+# Variable prefix: dn
+#
+dir_name()
+{
+  func_check dir_name = 1 "$@";
+  obj_from_output dn_name dir_name_chop "$1";
+  case "${dn_name}" in
+  ''|.)
+    echo1 '.';
+    ;;
+  /)
+    echo1 '/';
+    ;;
+  */*)
+    echo1 "$(echo1 "${dn_name}" | sed 's#/*[^/][^/]*$##')";
+    ;;
+  *)
+    echo1 "${dn_name}";
+    ;;
+  esac;
+  eval "${return_ok}";
+} # dir_name()
+
+
+#######################################################################
+# dir_name_append (<dir> <name>)
+#
+# Append `name' to `dir' with clean handling of `/'.
+#
+# Arguments : 2
+# Output    : the generated new directory name <dir>/<name>
+#
+dir_name_append()
+{
+  func_check dir_name_append = 2 "$@";
+  if is_empty "$1"
+  then
+    echo1 "$2";
+  elif is_empty "$2"
+  then
+    echo1 "$1";
+  else
+    dir_name_chop "$1"/"$2";
+  fi;
+  eval "${return_ok}";
+} # dir_name_append()
+
+
+########################################################################
+# dir_name_chop (<name>)
+#
+# Remove unnecessary slashes from directory name.
+#
+# Argument: 1, a directory name.
+# Output:   path without double, or trailing slashes.
+#
+# Variable prefix: dc
+#
+dir_name_chop()
+{
+  func_check dir_name_chop = 1 "$@";
+  # replace all multiple slashes by a single slash `/'.
+  dc_res="$(echo1 "$1" | sed 's|///*|/|g')";
+  exit_test;
+  case "${dc_res}" in
+  ?*/)
+    # remove trailing slash '/';
+    echo1 "${dc_res}" | sed 's|/$||';
+    ;;
+  *)
+    obj dc_res echo1
+    ;;
+  esac;
+  eval ${_UNSET} dc_res;
+  eval "${return_ok}";
+} # dir_name_chop()
+
+
+########################################################################
+# do_nothing ()
+#
+# Dummy function that does nothing.
+#
+do_nothing()
+{
+  eval return "${_OK}";
+} # do_nothing()
+
+
+########################################################################
+# echo1 (<text>*)
+#
+# Print to standard output with final line break.
+#
+# defined above
+
+
+########################################################################
+# echo2 (<text>*)
+#
+# Print to standard error with final line break.
+#
+# defined above
+
+
+
+########################################################################
+# error (<text>*)
+#
+# Print error message and exit with error code.
+#
+# defined above
+
+
+########################################################################
+# exit_test ()
+#
+# Test whether the former command ended with error().  Exit again.
+#
+# defined above
+
+
+if test _"${_DEBUG_FUNC_CHECK}"_ = _yes_
+then
+
+  #############
+  # func_check (<func_name> <rel_op> <nr_args> "$@")
+  #
+  # This is called at the first line of each function.  It checks the
+  # number of arguments of function <func_name> and registers the
+  # function call to _FUNC_STACK.
+  #
+  # Arguments: >=3
+  #   <func_name>: name of the calling function.
+  #   <rel_op>:    a relational operator: = != < > <= >=
+  #   <nr_args>:   number of arguments to be checked against <operator>
+  #   "$@":        the arguments of the calling function.
+  #
+  # Variable prefix: fc
+  #
+  func_check()
+  {
+    if test "$#" -lt 3
+    then
+      error 'func_check() needs at least 3 arguments.';
+    fi;
+    fc_fname="$1";
+    case "$3" in
+    1)
+      fc_nargs="$3";
+      fc_s='';
+      ;;
+    0|[2-9])
+      fc_nargs="$3";
+      fc_s='s';
+      ;;
+    *)
+      error "func_check(): third argument must be a digit.";
+      ;;
+    esac;
+### func_check()
+    case "$2" in
+    '='|'-eq')
+      fc_op='-eq';
+      fc_comp='exactly';
+      ;;
+    '>='|'-ge')
+      fc_op='-ge';
+      fc_comp='at least';
+      ;;
+    '<='|'-le')
+      fc_op='-le';
+      fc_comp='at most';
+      ;;
+    '<'|'-lt')
+      fc_op='-lt';
+      fc_comp='less than';
+      ;;
+    '>'|'-gt')
+      fc_op='-gt';
+      fc_comp='more than';
+      ;;
+    '!='|'-ne')
+      fc_op='-ne';
+      fc_comp='not';
+      ;;
+### func_check()
+    *)
+      error \
+        'func_check(): second argument is not a relational operator.';
+      ;;
+    esac;
+    shift;
+    shift;
+    shift;
+    if test "$#" "${fc_op}" "${fc_nargs}"
+    then
+      do_nothing;
+    else
+      error "func_check(): \
+${fc_fname}"'() needs '"${fc_comp} ${fc_nargs}"' argument'"${fc_s}"'.';
+    fi;
+    func_push "${fc_fname}";
+    if test _"${_DEBUG_STACKS}"_ = _yes_
+    then
+      echo2 '+++ '"${fc_fname} $@";
+      echo2 '>>> '"${_FUNC_STACK}";
+    fi;
+    eval ${_UNSET} fc_comp;
+    eval ${_UNSET} fc_fname;
+    eval ${_UNSET} fc_nargs;
+    eval ${_UNSET} fc_op;
+    eval ${_UNSET} fc_s;
+  } # func_check()
+
+
+  #############
+  # func_pop ()
+  #
+  # Retrieve the top element from the function stack.  This is called
+  # by every return variable in each function.
+  #
+  # The stack elements are separated by `!'; the popped element is
+  # identical to the original element, except that all `!' characters
+  # were removed.
+  #
+  # Arguments: 1
+  #
+  func_pop()
+  {
+    if test "$#" -ne 0
+    then
+      error 'func_pop() does not have arguments.';
+    fi;
+    case "${_FUNC_STACK}" in
+    '')
+      if test _"${_DEBUG_STACKS}"_ = _yes_
+      then
+        error 'func_pop(): stack is empty.';
+      fi;
+      ;;
+    *!*)
+      # split at first bang `!'.
+      _FUNC_STACK="$(echo1 "${_FUNC_STACK}" | sed 's/^[^!]*!//')";
+      exit_test;
+      ;;
+    *)
+      _FUNC_STACK='';
+      ;;
+    esac;
+    if test _"${_DEBUG_STACKS}"_ = _yes_
+    then
+      echo2 '<<< '"${_FUNC_STACK}";
+    fi;
+  } # func_pop()
+
+
+  #############
+  # func_push (<element>)
+  #
+  # Store another element to the function stack.  This is called by
+  # func_check() at the beginning of each function.
+  #
+  # The stack elements are separated by `!'; if <element> contains a `!'
+  # it is removed first.
+  #
+  # Arguments: 1
+  #
+  # Variable prefix: fp
+  #
+  func_push()
+  {
+    if test "$#" -ne 1
+    then
+      error 'func_push() needs 1 argument.';
+    fi;
+    case "$1" in
+    *'!'*)
+      # remove all bangs `!'.
+      fp_element="$(echo1 "$1" | sed 's/!//g')";
+      exit_test;
+      ;;
+    *)
+      fp_element="$1";
+      ;;
+    esac;
+    if test _"${_FUNC_STACK}"_ = __
+    then
+      _FUNC_STACK="${fp_element}";
+    else
+      _FUNC_STACK="${fp_element}!${_FUNC_STACK}";
+    fi;
+    eval ${_UNSET} fp_element;
+  } # func_push()
+
+
+  #############
+  # func_stack_dump ()
+  #
+  # Print the content of the function stack.  Ignore the arguments.
+  #
+  func_stack_dump()
+  {
+    diag 'call stack(): '"${_FUNC_STACK}";
+  } # func_stack_dump()
+
+else				# $_DEBUG_FUNC_CHECK is not `yes'
+
+  func_check() { return; }
+  func_pop() { return; }
+  func_push() { return; }
+  func_stack_dump() { return; }
+
+fi;				# test of $_DEBUG_FUNC_CHECK
+
+
+########################################################################
+# get_first_essential (<arg>*)
+#
+# Retrieve first non-empty argument.
+#
+# Return  : `1' if all arguments are empty, `0' if found.
+# Output  : the retrieved non-empty argument.
+#
+# Variable prefix: gfe
+#
+get_first_essential()
+{
+  func_check get_first_essential '>=' 0 "$@";
+  if is_equal "$#" 0
+  then
+    eval "${return_ok}";
+  fi;
+  for i
+  do
+    gfe_var="$i";
+    if obj gfe_var is_not_empty
+    then
+      obj gfe_var echo1;
+      eval ${_UNSET} gfe_var;
+      eval "${return_ok}";
+    fi;
+  done;
+  eval ${_UNSET} gfe_var;
+  eval "${return_bad}";
+} # get_first_essential()
+
+
+########################################################################
+landmark '5: is_*()';
+########################################################################
+
+########################################################################
+# is_dir (<name>)
+#
+# Test whether `name' is a readable directory.
+#
+# Arguments : 1
+# Return    : `0' if arg1 is a directory, `1' otherwise.
+#
+is_dir()
+{
+  func_check is_dir '=' 1 "$@";
+  if is_not_empty "$1" && test -d "$1" && test -r "$1"
+  then
+    eval "${return_yes}";
+  fi;
+  eval "${return_no}";
+} # is_dir()
+
+
+########################################################################
+# is_empty (<string>)
+#
+# Test whether <string> is empty.
+#
+# Arguments : <=1
+# Return    : `0' if arg1 is empty or does not exist, `1' otherwise.
+#
+is_empty()
+{
+  func_check is_empty '=' 1 "$@";
+  if test _"$1"_ = __
+  then
+    eval "${return_yes}";
+  fi;
+  eval "${return_no}";
+} # is_empty()
+
+
+########################################################################
+# is_empty_file (<file_name>)
+#
+# Test whether <file_name> is an empty existing file.
+#
+# Arguments : <=1
+# Return    :
+#   `0' if arg1 is an empty existing file
+#   `1' otherwise
+#
+is_empty_file()
+{
+  func_check is_empty_file '=' 1 "$@";
+  if is_file "$1"
+  then
+    if test -s "$1"
+    then
+      eval "${return_no}";
+    else
+      eval "${return_yes}";
+    fi;
+  fi;
+  eval "${return_no}";
+} # is_empty_file()
+
+
+########################################################################
+# is_equal (<string1> <string2>)
+#
+# Test whether <string1> is equal to <string2>.
+#
+# Arguments : 2
+# Return    : `0' both arguments are equal strings, `1' otherwise.
+#
+is_equal()
+{
+  func_check is_equal '=' 2 "$@";
+  if test _"$1"_ = _"$2"_
+  then
+    eval "${return_yes}";
+  fi;
+  eval "${return_no}";
+} # is_equal()
+
+
+########################################################################
+# is_existing (<name>)
+#
+# Test whether <name> is an existing file or directory.  Solaris 2.5 does
+# not have `test -e'.
+#
+# Arguments : 1
+# Return    : `0' if arg1 exists, `1' otherwise.
+#
+is_existing()
+{
+  func_check is_existing '=' 1 "$@";
+  if is_empty "$1"
+  then
+    eval "${return_no}";
+  fi;
+  if test -f "$1" || test -d "$1" || test -c "$1"
+  then
+    eval "${return_yes}";
+  fi;
+  eval "${return_no}";
+} # is_existing()
+
+
+########################################################################
+# is_file (<name>)
+#
+# Test whether <name> is a readable file.
+#
+# Arguments : 1
+# Return    : `0' if arg1 is a readable file, `1' otherwise.
+#
+is_file()
+{
+  func_check is_file '=' 1 "$@";
+  if is_not_empty "$1" && test -f "$1" && test -r "$1"
+  then
+    eval "${return_yes}";
+  fi;
+  eval "${return_no}";
+} # is_file()
+
+
+########################################################################
+# is_greater_than (<integer1> <integer2>)
+#
+# Test whether <integer1> is greater than <integer2>.
+#
+# Arguments : 2
+# Return    : `0' if <integer1> is a greater integer than <integer2>,
+#             `1' otherwise.
+#
+is_greater_than()
+{
+  func_check is_greater_than '=' 2 "$@";
+  if is_integer "$1" && is_integer "$2" && test "$1" -gt "$2"
+  then
+    eval "${return_yes}";
+  fi;
+  eval "${return_no}";
+} # is_greater_than()
+
+
+########################################################################
+# is_integer (<string>)
+#
+# Test whether `string' is an integer.
+#
+# Arguments : 1
+# Return    : `0' if argument is an integer, `1' otherwise.
+#
+is_integer()
+{
+  func_check is_integer '=' 1 "$@";
+  if is_equal "$(echo1 "$1" | sed -n '
+s/^[0-9][0-9]*$/ok/p
+s/^[-+][0-9][0-9]*$/ok/p
+')" 'ok'
+  then
+    eval "${return_yes}";
+  fi;
+  eval "${return_no}";
+} # is_integer()
+
+
+########################################################################
+# is_not_empty_file (<file_name>)
+#
+# Test whether <file_name> is a non-empty existing file.
+#
+# Arguments : <=1
+# Return    :
+#   `0' if arg1 is a non-empty existing file
+#   `1' otherwise
+#
+is_not_empty_file()
+{
+  func_check is_not_empty_file '=' 1 "$@";
+  if is_file "$1" && test -s "$1"
+  then
+    eval "${return_yes}";
+  fi;
+  eval "${return_no}";
+} # is_not_empty_file()
+
+
+########################################################################
+# is_not_dir (<name>)
+#
+# Test whether <name> is not a readable directory.
+#
+# Arguments : 1
+# Return    : `0' if arg1 is a directory, `1' otherwise.
+#
+is_not_dir()
+{
+  func_check is_not_dir '=' 1 "$@";
+  if is_dir "$1"
+  then
+    eval "${return_no}";
+  fi;
+  eval "${return_yes}";
+} # is_not_dir()
+
+
+########################################################################
+# is_not_empty (<string>)
+#
+# Test whether <string> is not empty.
+#
+# Arguments : <=1
+# Return    : `0' if arg1 exists and is not empty, `1' otherwise.
+#
+is_not_empty()
+{
+  func_check is_not_empty '=' 1 "$@";
+  if is_empty "$1"
+  then
+    eval "${return_no}";
+  fi;
+  eval "${return_yes}";
+} # is_not_empty()
+
+
+########################################################################
+# is_not_equal (<string1> <string2>)
+#
+# Test whether <string1> differs from <string2>.
+#
+# Arguments : 2
+#
+is_not_equal()
+{
+  func_check is_not_equal '=' 2 "$@";
+  if is_equal "$1" "$2"
+  then
+    eval "${return_no}";
+  fi
+  eval "${return_yes}";
+} # is_not_equal()
+
+
+########################################################################
+# is_not_file (<filename>)
+#
+# Test whether <filename> is a not readable file.
+#
+# Arguments : 1 (empty allowed)
+#
+is_not_file()
+{
+  func_check is_not_file '=' 1 "$@";
+  if is_file "$1"
+  then
+    eval "${return_no}";
+  fi;
+  eval "${return_yes}";
+} # is_not_file()
+
+
+########################################################################
+# is_not_prog (<program>)
+#
+# Verify that <program> is not a command in $PATH.
+#
+# Arguments : 1,  <program> can have spaces and arguments.
+#
+is_not_prog()
+{
+  func_check is_not_prog '=' 1 "$@";
+  if where_is_prog "$1" >${_NULL_DEV}
+  then
+    eval "${return_no}";
+  fi;
+  eval "${return_yes}";
+} # is_not_prog()
+
+
+########################################################################
+# is_not_writable (<name>)
+#
+# Test whether <name> is not a writable file or directory.
+#
+# Arguments : >=1 (empty allowed), more args are ignored
+#
+is_not_writable()
+{
+  func_check is_not_writable '>=' 1 "$@";
+  if is_writable "$1"
+  then
+    eval "${return_no}";
+  fi;
+  eval "${return_yes}";
+} # is_not_writable()
+
+
+########################################################################
+# is_not_X ()
+#
+# Test whether the script is not running in X Window by checking $DISPLAY.
+#
+is_not_X()
+{
+  func_check is_not_X '=' 0 "$@";
+  if obj DISPLAY is_empty
+  then
+    eval "${return_yes}";
+  fi;
+  eval "${return_no}";
+} # is_not_X()
+
+
+########################################################################
+# is_not_yes (<string>)
+#
+# Test whether <string> is not `yes'.
+#
+# Arguments : 1
+#
+is_not_yes()
+{
+  func_check is_not_yes = 1 "$@";
+  if is_yes "$1"
+  then
+    eval "${return_no}";
+  fi;
+  eval "${return_yes}";
+} # is_not_yes()
+
+
+########################################################################
+# is_prog (<name>)
+#
+# Determine whether <name> is a program in $PATH.
+#
+# Arguments : 1,  <program> can have spaces and arguments.
+#
+is_prog()
+{
+  func_check is_prog '=' 1 "$@";
+  if where_is_prog "$1" >${_NULL_DEV}
+  then
+    eval "${return_yes}";
+  fi;
+  eval "${return_no}";
+} # is_prog()
+
+
+########################################################################
+# is_writable (<name>)
+#
+# Test whether <name> is a writable file or directory.
+#
+# Arguments : >=1 (empty allowed), more args are ignored
+#
+is_writable()
+{
+  func_check is_writable '>=' 1 "$@";
+  if is_empty "$1"
+  then
+    eval "${return_no}";
+  fi;
+  if test -r "$1"
+  then
+    if test -w "$1"
+    then
+      eval "${return_yes}";
+    fi;
+  fi;
+  eval "${return_no}";
+} # is_writable()
+
+
+########################################################################
+# is_X ()
+#
+# Test whether the script is running in X Window by checking $DISPLAY.
+#
+is_X()
+{
+  func_check is_X '=' 0 "$@";
+  if obj DISPLAY is_not_empty
+  then
+    eval "${return_yes}";
+  fi;
+  eval "${return_no}";
+} # is_X()
+
+
+########################################################################
+# is_yes (<string>)
+#
+# Test whether <string> has value `yes'.
+#
+# Return    : `0' if arg1 is `yes', `1' otherwise.
+#
+is_yes()
+{
+  func_check is_yes '=' 1 "$@";
+  if is_equal "$1" 'yes'
+  then
+    eval "${return_yes}";
+  fi;
+  eval "${return_no}";
+} # is_yes()
+
+
+########################################################################
+# landmark ()
+#
+# Print debugging information on standard error if $_DEBUG_LM is `yes'.
+#
+# Globals: $_DEBUG_LM
+#
+# Defined in section `Debugging functions'.
+
+
+########################################################################
+# leave ([<code>])
+#
+# Clean exit without an error or with error <code>.
+#
+leave()
+{
+  clean_up;
+  if test $# = 0
+  then
+    exit "${_OK}";
+  else
+    exit "$1";
+  fi;
+} # leave()
+
+
+########################################################################
+landmark '6: list_*()';
+########################################################################
+#
+# `list' is an object class that represents an array or list.  Its
+# data consists of space-separated single-quoted elements.  So a list
+# has the form "'first' 'second' '...' 'last'".  See list_append() for
+# more details on the list structure.  The array elements of `list'
+# can be get by `eval set x "$list"; shift`.
+
+
+########################################################################
+# list_append (<list> <element>...)
+#
+# Add one or more elements to an existing list.  <list> may also be
+# empty.
+#
+# Arguments: >=2
+#   <list>: a variable name for a list of single-quoted elements
+#   <element>:  some sequence of characters.
+# Output: none, but $<list> is set to
+#   if <list> is empty:  "'<element>' '...'"
+#   otherwise:           "$list '<element>' ..."
+#
+# Variable prefix: la
+#
+list_append()
+{
+  func_check list_append '>=' 2 "$@";
+  la_name="$1";
+  eval la_list='"${'"$1"'}"';
+  shift;
+  for s
+  do
+    la_s="$s";
+    case "${la_s}" in
+    *\'*)
+      # escape each single quote by replacing each
+      # "'" (squote) by "'\''" (squote bslash squote squote);
+      # note that the backslash must be doubled in the following `sed'
+      la_element="$(echo1 "${la_s}" | sed 's/'"${_SQ}"'/&\\&&/g')";
+      exit_test;
+      ;;
+    '')
+      la_element="";
+      ;;
+    *)
+      la_element="${la_s}";
+      ;;
+    esac;
+### list_append()
+    if obj la_list is_empty
+    then
+      la_list="'${la_element}'";
+    else
+      la_list="${la_list} '${la_element}'";
+    fi;
+  done;
+  eval "${la_name}"='"${la_list}"';
+  eval ${_UNSET} la_element;
+  eval ${_UNSET} la_list;
+  eval ${_UNSET} la_name;
+  eval ${_UNSET} la_s;
+  eval "${return_ok}";
+} # list_append()
+
+
+########################################################################
+# list_from_cmdline (<pre_name_of_opt_lists> [<cmdline_arg>...])
+#
+# Transform command line arguments into a normalized form.
+#
+# Options, option arguments, and file parameters are identified and
+# output each as a single-quoted argument of its own.  Options and
+# file parameters are separated by a '--' argument.
+#
+# Arguments: >=1
+#   <pre_name>: common part of a set of 4 environment variable names:
+#     $<pre_name>_SHORT_NA:  list of short options without an arg.
+#     $<pre_name>_SHORT_ARG: list of short options that have an arg.
+#     $<pre_name>_LONG_NA:   list of long options without an arg.
+#     $<pre_name>_LONG_ARG:  list of long options that have an arg.
+#   <cmdline_arg>...: the arguments from a command line, such as "$@",
+#                     the content of a variable, or direct arguments.
+#
+# Output: ['-[-]opt' ['optarg']]... '--' ['filename']...
+#
+# Example:
+#   list_from_cmdline PRE -a f1 -bcarg --lon=larg f2 low larg2
+#     PRE_SHORT_NA="'a' 'b'"
+#     PRE_SHORT_ARG="'c' 'd'"
+#     PRE_LONG_NA="'help' 'version'"
+#     PRE_LONG_ARG="'longer' 'lower'"
+# This will result in printing:
+#   '-a' '-b' '-c' 'arg' '--longer' 'larg' '--lower' 'larg2' '--' 'f1' 'f2'
+#
+#   Use this function in the following way:
+#     eval set x "$(list_from_cmdline PRE_NAME "$@")";
+#     shift;
+#     while test "$1" != '--'; do
+#       case "$1" in
+#       ...
+#       esac;
+#       shift;
+#     done;
+#     shift;         #skip '--'
+#     # all positional parameters ("$@") left are file name parameters.
+#
+# Variable prefix: lfc
+#
+list_from_cmdline()
+{
+  func_check list_from_cmdline '>=' 1 "$@";
+  # short options, no argument
+  obj_from_output lfc_short_n obj_data "$1"_SHORT_NA;
+  # short options, with argument
+  obj_from_output lfc_short_a obj_data "$1"_SHORT_ARG;
+  # long options, no argument
+  obj_from_output lfc_long_n obj_data "$1"_LONG_NA;
+  # long options, with argument
+  obj_from_output lfc_long_a obj_data "$1"_LONG_ARG;
+  if obj lfc_short_n is_empty
+  then
+    error 'list_from_cmdline(): no $'"$1"'_SHORT_NA options.';
+  fi;
+  if obj lfc_short_a is_empty
+  then
+    error 'list_from_cmdline(): no $'"$1"'_SHORT_ARG options.';
+  fi;
+  if obj lfc_long_n is_empty
+  then
+    error 'list_from_cmdline(): no $'"$1"'_LONG_NA options.';
+  fi;
+  if obj lfc_long_a is_empty
+  then
+    error 'list_from_cmdline(): no $'"$1"'_LONG_ARG options.';
+  fi;
+  shift;
+
+  if is_equal "$#" 0
+  then
+    echo1 "'--'"
+    eval ${_UNSET} lfc_fparams;
+    eval ${_UNSET} lfc_short_a;
+    eval ${_UNSET} lfc_short_n;
+### list_from_cmdline()
+    eval ${_UNSET} lfc_long_a;
+    eval ${_UNSET} lfc_long_n;
+    eval ${_UNSET} lfc_result;
+    eval "${return_ok}";
+  fi;
+
+  lfc_fparams='';
+  lfc_result='';
+  while is_greater_than "$#" 0
+  do
+    lfc_arg="$1";
+    shift;
+    case "${lfc_arg}" in
+    --) break; ;;
+    --*=*)
+      # delete leading '--';
+      lfc_with_equal="$(echo1 "${lfc_arg}" | sed 's/^--//')";
+      # extract option by deleting from the first '=' to the end
+      lfc_abbrev="$(echo1 "${lfc_with_equal}" | \
+                    sed 's/^\([^=]*\)=.*$/\1/')";
+      obj_from_output lfc_opt \
+        list_single_from_abbrev lfc_long_a "${lfc_abbrev}";
+      if obj lfc_opt is_empty
+      then
+        error_user "--${lfc_abbrev} is not an option.";
+      else
+        # get the option argument by deleting up to first `='
+        lfc_optarg="$(echo1 "${lfc_with_equal}" | sed 's/^[^=]*=//')";
+        exit_test;
+        list_append lfc_result "--${lfc_opt}" "${lfc_optarg}";
+        continue;
+      fi;
+### list_from_cmdline()
+      ;;
+    --*)
+      # delete leading '--';
+      lfc_abbrev="$(echo1 "${lfc_arg}" | sed 's/^--//')";
+      if list_has lfc_long_n "${lfc_abbrev}"
+      then
+        lfc_opt="${lfc_abbrev}";
+      else
+        obj_from_output lfc_opt \
+          list_single_from_abbrev lfc_long_n "${lfc_abbrev}";
+        if obj lfc_opt is_not_empty && is_not_equal "$#" 0
+        then
+          obj_from_output a \
+            list_single_from_abbrev lfc_long_a "${lfc_abbrev}";
+          if obj a is_not_empty
+          then
+            error_user "The abbreviation ${lfc_arg} \
+has multiple options: --${lfc_opt} and --${a}.";
+          fi;
+        fi;
+      fi; # if list_has lfc_long_n "${lfc_abbrev}"
+      if obj lfc_opt is_not_empty
+      then
+        # long option, no argument
+        list_append lfc_result "--${lfc_opt}";
+        continue;
+      fi;
+      obj_from_output lfc_opt \
+        list_single_from_abbrev lfc_long_a "${lfc_abbrev}";
+      if obj lfc_opt is_not_empty
+      then
+### list_from_cmdline()
+        # long option with argument
+        if is_equal "$#" 0
+        then
+          error_user "no argument for option --${lfc_opt}."
+        fi;
+        list_append lfc_result "--${lfc_opt}" "$1";
+        shift;
+        continue;
+      fi; # if obj lfc_opt is_not_empty
+      error_user "${lfc_arg} is not an option.";
+      ;;
+    -?*)			# short option (cluster)
+      # delete leading `-';
+      lfc_rest="$(echo1 "${lfc_arg}" | sed 's/^-//')";
+      exit_test;
+      while obj lfc_rest is_not_empty
+      do
+        # get next short option from cluster (first char of $lfc_rest)
+        lfc_optchar="$(echo1 "${lfc_rest}" | sed 's/^\(.\).*$/\1/')";
+        # remove first character from ${lfc_rest};
+        lfc_rest="$(echo1 "${lfc_rest}" | sed 's/^.//')";
+        exit_test;
+        if list_has lfc_short_n "${lfc_optchar}"
+        then
+          list_append lfc_result "-${lfc_optchar}";
+          continue;
+        elif list_has lfc_short_a "${lfc_optchar}"
+        then
+          if obj lfc_rest is_empty
+          then
+            if is_greater_than "$#" 0
+            then
+### list_from_cmdline()
+              list_append lfc_result "-${lfc_optchar}" "$1";
+              shift;
+              continue;
+            else
+              error_user "no argument for option -${lfc_optchar}.";
+            fi;
+          else			# rest is the argument
+            list_append lfc_result "-${lfc_optchar}" "${lfc_rest}";
+            lfc_rest='';
+            continue;
+          fi; # if obj lfc_rest is_empty
+        else
+          error_user "unknown option -${lfc_optchar}.";
+        fi; # if list_has lfc_short_n "${lfc_optchar}"
+      done; # while obj lfc_rest is_not_empty
+      ;;
+    *)
+      # Here, $lfc_arg is not an option, so a file parameter.
+      list_append lfc_fparams "${lfc_arg}";
+
+      # Ignore the strange POSIX option handling to end option
+      # parsing after the first file name argument.  To reuse it, do
+      # a `break' here if $POSIXLY_CORRECT of `bash' is not empty.
+      # When `bash' is called as `sh' $POSIXLY_CORRECT is set
+      # automatically to `y'.
+      ;;
+    esac; # case "${lfc_arg}" in
+  done; # while is_greater_than "$#" 0
+  list_append lfc_result '--';
+  if obj lfc_fparams is_not_empty
+  then
+    lfc_result="${lfc_result} ${lfc_fparams}";
+  fi;
+### list_from_cmdline()
+  if is_greater_than "$#" 0
+  then
+    list_append lfc_result "$@";
+  fi;
+  obj lfc_result echo1;
+  eval ${_UNSET} lfc_abbrev;
+  eval ${_UNSET} lfc_fparams;
+  eval ${_UNSET} lfc_short_a;
+  eval ${_UNSET} lfc_short_n;
+  eval ${_UNSET} lfc_long_a;
+  eval ${_UNSET} lfc_long_n;
+  eval ${_UNSET} lfc_result;
+  eval ${_UNSET} lfc_arg;
+  eval ${_UNSET} lfc_opt;
+  eval ${_UNSET} lfc_opt_arg;
+  eval ${_UNSET} lfc_opt_char;
+  eval ${_UNSET} lfc_with_equal;
+  eval ${_UNSET} lfc_rest;
+  eval "${return_ok}";
+} # list_from_cmdline()
+
+
+########################################################################
+# list_from_cmdline_with_minus (<pre_name_of_opt_lists> [<cmdline_arg>...])
+#
+# Transform command line arguments into a normalized form with a double
+# abbreviation before and after an internal `-' sign.
+#
+# Options, option arguments, and file parameters are identified and
+# output each as a single-quoted argument of its own.  Options and
+# file parameters are separated by a `--' argument.
+#
+# Arguments: >=1
+#   <pre_name>: common part of a set of 4 environment variable names:
+#     $<pre_name>_SHORT_NA:  list of short options without an arg.
+#     $<pre_name>_SHORT_ARG: list of short options that have an arg.
+#     $<pre_name>_LONG_NA:   list of long options without an arg.
+#     $<pre_name>_LONG_ARG:  list of long options that have an arg.
+#   <cmdline_arg>...: the arguments from a command line, such as "$@",
+#                     the content of a variable, or direct arguments.
+#
+# Output: ['-[-]opt' ['optarg']]... '--' ['filename']...
+#
+# Example:
+#   list_from_cmdline PRE -a f1 -bcarg --lon=larg --h-n f2 low larg2
+#     PRE_SHORT_NA="'a' 'b'"
+#     PRE_SHORT_ARG="'c' 'd'"
+#     PRE_LONG_NA="'help' 'version' 'hi-non-arg'"
+#     PRE_LONG_ARG="'long-arg' 'low-arg'"
+# This will result in printing:
+#   '-a' '-b' '-c' 'arg' '--long-arg' 'larg' '--hi-non-arg' \
+#     '--low-arg' 'larg2' '--' 'f1' 'f2'
+#
+# Use this function in the following way:
+#   eval set x "$(list_from_cmdline_with_minus PRE_NAME "$@")";
+#   shift;
+#   while test "$1" != '--'; do
+#     case "$1" in
+#     ...
+#     esac;
+#     shift;
+#   done;
+#   shift;         #skip '--'
+#   # all positional parameters ("$@") left are file name parameters.
+#
+# Variable prefix: lfcwm
+#
+list_from_cmdline_with_minus()
+{
+  func_check list_from_cmdline_with_minus '>=' 1 "$@";
+  # short options, no argument
+  obj_from_output lfcwm_short_n obj_data "$1"_SHORT_NA;
+  # short options, with argument
+  obj_from_output lfcwm_short_a obj_data "$1"_SHORT_ARG;
+  # long options, no argument
+  obj_from_output lfcwm_long_n obj_data "$1"_LONG_NA;
+  # long options, with argument
+  obj_from_output lfcwm_long_a obj_data "$1"_LONG_ARG;
+  if obj lfcwm_short_n is_empty
+  then
+    error 'list_from_cmdline(): no $'"$1"'_SHORT_NA options.';
+  fi;
+  if obj lfcwm_short_a is_empty
+  then
+    error 'list_from_cmdline(): no $'"$1"'_SHORT_ARG options.';
+  fi;
+  if obj lfcwm_long_n is_empty
+  then
+    error 'list_from_cmdline(): no $'"$1"'_LONG_NA options.';
+  fi;
+  if obj lfcwm_long_a is_empty
+  then
+    error 'list_from_cmdline(): no $'"$1"'_LONG_ARG options.';
+  fi;
+  shift;
+
+  if is_equal "$#" 0
+  then
+    echo1 "'--'";
+    eval ${_UNSET} lfcwm_short_a;
+    eval ${_UNSET} lfcwm_short_n;
+### list_from_cmdline_with_minus()
+    eval ${_UNSET} lfcwm_long_a;
+    eval ${_UNSET} lfcwm_long_n;
+    eval "${return_ok}";
+  fi;
+  obj_from_output lfcwm_long_both lists_combine lfcwm_long_a lfcwm_long_n;
+  lfcwm_fparams='';
+  lfcwm_result='';
+  while is_greater_than "$#" 0	# command line arguments
+  do
+    lfcwm_arg="$1";
+    shift;
+    lfcwm_optarg='';
+    case "${lfcwm_arg}" in
+    --)
+      break;
+      ;;
+    --*=*)
+      # delete leading '--';
+      lfcwm_with_equal="$(echo1 "${lfcwm_arg}" | sed 's/^--//')";
+      # extract option by deleting from the first '=' to the end
+      lfcwm_abbrev="$(echo1 "${lfcwm_with_equal}" | \
+                    sed 's/^\([^=]*\)=.*$/\1/')";
+      # extract option argument by deleting up to the first '='
+      lfcwm_optarg="$(echo1 "${lfcwm_with_equal}" | \
+                    sed 's/^[^=]*=\(.*\)$/\1/')";
+### list_from_cmdline_with_minus()
+      if list_has lfcwm_long_a "${lfcwm_abbrev}"
+      then
+        lfcwm_opt="${lfcwm_abbrev}";
+      else
+        obj_from_output lfcwm_opt \
+          _search_abbrev lfcwm_long_a "${lfcwm_abbrev}";
+      fi;
+      list_append lfcwm_result "--${lfcwm_opt}" "${lfcwm_optarg}";
+      continue;
+      ;;
+    --*)
+      # delete leading '--';
+      lfcwm_abbrev="$(echo1 "${lfcwm_arg}" | sed 's/^--//')";
+      if list_has lfcwm_long_both "${lfcwm_abbrev}"
+      then
+        lfcwm_opt="${lfcwm_abbrev}";
+      else
+        obj_from_output lfcwm_opt \
+          _search_abbrev lfcwm_long_both "${lfcwm_abbrev}";
+      fi;
+### list_from_cmdline_with_minus()
+      if list_has lfcwm_long_a "${lfcwm_opt}"
+      then
+        if is_equal "$#" 0
+        then
+          error_user "Option ${lfcwm_opt} needs an argument.";
+        fi;
+        lfcwm_optarg="$1";
+        shift;
+        list_append lfcwm_result "--${lfcwm_opt}" "${lfcwm_optarg}";
+      else
+        list_append lfcwm_result "--${lfcwm_opt}";
+      fi;
+      continue;
+      ;;
+    -?*)			# short option (cluster)
+      # delete leading '-';
+      lfcwm_rest="$(echo1 "${lfcwm_arg}" | sed 's/^-//')";
+      while obj lfcwm_rest is_not_empty
+      do
+        # get next short option from cluster (first char of $lfcwm_rest)
+        lfcwm_optchar="$(echo1 "${lfcwm_rest}" | sed 's/^\(.\).*$/\1/')";
+        # remove first character from ${lfcwm_rest};
+        lfcwm_rest="$(echo1 "${lfcwm_rest}" | sed 's/^.//')";
+        if list_has lfcwm_short_n "${lfcwm_optchar}"
+        then
+          list_append lfcwm_result "-${lfcwm_optchar}";
+          continue;
+        elif list_has lfcwm_short_a "${lfcwm_optchar}"
+        then
+          if obj lfcwm_rest is_empty
+          then
+            if is_greater_than "$#" 0
+            then
+### list_from_cmdline_with_minus()
+              list_append lfcwm_result "-${lfcwm_optchar}" "$1";
+              shift;
+              continue;
+            else
+              error_user "no argument for option -${lfcwm_optchar}.";
+            fi;
+          else			# rest is the argument
+            list_append lfcwm_result "-${lfcwm_optchar}" "${lfcwm_rest}";
+            lfcwm_rest='';
+            continue;
+          fi; # if obj lfcwm_rest is_empty
+        else
+          error_user "unknown option -${lfcwm_optchar}.";
+        fi; # if list_has lfcwm_short_n "${lfcwm_optchar}"
+      done; # while obj lfcwm_rest is_not_empty
+      ;;
+    *)
+      # Here, $lfcwm_arg is not an option, so a file parameter.
+      list_append lfcwm_fparams "${lfcwm_arg}";
+
+      # Ignore the strange POSIX option handling to end option
+      # parsing after the first file name argument.  To reuse it, do
+      # a `break' here if $POSIXLY_CORRECT of `bash' is not empty.
+      # When `bash' is called as `sh' $POSIXLY_CORRECT is set
+      # automatically to `y'.
+      ;;
+    esac;
+  done;
+
+  list_append lfcwm_result '--';
+  if obj lfcwm_fparams is_not_empty
+  then
+    lfcwm_result="${lfcwm_result} ${lfcwm_fparams}";
+  fi;
+### list_from_cmdline_with_minus()
+  if is_greater_than "$#" 0
+  then
+    list_append lfcwm_result "$@";
+  fi;
+  obj lfcwm_result echo1;
+  eval ${_UNSET} lfcwm_abbrev;
+  eval ${_UNSET} lfcwm_fparams;
+  eval ${_UNSET} lfcwm_short_a;
+  eval ${_UNSET} lfcwm_short_n;
+  eval ${_UNSET} lfcwm_long_a;
+  eval ${_UNSET} lfcwm_long_both;
+  eval ${_UNSET} lfcwm_long_n;
+  eval ${_UNSET} lfcwm_result;
+  eval ${_UNSET} lfcwm_arg;
+  eval ${_UNSET} lfcwm_opt;
+  eval ${_UNSET} lfcwm_optarg;
+  eval ${_UNSET} lfcwm_optchar;
+  eval ${_UNSET} lfcwm_with_equal;
+  eval ${_UNSET} lfcwm_rest;
+  eval "${return_ok}";
+} # list_from_cmdline_with_minus()
+
+
+# _search_abbrev (<list> <abbrev>)
+#
+# Check whether <list> has an element constructed from the abbreviation
+# <abbrev>.  All `-' in <abbrev> are replaced by `-*'.  This construction
+# is searched first with `<construction>[^-]*'.  If there is more than a
+# single element an error is created.  If none is found `<construction>*'
+# is searched.  Again an error is created for several results.
+# This function was constructed from the former function
+# list_single_from_abbrev().
+#
+# This is a local function of list_from_cmdline_with_minus().
+#
+# Arguments: 2
+#   <list>:   a variable name for a list of single-quoted elements
+#   <abbrev>: some sequence of characters.
+#
+# Output: the found element (always not empty), error when none found.
+#
+# Variable prefix: _sa
+#
+_search_abbrev()
+{
+  func_check _search_abbrev '=' 2 "$@";
+  eval _sa_list='"${'$1'}"';
+  if obj _sa_list is_empty
+  then
+    error "_search_abbrev(): list is empty.";
+  fi;
+
+  _sa_abbrev="$2";
+  if obj _sa_abbrev is_empty
+  then
+    error "_search_abbrev(): abbreviation argument is empty.";
+  fi;
+
+  _sa_case="$(echo1 "${_sa_abbrev}" | sed 's/-/\*-/g')";
+  _sa_opt='';
+  case " ${_sa_list}" in
+  *\ \'${_sa_case}*)		# list has the abbreviation
+    _sa_m1='';
+    _sa_m2='';
+    _sa_nm='';
+    eval set x "${_sa_list}";
+    shift;
+    for i			# over the option list
+    do
+      _sa_i="$i";
+### _search_abbrev() of list_from_cmdline_with_minus()
+      case "${_sa_i}" in
+      ${_sa_case}*-*)
+        if obj _sa_m1 is_empty
+        then
+          _sa_m1="${_sa_i}";
+          continue;
+        fi;
+        _sa_m2="${_sa_i}";
+        continue;
+        ;;
+      ${_sa_case}*)
+        if obj _sa_nm is_empty
+        then
+          _sa_nm="${_sa_i}";
+          continue;
+        fi;
+        error_user "The abbreviation --${_sa_abbrev} has multiple options "\
+"--${_sa_nm} and --${_sa_i}.";
+        ;;
+      esac;
+    done;
+    if obj _sa_nm is_empty
+    then
+      if obj _sa_m2 is_not_empty
+      then
+        error_user "The abbreviation --${_sa_abbrev} has multiple options "\
+"--${_sa_m1} and --${_sa_m2}.";
+      fi;
+### _search_abbrev() of list_from_cmdline_with_minus()
+      if obj _sa_m1 is_not_empty
+      then
+        _sa_opt="${_sa_m1}";
+      fi;
+    else
+      _sa_opt="${_sa_nm}";
+    fi;
+    ;;
+  esac;
+  if obj _sa_opt is_empty
+  then
+    error_user "--${_sa_abbrev} is not an option.";
+  fi;
+  obj _sa_opt echo1;
+  eval "${_UNSET}" _sa_abbrev;
+  eval "${_UNSET}" _sa_case;
+  eval "${_UNSET}" _sa_i;
+  eval "${_UNSET}" _sa_list;
+  eval "${_UNSET}" _sa_m1;
+  eval "${_UNSET}" _sa_m2;
+  eval "${_UNSET}" _sa_nm;
+  eval "${_UNSET}" _sa_opt;
+  eval "${return_ok}";
+} # _search_abbrev() of list_from_cmdline_with_minus()
+
+
+########################################################################
+# list_from_file (<list_name> <file_name>)
+#
+# Extrect the lines from <file_name> and store them as elements to list
+# <list_name>.
+#
+# Arguments: 2
+#   <list_name>: a variable name for output, a list of single-quoted elts
+#   <file_name>: the name of an existing file
+#
+# Variable prefix: lff
+#
+list_from_file()
+{
+  func_check list_from_file '=' 2 "$@";
+  if is_not_file "$2"
+  then
+    eval "${return_bad}";
+  fi;
+  lff_n="$(wc -l "$2" | eval sed "'s/^[ ${_TAB}]*\([0-9]\+\).*$/\1/'")";
+  eval "$1"="''";
+  if obj lff_n is_equal 0
+  then
+    eval "${return_good}";
+  fi;
+  lff_i=0;
+  while obj lff_i is_not_equal "${lff_n}"
+  do
+    lff_i="$(expr "${lff_i}" + 1)";
+    list_append "$1" "$(eval sed -n "'${lff_i}p
+${lff_i}q'" "'$2'")";
+  done;
+  eval "${_UNSET}" lff_i;
+  eval "${_UNSET}" lff_n;
+  eval "${return_good}";
+} # list_from_file()
+
+
+########################################################################
+# list_from_split (<string> <separator_char>)
+#
+# Split <string> by <separator_char> into a list, omitting the separator.
+#
+# Arguments: 2: a <string> that is to be split into parts divided by
+#               character <separator_char>
+# Output: the resulting list string
+#
+# Variable prefix: lfs
+#
+list_from_split()
+{
+  func_check list_from_split = 2 "$@";
+  if is_empty "$1"
+  then
+    eval "${return_ok}";
+  fi;
+  case "$2" in
+  ?)
+    lfs_splitter="$2";
+    ;;
+  '\:')
+    lfs_splitter=':';
+    ;;
+  *)
+    error "list_from_split(): split argument $2 must be a single character.";
+    ;;
+  esac;
+  lfs_list='';
+  lfs_rest="$1";
+  while :
+  do
+    case "${lfs_rest}" in
+    *${lfs_splitter}*)
+      case "${lfs_splitter}" in
+      /)
+        lfs_elt="$(echo1 ${lfs_rest} | sed \
+          's|^\([^'"${lfs_splitter}"']*\)'"${lfs_splitter}"'.*|\1|')";
+        lfs_rest="$(echo1 ${lfs_rest} | sed \
+          's|^[^'"${lfs_splitter}"']*'"${lfs_splitter}"'\(.*\)$|\1|')";
+        ;;
+      *)
+### list_from_split()
+        lfs_elt="$(echo1 ${lfs_rest} | sed \
+          's/^\([^'"${lfs_splitter}"']*\)'"${lfs_splitter}"'.*/\1/')";
+        lfs_rest="$(echo1 ${lfs_rest} | sed \
+          's/^[^'"${lfs_splitter}"']*'"${lfs_splitter}"'\(.*\)$/\1/')";
+        ;;
+      esac;
+      list_append lfs_list "${lfs_elt}"
+      continue;
+      ;;
+    *)
+      list_append lfs_list "${lfs_rest}"
+      break
+      ;;
+    esac;
+  done
+  echo1 "${lfs_list}";
+
+  eval ${_UNSET} lfs_elt;
+  eval ${_UNSET} lfs_list;
+  eval ${_UNSET} lfs_rest;
+  eval ${_UNSET} lfs_splitter;
+  eval "${return_ok}";
+} # list_from_split()
+
+
+########################################################################
+# list_has (<list-name> <element>)
+#
+# Test whether the list <list-name> has the element <element>.
+#
+# Arguments: 2
+#   <list_name>: a variable name for a list of single-quoted elements
+#   <element>:  some sequence of characters.
+#
+# Variable prefix: lh
+#
+list_has()
+{
+  func_check list_has = 2 "$@";
+  eval lh_list='"${'$1'}"';
+  if obj lh_list is_empty
+  then
+    eval "${_UNSET}" lh_list;
+    eval "${return_no}";
+  fi;
+  case "$2" in
+    \'*\')  lh_element=" $2 "; ;;
+    *)      lh_element=" '$2' "; ;;
+  esac;
+  if string_contains " ${lh_list} " "${lh_element}"
+  then
+    eval "${_UNSET}" lh_list;
+    eval "${_UNSET}" lh_element;
+    eval "${return_yes}";
+  else
+    eval "${_UNSET}" lh_list;
+    eval "${_UNSET}" lh_element;
+    eval "${return_no}";
+  fi;
+} # list_has()
+
+
+########################################################################
+# list_has_abbrev (<list_var> <abbrev>)
+#
+# Test whether the list of <list_var> has an element starting with
+# <abbrev>.
+#
+# Arguments: 2
+#   <list_var>: a variable name for a list of single-quoted elements
+#   <abbrev>:   some sequence of characters.
+#
+# Variable prefix: lha
+#
+list_has_abbrev()
+{
+  func_check list_has_abbrev '=' 2 "$@";
+  eval lha_list='"${'$1'}"';
+  if obj lha_list is_empty
+  then
+    eval "${_UNSET}" lha_list;
+    eval "${return_no}";
+  fi;
+  case "$2" in
+  \'*)
+    lha_element="$(echo1 "$2" | sed 's/'"${_SQ}"'$//')";
+    ;;
+  *)
+    lha_element="'$2";
+    ;;
+  esac;
+  if string_contains " ${lha_list}" " ${lha_element}"
+  then
+    eval "${_UNSET}" lha_list;
+    eval "${_UNSET}" lha_element;
+    eval "${return_yes}";
+  else
+    eval "${_UNSET}" lha_list;
+    eval "${_UNSET}" lha_element;
+    eval "${return_no}";
+  fi;
+  eval "${return_ok}";
+} # list_has_abbrev()
+
+
+########################################################################
+# list_has_not (<list> <element>)
+#
+# Test whether <list> has no <element>.
+#
+# Arguments: 2
+#   <list>:    a space-separated list of single-quoted elements.
+#   <element>: some sequence of characters.
+#
+# Variable prefix: lhn
+#
+list_has_not()
+{
+  func_check list_has_not = 2 "$@";
+  eval lhn_list='"${'$1'}"';
+  if obj lhn_list is_empty
+  then
+    eval "${_UNSET}" lhn_list;
+    eval "${return_yes}";
+  fi;
+  case "$2" in
+    \'*\') lhn_element=" $2 "; ;;
+    *)     lhn_element=" '$2' "; ;;
+  esac;
+  if string_contains " ${lhn_list} " "${lhn_element}"
+  then
+    eval "${_UNSET}" lhn_list;
+    eval "${_UNSET}" lhn_element;
+    eval "${return_no}";
+  else
+    eval "${_UNSET}" lhn_list;
+    eval "${_UNSET}" lhn_element;
+    eval "${return_yes}";
+  fi;
+} # list_has_not()
+
+
+########################################################################
+# list_single_from_abbrev (<list-var> <abbrev>)
+#
+# Check whether the list has an element starting with <abbrev>.  If
+# there are more than a single element an error is raised.
+#
+# Arguments: 2
+#   <list-var>: a variable name for a list of single-quoted elements
+#   <abbrev>:   some sequence of characters.
+#
+# Output: the found element.
+#
+# Variable prefix: lsfa
+#
+list_single_from_abbrev()
+{
+  func_check list_single_from_abbrev '=' 2 "$@";
+  eval lsfa_list='"${'$1'}"';
+  if obj lsfa_list is_empty
+  then
+    eval "${_UNSET}" lsfa_list;
+    eval "${return_no}";
+  fi;
+  lsfa_abbrev="$2";
+  if list_has lsfa_list "${lsfa_abbrev}"
+  then
+    obj lsfa_abbrev echo1;
+    eval "${_UNSET}" lsfa_abbrev;
+    eval "${_UNSET}" lsfa_list;
+    eval "${return_yes}";
+  fi;
+  if list_has_abbrev lsfa_list "${lsfa_abbrev}"
+  then
+    lsfa_element='';
+    eval set x "${lsfa_list}";
+    shift;
+### list_single_from_abbrev()
+    for i
+    do
+      case "$i" in
+      ${lsfa_abbrev}*)
+        if obj lsfa_element is_not_empty
+        then
+          error_user "The abbreviation --${lsfa_abbrev} \
+has multiple options: --${lsfa_element} and --${i}.";
+        fi;
+        lsfa_element="$i";
+        ;;
+      esac;
+    done;
+    obj lsfa_element echo1;
+    eval "${_UNSET}" lsfa_abbrev;
+    eval "${_UNSET}" lsfa_element;
+    eval "${_UNSET}" lsfa_list;
+    eval "${return_yes}";
+  else
+    eval "${_UNSET}" lsfa_abbrev;
+    eval "${_UNSET}" lsfa_element;
+    eval "${_UNSET}" lsfa_list;
+    eval "${return_no}";
+  fi;
+} # list_single_from_abbrev()
+
+
+########################################################################
+# list_uniq (<list>)
+#
+# Generate a list with only unique elements.
+#
+# Output: the corrected list
+#
+# Variable prefix: lu
+#
+list_uniq()
+{
+  func_check list_uniq '=' 1 "$@";
+  if is_empty "$1"
+  then
+    eval "${return_ok}";
+  fi;
+  eval a='"${'"$1"'}"';
+  if obj a is_empty
+  then
+    eval "${return_ok}";
+  fi;
+  eval set x "$a";
+  shift;
+  lu_list='';
+  for i
+  do
+    lu_i="$i";
+    if list_has lu_list "${lu_i}"
+    then
+      continue;
+    else
+      list_append lu_list ${lu_i};
+    fi;
+  done;
+  obj lu_list echo1;
+  eval "${_UNSET}" lu_i;
+  eval "${_UNSET}" lu_list;
+  eval "${return_ok}";
+} # list_uniq()
+
+
+########################################################################
+# lists_combine (<list1> <list2> ...)
+#
+# Combine several lists to a single list.  All arguments are list names.
+#
+# Output: the combined list
+#
+# Variable prefix: lc
+#
+lists_combine()
+{
+  func_check lists_combine '>=' 2 "$@";
+  lc_list='';
+  for i
+  do
+    eval lc_arg='"${'"$i"'}"';
+    case "${lc_arg}" in
+    '') :; ;;
+    "'"*"'")
+      if obj lc_list is_empty
+      then
+        lc_list="${lc_arg}";
+      else
+        lc_list="${lc_list} ${lc_arg}";
+      fi;
+      ;;
+    *)
+      error 'lists_combine(): $'"$i"' is not a list.';
+      ;;
+    esac;
+  done;
+  obj lc_list echo1;
+  eval "${_UNSET}" lc_arg;
+  eval "${_UNSET}" lc_list;
+  eval "${return_ok}";
+} # lists_combine()
+
+
+########################################################################
+landmark '7: man_*()';
+########################################################################
+
+########################################################################
+# Information on the search of man pages in groffer
+
+# The search of man pages is based on a set of directories.  That
+# starts with the so-called man path.  This is determined in function
+# man_setup() either by the command-line option --manpath, by $MANOPT,
+# or by $MANPATH.  There is also a program `manpath'.  If all of this
+# does not work a man path is created from $PATH with function
+# manpath_set_from_path().  We now have a set of existing directories
+# for the search of man pages; usually they end with `/man'.
+
+# The directory set of the man path can be changed in 2 ways.  If
+# operating system names are given in $SYSTEM or by --systems on the
+# command-line all man path directory will be appended by these names.
+# The appended system names replace the original man path; but if no
+# system name is set, the original man path is kept.  In `groffer',
+# this is done by the function manpath_add_lang_sys() in man_setup().
+
+# The next addition for directories is the language.  It is specified
+# by --locale or by one of the environment variables $LC_ALL,
+# $LC_MESSAGES, and $LANG.  The language name of `C' or `POSIX' means
+# the return to the default language (usually English); this deletes
+# former language specifications.  The language name and its
+# abbreviation with 2 characters is appended to the man page
+# directories.  But these new arising directories are added to the man
+# page, they do not replace it such as the system names did.  This is
+# done by function manpath_add_lang_sys() in man_setup() as well.
+
+# Now we have the basic set of directories for the search of man pages
+# for given filespec arguments.  The real directories with the man
+# page source files are gotten by appending `man<section>' to each
+# directory, where section is a single character of the form
+# `[1-9on]'.
+
+# There you find files named according to the form
+# <name>.<section>[<extension>][<compression>], where `[]' means
+# optional this time.  <name> is the name of the man page; <section>
+# is the single character from the last paragraphe; the optional
+# <extension> consists of some letters denoting special aspects for
+# the section; and the optional <compression> is something like `.gz',
+# `.Z', or `.bz2', meaning that the file is compressed.
+
+# If name, section. and extension are specified on the command-line
+# the file of the form <name>.<section><extension> with or without
+# <compression> are handled.  The first one found according to the
+# directory set for the section is shown.
+
+# If just name and section are specified on the command-line then
+# first <name>.<section> with or without <compression> are searched.
+# If no matching file was found, <name>.<section><extension> with or
+# without <compression> are searched for all possible extensions.
+
+# If only name is specified on the command-line then the section
+# directories are searched by and by, starting with section `1', until
+# a file is matched.
+
+# The function man_is_man() determines all suitable man files for a
+# command-line argument, while man_get() searches the single matching
+# file for display.
+
+
+########################################################################
+# man_get (<man-name> [<section> [<extension>]])
+#
+# Write a man page to the temporary file.
+#
+# Globals in: $_TMP_MANSPEC, $_MAN_SEC_CHARS, $_MAN_EXT, $_MAN_ALL
+#
+# Arguments: 1, 2, or 3
+#
+# Variable prefix: mg
+#
+man_get()
+{
+  func_check man_get '>=' 1 "$@";
+  if obj _TMP_MANSPEC is_empty
+  then
+    error 'man_get(): man_is_man() must be run first on '"$*".;
+  fi;
+  mg_name="$1";
+  mg_sec="$2";
+  if is_empty "$2"
+  then
+    mg_sec="${_MAN_SEC_CHARS}";	# take care it is not a single section
+  fi;
+  mg_ext="$3";
+  if is_empty "$3"
+  then
+    mg_ext="${_MAN_EXT}";
+  fi;
+  if obj _TMP_MANSPEC is_not_equal "${_TMP_DIR}/,man:$1:${mg_sec}${mg_ext}"
+  then
+    error 'man_get(): $_TMP_MANSPEC does not suit to the arguments '"$*".;
+  fi;
+### man_get()
+
+  if obj _MAN_ALL is_yes
+  then
+    list_from_file mg_list "${_TMP_MANSPEC}";
+    eval set x ${mg_list};
+    shift;
+    mg_ok='no';
+    mg_list='';
+    for f
+    do
+      mg_f="$f";
+      if list_has mg_list "${mg_f}"
+      then
+        continue;
+      else
+        list_append mg_list "${mg_f}";
+      fi;
+### man_get()
+      if obj mg_f is_file
+      then
+        to_tmp "${mg_f}" && mg_ok='yes';
+      fi;
+    done;
+    if obj mg_ok is_yes
+    then
+      register_title man:"${mg_name}";
+    fi;
+    eval ${_UNSET} mg_ext;
+    eval ${_UNSET} mg_f;
+    eval ${_UNSET} mg_list;
+    eval ${_UNSET} mg_name;
+    eval ${_UNSET} mg_sec;
+    eval "${return_ok}";
+  else				# $_MAN_ALL is not 'yes'
+    if is_empty "$2"
+    then			# no section from command line
+      if obj _MAN_SEC_LIST is_empty
+      then
+        m="${_MAN_AUTO_SEC_LIST}"; # list of all sections
+      else
+        m="${_MAN_SEC_LIST}";	# from --sections
+      fi;
+### man_get()
+      for s in $(eval set x $m; shift; echo1 "$@")
+      do
+        mg_s="$s";
+        list_from_file mg_list "${_TMP_MANSPEC}";
+        eval set x ${mg_list};
+        shift;
+        if obj mg_ext is_empty
+        then
+          for f
+          do
+            mg_f="$f";
+            case "${mg_f}" in
+*/man"${mg_s}"/"${mg_name}"."${mg_s}"|*/man"${mg_s}"/"${mg_name}"."${mg_s}".*)
+              if obj mg_f is_file
+              then
+                to_tmp "${mg_f}" && register_title "${mg_name}(${mg_s})";
+                eval ${_UNSET} mg_ext;
+                eval ${_UNSET} mg_f;
+                eval ${_UNSET} mg_list;
+                eval ${_UNSET} mg_name;
+                eval ${_UNSET} mg_s;
+                eval ${_UNSET} mg_sec;
+                eval "${return_ok}";
+              fi;
+              ;;
+             esac;		# "$mg_f"
+          done;			# for f
+        fi;			# mg_ext is_empty
+### man_get()
+        for f
+        do
+          mg_f="$f";
+          case "${mg_f}" in
+          */man"${mg_s}"/"${mg_name}"."${mg_s}""${mg_ext}"*)
+            if obj mg_f is_file
+            then
+              to_tmp "${mg_f}" && register_title "${mg_name}(${mg_s})";
+              eval ${_UNSET} mg_ext;
+              eval ${_UNSET} mg_f;
+              eval ${_UNSET} mg_list;
+              eval ${_UNSET} mg_name;
+              eval ${_UNSET} mg_s;
+              eval ${_UNSET} mg_sec;
+              eval "${return_ok}";
+            fi;
+            ;;
+           esac;		# "$mg_f"
+        done;			# for f
+      done;			# for s
+    else			# $mg_sec is not empty, do with section
+      list_from_file mg_list "${_TMP_MANSPEC}";
+      eval set x ${mg_list};
+      shift;
+      if obj mg_ext is_empty
+      then
+        for f
+        do
+          mg_f="$f";
+### man_get()
+          case "${mg_f}" in
+*/man"${mg_sec}"/"${mg_name}"."${mg_sec}"|\
+*/man"${mg_sec}"/"${mg_name}"."${mg_sec}".*)
+            if obj mg_f is_file
+            then
+              obj mg_f to_tmp && \
+                register_title "${mg_name}(${mg_sec})";
+              eval ${_UNSET} mg_ext;
+              eval ${_UNSET} mg_f;
+              eval ${_UNSET} mg_list;
+              eval ${_UNSET} mg_name;
+              eval ${_UNSET} mg_s;
+              eval ${_UNSET} mg_sec;
+              eval "${return_ok}";
+            fi;
+            ;;
+          esac;
+        done;			# for f
+        for f
+        do
+          mg_f="$f";
+### man_get()
+          case "${mg_f}" in
+*/man"${mg_sec}"/"${mg_name}"."${mg_sec}"*)
+            if obj mg_f is_file
+            then
+              obj mg_f to_tmp && \
+                register_title "${mg_name}(${mg_sec})";
+              eval ${_UNSET} mg_ext;
+              eval ${_UNSET} mg_f;
+              eval ${_UNSET} mg_list;
+              eval ${_UNSET} mg_name;
+              eval ${_UNSET} mg_s;
+              eval ${_UNSET} mg_sec;
+              eval "${return_ok}";
+            fi;
+            ;;
+          esac;
+        done;			# for f
+      else			# mg_ext is not empty
+        for f
+        do
+          mg_f="$f";
+### man_get()
+          case "${mg_f}" in
+*/man"${mg_sec}"/"${mg_name}"."${mg_sec}""${mg_ext}"|\
+*/man"${mg_sec}"/"${mg_name}"."${mg_sec}""${mg_ext}".*)
+            if obj mg_f is_file
+            then
+              obj mg_f to_tmp && \
+                register_title "${mg_name}(${mg_sec}${mg_ext})";
+              eval ${_UNSET} mg_ext;
+              eval ${_UNSET} mg_f;
+              eval ${_UNSET} mg_list;
+              eval ${_UNSET} mg_name;
+              eval ${_UNSET} mg_s;
+              eval ${_UNSET} mg_sec;
+              eval "${return_ok}";
+            fi;
+            ;;
+          esac;
+        done;			# for f
+        for f
+        do
+          mg_f="$f";
+### man_get()
+          case "${mg_f}" in
+          */man"${mg_sec}"/"${mg_name}"."${mg_sec}""${mg_ext}"*)
+            if obj mg_f is_file
+            then
+              obj mg_f to_tmp && \
+                register_title "${mg_name}(${mg_sec}${mg_ext})";
+              eval ${_UNSET} mg_ext;
+              eval ${_UNSET} mg_f;
+              eval ${_UNSET} mg_list;
+              eval ${_UNSET} mg_name;
+              eval ${_UNSET} mg_s;
+              eval ${_UNSET} mg_sec;
+              eval "${return_ok}";
+            fi;
+            ;;
+          esac;
+        done;			# for f
+      fi;
+    fi;				# $mg_sec
+  fi;				# $_MAN_ALL
+
+  eval ${_UNSET} mg_ext;
+  eval ${_UNSET} mg_f;
+  eval ${_UNSET} mg_list;
+  eval ${_UNSET} mg_name;
+  eval ${_UNSET} mg_sec;
+  eval ${_UNSET} mg_s;
+  eval "${return_ok}";
+} # man_get()
+
+
+########################################################################
+# man_is_man (<man-name> [<section> [<extension>]])
+#
+# Test whether <man-name> exists as man page.
+#
+# Globals: in: $_TMP_MAN, $_MAN_SEC_CHARS, $_TMP_DIR, $_MAN_EXT,
+#              $_MAN_AUTO_SEC_CHARS
+#         out: $_TMP_MANSPEC
+#
+# Arguments: 1, 2, or 3
+#
+# Variable prefix: mim
+#
+man_is_man()
+{
+  func_check man_is_man '>=' 1 "$@";
+  if is_empty "$1"
+  then
+    _TMP_MANSPEC='';
+    eval "${return_no}";
+  fi;
+  if obj _TMP_DIR is_empty
+  then
+    error 'man_is_man(): main_init() must be run first.';
+  fi;
+  if obj _MAN_IS_SETUP is_not_yes
+  then
+    error 'man_is_man(): man_setup() must be run first.';
+  fi;
+  mim_sec="$2";
+  if is_empty "$2"
+  then
+    mim_sec="${_MAN_SEC_CHARS}";
+  fi;
+  if is_empty "$3"
+  then
+    mim_ext="${_MAN_EXT}";
+  else
+    mim_ext="$3";
+  fi;
+  _TMP_MANSPEC="${_TMP_DIR}/,man:$1:${mim_sec}${mim_ext}";
+### man_is_man()
+  if obj _TMP_MANSPEC is_not_file
+  then
+    if obj mim_sec is_empty
+    then
+      m="${_MAN_AUTO_SEC_CHARS}";
+      eval grep "'/man$m/$1\.$m${mim_ext}'" \
+           "${_TMP_MAN}" > "${_TMP_MANSPEC}";
+    else
+      eval grep "'/man${mim_sec}/$1\.${mim_sec}${mim_ext}'" \
+           "${_TMP_MAN}" > "${_TMP_MANSPEC}";
+    fi;
+  fi;
+  eval ${_UNSET} mim_ext;
+  eval ${_UNSET} mim_sec;
+  if obj _TMP_MANSPEC is_empty_file
+  then
+    rm_file_with_debug "${_TMP_MANSPEC}";
+    eval "${return_no}";
+  else
+    eval "${return_yes}";
+  fi;
+} # man_is_man()
+
+
+########################################################################
+# man_setup ()
+#
+# Setup the variables $_MAN_* needed for man page searching.
+#
+# Globals:
+#   in:     $_OPT_*, $_MANOPT_*, $LANG, $LC_MESSAGES, $LC_ALL,
+#           $MANPATH, $MANSEC, $PAGER, $SYSTEM, $MANOPT.
+#   out:    $_MAN_PATH, $_MAN_LANG, $_MAN_SYS, $_MAN_LANG, $_MAN_LANG2,
+#           $_MAN_SEC, $_MAN_ALL, $_TMP_MAN
+#   in/out: $_MAN_ENABLE
+#
+# The precedence for the variables related to `man' is that of GNU
+# `man', i.e.
+#
+# $LANG; overridden by
+# $LC_MESSAGES; overridden by
+# $LC_ALL; this has the same precedence as
+# $MANPATH, $MANSEC, $PAGER, $SYSTEM; overridden by
+# $MANOPT; overridden by
+# the groffer command line options.
+#
+# $MANROFFSEQ is ignored because grog determines the preprocessors.
+#
+# Variable prefix: ms
+#
+man_setup()
+{
+  func_check man_setup '=' 0 "$@";
+
+  if obj _MAN_IS_SETUP is_yes
+  then
+    eval "${return_ok}";
+  fi;
+  _MAN_IS_SETUP='yes';
+
+  if obj _MAN_ENABLE is_not_yes
+  then
+    eval "${return_ok}";
+  fi;
+
+  # determine basic path for man pages
+  obj_from_output ms_path \
+    get_first_essential "${_OPT_MANPATH}" "${_MANOPT_PATH}" "${MANPATH}";
+  if obj ms_path is_empty && is_prog 'manpath'
+  then
+    obj_from_output ms_path manpath 2>${_NULL_DEV}; # not always available
+  fi;
+  if obj ms_path is_empty
+  then
+    manpath_set_from_path;
+  else
+    obj_from_output _MAN_PATH path_list "${ms_path}";
+  fi;
+  if obj _MAN_PATH is_empty
+  then
+    _MAN_ENABLE="no";
+    echo2 "man_setup(): man path is empty";
+    eval ${_UNSET} ms_path;
+    eval "${return_ok}";
+  fi;
+  obj_from_output _MAN_PATH list_uniq _MAN_PATH;
+### man_setup()
+
+  if obj _MAN_ALL is_not_yes
+  then
+    if obj _OPT_ALL is_yes || obj _MANOPT_ALL is_yes
+    then
+      _MAN_ALL='yes';
+    else
+      _MAN_ALL='no';
+    fi;
+  fi;
+
+  ms_sys="$(get_first_essential \
+              "${_OPT_SYSTEMS}" "${_MANOPT_SYS}" "${SYSTEM}")";
+  if obj ms_sys is_not_empty
+  then
+    obj_from_output _MAN_SYS list_from_split "${ms_sys}" ',';
+  fi;
+
+  obj_from_output ms_lang get_first_essential \
+           "${_OPT_LANG}" "${LC_ALL}" "${LC_MESSAGES}" "${LANG}";
+  case "${ms_lang}" in
+    C|POSIX)
+      _MAN_LANG="";
+      _MAN_LANG2="";
+      ;;
+    ?)
+      _MAN_LANG="${ms_lang}";
+      _MAN_LANG2="";
+      ;;
+    ??)
+      _MAN_LANG="${ms_lang}";
+      _MAN_LANG2="${ms_lang}";
+      ;;
+### man_setup()
+    *)
+      _MAN_LANG="${ms_lang}";
+      # get first two characters of $ms_lang
+      _MAN_LANG2="$(echo1 "${ms_lang}" | sed 's/^\(..\).*$/\1/')";
+      exit_test;
+      ;;
+  esac;
+  # from now on, use only $_MAN_LANG*, forget about $_OPT_LANG, $LC_*.
+
+  manpath_add_lang_sys;
+  obj_from_output _MAN_PATH list_uniq _MAN_PATH;
+
+  obj_from_output _MAN_SEC get_first_essential \
+    "${_OPT_SECTIONS}" "${_MANOPT_SEC}" "${MANSEC}";
+  _MAN_SEC_LIST="";
+  _MAN_SEC_CHARS="";
+  case "${_MAN_SEC}" in
+  *:*)
+    eval set x "$(list_from_split "${_MAN_SEC}" :)";
+    shift;
+    for s
+    do
+      if list_has _MAN_AUTO_SEC_LIST "$s"
+      then
+        list_append _MAN_SEC_LIST "$s";
+        _MAN_SEC_CHARS="${_MAN_SEC_CHARS}$s";
+      fi;
+    done
+    if obj _MAN_SEC_CHARS is_not_empty
+    then
+      _MAN_SEC_CHARS="[${_MAN_SEC_CHARS}]";
+    fi;
+    ;;
+  *)
+    if list_has _MAN_AUTO_SEC_LIST "${_MAN_SEC}"
+    then
+      list_append _MAN_SEC_LIST "${_MAN_SEC}";
+      _MAN_SEC_CHARS="[${_MAN_SEC}]";
+    fi;
+    ;;
+  esac;
+
+### man_setup()
+  obj_from_output _MAN_EXT get_first_essential \
+    "${_OPT_EXTENSION}" "${_MANOPT_EXTENSION}" "${EXTENSION}";
+
+  _TMP_MAN="$(tmp_create man)";
+
+  eval set x "${_MAN_PATH}";
+  shift;
+  if is_not_equal "$#" 0
+  then
+    for i
+    do
+      for j in "$i"/man*
+      do
+        if obj j is_dir
+	then
+          find "$j" >>"${_TMP_MAN}";
+        fi;
+      done
+    done;
+  fi;
+
+  eval ${_UNSET} ms_lang;
+  eval ${_UNSET} ms_list;
+  eval ${_UNSET} ms_path;
+  eval ${_UNSET} ms_sys;
+  eval "${return_ok}";
+} # man_setup()
+
+
+########################################################################
+landmark '8: manpath_*()';
+########################################################################
+
+########################################################################
+# manpath_add_lang_sys ()
+#
+# Add language and operating system specific directories to man path.
+#
+# Arguments : 0
+# Output    : none
+# Globals:
+#   in:     $_MAN_SYS: a list of names of operating systems.
+#           $_MAN_LANG and $_MAN_LANG2: each a single name
+#   in/out: $_MAN_PATH: list of directories which shall have the `man?'
+#             subdirectories.
+#
+# Variable prefix: mals
+#
+manpath_add_lang_sys()
+{
+  func_check manpath_add_lang_sys '=' 0 "$@";
+  if obj _MAN_PATH is_empty
+  then
+    eval "${return_ok}";
+  fi;
+  if obj _MAN_SYS is_empty
+  then
+    mals_mp="${_MAN_PATH}";
+  else
+    mals_mp='';
+    eval set x "${_MAN_SYS}";
+    shift;
+    for s
+    do
+      _manpath_add_sys "$s";
+    done;
+  fi;
+
+  if obj mals_mp is_not_empty
+  then
+    mals_lang_path='';
+    if is_equal "$_MAN_LANG" "$_MAN_LANG2"
+    then
+      mals_man_lang2='';
+    else
+      mals_man_lang2="${_MAN_LANG2}";
+    fi;
+    for i in "${_MAN_LANG}" "${mals_man_lang2}"
+    do
+      if obj i is_empty
+      then
+        continue;
+      fi;
+### manpath_add_lang_sys()
+      mals_lang="$i";
+      eval set x "${mals_mp}";
+      shift;
+      for p
+      do
+        obj_from_output mals_dir dir_name_append "${p}" "${mals_lang}";
+        if obj mals_dir is_dir
+        then
+          list_append mals_lang_path "${mals_dir}";
+        fi;
+      done;
+    done;
+    obj_from_output mals_mp lists_combine mals_lang_path mals_mp;
+  fi;
+
+  _MAN_PATH="${mals_mp}";
+  eval ${_UNSET} mals_dir;
+  eval ${_UNSET} mals_lang;
+  eval ${_UNSET} mals_lang_path;
+  eval ${_UNSET} mals_man_lang2;
+  eval ${_UNSET} mals_mp;
+  eval "${return_ok}";
+} # manpath_add_lang_sys()
+
+
+# _manpath_add_sys (<system>)
+#
+# Append the existing subdirectories <system> of man path directories to
+# the list $mals_mp.
+#
+# Local function to manpath_add_lang_sys().
+#
+# Argument: 1, a operating system name (for appending to a man path
+#              directory)
+#
+# Globals in:     $_MAN_PATH
+# Globals in/out: $mals_mp
+#
+# Variable prefix: _mas
+#
+_manpath_add_sys()
+{
+  func_check _manpath_add_sys '=' 1 "$@";
+  case "$1" in
+  '')
+    :;
+    ;;
+  man)
+    obj_from_output mals_mp lists_combine mals_mp _MAN_PATH;
+    ;;
+  *)
+    _mas_sys="$1";
+    eval set x "${_MAN_PATH}";
+    shift;
+    for p
+    do
+      obj_from_output _mas_dir dir_name_append "${p}" "${_mas_sys}";
+      if obj _mas_dir is_dir
+      then
+        list_append mals_mp "${_mas_dir}";
+      fi;
+    done;
+    ;;
+  esac;
+  eval ${_UNSET} _mas_dir;
+  eval ${_UNSET} _mas_sys;
+  eval "${return_ok}";
+} # _manpath_add_sys() of manpath_add_lang_sys()
+
+
+########################################################################
+# manpath_set_from_path ()
+#
+# Determine basic search path for man pages from $PATH.
+#
+# Return:    `0' if a valid man path was retrieved.
+# Output:    none
+# Globals:
+#   in:  $PATH
+#   out: $_MAN_PATH
+#
+# Variable prefix: msfp
+#
+manpath_set_from_path()
+{
+  func_check manpath_set_from_path '=' 0 "$@";
+
+  msfp_manpath='';
+
+  # get a basic man path from $PATH
+  if obj PATH is_not_empty
+  then
+    # delete the final `/bin' part
+    p="$(echo1 "${PATH}" | sed 's|//*bin/*:|:|g')";
+    obj_from_output msfp_list path_list "$p";
+    # append some default directories
+    for b in /usr/local /usr/local /usr /usr \
+           /usr/X11R6 /usr/openwin \
+           /opt /opt/gnome /opt/kde
+    do
+      msfp_base="$b";
+      if list_has_not msfp_list "${msfp_base}" && obj msfp_base is_dir
+      then
+        list_append msfp_list "${msfp_base}";
+      fi;
+    done;
+    eval set x "${msfp_list}";
+    shift;
+    for d
+    do
+      # including empty for former `/bin'.
+      msfp_base="$d";
+      for e in /share/man /share/MAN /man /MAN
+      do
+        msfp_mandir="${msfp_base}$e";
+        if obj msfp_mandir is_dir
+        then
+          list_append msfp_manpath "${msfp_mandir}";
+        fi;
+      done;
+    done;
+  fi;
+
+  _MAN_PATH="${msfp_manpath}";
+  eval ${_UNSET} msfp_base;
+  eval ${_UNSET} msfp_list;
+  eval ${_UNSET} msfp_mandir;
+  eval ${_UNSET} msfp_manpath;
+  eval "${return_ok}";
+} # manpath_set_from_path()
+
+
+########################################################################
+landmark '9: obj_*()';
+########################################################################
+
+########################################################################
+# obj (<object> <call_name> <arg>...)
+#
+# This works like a method (object function) call for an object.
+# Run "<call_name> $<object> <arg> ...".
+#
+# The first argument represents an object name whose data is given as
+# first argument to <call_name>().
+#
+# Argument: >=2
+#           <object>: variable name
+#           <call_name>: a program or function name
+#
+# Variable prefix: o
+#
+obj()
+{
+  func_check obj '>=' 2 "$@";
+  eval o_arg1='"${'$1'}"';
+  if is_empty "$2"
+  then
+    error "obj(): function name is empty."
+  else
+    o_func="$2";
+  fi;
+  shift;
+  shift;
+  eval "${o_func}"' "${o_arg1}" "$@"';
+  n="$?";
+  eval ${_UNSET} o_arg1;
+  eval ${_UNSET} o_func;
+  eval "${return_var} $n";
+} # obj()
+
+
+########################################################################
+# obj_data (<object>)
+#
+# Print the data of <object>, i.e. the content of $<object>.
+# For possible later extensions.
+#
+# Arguments: 1
+#            <object>: a variable name
+# Output:    the data of <object>
+#
+# Variable prefix: od
+#
+obj_data()
+{
+  func_check obj_data '=' 1 "$@";
+  if is_empty "$1"
+  then
+    error "obj_data(): object name is empty."
+  fi;
+  eval od_res='"${'"$1"'}"';
+  obj od_res echo1;
+  eval ${_UNSET} od_res;
+  eval "${return_ok}";
+} # obj_data()
+
+
+########################################################################
+# obj_from_output (<object> <call_name> <arg>...)
+#
+# Run '$<object>="$(<call_name> <arg>...)"' to set the result of a
+# function call to a global variable.  Variables are not stored.
+#
+# Arguments: >=2
+#            <object>: a variable name
+#            <call_name>: the name of a function or program
+#            <arg>: optional argument to <call_name>
+# Output:    none
+#
+# Variable prefix: ofo
+#
+obj_from_output()
+{
+  func_check obj_from_output '>=' 2 "$@";
+  if is_empty "$1"
+  then
+    error "obj_from_output(): variable name is empty.";
+  fi;
+  if is_empty "$2"
+  then
+    error "obj_from_output(): function name is empty."
+  fi;
+  ofo_result_name="$1";
+  shift;
+  ofo_return=0;
+  if is_equal "$#" 0
+  then
+    eval "${ofo_result_name}"'=""';
+  else
+    ofo_list='';
+    for i
+    do
+      list_append ofo_list "$i";
+    done;
+    eval "${ofo_result_name}"'="$('"${ofo_list}"')"';
+    ofo_return="$?";
+    exit_test;
+  fi;
+  r="${ofo_return}";
+  eval ${_UNSET} ofo_list;
+  eval ${_UNSET} ofo_return;
+  eval ${_UNSET} ofo_result_name;
+  eval "${return_var} $r";
+} # obj_from_output()
+
+
+########################################################################
+# obj_set (<object> <data>)
+#
+# Set the data of <object>, i.e. call "$<object>=<data>".
+#
+# Arguments: 2
+#            <object>: a variable name
+#            <data>: a string
+# Output::   none
+#
+obj_set()
+{
+  func_check obj_set '=' 2 "$@";
+  if is_empty "$1"
+  then
+    error "obj_set(): object name is empty."
+  fi;
+  eval "$1"='"$2"';
+  eval "${return_ok}";
+} # obj_set()
+
+
+########################################################################
+# path_chop (<path>)
+#
+# Remove unnecessary colons from path.
+#
+# Argument: 1, a colon separated path.
+# Output:   path without leading, double, or trailing colons.
+#
+path_chop()
+{
+  func_check path_chop = 1 "$@";
+
+  # replace multiple colons by a single colon `:'
+  # remove leading and trailing colons
+  echo1 "$1" | sed '
+s/^:*//
+s/:::*/:/g
+s/:*$//
+';
+  eval "${return_ok}";
+} # path_chop()
+
+
+########################################################################
+# path_clean (<path>)
+#
+# Remove non-existing directories from a colon-separated list.
+#
+# Argument: 1, a colon separated path.
+# Output:   colon-separated list of existing directories.
+#
+# Variable prefix: pc
+#
+path_clean()
+{
+  func_check path_clean = 1 "$@";
+  if is_not_equal "$#" 1
+  then
+    error 'path_clean() needs 1 argument.';
+  fi;
+  pc_arg="$1";
+  eval set x "$(path_list "${pc_arg}")";
+  exit_test;
+  shift;
+  pc_res="";
+  for i
+  do
+    pc_i="$i";
+    if obj pc_i is_not_empty \
+       && obj pc_res path_not_contains "${pc_i}" \
+       && obj pc_i is_dir
+    then
+      case "${pc_i}" in
+      ?*/)
+        pc_res="${pc_res}:$(dir_name_chop "${pc_i}")";
+        exit_test;
+        ;;
+      *)
+        pc_res="${pc_res}:${pc_i}";
+        ;;
+      esac;
+    fi;
+  done;
+  path_chop "${pc_res}";
+  eval ${_UNSET} pc_arg;
+  eval ${_UNSET} pc_i;
+  eval ${_UNSET} pc_res;
+  eval "${return_ok}";
+} # path_clean()
+
+
+########################################################################
+# path_contains (<path> <dir>)
+#
+# Test whether <dir> is contained in <path>, a list separated by `:'.
+#
+# Arguments : 2
+# Return    : `0' if arg2 is substring of arg1, `1' otherwise.
+#
+path_contains()
+{
+  func_check path_contains = 2 "$@";
+  case ":$1:" in
+    *:${2}:*)
+      eval "${return_yes}";
+      ;;
+    *)
+      eval "${return_no}";
+      ;;
+  esac;
+  eval "${return_ok}";
+} # path_contains()
+
+
+########################################################################
+# path_not_contains (<path> <dir>)
+#
+# Test whether <dir> is not contained in colon separated <path>.
+#
+# Arguments : 2
+#
+path_not_contains()
+{
+  func_check path_not_contains = 2 "$@";
+  if path_contains "$1" "$2"
+  then
+    eval "${return_no}";
+  else
+    eval "${return_yes}";
+  fi;
+  eval "${return_ok}";
+} # path_not_contains()
+
+
+########################################################################
+# path_list (<path>)
+#
+# From a `:' separated path generate a list with unique elements.
+#
+# Arguments: 1: a colon-separated path
+# Output:    the resulting list, process it with `eval set'
+#
+# Variable prefix: pl
+#
+path_list()
+{
+  func_check path_list = 1 "$@";
+  eval set x "$(list_from_split "$1" '\:')";
+  shift;
+  pl_list='';
+  for e
+  do
+    pl_elt="$e";
+    if list_has pl_list "${pl_elt}"
+    then
+      continue;
+    else
+      list_append pl_list "${pl_elt}";
+    fi;
+  done;
+  obj pl_list echo1;
+  eval ${_UNSET} pl_elt;
+  eval ${_UNSET} pl_list;
+  eval "${return_ok}";
+} # path_list()
+
+
+########################################################################
+landmark '10: register_*()';
+########################################################################
+
+########################################################################
+# register_file (<filename>)
+#
+# Write a found file and register the title element.
+#
+# Arguments: 1: a file name
+# Output: none
+#
+register_file()
+{
+  func_check register_file = 1 "$@";
+  if is_empty "$1"
+  then
+    error 'register_file(): file name is empty';
+  fi;
+  if is_equal "$1" '-'
+  then
+    to_tmp "${_TMP_STDIN}" && register_title 'stdin';
+  else
+    to_tmp "$1" && register_title "$1";
+    exit_test;
+  fi;
+  eval "${return_ok}";
+} # register_file()
+
+
+########################################################################
+# register_title (<filespec>)
+#
+# Create title element from <filespec> and append to $_REG_TITLE_LIST.
+# Basename is created.
+#
+# Globals: $_REG_TITLE_LIST (rw)
+#
+# Variable prefix: rt
+#
+register_title()
+{
+  func_check register_title '=' 1 "$@";
+  if is_empty "$1"
+  then
+    eval "${return_ok}";
+  fi;
+
+  if obj _DEBUG_PRINT_FILENAMES is_yes
+  then
+    if is_equal "$1" 'stdin'
+    then
+      echo2 "file: standard input";
+    else
+      if obj _FILESPEC_IS_MAN is_yes
+      then
+        echo2 "file title: $1";
+      else
+        echo2 "file: $1";
+      fi;
+    fi;
+  fi;
+
+  case "${_REG_TITLE_LIST}" in
+  *\ *\ *\ *)
+    eval "${return_ok}";
+    ;;
+  esac;
+
+  # remove directory part
+  obj_from_output rt_title base_name "$1";
+  # replace space characters by `_'
+  rt_title="$(echo1 "${rt_title}" | sed 's/[ 	]/_/g')";
+  # remove extension `.bz2'
+  rt_title="$(echo1 "${rt_title}" | sed 's/\.bz2$//')";
+  # remove extension `.gz'
+  rt_title="$(echo1 "${rt_title}" | sed 's/\.gz$//')";
+  # remove extension `.Z'
+  rt_title="$(echo1 "${rt_title}" | sed 's/\.Z$//')";
+
+  if obj rt_title is_empty
+  then
+    eval ${_UNSET} rt_title;
+    eval "${return_ok}";
+  fi;
+  list_append _REG_TITLE_LIST "${rt_title}";
+  eval ${_UNSET} rt_title;
+  eval "${return_ok}";
+} # register_title()
+
+
+########################################################################
+# reset ()
+#
+# Reset the variables that can be affected by options to their default.
+#
+#
+# Defined in section `Preset' after the rudimentary shell tests.
+
+
+########################################################################
+# rm_file (<file_name>)
+#
+# Remove file.
+#
+rm_file()
+{
+  func_check rm_file '=' 1 "$@";
+  if is_file "$1"
+  then
+    rm -f "$1" >${_NULL_DEV} 2>&1;
+  fi;
+  if is_existing "$1"
+  then
+    eval "${return_bad}";
+  else
+    eval "${return_good}";
+  fi;
+} # rm_file()
+
+
+########################################################################
+# rm_file_with_debug (<file_name>)
+#
+# Remove file if $_DEBUG_KEEP_FILES allows it.
+#
+# Globals: $_DEBUG_KEEP_FILES
+#
+rm_file_with_debug()
+{
+  func_check rm_file_with_debug '=' 1 "$@";
+  if obj _DEBUG_KEEP_FILES is_not_yes
+  then
+    if is_file "$1"
+    then
+      rm -f "$1" >${_NULL_DEV} 2>&1;
+    fi;
+  fi;
+  if is_existing "$1"
+  then
+    eval "${return_bad}";
+  else
+    eval "${return_good}";
+  fi;
+} # rm_file_with_debug()
+
+
+########################################################################
+# rm_tree (<dir_name>)
+#
+# Remove a file or a complete directory tree.
+#
+# Globals: $_DEBUG_KEEP_FILES
+#
+rm_tree()
+{
+  func_check rm_tree '=' 1 "$@";
+  if is_existing "$1"
+  then
+    rm -f -r "$1" >${_NULL_DEV} 2>&1;
+  fi;
+  if is_existing "$1"
+  then
+    eval "${return_bad}";
+  else
+    eval "${return_good}";
+  fi;
+} # rm_tree()
+
+
+########################################################################
+# save_stdin ()
+#
+# Store standard input to temporary file (with decompression).
+#
+# Variable prefix: ss
+#
+if obj _HAS_COMPRESSION is_yes
+then
+  save_stdin()
+  {
+    func_check save_stdin '=' 0 "$@";
+    ss_f="${_TMP_DIR}"/INPUT;
+    cat >"${ss_f}";
+    cat_z "${ss_f}" >"${_TMP_STDIN}";
+    rm_file "${ss_f}";
+    eval ${_UNSET} ss_f;
+    eval "${return_ok}";
+  } # save_stdin()
+else				# no compression
+  save_stdin()
+  {
+    func_check save_stdin '=' 0 "$@";
+    cat >"${_TMP_STDIN}";
+    eval "${return_ok}";
+  } # save_stdin()
+fi;
+
+
+########################################################################
+# special_filespec ()
+#
+# Handle special modes like whatis and apropos.  Run their filespec
+# functions if suitable.
+#
+# Globals:  in: $_OPT_APROPOS, $_OPT_WHATIS, $_SPECIAL_SETUP
+#          out: $_SPECIAL_FILESPEC (internal)
+#
+special_filespec()
+{
+  func_check special_filespec '=' 0 "$@";
+  if obj _OPT_APROPOS is_not_yes && obj _OPT_WHATIS is_not_yes
+  then
+    eval "${return_bad}";
+  fi;
+  if obj _OPT_APROPOS is_yes && obj _OPT_WHATIS is_yes
+  then
+    error \
+      'special_filespec(): $_OPT_APROPOS and $_OPT_WHATIS are both "yes"';
+  fi;
+  if obj _SPECIAL_SETUP is_not_yes
+  then
+    error 'special_filespec(): setup for apropos or whatis must be run first.';
+  fi;
+  if apropos_filespec || whatis_filespec;
+  then
+    eval "${return_ok}";
+  else
+    eval "${return_bad}";
+  fi;
+} # special_filespec()
+
+
+########################################################################
+# special_setup ()
+#
+# Handle special modes like whatis and apropos.  Run their setup
+# functions if suitable.
+#
+special_setup()
+{
+  func_check special_setup '=' 0 "$@";
+  if obj _OPT_APROPOS is_yes && obj _OPT_WHATIS is_yes
+  then
+    error \
+      'special_setup(): $_OPT_APROPOS and $_OPT_WHATIS are both "yes"';
+  fi;
+  if apropos_setup || whatis_setup
+  then
+    eval "${return_ok}";
+  else
+    eval "${return_bad}";
+  fi;
+} # special_setup()
+
+
+########################################################################
+landmark '11: stack_*()';
+########################################################################
+
+########################################################################
+# string_contains (<string> <part>)
+#
+# Test whether <part> is contained in <string>.
+#
+# Arguments : 2 text arguments.
+# Return    : `0' if arg2 is substring of arg1, `1' otherwise.
+#
+string_contains()
+{
+  func_check string_contains '=' 2 "$@";
+  case "$1" in
+    *${2}*)
+      eval "${return_yes}";
+      ;;
+    *)
+      eval "${return_no}";
+      ;;
+  esac;
+  eval "${return_ok}";
+} # string_contains()
+
+
+########################################################################
+# string_not_contains (<string> <part>)
+#
+# Test whether <part> is not substring of <string>.
+#
+# Arguments : 2 text arguments.
+# Return    : `0' if arg2 is substring of arg1, `1' otherwise.
+#
+string_not_contains()
+{
+  func_check string_not_contains '=' 2 "$@";
+  if string_contains "$1" "$2"
+  then
+    eval "${return_no}";
+  else
+    eval "${return_yes}";
+  fi;
+  eval "${return_ok}";
+} # string_not_contains()
+
+
+########################################################################
+landmark '12: tmp_*()';
+########################################################################
+
+########################################################################
+# tmp_cat ()
+#
+# Output the temporary cat file (the concatenation of all input).
+#
+tmp_cat()
+{
+  func_check tmp_cat '=' 0 "$@";
+  cat "${_TMP_CAT}";
+  eval "${return_var}" "$?";
+} # tmp_cat()
+
+
+########################################################################
+# tmp_create (<suffix>?)
+#
+# Create temporary file.  The generated name is `,' followed by
+# <suffix>.
+#
+# Argument: 0 or 1
+#
+# Globals: $_TMP_DIR
+#
+# Output : name of created file
+#
+# Variable prefix: tc
+#
+tmp_create()
+{
+  func_check tmp_create '<=' 1 "$@";
+  if obj _TMP_DIR is_empty || obj _TMP_DIR is_not_dir
+  then
+    error 'tmp_create(): there is no temporary directory.';
+  else
+    # the output file does not have `,' as first character, so these are
+    # different names from the output file.
+    tc_tmp="${_TMP_DIR}/,$1";
+    obj tc_tmp rm_file;
+    : >"${tc_tmp}"
+    obj tc_tmp echo1;
+  fi;
+  eval ${_UNSET} tc_tmp;
+  eval "${return_ok}";
+} # tmp_create()
+
+
+########################################################################
+# to_tmp (<filename>)
+#
+# Print file (decompressed) to the temporary cat file.
+#
+# Variable prefix: tt
+#
+to_tmp()
+{
+  func_check to_tmp '=' 1 "$@";
+  if obj _TMP_CAT is_empty
+  then
+    error 'to_tmp(): $_TMP_CAT is not yet set';
+  fi;
+  tt_1="$1";
+  tt_so_nr=0;			# number for temporary `,so,*,*'
+  if is_file "${tt_1}"
+  then
+    tt_dir="$(dir_name "${tt_1}")";
+    if obj _OPT_WHATIS is_yes
+    then
+      whatis_filename "${tt_1}" >>"${_TMP_CAT}";
+    else
+      _FILE_NR="$(expr ${_FILE_NR} + 1)";
+      tt_file="${_TMP_DIR}/,file${_FILE_NR}";
+      if obj _FILESPEC_IS_MAN is_yes
+      then
+        if obj _DEBUG_PRINT_FILENAMES is_yes
+        then
+          echo2 "file: ${tt_1}";
+        fi;
+        tt_tmp="${_TMP_DIR}/,tmp";
+        cat_z "${tt_1}" >"${tt_file}";
+        grep '^\.[ 	]*so[ 	]' "${tt_file}" |
+	  sed 's/^\.[ 	]*so[ 	]*//' >"${tt_tmp}";
+        list_from_file tt_list "${tt_tmp}";
+        eval set x ${tt_list};
+        shift;
+        for i
+        do
+          tt_i="$i";
+          tt_so_nr="$(expr ${tt_so_nr} + 1)";
+          tt_sofile="${_TMP_DIR}/,so${_FILE_NR}_${tt_so_nr}";
+          tt_sofiles="${tt_sofiles} ${tt_sofile}";
+          _do_man_so "${tt_i}";
+        done;
+        rm_file "${tt_tmp}";
+        mv "${tt_file}" "${tt_tmp}";
+        cat "${tt_tmp}" | soelim -I "${tt_dir}" ${_SOELIM_R} >"${tt_file}";
+        for f in ${tt_sofiles}
+        do
+          rm_file_with_debug $f;
+        done;
+        rm_file "${tt_tmp}";
+      else			# $_FILESPEC_IS_MAN ist not yes
+        cat_z "${tt_1}" | soelim -I "${tt_dir}" ${_SOELIM_R} >"${tt_file}";
+      fi;
+### to_tmp()
+      obj_from_output tt_grog grog "${tt_file}";
+      if is_not_equal "$?" 0
+      then
+        exit "${_ERROR}";
+      fi;
+      echo2 "grog output: ${tt_grog}";
+      case " ${tt_grog} " in
+      *\ -m*)
+        eval set x "$(echo1 " ${tt_grog} " | sed '
+s/'"${_TAB}"'/ /g
+s/  */ /g
+s/ -m / -m/g
+s/ -mm\([^ ]\)/ -m\1/g
+')";
+        shift;
+        for i
+        do
+          tt_i="$i";
+          case "${tt_i}" in
+          -m*)
+            if list_has _MACRO_PACKAGES "${tt_i}"
+            then
+              case "${_MACRO_PKG}" in
+              '')
+                _MACRO_PKG="${tt_i}";
+                ;;
+              ${tt_i})
+                :;
+                ;;
+              -m*)
+                echo2 "Ignore ${tt_1} because it needs ${tt_i} instead "\
+"of ${_MACRO_PKG}."
+                rm_file_with_debug "${tt_file}";
+                eval ${_UNSET} tt_1;
+                eval ${_UNSET} tt_dir;
+                eval ${_UNSET} tt_file;
+                eval ${_UNSET} tt_grog;
+                eval ${_UNSET} tt_i;
+                eval ${_UNSET} tt_so_nr;
+                eval ${_UNSET} tt_sofile;
+                eval ${_UNSET} tt_sofiles;
+                eval ${_UNSET} tt_sofound;
+                eval ${_UNSET} tt_list;
+                eval ${_UNSET} tt_tmp;
+                eval "${return_bad}";
+                ;;
+### to_tmp()
+              *)
+                error \
+'to_tmp(): $_MACRO_PKG does not start with -m: '"${_MACRO_PKG}";
+                ;;
+              esac;
+            fi;
+            ;;
+          esac;
+        done;
+        ;;
+      esac;
+      cat "${tt_file}" >>"${_TMP_CAT}";
+      rm_file_with_debug "${tt_file}";
+    fi;
+  else
+    error "to_tmp(): could not read file \`${tt_1}'.";
+  fi;
+  eval ${_UNSET} tt_1;
+  eval ${_UNSET} tt_dir;
+  eval ${_UNSET} tt_file;
+  eval ${_UNSET} tt_grog;
+  eval ${_UNSET} tt_i;
+  eval ${_UNSET} tt_so_nr;
+  eval ${_UNSET} tt_sofile;
+  eval ${_UNSET} tt_sofiles;
+  eval ${_UNSET} tt_sofound;
+  eval ${_UNSET} tt_list;
+  eval ${_UNSET} tt_tmp;
+  eval "${return_ok}";
+} # to_tmp()
+
+
+#############
+# _do_man_so (<so_arg>)
+#
+# Handle single .so file name for man pages.
+#
+# Local function to to_tmp().
+#
+# Globals from to_tmp(): $tt_tmp, $tt_sofile, $tt_file
+# Globals: $_TMP_MAN
+#
+# Variable prefix: dms
+#
+_do_man_so() {
+  func_check _do_man_so '=' 1 "$@";
+  _dms_so="$1";			# evt. with `\ '
+  _dms_soname="$(echo $1 | sed 's/\\[ 	]/ /g')"; # without `\ '
+  case "${_dms_soname}" in
+  /*)				# absolute path
+    if test -f "${_dms_soname}"
+    then
+      eval "${return_ok}";
+    fi;
+    if test -f "${_dms_soname}"'.gz'
+    then
+      _dms_sofound="${_dms_soname}"'.gz';
+    elif test -f "${_dms_soname}"'.Z'
+    then
+      _dms_sofound="${_dms_soname}"'.Z';
+    elif test -f "${_dms_soname}"'.bz2'
+    then
+      _dms_sofound="${_dms_soname}"'.bz2';
+    else
+      eval ${_UNSET} _dms_so;
+      eval ${_UNSET} _dms_soname;
+      eval "${return_ok}";
+    fi;
+    ;;
+### _do_man_so() of to_tmp()
+  *)				# relative to man path
+    eval grep "'/${_dms_soname}\$'" "${_TMP_MAN}" >"${tt_tmp}";
+    if is_empty_file "${tt_tmp}"
+    then
+      eval grep "'/${_dms_soname}.gz\$'" "${_TMP_MAN}" >"${tt_tmp}";
+      if is_empty_file "${tt_tmp}"
+      then
+        eval grep "'/${_dms_soname}.Z\$'" "${_TMP_MAN}" >"${tt_tmp}";
+        if is_empty_file "${tt_tmp}"
+        then
+          eval grep "'/${_dms_soname}.bz2\$'" "${_TMP_MAN}" >"${tt_tmp}";
+        fi;
+      fi;
+    fi;
+    if is_empty_file "${tt_tmp}"
+    then
+      eval "${return_ok}";
+    fi;
+    _dms_done='no';
+    list_from_file _dms_list "${tt_tmp}";
+    eval set x ${_dms_list};
+    shift;
+    for i
+    do
+      _dms_sofound="$i";
+      if obj _dms_sofound is_empty
+      then
+        continue;
+      fi;
+      _dms_done='yes';
+      break;
+    done;
+### _do_man_so() of to_tmp()
+    if obj _dms_done is_not_yes
+    then
+      eval ${_UNSET} _dms_done;
+      eval ${_UNSET} _dms_sofound;
+      eval "${return_ok}";
+    fi;
+    ;;
+  esac;
+  if obj _DEBUG_PRINT_FILENAMES is_yes
+  then
+    echo2 "file from .so: ${_dms_so}";
+  fi;
+  cat_z "${_dms_sofound}" >"${tt_sofile}";
+  _dms_esc="$(echo ${_dms_so} | sed 's/\\/\\\\/g')";
+  cat "${tt_file}" | eval sed \
+"'s#^\\.[ 	]*so[ 	]*\(${_dms_so}\|${_dms_esc}\|${_dms_soname}\)[ 	]*\$'"\
+"'#.so ${tt_sofile}#'" \
+    >"${tt_tmp}";
+  rm_file "${tt_file}";
+  mv "${tt_tmp}" "${tt_file}";
+  eval ${_UNSET} _dms_done;
+  eval ${_UNSET} _dms_esc;
+  eval ${_UNSET} _dms_so;
+  eval ${_UNSET} _dms_sofound;
+  eval ${_UNSET} _dms_soname;
+  eval "${return_ok}";
+} # _do_man_so() of to_tmp()
+
+
+########################################################################
+# to_tmp_line (<text>...)
+#
+# Print single line with <text> to the temporary cat file.
+#
+to_tmp_line()
+{
+  func_check to_tmp_line '>=' 1 "$@";
+  if obj _TMP_CAT is_empty
+  then
+    error 'to_tmp_line(): $_TMP_CAT is not yet set';
+  fi;
+  echo1 "$*" >>"${_TMP_CAT}";
+  eval "${return_ok}";
+} # to_tmp_line()
+
+
+########################################################################
+# trap_set
+#
+# Call function on signal 0.
+#
+trap_set()
+{
+  func_check trap_set '=' 0 "$@";
+  trap 'clean_up' 0 2>${_NULL_DEV} || :;
+  eval "${return_ok}";
+} # trap_set()
+
+
+########################################################################
+# trap_unset ()
+#
+# Disable trap on signal 0.
+#
+trap_unset()
+{
+  func_check trap_unset '=' 0 "$@";
+  trap '' 0 2>${_NULL_DEV} || :;
+  eval "${return_ok}";
+} # trap_unset()
+
+
+########################################################################
+# usage ()
+#
+# Print usage information to standard output; for groffer option --help.
+#
+usage()
+{
+  func_check usage = 0 "$@";
+  echo;
+  version;
+  cat <<EOF
+
+Usage: groffer [option]... [filespec]...
+
+Display roff files, standard input, and/or Unix manual pages with a X
+Window viewer or in several text modes.  All input is decompressed
+on-the-fly with all formats that gzip can handle.
+
+"filespec" is one of
+  "filename"       name of a readable file
+  "-"              for standard input
+  "man:name(n)"    man page "name" in section "n"
+  "man:name.n"     man page "name" in section "n"
+  "man:name"       man page "name" in first section found
+  "name(n)"        man page "name" in section "n"
+  "name.n"         man page "name" in section "n"
+  "n name"         man page "name" in section "n"
+  "name"           man page "name" in first section found
+where `section' is a single character out of [1-9on], optionally followed
+by some more letters that are called the `extension'.
+
+-h --help         print this usage message.
+-T --device=name  pass to groff using output device "name".
+-v --version      print version information.
+-V                display the groff execution pipe instead of formatting.
+-X                display with "gxditview" using groff -X.
+-Z --ditroff --intermediate-output
+                  generate groff intermediate output without
+                  post-processing and viewing, like groff -Z.
+All other short options are interpreted as "groff" formatting options.
+
+The most important groffer long options are
+
+--apropos=name    start man's "apropos" program for "name".
+--apropos-data=name
+                  "apropos" for "name" in man's data sections 4, 5, 7.
+--apropos-devel=name
+                  "apropos" for "name" in development sections 2, 3, 9.
+--apropos-progs=name
+                  "apropos" for "name" in man's program sections 1, 6, 8.
+--auto            choose mode automatically from the default mode list.
+--default         reset all options to the default value.
+--default-modes=mode1,mode2,...
+                  set sequence of automatically tried modes.
+--dvi             display in a viewer for TeX device independent format.
+--dvi-viewer=prog choose the viewer program for dvi mode.
+--groff           process like groff, disable viewing features.
+--help            display this helping output.
+--html            display in a web browser.
+--html-viewer=program
+                  choose a web browser for html mode.
+--man             check file parameters first whether they are man pages.
+--mode=auto|dvi|groff|html|pdf|ps|source|text|tty|www|x|X
+                  choose display mode.
+--no-man          disable man-page facility.
+--no-special      disable --all, --apropos*, and --whatis
+--pager=program   preset the paging program for tty mode.
+--pdf             display in a PDF viewer.
+--pdf-viewer=prog choose the viewer program for pdf mode.
+--ps              display in a Postscript viewer.
+--ps-viewer=prog  choose the viewer program for ps mode.
+--shell=program   specify a shell under which to run groffer2.sh.
+--source          output as roff source.
+--text            output in a text device without a pager.
+--to-stdout       output the content of the mode file without display.
+--tty             display with a pager on text terminal even when in X.
+--tty-viewer=prog select a pager for tty mode; same as --pager.
+--whatis          display the file name and description of man pages
+--www             same as --html.
+--www-viewer=prog same as --html-viewer
+--x --X           display with "gxditview" using an X* device.
+--x-viewer=prog   choose viewer program for x mode (X mode).
+--X-viewer=prog   same as "--xviewer".
+
+The usual X Windows toolkit options transformed into GNU long options:
+--background=color, --bd=size, --bg=color, --bordercolor=color,
+--borderwidth=size, --bw=size, --display=Xdisplay, --fg=color,
+--fn=font, --font=font, --foreground=color, --geometry=geom, --iconic,
+--resolution=dpi, --rv, --title=text, --xrm=resource
+
+Long options of GNU "man":
+--all, --ascii, --ditroff, --extension=suffix, --locale=language,
+--local-file=name, --location, --manpath=dir1:dir2:...,
+--sections=s1:s2:..., --systems=s1,s2,..., --where, ...
+
+Development options that are not useful for normal usage:
+--debug, --debug-all, --debug-filenames, --debug-func,
+--debug-not-func, --debug-grog, --debug-keep, --debug-lm,
+--debug-params, --debug-shell, --debug-stacks, --debug-tmpdir,
+--debug-user, --do-nothing, --print=text, --shell=prog
+
+EOF
+
+  eval "${return_ok}";
+} # usage()
+
+
+########################################################################
+# version ()
+#
+# Print version information to standard output.
+# For groffer option --version.
+#
+version()
+{
+  func_check version = 0 "$@";
+  y="$(echo "${_LAST_UPDATE}" | sed 's/^.* //')";
+  cat <<EOF
+groffer ${_PROGRAM_VERSION} of ${_LAST_UPDATE} (shell version)
+is part of groff version ${_GROFF_VERSION}.
+Copyright (C) $y Free Software Foundation, Inc.
+GNU groff and groffer come with ABSOLUTELY NO WARRANTY.
+You may redistribute copies of groff and its subprograms
+under the terms of the GNU General Public License.
+EOF
+  eval "${return_ok}";
+} # version()
+
+
+########################################################################
+# warning (<string>)
+#
+# Print warning to stderr.
+#
+warning()
+{
+  echo2 "warning: $*";
+} # warning()
+
+
+########################################################################
+# whatis_filename (<filename>)
+#
+# Interpret <filename> as a man page and display its `whatis'
+# information as a fragment written in the groff language.
+#
+# Globals:  in: $_OPT_WHATIS, $_SPECIAL_SETUP, $_SPECIAL_FILESPEC,
+#               $_FILESPEC_ARG
+#
+# Variable prefix: wf
+#
+whatis_filename()
+{
+  func_check whatis_filename = 1 "$@";
+  if obj _OPT_WHATIS is_not_yes
+  then
+    error 'whatis_filename(): $_OPT_WHATIS is not yes.';
+  fi;
+  if obj _SPECIAL_SETUP is_not_yes
+  then
+    error \
+      'whatis_filename(): setup for whatis whatis_setup() must be run first.';
+  fi;
+  if obj _SPECIAL_FILESPEC is_not_yes
+  then
+    error 'whatis_filename(): whatis_filespec() must be run first.';
+  fi;
+  wf_arg="$1";
+  if obj wf_arg is_not_file
+  then
+    error "whatis_filename(): argument is not a readable file."
+  fi;
+  wf_dot='^\.'"${_SPACE_SED}"'*';
+### whatis_filename()
+  if obj _FILESPEC_ARG is_equal '-'
+  then
+    wf_arg='stdin';
+  fi;
+  cat <<EOF
+\f[CR]${wf_arg}\f[]:
+.br
+EOF
+
+  # get the parts of the file name
+  wf_name="$(base_name $1)";
+  wf_section="$(echo1 $1 | sed -n '
+s|^.*/man\('"${_MAN_AUTO_SEC_CHARS}"'\).*$|\1|p
+')";
+  if obj wf_section is_not_empty
+  then
+    case "${wf_name}" in
+    *.${wf_section}*)
+      s='yes';
+      ;;
+    *)
+      s='';
+      wf_section='';
+      ;;
+### whatis_filename()
+    esac
+    if obj s is_yes
+    then
+      wf_name="$(echo1 ${wf_name} | sed '
+s/^\(.*\)\.'${wf_section}'.*$/\1/
+')";
+    fi;
+  fi;
+
+  # traditional man style; grep the line containing `.TH' macro, if any
+  wf_res="$(cat_z "$1" | sed '
+/'"${wf_dot}"'TH /p
+d
+')";
+  exit_test;
+  if obj wf_res is_not_empty
+  then				# traditional man style
+    # get the first line after the first `.SH' macro, by
+    # - delete up to first .SH;
+    # - print all lines before the next .SH;
+    # - quit.
+    wf_res="$(cat_z "$1" | sed -n '
+1,/'"${wf_dot}"'SH/d
+/'"${wf_dot}"'SH/q
+p
+')";
+
+    if obj wf_section is_not_empty
+    then
+      case "${wf_res}" in
+      ${wf_name}${_SPACE_CASE}*-${_SPACE_CASE}*)
+        s='yes';
+        ;;
+### whatis_filename()
+      *)
+        s='';
+        ;;
+      esac;
+      if obj s is_yes
+      then
+        wf_res="$(obj wf_res echo1 | sed '
+s/^'"${wf_name}${_SPACE_SED}"'[^-]*-'"${_SPACE_SED}"'*\(.*\)$/'"${wf_name}"' ('"${wf_section}"') \\[em] \1/
+')";
+      fi;
+    fi;
+    obj wf_res echo1;
+    echo;
+    eval ${_UNSET} wf_arg;
+    eval ${_UNSET} wf_dot;
+    eval ${_UNSET} wf_name;
+    eval ${_UNSET} wf_res;
+    eval ${_UNSET} wf_section;
+    eval "${return_ok}";
+  fi;
+
+  # mdoc style (BSD doc); grep the line containing `.Nd' macro, if any
+  wf_res="$(cat_z "$1" | sed -n '/'"${wf_dot}"'Nd /s///p')";
+  exit_test;
+  if obj wf_res is_not_empty
+  then				# BSD doc style
+    if obj wf_section is_not_empty
+    then
+      wf_res="$(obj wf_res echo1 | sed -n '
+s/^\(.*\)$/'"${wf_name}"' ('"${wf_section}"') \\[em] \1/p
+')";
+    fi;
+### whatis_filename()
+    obj wf_res echo1;
+    echo;
+    eval ${_UNSET} wf_arg;
+    eval ${_UNSET} wf_dot;
+    eval ${_UNSET} wf_name;
+    eval ${_UNSET} wf_res;
+    eval ${_UNSET} wf_section;
+    eval "${return_ok}";
+  fi;
+  echo1 'is not a man page';
+  echo;
+  eval ${_UNSET} wf_arg;
+  eval ${_UNSET} wf_dot;
+  eval ${_UNSET} wf_name;
+  eval ${_UNSET} wf_res;
+  eval ${_UNSET} wf_section;
+  eval "${return_bad}";
+} # whatis_filename()
+
+
+
+########################################################################
+# whatis_filespec ()
+#
+# Print the filespec name as .SH to the temporary cat file.
+#
+# Globals:  in: $_OPT_WHATIS, $_SPECIAL_SETUP
+#          out: $_SPECIAL_FILESPEC
+#
+whatis_filespec()
+{
+  func_check whatis_filespec '=' 0 "$@";
+  if obj _OPT_WHATIS is_yes
+  then
+    if obj _SPECIAL_SETUP is_not_yes
+    then
+      error 'whatis_filespec(): whatis_setup() must be run first.';
+    fi;
+    _SPECIAL_FILESPEC='yes';
+    eval to_tmp_line \
+      "'.SH $(echo1 "${_FILESPEC_ARG}" | sed 's/[^\\]-/\\-/g')'";
+    exit_test;
+    eval "${return_ok}";
+  else
+    eval "${return_bad}";
+  fi;
+} # whatis_filespec()
+
+
+########################################################################
+# whatis_setup ()
+#
+# Print the whatis header to the temporary cat file; this is the setup
+# for whatis.
+#
+# Globals:  in: $_OPT_WHATIS
+#          out: $_SPECIAL_SETUP
+#
+whatis_setup()
+{
+  func_check whatis_setup '=' 0 "$@";
+  if obj _OPT_WHATIS is_yes
+  then
+    to_tmp_line '.TH GROFFER WHATIS';
+    _SPECIAL_SETUP='yes';
+    if obj _OPT_TITLE is_empty
+    then
+      _OPT_TITLE='whatis';
+    fi;
+    eval "${return_ok}";
+  else
+    eval "${return_bad}";
+  fi;
+} # whatis_setup()
+
+
+########################################################################
+# where_is_prog (<program>)
+#
+# Output path of a program and the given arguments if in $PATH.
+#
+# Arguments : 1, <program> can have spaces and arguments.
+# Output    : list of 2 elements: prog name (with directory) and arguments
+# Return    : `0' if arg1 is a program in $PATH, `1' otherwise.
+#
+# Variable prefix: wip
+#
+where_is_prog()
+{
+  func_check where_is_prog '=' 1 "$@";
+  if is_empty "$1"
+  then
+    eval "${return_bad}";
+  fi;
+
+  # Remove disturbing multiple spaces and tabs
+  wip_1="$(echo1 "$1" | sed 's/[ 	][ 	]*/ /g' | \
+           sed 's/\(\\\)* / /g' | sed 's/^ //' | sed 's/ $//')";
+  wip_noarg="$(echo1 "${wip_1}" | sed 's/ -.*$//')";
+  exit_test;
+
+  if obj wip_noarg is_empty
+  then
+    eval ${_UNSET} wip_1;
+    eval ${_UNSET} wip_noarg;
+    eval "${return_bad}";
+  fi;
+
+  case "${wip_1}" in
+  *\ -*)
+    wip_args="$(echo1 "${wip_1}" |
+                eval sed "'s#^${wip_noarg} ##'")";
+    exit_test;
+    ;;
+  *)
+    wip_args='';
+    ;;
+  esac;
+
+  wip_result='';
+### where_is_prog()
+
+  if test -f "${wip_noarg}" && test -x "${wip_noarg}"
+  then
+    list_append wip_result "${wip_noarg}" "${wip_args}";
+    exit_test;
+    obj wip_result echo1;
+    exit_test;
+    eval ${_UNSET} wip_1;
+    eval ${_UNSET} wip_args;
+    eval ${_UNSET} wip_noarg;
+    eval ${_UNSET} wip_result;
+    eval "${return_ok}";
+  fi;
+
+  # test whether $wip_noarg has directory, so it is not tested with $PATH
+  case "${wip_noarg}" in
+  */*)
+    # now $wip_noarg (with /) is not an executable file
+
+    # test name with space
+    obj_from_output wip_name base_name "${wip_noarg}";
+    obj_from_output wip_dir dir_name "${wip_noarg}";
+    case "${wip_name}" in
+    *\ *)
+      wip_base="$(echo1 "${wip_name}" | sed 's/ .*$//')";
+      exit_test;
+      obj_from_output wip_file dir_name_append "${wip_dir}" "${wip_base}";
+      exit_test;
+### where_is_prog()
+      if test -f "${wip_file}" && test -x "${wip_file}"
+      then
+        wip_baseargs="$(echo1 "${wip_name}" |
+                        eval sed "'s#^${wip_base} ##'")";
+        exit_test;
+        if obj wip_args is_empty
+        then
+          wip_args="${wip_baseargs}";
+        else
+          wip_args="${wip_baseargs} ${wip_args}";
+        fi;
+
+        list_append wip_result "${wip_file}" "${wip_args}";
+        exit_test;
+        obj wip_result echo1;
+        exit_test;
+        eval ${_UNSET} wip_1;
+        eval ${_UNSET} wip_args;
+        eval ${_UNSET} wip_base;
+        eval ${_UNSET} wip_baseargs;
+        eval ${_UNSET} wip_dir;
+        eval ${_UNSET} wip_file;
+        eval ${_UNSET} wip_name;
+        eval ${_UNSET} wip_noarg;
+        eval ${_UNSET} wip_result;
+        eval "${return_ok}";
+      fi; # test ${wip_file}
+      ;;
+    esac; # end of test name with space
+
+### where_is_prog()
+    eval ${_UNSET} wip_1;
+    eval ${_UNSET} wip_args;
+    eval ${_UNSET} wip_base;
+    eval ${_UNSET} wip_dir;
+    eval ${_UNSET} wip_name;
+    eval ${_UNSET} wip_noarg;
+    eval ${_UNSET} wip_result;
+    eval "${return_bad}";
+    ;;
+  esac; # test of $wip_noarg on path with directory
+
+
+  # now $wip_noarg does not have a /, so it is checked with $PATH.
+
+  eval set x "$(path_list "${PATH}")";
+  exit_test;
+  shift;
+
+  # test path with $win_noarg, evt. with spaces
+  for d
+  do
+    wip_dir="$d";
+    obj_from_output wip_file dir_name_append "${wip_dir}" "${wip_noarg}";
+### where_is_prog()
+
+    # test $win_file on executable file
+    if test -f "${wip_file}" && test -x "${wip_file}"
+    then
+      list_append wip_result "${wip_file}" "${wip_args}";
+      exit_test;
+      obj wip_result echo1;
+      exit_test;
+      eval ${_UNSET} wip_1;
+      eval ${_UNSET} wip_dir;
+      eval ${_UNSET} wip_file;
+      eval ${_UNSET} wip_noarg;
+      eval ${_UNSET} wip_result;
+      eval "${return_ok}";
+    fi; # test $win_file on executable file
+  done; # test path with $win_prog with spaces
+
+  case "${wip_noarg}" in
+  *\ *)
+    # test on path with base name without space
+    wip_base="$(echo1 "${wip_noarg}" | sed 's/^\([^ ]*\) .*$/\1/')";
+    exit_test;
+    for d
+    do
+      wip_dir="$d";
+      obj_from_output wip_file dir_name_append "${wip_dir}" "${wip_base}";
+      exit_test;
+### where_is_prog()
+
+      # test $win_file on executable file
+      if test -f "${wip_file}" && test -x "${wip_file}"
+      then
+        wip_baseargs="$(echo1 "${wip_noarg}" |
+                        sed 's/[^ ]* \(.*\)$/\1/')";
+        exit_test;
+        if obj wip_args is_empty
+        then
+          wip_args="${wip_baseargs}";
+        else
+          wip_args="${wip_args} ${wip_baseargs}";
+        fi;
+        list_append wip_result "${wip_file}" "${wip_args}";
+        exit_test;
+        obj wip_result echo1;
+        exit_test;
+        eval ${_UNSET} wip_1;
+        eval ${_UNSET} wip_args;
+        eval ${_UNSET} wip_base;
+        eval ${_UNSET} wip_baseargs;
+        eval ${_UNSET} wip_dir;
+        eval ${_UNSET} wip_file;
+        eval ${_UNSET} wip_name;
+        eval ${_UNSET} wip_noarg;
+        eval ${_UNSET} wip_result;
+        eval "${return_ok}";
+      fi; # test of $wip_file on executable file
+    done; # test path with base name without space
+### where_is_prog()
+    ;;
+  esac; # test of $wip_noarg on space
+
+  eval ${_UNSET} wip_1;
+  eval ${_UNSET} wip_args;
+  eval ${_UNSET} wip_base;
+  eval ${_UNSET} wip_baseargs;
+  eval ${_UNSET} wip_dir;
+  eval ${_UNSET} wip_file;
+  eval ${_UNSET} wip_name;
+  eval ${_UNSET} wip_noarg;
+  eval ${_UNSET} wip_result;
+  eval "${return_bad}";
+} # where_is_prog()
+
+
+########################################################################
+#                        main* Functions
+########################################################################
+
+# The main area contains the following parts:
+# - main_init(): initialize temporary files and set exit trap
+# - main_parse_MANOPT(): parse $MANOPT
+# - main_parse_args(): argument parsing
+# - main_set_mode (): determine the display mode
+# - main_do_fileargs(): process filespec arguments
+# - main_set_resources(): setup X resources
+# - main_display(): do the displaying
+# - main(): the main function that calls all main_*()
+
+
+#######################################################################
+# main_init ()
+#
+# Set exit trap and create temporary directory and some temporary files.
+#
+# Globals: $_TMP_DIR, $_TMP_CAT, $_TMP_STDIN
+#
+# Variable prefix: mi
+#
+main_init()
+{
+  func_check main_init = 0 "$@";
+  # call clean_up() on shell termination.
+  trap_set;
+
+  # create temporary directory
+  umask 0077;
+  _TMP_DIR='';
+  for d in "${GROFF_TMPDIR}" "${TMPDIR}" "${TMP}" "${TEMP}" \
+           "${TEMPDIR}" "${HOME}"'/tmp' '/tmp' "${HOME}" '.'
+  do
+    mi_dir="$d";
+    if obj mi_dir is_empty || obj mi_dir is_not_dir || \
+       obj mi_dir is_not_writable
+    then
+      continue;
+    fi;
+
+    case "${mi_dir}" in
+    */)
+      _TMP_DIR="${mi_dir}";
+      ;;
+    *)
+      _TMP_DIR="${mi_dir}"'/';
+      ;;
+    esac;
+    _TMP_DIR="${_TMP_DIR}groffer${_PROCESS_ID}";
+    if obj _TMP_DIR rm_tree
+    then
+      :
+    else
+      mi_tdir_="${_TMP_DIR}"_;
+      mi_n=1;
+      mi_tdir_n="${mi_tdir_}${mi_n}";
+### main_init()
+      while obj mi_tdir_n is_existing
+      do
+        if obj mi_tdir_n rm_tree
+        then
+          # directory could not be removed
+          mi_n="$(expr "${mi_n}" + 1)";
+          mi_tdir_n="${mi_tdir_}${mi_n}";
+          continue;
+        fi;
+      done;
+      _TMP_DIR="${mi_tdir_n}";
+    fi;
+    eval mkdir "${_TMP_DIR}";
+    if is_not_equal "$?" 0
+    then
+      obj _TMP_DIR rm_tree;
+      _TMP_DIR='';
+      continue;
+    fi;
+    if obj _TMP_DIR is_dir && obj _TMP_DIR is_writable
+    then
+      # $_TMP_DIR can now be used as temporary directory
+      break;
+    fi;
+    obj _TMP_DIR rm_tree;
+    _TMP_DIR='';
+    continue;
+  done;
+  if obj _TMP_DIR is_empty
+  then
+    error "main_init(): \
+Couldn't create a directory for storing temporary files.";
+  fi;
+### main_init()
+  if obj _DEBUG_PRINT_TMPDIR is_yes
+  then
+    echo2 "temporary directory: ${_TMP_DIR}";
+  fi;
+
+  obj_from_output _TMP_CAT tmp_create groffer_cat;
+  obj_from_output _TMP_STDIN tmp_create groffer_input;
+
+  eval ${_UNSET} mi_dir;
+  eval ${_UNSET} mi_n;
+  eval ${_UNSET} mi_tdir_;
+  eval ${_UNSET} mi_tdir_n;
+  eval "${return_ok}";
+} # main_init()
+
+
+########################################################################
+# main_parse_MANOPT ()
+#
+# Parse $MANOPT to retrieve man options, but only if it is a non-empty
+# string; found man arguments can be overwritten by the command line.
+#
+# Globals:
+#   in: $MANOPT, $_OPTS_MANOPT_*
+#   out: $_MANOPT_*
+#
+# Variable prefix: mpm
+#
+main_parse_MANOPT()
+{
+  func_check main_parse_MANOPT = 0 "$@";
+
+  if obj MANOPT is_not_empty
+  then
+    # Delete leading and final spaces
+    MANOPT="$(echo1 "${MANOPT}" | sed '
+s/^'"${_SPACE_SED}"'*//
+s/'"${_SPACE_SED}"'*$//
+')";
+    exit_test;
+  fi;
+  if obj MANOPT is_empty
+  then
+    eval "${return_ok}";
+  fi;
+
+  mpm_list='';
+  # add arguments in $MANOPT by mapping them to groffer options
+  eval set x "$(list_from_cmdline _OPTS_MANOPT "${MANOPT}")";
+  exit_test;
+  shift;
+  until test "$#" -le 0 || is_equal "$1" '--'
+  do
+    mpm_opt="$1";
+    shift;
+    case "${mpm_opt}" in
+    -7|--ascii)
+      list_append mpm_list '--ascii';
+      ;;
+    -a|--all)
+      list_append mpm_list '--all';
+      ;;
+### main_parse_MANOPT()
+    -c|--catman)
+      do_nothing;
+      shift;
+      ;;
+    -d|--debug)
+      do_nothing;
+      ;;
+    -D|--default)
+      # undo all man options so far
+      mpm_list='';
+      ;;
+    -e|--extension)
+      list_append mpm_list '--extension';
+      shift;
+      ;;
+    -f|--whatis)
+      list_append mpm_list '--whatis';
+      shift;
+      ;;
+    -h|--help)
+      do_nothing;
+      ;;
+    -k|--apropos)
+      # groffer's --apropos takes an argument, but man's does not, so
+      do_nothing;
+      ;;
+    -l|--local-file)
+      do_nothing;
+      ;;
+    -L|--locale)
+      list_append mpm_list '--locale' "$1";
+      shift;
+      ;;
+### main_parse_MANOPT()
+    -m|--systems)
+      list_append mpm_list '--systems' "$1";
+      shift;
+      ;;
+    -M|--manpath)
+      list_append mpm_list '--manpath' "$1";
+      shift;
+      ;;
+    -p|--preprocessor)
+      do_nothing;
+      shift;
+      ;;
+    -P|--pager)
+      list_append mpm_list '--pager' "$1";
+      shift;
+      ;;
+    -r|--prompt)
+      do_nothing;
+      shift;
+      ;;
+    -S|--sections)
+      list_append mpm_list '--sections' "$1";
+      shift;
+      ;;
+    -t|--troff)
+      do_nothing;
+      ;;
+    -T|--device)
+      list_append mpm_list '-T' "$1";
+      shift;
+      ;;
+### main_parse_MANOPT()
+    -u|--update)
+      do_nothing;
+      ;;
+    -V|--version)
+      do_nothing;
+      ;;
+    -w|--where|--location)
+      list_append mpm_list '--location';
+      ;;
+    -Z|--ditroff)
+      do_nothing;
+      ;;
+    # ignore all other options
+    esac;
+  done;
+
+  # prepend $mpm_list to the command line
+  if obj mpm_list is_not_empty
+  then
+    eval set x "${mpm_list}" '"$@"';
+    shift;
+  fi;
+
+  eval ${_UNSET} mpm_list;
+  eval ${_UNSET} mpm_opt;
+  eval "${return_ok}";
+} # main_parse_MANOPT()
+
+
+########################################################################
+# main_parse_args (<command_line_args>*)
+#
+# Parse arguments; process options and filespec parameters.
+#
+# Arguments: pass the command line arguments unaltered.
+# Globals:
+#   in:  $_OPTS_*
+#   out: $_OPT_*, $_ADDOPTS, $_FILEARGS
+#
+# Variable prefix: mpa
+#
+main_parse_args()
+{
+  func_check main_parse_args '>=' 0 "$@";
+  obj_from_output _ALL_PARAMS list_from_cmdline_with_minus _OPTS_CMDLINE "$@";
+  if obj _DEBUG_PRINT_PARAMS is_yes
+  then
+    echo2 "parameters: ${_ALL_PARAMS}";
+  fi;
+  eval set x "${_ALL_PARAMS}";
+  shift;
+
+  # By the call of `eval', unnecessary quoting was removed.  So the
+  # positional shell parameters ($1, $2, ...) are now guaranteed to
+  # represent an option or an argument to the previous option, if any;
+  # then a `--' argument for separating options and
+  # parameters; followed by the filespec parameters if any.
+
+  # Note, the existence of arguments to options has already been checked.
+  # So a check for `$#' or `--' should not be done for arguments.
+
+  until test "$#" -le 0 || is_equal "$1" '--'
+  do
+    mpa_opt="$1";		# $mpa_opt is fed into the option handler
+    shift;
+    case "${mpa_opt}" in
+    -h|--help)
+      usage;
+      leave;
+      ;;
+    -Q|--source)		# output source code (`Quellcode').
+      _OPT_MODE='source';
+      ;;
+### main_parse_args()
+    -T|--device|--troff-device) # device; arg
+      _OPT_DEVICE="$1";
+      _check_device_with_mode;
+      shift;
+      ;;
+    -v|--version)
+      version;
+      leave;
+      ;;
+    -V)
+      _OPT_V='yes';
+      ;;
+    -Z|--ditroff|--intermediate-output) # groff intermediate output
+      _OPT_Z='yes';
+      ;;
+    -X)
+      _OPT_MODE=X;
+      ;;
+    -?)
+      # delete leading `-'
+      mpa_optchar="$(echo1 "${mpa_opt}" | sed 's/^-//')";
+      exit_test;
+      if list_has _OPTS_GROFF_SHORT_NA "${mpa_optchar}"
+      then
+        list_append _ADDOPTS_GROFF "${mpa_opt}";
+      elif list_has _OPTS_GROFF_SHORT_ARG "${mpa_optchar}"
+      then
+        list_append _ADDOPTS_GROFF "${mpa_opt}" "$1";
+        shift;
+### main_parse_args()
+      else
+        error "main_parse_args(): Unknown option : \`$1'";
+      fi;
+      ;;
+    --all)
+        _OPT_ALL='yes';
+        ;;
+    --apropos)			# run `apropos'
+      _OPT_APROPOS='yes';
+      _APROPOS_SECTIONS='';
+      _OPT_WHATIS='no';
+      ;;
+    --apropos-data)		# run `apropos' for data sections
+      _OPT_APROPOS='yes';
+      _APROPOS_SECTIONS='457';
+      _OPT_WHATIS='no';
+      ;;
+    --apropos-devel)		# run `apropos' for development sections
+      _OPT_APROPOS='yes';
+      _APROPOS_SECTIONS='239';
+      _OPT_WHATIS='no';
+      ;;
+    --apropos-progs)		# run `apropos' for program sections
+      _OPT_APROPOS='yes';
+      _APROPOS_SECTIONS='168';
+      _OPT_WHATIS='no';
+      ;;
+### main_parse_args()
+    --ascii)
+      list_append _ADDOPTS_GROFF '-mtty-char';
+      if obj _OPT_MODE is_empty
+      then
+        _OPT_MODE='text';
+      fi;
+      ;;
+    --auto)			# the default automatic mode
+      _OPT_MODE='';
+      ;;
+    --bd|--bordercolor)		# border color for viewers, arg;
+      _OPT_BD="$1";
+      shift;
+      ;;
+    --bg|--backgroud)		# background color for viewers, arg;
+      _OPT_BG="$1";
+      shift;
+      ;;
+    --bw|--borderwidth)		# border width for viewers, arg;
+      _OPT_BW="$1";
+      shift;
+      ;;
+    --debug|--debug-all|--debug-filenames|--debug-func|--debug-not-func|\
+--debug-grog|--debug-keep|--debug-lm|--debug-params|--debug-shell|\
+--debug-stacks|--debug-tmpdir|--debug-user)
+      # debug is handled at the beginning
+      :;
+      ;;
+    --default)			# reset variables to default
+      reset;
+      ;;
+### main_parse_args()
+    --default-modes)		# sequence of modes in auto mode; arg
+      _OPT_DEFAULT_MODES="$1";
+      shift;
+      ;;
+    --display)			# set X display, arg
+      _OPT_DISPLAY="$1";
+      shift;
+      ;;
+    --do-nothing)
+      _OPT_DO_NOTHING='yes';
+      ;;
+    --dvi)
+      _OPT_MODE='dvi';
+      ;;
+    --dvi-viewer|--dvi-viewer-tty) # viewer program for dvi mode; arg
+      _OPT_VIEWER_DVI="$1";
+      shift;
+      ;;
+    --extension)		# the extension for man pages, arg
+      _OPT_EXTENSION="$1";
+      shift;
+      ;;
+### main_parse_args()
+    --fg|--foreground)		# foreground color for viewers, arg;
+      _OPT_FG="$1";
+      shift;
+      ;;
+    --fn|--ft|--font)		# set font for viewers, arg;
+      _OPT_FN="$1";
+      shift;
+      ;;
+    --geometry)			# window geometry for viewers, arg;
+      _OPT_GEOMETRY="$1";
+      shift;
+      ;;
+    --groff)
+      _OPT_MODE='groff';
+      ;;
+    --html|--www)		# display with web browser
+      _OPT_MODE=html;
+      ;;
+    --html-viewer|--www-viewer|--html-viewer-tty|--www-viewer-tty)
+      # viewer program for html mode; arg
+      _OPT_VIEWER_HTML="$1";
+      shift;
+      ;;
+    --iconic)			# start viewers as icons
+      _OPT_ICONIC='yes';
+      ;;
+### main_parse_args()
+    --locale)			# set language for man pages, arg
+      # argument is xx[_territory[.codeset[@modifier]]] (ISO 639,...)
+      _OPT_LANG="$1";
+      shift;
+      ;;
+    --local-file)		# force local files; same as `--no-man'
+      _MAN_FORCE='no';
+      _MAN_ENABLE='no';
+      ;;
+    --location|--where)		# print file locations to stderr
+      _DEBUG_PRINT_FILENAMES='yes';
+      ;;
+    --man)		       # force all file params to be man pages
+      _MAN_ENABLE='yes';
+      _MAN_FORCE='yes';
+      ;;
+    --manpath)		      # specify search path for man pages, arg
+      # arg is colon-separated list of directories
+      _OPT_MANPATH="$1";
+      shift;
+      ;;
+    --mode)			# display mode
+      mpa_arg="$1";
+      shift;
+      case "${mpa_arg}" in
+      auto|'')		     # search mode automatically among default
+        _OPT_MODE='';
+        ;;
+      groff)			# pass input to plain groff
+        _OPT_MODE='groff';
+        ;;
+### main_parse_args()
+      html|www)			# display with a web browser
+        _OPT_MODE='html';
+        ;;
+      dvi)			# display with xdvi viewer
+        _OPT_MODE='dvi';
+        ;;
+      pdf)			# display with PDF viewer
+        _OPT_MODE='pdf';
+        ;;
+      ps)			# display with Postscript viewer
+        _OPT_MODE='ps';
+        ;;
+      text)			# output on terminal
+        _OPT_MODE='text';
+        ;;
+      tty)			# output on terminal
+        _OPT_MODE='tty';
+        ;;
+      X|x)			# output on X roff viewer
+        _OPT_MODE='x';
+        ;;
+### main_parse_args()
+      Q|source)			# display source code
+        _OPT_MODE="source";
+        ;;
+      *)
+        error "main_parse_args(): unknown mode ${mpa_arg}";
+        ;;
+      esac;
+      ;;
+    --no-location)		# disable former call to `--location'
+      _DEBUG_PRINT_FILENAMES='no';
+      ;;
+    --no-man)			# disable search for man pages
+      # the same as --local-file
+      _MAN_FORCE='no';
+      _MAN_ENABLE='no';
+      ;;
+    --no-special)		# disable some special former calls
+      _OPT_ALL='no'
+      _OPT_APROPOS='no'
+      _OPT_WHATIS='no'
+      ;;
+    --pager|--tty-viewer|--tty-viewer-tty)
+      # set paging program for tty mode, arg
+      _OPT_PAGER="$1";
+      shift;
+      ;;
+    --pdf)
+      _OPT_MODE='pdf';
+      ;;
+### main_parse_args()
+    --pdf-viewer|--pdf-viewer-tty) # viewer program for pdf mode; arg
+      _OPT_VIEWER_PDF="$1";
+      shift;
+      ;;
+    --print)			# for argument test
+      echo2 "$1";
+      shift;
+      ;;
+    --ps)
+      _OPT_MODE='ps';
+      ;;
+    --ps-viewer|--ps-viewer-tty) # viewer program for ps mode; arg
+      _OPT_VIEWER_PS="$1";
+      shift;
+      ;;
+### main_parse_args()
+    --resolution)		# set resolution for X devices, arg
+      mpa_arg="$1";
+      shift;
+      case "${mpa_arg}" in
+      75|75dpi)
+        mpa_dpi=75;
+        ;;
+      100|100dpi)
+        mpa_dpi=100;
+        ;;
+      *)
+        error "main_parse_args(): \
+only resoutions of 75 or 100 dpi are supported";
+        ;;
+      esac;
+      _OPT_RESOLUTION="${mpa_dpi}";
+      ;;
+    --rv)
+      _OPT_RV='yes';
+      ;;
+    --sections)			# specify sections for man pages, arg
+      # arg is colon-separated list of section names
+      _OPT_SECTIONS="$1";
+      shift;
+      ;;
+    --shell)
+      # already done during the first run; so ignore the argument
+      shift;
+      ;;
+### main_parse_args()
+    --systems)			# man pages for different OS's, arg
+      # argument is a comma-separated list
+      _OPT_SYSTEMS="$1";
+      shift;
+      ;;
+    --text)			# text mode without pager
+      _OPT_MODE=text;
+      ;;
+    --title)			# title for X viewers; arg
+      if is_not_empty "$1"
+      then
+        list_append _OPT_TITLE "$1";
+      fi;
+      shift;
+      ;;
+     --to-stdout)		# print mode file without display
+      _OPT_STDOUT='yes';
+      ;;
+     --tty)			# tty mode, text with pager
+      _OPT_MODE=tty;
+      ;;
+    --text-device|--tty-device) # device for tty mode; arg
+      _OPT_TEXT_DEVICE="$1";
+      shift;
+      ;;
+    --whatis)
+      _OPT_WHATIS='yes';
+      _OPT_APROPOS='no';
+      ;;
+    --X|--x)
+      _OPT_MODE=x;
+      ;;
+### main_parse_args()
+    --xrm)			# pass X resource string, arg;
+      list_append _OPT_XRM "$1";
+      shift;
+      ;;
+    --x-viewer|--X-viewer|--x-viewer-tty|--X-viewer-tty)
+      # viewer program for x mode; arg
+      _OPT_VIEWER_X="$1";
+      shift;
+      ;;
+    *)
+      error 'main_parse_args(): unknown option '"\`${mpa_opt}'.";
+      ;;
+    esac;
+  done;
+  shift;			# remove `--' argument
+
+  if obj _OPT_WHATIS is_yes
+  then
+    _MAN_ALL='yes';
+    _APROPOS_SECTIONS='';
+  fi;
+
+  if obj _OPT_DO_NOTHING is_yes
+  then
+    leave;
+  fi;
+
+### main_parse_args()
+  case "$_OPT_DEFAULT_MODES" in
+  '') :; ;;
+  *,*)
+    obj_from_output _OPT_DEFAULT_MODES \
+      obj _OPT_DEFAULT_MODES list_from_split ',';
+    ;;
+  *) :; ;;
+  esac;
+
+  # Remaining arguments are file names (filespecs).
+  # Save them to list $_FILEARGS
+  if is_equal "$#" 0
+  then				# use "-" for standard input
+    _NO_FILESPECS='yes';
+    set x '-';
+    shift;
+  fi;
+  _FILEARGS='';
+  list_append _FILEARGS "$@";
+  # $_FILEARGS must be retrieved with `eval set x "$_FILEARGS"; shift;'
+  eval ${_UNSET} mpa_arg;
+  eval ${_UNSET} mpa_dpi;
+  eval ${_UNSET} mpa_opt;
+  eval ${_UNSET} mpa_optchar;
+  eval "${return_ok}";
+} # main_parse_args()
+
+
+# Called from main_parse_args() because double `case' is not possible.
+# Globals: $_OPT_DEVICE, $_OPT_MODE
+_check_device_with_mode()
+{
+  func_check _check_device_with_mode = 0 "$@";
+  case "${_OPT_DEVICE}" in
+  dvi)
+    _OPT_MODE=dvi;
+    eval "${return_ok}";
+    ;;
+  html)
+    _OPT_MODE=html;
+    eval "${return_ok}";
+    ;;
+  lbp|lj4)
+    _OPT_MODE=groff;
+    eval "${return_ok}";
+    ;;
+  ps)
+    _OPT_MODE=ps;
+    eval "${return_ok}";
+    ;;
+  ascii|cp1047|latin1|utf8)
+    if obj _OPT_MODE is_not_equal text
+    then
+      _OPT_MODE=tty;		# default text mode
+    fi;
+    eval "${return_ok}";
+    ;;
+  X*)
+    _OPT_MODE=x;
+    eval "${return_ok}";
+    ;;
+  *)				# unknown device, go to groff mode
+    _OPT_MODE=groff;
+    eval "${return_ok}";
+    ;;
+  esac;
+  eval "${return_error}";
+} # _check_device_with_mode() of main_parse_args()
+
+
+########################################################################
+# main_set_mode ()
+#
+# Determine the display mode and the corresponding viewer program.
+#
+# Globals:
+#   in:  $DISPLAY, $_OPT_MODE, $_OPT_DEVICE
+#   out: $_DISPLAY_MODE
+#
+# Variable prefix: msm
+#
+main_set_mode()
+{
+  func_check main_set_mode = 0 "$@";
+
+  # set display
+  if obj _OPT_DISPLAY is_not_empty
+  then
+    DISPLAY="${_OPT_DISPLAY}";
+  fi;
+
+  if obj _OPT_V is_yes
+  then
+    list_append _ADDOPTS_GROFF '-V';
+  fi;
+  if obj _OPT_Z is_yes
+  then
+    _DISPLAY_MODE='groff';
+    list_append _ADDOPTS_GROFF '-Z';
+  fi;
+  if obj _OPT_MODE is_equal 'groff'
+  then
+    _DISPLAY_MODE='groff';
+  fi;
+  if obj _DISPLAY_MODE is_equal 'groff'
+  then
+    eval ${_UNSET} msm_modes;
+    eval ${_UNSET} msm_viewers;
+    eval "${return_ok}";
+  fi;
+
+### main_set_mode()
+
+  case "${_OPT_MODE}" in
+  '')				# automatic mode
+    case "${_OPT_DEVICE}" in
+    X*)
+     if is_not_X
+      then
+        error_user "no X display found for device ${_OPT_DEVICE}";
+      fi;
+      _DISPLAY_MODE='x';
+      eval ${_UNSET} msm_modes;
+      eval ${_UNSET} msm_viewers;
+      eval "${return_ok}";
+      ;;
+    ascii|cp1047|latin1|utf8)
+      if obj _DISPLAY_MODE is_not_equal 'text'
+      then
+        _DISPLAY_MODE='tty';
+      fi;
+      eval ${_UNSET} msm_modes;
+      eval ${_UNSET} msm_viewers;
+      eval "${return_ok}";
+      ;;
+### main_set_mode()
+    esac;
+    if is_not_X
+    then
+      _DISPLAY_MODE='tty';
+      eval ${_UNSET} msm_modes;
+      eval ${_UNSET} msm_viewers;
+      eval "${return_ok}";
+    fi;
+
+    if obj _OPT_DEFAULT_MODES is_empty
+    then
+      msm_modes="${_DEFAULT_MODES}";
+    else
+      msm_modes="${_OPT_DEFAULT_MODES}";
+    fi;
+    ;;
+  source)
+    _DISPLAY_MODE='source';
+    eval ${_UNSET} msm_modes;
+    eval ${_UNSET} msm_viewers;
+    eval "${return_ok}";
+    ;;
+  text)
+    _DISPLAY_MODE='text';
+    eval ${_UNSET} msm_modes;
+    eval ${_UNSET} msm_viewers;
+    eval "${return_ok}";
+    ;;
+  tty)
+    _DISPLAY_MODE='tty';
+    eval ${_UNSET} msm_modes;
+    eval ${_UNSET} msm_viewers;
+    eval "${return_ok}";
+    ;;
+### main_set_mode()
+  html)
+    _DISPLAY_MODE='html';
+    msm_modes="${_OPT_MODE}";
+    ;;
+  *)				# display mode was given
+    msm_modes="${_OPT_MODE}";
+    ;;
+  esac;
+
+  eval set x "${msm_modes}";
+  shift;
+  while is_greater_than "$#" 0
+  do
+    msm_1="$1";
+    shift;
+
+    _VIEWER_BACKGROUND='no';
+
+    case "${msm_1}" in
+    dvi)
+      _get_prog_args DVI;
+      if is_not_equal "$?" 0
+      then
+        continue;
+      fi;
+      if obj _DISPLAY_PROG is_empty
+      then
+        if is_equal "$#" 0
+        then
+          error 'main_set_mode(): No viewer for dvi mode available.';
+        else
+          continue;
+        fi;
+      fi;
+### main_set_mode()
+      _DISPLAY_MODE="dvi";
+      eval ${_UNSET} msm_1;
+      eval ${_UNSET} msm_modes;
+      eval ${_UNSET} msm_viewers;
+      eval "${return_ok}";
+      ;;
+    html)
+      _get_prog_args HTML;
+      if is_not_equal "$?" 0
+      then
+        continue;
+      fi;
+      if obj _DISPLAY_PROG is_empty
+      then
+        if is_equal "$#" 0
+        then
+          error 'main_set_mode(): No viewer for html mode available.';
+        else
+          continue;
+        fi;
+      fi;
+### main_set_mode()
+      _DISPLAY_MODE=html;
+      eval ${_UNSET} msm_1;
+      eval ${_UNSET} msm_modes;
+      eval ${_UNSET} msm_viewers;
+      eval "${return_ok}";
+      ;;
+    pdf)
+      if obj _PDF_DID_NOT_WORK is_yes
+      then
+        if is_equal "$#" 0
+        then
+          error 'main_set_mode(): pdf mode did not work.';
+        else
+          continue;
+        fi;
+      fi;
+      if obj _PDF_HAS_PS2PDF is_not_yes
+      then
+        if is_prog ps2pdf
+        then
+          _PDF_HAS_PS2PDF='yes';
+        fi;
+      fi;
+      if obj _PDF_HAS_GS is_not_yes
+      then
+        if is_prog gs
+        then
+          _PDF_HAS_GS='yes';
+        fi;
+      fi;
+      _get_prog_args PDF;
+      if is_not_equal "$?" 0
+      then
+        _PDF_DID_NOT_WORK='yes';
+        continue;
+      fi;
+      if obj _DISPLAY_PROG is_empty
+      then
+        _PDF_DID_NOT_WORK='yes';
+        if is_equal "$#" 0
+        then
+          error 'main_set_mode(): No viewer for pdf mode available.';
+        else
+          continue;
+        fi;
+      fi;
+      _DISPLAY_MODE="pdf";
+      eval ${_UNSET} msm_1;
+      eval ${_UNSET} msm_modes;
+      eval ${_UNSET} msm_viewers;
+      eval "${return_ok}";
+      ;;
+### main_set_mode()
+    ps)
+      _get_prog_args PS;
+      if is_not_equal "$?" 0
+      then
+        continue;
+      fi;
+      if obj _DISPLAY_PROG is_empty
+      then
+        if is_equal "$#" 0
+        then
+          error 'main_set_mode(): No viewer for ps mode available.';
+        else
+          continue;
+        fi;
+      fi;
+      _DISPLAY_MODE="ps";
+      eval ${_UNSET} msm_1;
+      eval ${_UNSET} msm_modes;
+      eval ${_UNSET} msm_viewers;
+      eval "${return_ok}";
+      ;;
+    text)
+      _DISPLAY_MODE='text';
+      eval ${_UNSET} msm_1;
+      eval ${_UNSET} msm_modes;
+      eval ${_UNSET} msm_viewers;
+      eval "${return_ok}";
+      ;;
+### main_set_mode()
+    tty)
+      _DISPLAY_MODE='tty';
+      eval ${_UNSET} msm_1;
+      eval ${_UNSET} msm_modes;
+      eval ${_UNSET} msm_viewers;
+      eval "${return_ok}";
+      ;;
+    x)
+      _get_prog_args x;
+      if is_not_equal "$?" 0
+      then
+        continue;
+      fi;
+      if obj _DISPLAY_PROG is_empty
+      then
+        if is_equal "$#" 0
+        then
+          error 'main_set_mode(): No viewer for x mode available.';
+        else
+          continue;
+        fi;
+      fi;
+      _DISPLAY_MODE='x';
+      eval ${_UNSET} msm_1;
+      eval ${_UNSET} msm_modes;
+      eval ${_UNSET} msm_viewers;
+      eval "${return_ok}";
+      ;;
+### main_set_mode()
+    X)
+      _DISPLAY_MODE='X';
+      eval ${_UNSET} msm_1;
+      eval ${_UNSET} msm_modes;
+      eval ${_UNSET} msm_viewers;
+      eval "${return_ok}";
+      ;;
+    esac;
+  done;
+  eval ${_UNSET} msm_1;
+  eval ${_UNSET} msm_modes;
+  eval ${_UNSET} msm_viewers;
+  error_user "No suitable display mode found.";
+} # main_set_mode()
+
+
+# _get_prog_args (<MODE>)
+#
+# Simplification for loop in main_set_mode().
+#
+# Globals in/out: $_VIEWER_BACKGROUND
+# Globals in    : $_OPT_VIEWER_<MODE>, $_VIEWER_<MODE>_X, $_VIEWER_<MODE>_TTY
+#
+# Variable prefix: _gpa
+#
+_get_prog_args()
+{
+  func_check _get_prog_args '=' 1 "$@";
+
+  x="$(echo1 $1 | tr [a-z] [A-Z])";
+  eval _gpa_opt='"${_OPT_VIEWER_'"$x"'}"';
+  _gpa_xlist=_VIEWER_"$x"_X;
+  _gpa_ttylist=_VIEWER_"$x"_TTY;
+
+  if obj _gpa_opt is_empty
+  then
+    _VIEWER_BACKGROUND='no';
+    if is_X
+    then
+      _get_first_prog "${_gpa_xlist}";
+      x="$?";
+      if is_equal "$x" 0
+      then
+        _VIEWER_BACKGROUND='yes';
+      fi;
+    else
+      _get_first_prog "${_gpa_ttylist}";
+      x="$?";
+    fi;
+    exit_test;
+    eval ${_UNSET} _gpa_opt;
+    eval ${_UNSET} _gpa_prog;
+    eval ${_UNSET} _gpa_ttylist;
+    eval ${_UNSET} _gpa_xlist;
+    eval "${return_var} $x";
+### _get_prog_args() of main_set_mode()
+  else				# $_gpa_opt is not empty
+    obj_from_output _gpa_prog where_is_prog "${_gpa_opt}";
+    if is_not_equal "$?" 0 || obj _gpa_prog is_empty
+    then
+      exit_test;
+      echo2 "_get_prog_args(): '${_gpa_opt}' is not an existing program.";
+      eval ${_UNSET} _gpa_opt;
+      eval ${_UNSET} _gpa_prog;
+      eval ${_UNSET} _gpa_ttylist;
+      eval ${_UNSET} _gpa_xlist;
+      eval "${return_bad}";
+    fi;
+    exit_test;
+
+    # $_gpa_prog from opt is an existing program
+
+### _get_prog_args() of main_set_mode()
+    if is_X
+    then
+      eval _check_prog_on_list ${_gpa_prog} ${_gpa_xlist};
+      if is_equal "$?" 0
+      then
+        _VIEWER_BACKGROUND='yes';
+      else
+        _VIEWER_BACKGROUND='no';
+        eval _check_prog_on_list ${_gpa_prog} ${_gpa_ttylist};
+      fi;
+    else			# is not X
+      _VIEWER_BACKGROUND='no';
+      eval _check_prog_on_list ${_gpa_prog} ${_gpa_ttylist};
+    fi;				# is_X
+  fi;				# test of $_gpa_opt
+  eval ${_UNSET} _gpa_opt;
+  eval ${_UNSET} _gpa_prog;
+  eval ${_UNSET} _gpa_ttylist;
+  eval ${_UNSET} _gpa_xlist;
+  eval "${return_good}";
+} # _get_prog_args() of main_set_mode()
+
+
+# _get_first_prog (<prog_list_name>)
+#
+# Retrieve from the elements of the list in the argument the first
+# existing program in $PATH.
+#
+# Local function for main_set_mode().
+#
+# Return  : `1' if none found, `0' if found.
+# Output  : none
+#
+# Variable prefix: _gfp
+#
+_get_first_prog()
+{
+  func_check _get_first_prog '=' 1 "$@";
+  eval x='"${'"$1"'}"';
+  eval set x "$x";
+  shift;
+  for i
+  do
+    _gfp_i="$i";
+    if obj _gfp_i is_empty
+    then
+      continue;
+    fi;
+    obj_from_output _gfp_result where_is_prog "${_gfp_i}";
+    if is_equal "$?" 0 && obj _gfp_result is_not_empty
+    then
+      exit_test;
+      eval set x ${_gfp_result};
+      shift;
+      _DISPLAY_PROG="$1";
+      _DISPLAY_ARGS="$2";
+      eval ${_UNSET} _gfp_i;
+      eval ${_UNSET} _gfp_result;
+      eval "${return_good}";
+    fi;
+    exit_test;
+  done;
+  eval ${_UNSET} _gfp_i;
+  eval ${_UNSET} _gfp_result;
+  eval "${return_bad}";
+} # _get_first_prog() of main_set_mode()
+
+
+# _check_prog_on_list (<prog> <args> <prog_list_name>)
+#
+# Check whether the content of <prog> is in the list <prog_list_name>.
+# The globals are set correspondingly.
+#
+# Local function for main_set_mode().
+#
+# Arguments: 3
+#
+# Return  : `1' if not a part of the list, `0' if found in the list.
+# Output  : none
+#
+# Globals in    : $_VIEWER_<MODE>_X, $_VIEWER_<MODE>_TTY
+# Globals in/out: $_DISPLAY_PROG, $_DISPLAY_ARGS
+#
+# Variable prefix: _cpol
+#
+_check_prog_on_list()
+{
+  func_check _check_prog_on_list '=' 3 "$@";
+  _DISPLAY_PROG="$1";
+  _DISPLAY_ARGS="$2";
+
+  eval _cpol_3='"${'"$3"'}"';
+  eval set x "${_cpol_3}";
+  shift;
+  eval ${_UNSET} _cpol_3;
+
+  for i
+  do
+    _cpol_i="$i";
+    obj_from_output _cpol_list where_is_prog "${_cpol_i}";
+    if is_not_equal "$?" 0 || obj _cpol_list is_empty
+    then
+      exit_test;
+      continue;
+    fi;
+    exit_test;
+    _cpol_prog="$(eval set x ${_cpol_list}; shift; echo1 "$1")";
+
+    if is_not_equal "${_DISPLAY_PROG}" "${_cpol_prog}"
+    then
+      exit_test;
+      continue;
+    fi;
+    exit_test;
+### _check_prog_on_list() of main_set_mode()
+
+    # equal, prog found
+
+    _cpol_args="$(eval set x ${_cpol_list}; shift; echo1 "$2")";
+    eval ${_UNSET} _cpol_list;
+    if obj _cpol_args is_not_empty
+    then
+      if obj _DISPLAY_ARGS is_empty
+      then
+        _DISPLAY_ARGS="${_cpol_args}";
+      else
+        _DISPLAY_ARGS="${_cpol_args} ${_DISPLAY_ARGS}";
+      fi;
+    fi;
+
+    eval ${_UNSET} _cpol_i;
+    eval ${_UNSET} _cpol_args;
+    eval ${_UNSET} _cpol_prog;
+    eval "${return_good}";
+  done; # for vars in list
+
+  # prog was not in the list
+  eval ${_UNSET} _cpol_i;
+  eval ${_UNSET} _cpol_args;
+  eval ${_UNSET} _cpol_list;
+  eval ${_UNSET} _cpol_prog;
+  eval "${return_bad}";
+} # _check_prog_on_list() of main_set_mode()
+
+
+#######################################################################
+# main_do_fileargs ()
+#
+# Process filespec arguments.
+#
+# Globals:
+#   in: $_FILEARGS (process with `eval set x "$_FILEARGS"; shift;')
+#
+# Variable prefix: mdfa
+#
+main_do_fileargs()
+{
+  func_check main_do_fileargs = 0 "$@";
+  special_setup;
+  if obj _OPT_APROPOS is_yes
+  then
+    if obj _NO_FILESPECS is_yes
+    then
+      apropos_filespec;
+      eval "${return_ok}";
+    fi;
+  else
+    if list_has _FILEARGS '-'
+    then
+      save_stdin;
+    fi;
+  fi;
+  eval set x "${_FILEARGS}";
+  shift;
+  eval ${_UNSET} _FILEARGS;
+### main_do_fileargs()
+  while is_greater_than "$#" 0
+  do
+    mdfa_filespec="$1";
+    _FILESPEC_ARG="$1";
+    shift;
+    _FILESPEC_IS_MAN='no';
+    _TMP_MANSPEC='';
+    _SPECIAL_FILESPEC='no';
+
+    case "${mdfa_filespec}" in
+    '')
+      continue;
+      ;;
+    esac;
+
+    # check for file
+    case "${mdfa_filespec}" in
+    '-')
+      special_filespec;
+      if obj _OPT_APROPOS is_yes
+      then
+        continue;
+      fi;
+      register_file '-';
+      continue;
+      ;;
+### main_do_fileargs()
+    */*)
+      special_filespec;
+      if obj _OPT_APROPOS is_yes
+      then
+        continue;
+      fi;
+      if obj mdfa_filespec is_file
+      then
+        obj mdfa_filespec register_file;
+      else
+        echo2 "The argument ${mdfa_filespec} is not a file.";
+      fi;
+      continue;
+      ;;
+    *)
+      if obj _OPT_APROPOS is_yes
+      then
+        special_filespec;
+        continue;
+      fi;
+      # check whether filespec is an existing file
+      if obj _MAN_FORCE is_not_yes
+      then
+        if obj mdfa_filespec is_file
+        then
+          special_filespec;
+          obj mdfa_filespec register_file;
+          continue;
+        fi;
+      fi;
+      ;;
+    esac;
+### main_do_fileargs()
+
+    # now it must be a man page pattern
+
+    if obj _MACRO_PKG is_not_empty && obj _MACRO_PKG is_not_equal '-man'
+    then
+      echo2 "${mdfa_filespec} is not a file, man pages are ignored "\
+"due to ${_MACRO_PKG}.";
+      continue;
+    fi;
+
+    # check for man page
+    if obj _MAN_ENABLE is_not_yes
+    then
+      echo2 "The argument ${mdfa_filespec} is not a file.";
+      continue;
+    fi;
+    if obj _MAN_FORCE is_yes
+    then
+      mdfa_errmsg='is not a man page.';
+    else
+      mdfa_errmsg='is neither a file nor a man page.';
+    fi;
+### main_do_fileargs()
+    man_setup;
+    _FILESPEC_IS_MAN='yes';
+
+    # test filespec with `man:...' or `...(...)' on man page
+    mdfa_name='';
+    mdfa_section='';
+    mdfa_ext='';
+
+    mdfa_names="${mdfa_filespec}";
+    case "${mdfa_filespec}" in
+    man:*)
+        mdfa_names="${mdfa_names} "\
+"$(obj mdfa_filespec echo1 | sed 's/^man://')";
+        ;;
+    esac;
+
+    mdfa_continue='no';
+    for i in ${mdfa_names}
+    do
+      mdfa_i=$i;
+      if obj mdfa_i man_is_man
+      then
+        special_filespec;
+        obj mdfa_i man_get;
+        mdfa_continue='yes';
+        break;
+      fi;
+      case "${mdfa_i}" in
+      *\(${_MAN_AUTO_SEC_CHARS}*\))
+        mdfa_section="$(obj mdfa_i echo1 | sed 's/^[^(]*(\(.\).*)$/\1/')";
+        mdfa_name="$(obj mdfa_i echo1 | sed 's/^\([^(]*\)(.*)$/\1/')";
+        mdfa_ext="$(obj mdfa_i echo1 | sed 's/^[^(]*(.\(.*\))$/\1/')";
+        if man_is_man "${mdfa_name}" "${mdfa_section}" "${mdfa_ext}"
+        then
+          special_filespec;
+          man_get "${mdfa_name}" "${mdfa_section}" "${mdfa_ext}";
+          mdfa_continue='yes';
+          break;
+        fi;
+        ;;
+      *.${_MAN_AUTO_SEC_CHARS}*)
+        mdfa_name="$(obj mdfa_i echo1 | \
+          sed 's/^\(.*\)\.'"${_MAN_AUTO_SEC_CHARS}"'.*$/\1/')";
+        mdfa_section="$(obj mdfa_i echo1 | \
+          sed 's/^.*\.\('"${_MAN_AUTO_SEC_CHARS}"'\).*$/\1/')";
+        mdfa_ext="$(obj mdfa_i echo1 | \
+          sed 's/^.*\.'"${_MAN_AUTO_SEC_CHARS}"'\(.*\)$/\1/')";
+        if man_is_man "${mdfa_name}" "${mdfa_section}" "${mdfa_ext}"
+        then
+          special_filespec;
+          man_get "${mdfa_name}" "${mdfa_section}" "${mdfa_ext}";
+          mdfa_continue='yes';
+          break;
+        fi;
+      ;;
+      esac;
+    done;
+
+    if obj mdfa_continue is_yes
+    then
+      continue;
+    fi;
+
+### main_do_fileargs()
+    # check on "s name", where "s" is a section with or without an extension
+    if is_not_empty "$1"
+    then
+      mdfa_name="$1";
+      case "${mdfa_filespec}" in
+      ${_MAN_AUTO_SEC_CHARS})
+        mdfa_section="${mdfa_filespec}";
+        mdfa_ext='';
+        ;;
+      ${_MAN_AUTO_SEC_CHARS}*)
+        mdfa_section="$(echo1 "${mdfa_filespec}" | \
+                        sed 's/^\(.\).*$/\1/')";
+        mdfa_ext="$(echo1 "${mdfa_filespec}" | \
+                    sed 's/^.\(.*\)$/\1/')";
+        ;;
+      *)
+        echo2 "${mdfa_filespec} ${mdfa_errmsg}";
+        continue;
+        ;;
+      esac;
+      shift;
+      if man_is_man "${mdfa_name}" "${mdfa_section}" "${mdfa_ext}"
+      then
+        _FILESPEC_ARG="${mdfa_filespec} ${mdfa_name}";
+        special_filespec;
+        man_get "${mdfa_name}" "${mdfa_section}" "${mdfa_ext}";
+        continue;
+      else
+        echo2 "No man page for ${mdfa_name} with section ${mdfa_filespec}.";
+        continue;
+      fi;
+    fi;
+
+### main_do_fileargs()
+    echo2 "${mdfa_filespec} ${mdfa_errmsg}";
+    continue;
+  done;
+
+  obj _TMP_STDIN rm_file_with_debug;
+  eval ${_UNSET} mdfa_filespec;
+  eval ${_UNSET} mdfa_i;
+  eval ${_UNSET} mdfa_name;
+  eval ${_UNSET} mdfa_names;
+  eval "${return_ok}";
+} # main_do_fileargs()
+
+
+########################################################################
+# main_set_resources ()
+#
+# Determine options for setting X resources with $_DISPLAY_PROG.
+#
+# Globals: $_DISPLAY_PROG, $_OUTPUT_FILE_NAME
+#
+# Variable prefix: msr
+#
+main_set_resources()
+{
+  func_check main_set_resources = 0 "$@";
+  # $msr_prog   viewer program
+  # $msr_rl     resource list
+  for f in ${_TMP_DIR}/,man*
+  do
+    rm_file_with_debug $f;
+  done;
+  obj_from_output msr_title \
+    get_first_essential "${_OPT_TITLE}" "${_REG_TITLE_LIST}";
+  _OUTPUT_FILE_NAME='';
+  eval set x "${msr_title}";
+  shift;
+  until is_equal "$#" 0
+  do
+    msr_n="$1";
+    case "${msr_n}" in
+    '')
+      continue;
+      ;;
+    ,*)
+      msr_n="$(echo1 "$1" | sed 's/^,,*//')";
+      exit_test;
+      ;;
+    esac;
+    if obj msr_n is_empty
+    then
+      continue;
+    fi;
+    if obj _OUTPUT_FILE_NAME is_not_empty
+    then
+      _OUTPUT_FILE_NAME="${_OUTPUT_FILE_NAME}"',';
+    fi;
+    _OUTPUT_FILE_NAME="${_OUTPUT_FILE_NAME}${msr_n}";
+    shift;
+  done; # until $# is 0
+### main_set_resources()
+
+  case "${_OUTPUT_FILE_NAME}" in
+  '')
+    _OUTPUT_FILE_NAME='-';
+    ;;
+  ,*)
+    error "main_set_resources(): ${_OUTPUT_FILE_NAME} starts with a comma.";
+    ;;
+  esac;
+  _OUTPUT_FILE_NAME="${_TMP_DIR}/${_OUTPUT_FILE_NAME}";
+
+  if obj _DISPLAY_PROG is_empty
+  then				# for example, for groff mode
+    _DISPLAY_ARGS='';
+    eval ${_UNSET} msr_n;
+    eval ${_UNSET} msr_prog;
+    eval ${_UNSET} msr_rl;
+    eval ${_UNSET} msr_title;
+    eval "${return_ok}";
+  fi;
+
+  eval set x "${_DISPLAY_PROG}";
+  shift;
+  obj_from_output msr_prog base_name "$1";
+  shift;
+  if is_greater_than $# 0
+  then
+    if obj _DISPLAY_ARGS is_empty
+    then
+      _DISPLAY_ARGS="$*";
+    else
+      _DISPLAY_ARGS="$* ${_DISPLAY_ARGS}";
+    fi;
+  fi;
+### main_set_resources()
+  msr_rl='';
+  if obj _OPT_BD is_not_empty
+  then
+    case "${msr_prog}" in
+    ghostview|gv|gxditview|xditview|xdvi)
+      list_append msr_rl '-bd' "${_OPT_BD}";
+      ;;
+    esac;
+  fi;
+  if obj _OPT_BG is_not_empty
+  then
+    case "${msr_prog}" in
+    ghostview|gv|gxditview|xditview|xdvi)
+      list_append msr_rl '-bg' "${_OPT_BG}";
+      ;;
+    kghostview)
+      list_append msr_rl '--bg' "${_OPT_BG}";
+      ;;
+    xpdf)
+      list_append msr_rl '-papercolor' "${_OPT_BG}";
+      ;;
+    esac;
+  fi;
+  if obj _OPT_BW is_not_empty
+  then
+    case "${msr_prog}" in
+    ghostview|gv|gxditview|xditview|xdvi)
+      _list_append msr_rl '-bw' "${_OPT_BW}";
+      ;;
+    esac;
+  fi;
+### main_set_resources()
+  if obj _OPT_FG is_not_empty
+  then
+    case "${msr_prog}" in
+    ghostview|gv|gxditview|xditview|xdvi)
+      list_append msr_rl '-fg' "${_OPT_FG}";
+      ;;
+    kghostview)
+      list_append msr_rl '--fg' "${_OPT_FG}";
+      ;;
+    esac;
+  fi;
+  if is_not_empty "${_OPT_FN}"
+  then
+    case "${msr_prog}" in
+    ghostview|gv|gxditview|xditview|xdvi)
+      list_append msr_rl '-fn' "${_OPT_FN}";
+      ;;
+    kghostview)
+      list_append msr_rl '--fn' "${_OPT_FN}";
+      ;;
+    esac;
+  fi;
+  if is_not_empty "${_OPT_GEOMETRY}"
+  then
+    case "${msr_prog}" in
+    ghostview|gv|gxditview|xditview|xdvi|xpdf)
+      list_append msr_rl '-geometry' "${_OPT_GEOMETRY}";
+      ;;
+    kghostview)
+      list_append msr_rl '--geometry' "${_OPT_GEOMETRY}";
+      ;;
+    esac;
+  fi;
+### main_set_resources()
+  if is_empty "${_OPT_RESOLUTION}"
+  then
+    _OPT_RESOLUTION="${_DEFAULT_RESOLUTION}";
+    case "${msr_prog}" in
+    gxditview|xditview)
+      list_append msr_rl '-resolution' "${_DEFAULT_RESOLUTION}";
+      ;;
+    xpdf)
+      case "${_DISPLAY_PROG}" in
+      *-z*)
+        :;
+        ;;
+      *)			# if xpdf does not have option -z
+        case "${_DEFAULT_RESOLUTION}" in
+        75)
+          # 72dpi is '100'
+          list_append msr_rl '-z' '104';
+          ;;
+        100)
+          list_append msr_rl '-z' '139';
+          ;;
+        esac;
+        ;;
+      esac;
+      ;;
+    esac;
+  else
+    case "${msr_prog}" in
+    ghostview|gv|gxditview|xditview|xdvi)
+      list_append msr_rl '-resolution' "${_OPT_RESOLUTION}";
+      ;;
+    xpdf)
+      case "${_DISPLAY_PROG}" in
+      *-z*)
+        :;
+        ;;
+      *)			# if xpdf does not have option -z
+        case "${_OPT_RESOLUTION}" in
+        75)
+          list_append msr_rl '-z' '104';
+          # '100' corresponds to 72dpi
+          ;;
+### main_set_resources()
+        100)
+          list_append msr_rl '-z' '139';
+          ;;
+        esac;
+        ;;
+      esac;
+      ;;
+    esac;
+  fi;
+  if is_yes "${_OPT_ICONIC}"
+  then
+    case "${msr_prog}" in
+    ghostview|gv|gxditview|xditview|xdvi)
+      list_append msr_rl '-iconic';
+      ;;
+    esac;
+  fi;
+  if is_yes "${_OPT_RV}"
+  then
+    case "${msr_prog}" in
+    ghostview|gv|gxditview|xditview|xdvi)
+      list_append msr_rl '-rv';
+      ;;
+    esac;
+  fi;
+  if is_not_empty "${_OPT_XRM}"
+  then
+    case "${msr_prog}" in
+    ghostview|gv|gxditview|xditview|xdvi|xpdf)
+      eval set x "${_OPT_XRM}";
+      shift;
+      for i
+      do
+        list_append msr_rl '-xrm' "$i";
+      done;
+### main_set_resources()
+      ;;
+    esac;
+  fi;
+  if is_not_empty "${msr_title}"
+  then
+    case "${msr_prog}" in
+    gxditview|xditview)
+      list_append msr_rl '-title' "${msr_title}";
+      ;;
+    esac;
+  fi;
+  if obj _DISPLAY_ARGS is_empty
+  then
+    _DISPLAY_ARGS="${msr_rl}";
+  else
+    _DISPLAY_ARGS="${msr_l} ${_DISPLAY_ARGS}";
+  fi;
+  eval ${_UNSET} msr_n;
+  eval ${_UNSET} msr_prog;
+  eval ${_UNSET} msr_rl;
+  eval ${_UNSET} msr_title;
+  eval "${return_ok}";
+} # main_set_resources
+
+
+########################################################################
+# main_display ()
+#
+# Do the actual display of the whole thing.
+#
+# Globals:
+#   in: $_DISPLAY_MODE, $_OPT_DEVICE, $_ADDOPTS_GROFF,
+#       $_TMP_CAT, $_OPT_PAGER, $_MANOPT_PAGER, $_OUTPUT_FILE_NAME
+#
+# Variable prefix: md
+#
+main_display()
+{
+  func_check main_display = 0 "$@";
+
+  export md_addopts;
+  export md_groggy;
+  export md_modefile;
+
+  if obj _TMP_CAT is_empty_file
+  then
+    echo2 'groffer: empty input.';
+    clean_up;
+    eval "${return_ok}";
+  fi;
+
+  md_modefile="${_OUTPUT_FILE_NAME}";
+
+  # go to the temporary directory to be able to access internal data files
+  cd "${_TMP_DIR}" >"${_NULL_DEV}" 2>&1;
+
+  case "${_DISPLAY_MODE}" in
+  groff)
+    if obj _OPT_DEVICE is_not_empty
+    then
+      _ADDOPTS_GROFF="${_ADDOPTS_GROFF} -T${_OPT_DEVICE}";
+    fi;
+    md_groggy="$(tmp_cat | eval grog)";
+    if is_not_equal "$?" 0
+    then
+      exit "${_ERROR}";
+    fi;
+    echo2 "grog output: ${md_groggy}";
+    exit_test;
+    _do_opt_V;
+
+### main_display()
+    obj md_modefile rm_file;
+    mv "${_TMP_CAT}" "${md_modefile}";
+    trap_unset;
+    cat "${md_modefile}" | \
+    {
+      trap_set;
+      eval "${md_groggy}" "${_ADDOPTS_GROFF}";
+    } &
+    ;;
+  text|tty)
+    case "${_OPT_DEVICE}" in
+    '')
+      obj_from_output md_device \
+        get_first_essential "${_OPT_TEXT_DEVICE}" "${_DEFAULT_TTY_DEVICE}";
+      ;;
+    ascii|cp1047|latin1|utf8)
+      md_device="${_OPT_DEVICE}";
+      ;;
+    *)
+      warning "main_display(): \
+wrong device for ${_DISPLAY_MODE} mode: ${_OPT_DEVICE}";
+      ;;
+    esac;
+    md_addopts="${_ADDOPTS_GROFF}";
+    md_groggy="$(tmp_cat | grog -T${md_device})";
+    if is_not_equal "$?" 0
+    then
+      exit "${_ERROR}";
+    fi;
+    echo2 "grog output: ${md_groggy}";
+    exit_test;
+    if obj _DISPLAY_MODE is_equal 'text'
+    then
+      _do_opt_V;
+      tmp_cat | eval "${md_groggy}" "${md_addopts}";
+    else			# $_DISPLAY_MODE is 'tty'
+### main_display()
+      md_pager='';
+      for p in "${_OPT_PAGER}" "${_MANOPT_PAGER}" "${PAGER}"
+      do
+        if obj p is_empty
+        then
+          continue;
+        fi;
+        obj_from_output md_pager where_is_prog "$p";
+        if is_not_equal "$?" 0 || obj md_pager is_empty
+        then
+          md_pager='';
+          continue;
+        fi;
+        eval set x $md_pager;
+        shift;
+        case "$1" in
+        */less)
+          if is_empty "$2"
+          then
+            md_pager="$1"' -r -R';
+          else
+            md_pager="$1"' -r -R '"$2";
+          fi;
+          ;;
+### main_display()
+        *)
+          if is_empty "$2"
+          then
+            md_pager="$1";
+          else
+            md_pager="$1 $2";
+          fi;
+          ;;
+        esac;
+        break;
+      done;
+      if obj md_pager is_empty
+      then
+        eval set x ${_VIEWER_TTY_TTY} ${_VIEWER_TTY_X} 'cat';
+        shift;
+        # that is: 'less -r -R' 'more' 'pager' 'xless' 'cat'
+        for p
+        do
+          if obj p is_empty
+          then
+            continue;
+          fi;
+          md_p="$p";
+          if is_prog "${md_p}"
+          then
+            md_pager="${md_p}";
+            break;
+          fi;
+        done;
+      fi;
+### main_display()
+      if obj md_pager is_empty
+      then
+        error 'main_display(): no pager program found for tty mode';
+      fi;
+      _do_opt_V;
+      tmp_cat | eval "${md_groggy}" "${md_addopts}" | \
+                eval "${md_pager}";
+    fi;				# $_DISPLAY_MODE
+    clean_up;
+    ;;				# text|tty)
+  source)
+    tmp_cat;
+    clean_up;
+    ;;
+
+  #### viewer modes
+
+### main_display()
+  dvi)
+    case "${_OPT_DEVICE}" in
+    ''|dvi) do_nothing; ;;
+    *)
+      warning "main_display(): \
+wrong device for ${_DISPLAY_MODE} mode: ${_OPT_DEVICE}"
+      ;;
+    esac;
+    md_modefile="${md_modefile}".dvi;
+    md_groggy="$(tmp_cat | grog -Tdvi)";
+    if is_not_equal "$?" 0
+    then
+      exit "${_ERROR}";
+    fi;
+    echo2 "grog output: ${md_groggy}";
+    exit_test;
+    _do_display;
+    ;;
+  html)
+    case "${_OPT_DEVICE}" in
+    ''|html) do_nothing; ;;
+    *)
+      warning "main_display(): \
+wrong device for ${_DISPLAY_MODE} mode: ${_OPT_DEVICE}";
+      ;;
+    esac;
+    md_modefile="${md_modefile}".html;
+    md_groggy="$(tmp_cat | grog -Thtml)";
+    if is_not_equal "$?" 0
+    then
+      exit "${_ERROR}";
+    fi;
+    echo2 "grog output: ${md_groggy}";
+    exit_test;
+    _do_display;
+    ;;
+### main_display()
+  pdf)
+    case "${_OPT_DEVICE}" in
+    ''|ps)
+      do_nothing;
+      ;;
+    *)
+      warning "main_display(): \
+wrong device for ${_DISPLAY_MODE} mode: ${_OPT_DEVICE}";
+      ;;
+    esac;
+    md_groggy="$(tmp_cat | grog -Tps)";
+    if is_not_equal "$?" 0
+    then
+      exit "${_ERROR}";
+    fi;
+    echo2 "grog output: ${md_groggy}";
+    exit_test;
+    _do_display _make_pdf;
+    ;;
+  ps)
+    case "${_OPT_DEVICE}" in
+    ''|ps)
+      do_nothing;
+      ;;
+    *)
+      warning "main_display(): \
+wrong device for ${_DISPLAY_MODE} mode: ${_OPT_DEVICE}";
+      ;;
+    esac;
+    md_modefile="${md_modefile}".ps;
+    md_groggy="$(tmp_cat | grog -Tps)";
+    if is_not_equal "$?" 0
+    then
+      exit "${_ERROR}";
+    fi;
+    echo2 "grog output: ${md_groggy}";
+    exit_test;
+    _do_display;
+    ;;
+### main_display()
+  x)
+    case "${_OPT_DEVICE}" in
+    X*)
+      md_device="${_OPT_DEVICE}"
+      ;;
+    *)
+      case "${_OPT_RESOLUTION}" in
+      100)
+        md_device='X100';
+        if obj _OPT_GEOMETRY is_empty
+        then
+          case "${_DISPLAY_PROG}" in
+          gxditview|xditview)
+            # add width of 800dpi for resolution of 100dpi to the args
+            list_append _DISPLAY_ARGS '-geometry' '800';
+            ;;
+          esac;
+        fi;
+        ;;
+      *)
+        md_device='X75-12';
+        ;;
+      esac
+    esac;
+    md_groggy="$(tmp_cat | grog -T${md_device} -Z)";
+    if is_not_equal "$?" 0
+    then
+      exit "${_ERROR}";
+    fi;
+    echo2 "grog output: ${md_groggy}";
+    exit_test;
+    _do_display;
+    ;;
+### main_display()
+  X)
+    case "${_OPT_DEVICE}" in
+    '')
+      md_groggy="$(tmp_cat | grog -X)";
+      if is_not_equal "$?" 0
+      then
+        exit "${_ERROR}";
+      fi;
+      echo2 "grog output: ${md_groggy}";
+      exit_test;
+      ;;
+    X*|dvi|html|lbp|lj4|ps)
+      # these devices work with
+      md_groggy="$(tmp_cat | grog -T"${_OPT_DEVICE}" -X)";
+      if is_not_equal "$?" 0
+      then
+        exit "${_ERROR}";
+      fi;
+      echo2 "grog output: ${md_groggy}";
+      exit_test;
+      ;;
+    *)
+      warning "main_display(): \
+wrong device for ${_DISPLAY_MODE} mode: ${_OPT_DEVICE}";
+      md_groggy="$(tmp_cat | grog -Z)";
+      if is_not_equal "$?" 0
+      then
+        exit "${_ERROR}";
+      fi;
+      echo2 "grog output: ${md_groggy}";
+      exit_test;
+      ;;
+    esac;
+    _do_display;
+    ;;
+  *)
+    error "main_display(): unknown mode \`${_DISPLAY_MODE}'";
+    ;;
+  esac;
+  eval ${_UNSET} md_addopts;
+  eval ${_UNSET} md_device;
+  eval ${_UNSET} md_groggy;
+  eval ${_UNSET} md_modefile;
+  eval ${_UNSET} md_p;
+  eval ${_UNSET} md_pager;
+  eval "${return_ok}";
+} # main_display()
+
+
+########################
+# _do_display ([<prog>])
+#
+# Perform the generation of the output and view the result.  If an
+# argument is given interpret it as a function name that is called in
+# the midst (actually only for `pdf').
+#
+# Globals: $md_modefile, $md_groggy (from main_display())
+#
+_do_display()
+{
+  func_check _do_display '>=' 0 "$@";
+  _do_opt_V;
+  if obj _DISPLAY_PROG is_empty
+  then
+    trap_unset;
+    {
+      trap_set;
+      eval "${md_groggy}" "${_ADDOPTS_GROFF}" "${_TMP_CAT}";
+    } &
+  else
+    obj md_modefile rm_file;
+    cat "${_TMP_CAT}" | \
+      eval "${md_groggy}" "${_ADDOPTS_GROFF}" > "${md_modefile}";
+    if obj md_modefile is_empty_file
+    then
+      echo2 '_do_display(): empty output.';
+      clean_up;
+      exit;
+    fi;
+    if is_not_empty "$1"
+    then
+      eval "$1";
+    fi;
+### _do_display() of main_display()
+    obj _TMP_CAT rm_file_with_debug;
+    if obj _OPT_STDOUT is_yes
+    then
+      cat "${md_modefile}";
+      clean_up;
+      exit;
+    fi;
+    if obj _VIEWER_BACKGROUND is_not_yes # for programs that run on tty
+    then
+      eval "'${_DISPLAY_PROG}'" ${_DISPLAY_ARGS} "\"${md_modefile}\"";
+    else
+      trap_unset;
+      {
+        trap_set;
+        eval "${_DISPLAY_PROG}" ${_DISPLAY_ARGS} "\"${md_modefile}\"";
+      } &
+    fi;
+  fi;
+  eval "${return_ok}";
+} # _do_display() of main_display()
+
+
+#############
+# _do_opt_V ()
+#
+# Check on option `-V'; if set print the corresponding output and leave.
+#
+# Globals: $_ALL_PARAMS, $_ADDOPTS_GROFF, $_DISPLAY_MODE, $_DISPLAY_PROG,
+#          $_DISPLAY_ARGS, $md_groggy,  $md_modefile
+#
+# Variable prefix: _doV
+#
+_do_opt_V()
+{
+  func_check _do_opt_V '=' 0 "$@";
+  if obj _OPT_V is_yes
+  then
+    _OPT_V='no';
+    echo1 "Parameters:     ${_ALL_PARAMS}";
+    echo1 "Display mode:   ${_DISPLAY_MODE}";
+    echo1 "Output file:    ${md_modefile}";
+    echo1 "Display prog:   ${_DISPLAY_PROG} ${_DISPLAY_ARGS}";
+    a="$(eval echo1 "'${_ADDOPTS_GROFF}'")";
+    exit_test;
+    echo1 "Output of grog: ${md_groggy} $a";
+    _doV_res="$(eval "${md_groggy}" "${_ADDOPTS_GROFF}")";
+    exit_test;
+    echo1 "groff -V:       ${_doV_res}"
+    leave;
+  fi;
+  eval "${return_ok}";
+} # _do_opt_V() of main_display()
+
+
+##############
+# _make_pdf ()
+#
+# Transform to pdf format; for pdf mode in _do_display().
+#
+# Globals: $md_modefile (from main_display())
+#
+# Variable prefix: _mp
+#
+_make_pdf()
+{
+  func_check _make_pdf '=' 0 "$@";
+  _mp_psfile="${md_modefile}";
+  md_modefile="${md_modefile}.pdf";
+  obj md_modefile rm_file;
+  if obj _PDF_HAS_PS2PDF is_yes && ps2pdf "${_mp_psfile}" "${md_modefile}";
+  then
+    :;
+  elif obj _PDF_HAS_GS is_yes && gs -q -dNOPAUSE -dBATCH -sDEVICE=pdfwrite \
+       -sOutputFile="${md_modefile}" -c save pop -f "${_mp_psfile}";
+  then
+    :;
+  else
+    _PDF_DID_NOT_WORK='yes';
+    echo2 '_make_pdf(): Could not transform into pdf format. '\
+'The Postscript mode (ps) is used instead.';
+    _OPT_MODE='ps';
+    main_set_mode;
+    main_set_resources;
+    main_display;
+    exit;
+  fi;
+  obj _mp_psfile rm_file_with_debug;
+  eval ${_UNSET} _mp_psfile;
+  eval "${return_ok}";
+} # _make_pdf() of main_display()
+
+
+########################################################################
+# main (<command_line_args>*)
+#
+# The main function for groffer.
+#
+# Arguments:
+#
+main()
+{
+  func_check main '>=' 0 "$@";
+  # Do not change the sequence of the following functions!
+  landmark '13: main_init()';
+  main_init;
+  landmark '14: main_parse_MANOPT()';
+  main_parse_MANOPT;
+  landmark '15: main_parse_args()';
+  main_parse_args "$@";
+  landmark '16: main_set_mode()';
+  main_set_mode;
+  landmark '17: main_do_fileargs()';
+  main_do_fileargs;
+  landmark '18: main_set_resources()';
+  main_set_resources;
+  landmark '19: main_display()';
+  main_display;
+  eval "${return_ok}";
+}
+
+
+########################################################################
+
+main "$@";

Index: roff2.sh
===================================================================
RCS file: roff2.sh
diff -N roff2.sh
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ roff2.sh	11 Aug 2013 08:28:24 -0000	1.7
@@ -0,0 +1,339 @@
+#! /bin/sh
+
+# roff2* - transform roff files into other formats
+
+# Source file position: <groff-source>/contrib/groffer/shell/roff2.sh
+# Installed position: <prefix>/bin/roff2*
+
+# Copyright (C) 2006, 2009 Free Software Foundation, Inc.
+# Written by Bernd Warken <groff-bernd.warken-72@web.de>.
+
+# Last update: 5 Jan 2009
+
+# 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/>.
+
+########################################################################
+
+
+##############
+# echo1 (<text>*)
+#
+# Output to stdout with final line break.
+#
+# Arguments : arbitrary text including `-'.
+#
+echo1()
+{
+  cat <<EOF
+$@
+EOF
+} # echo1()
+
+
+##############
+# echo2 (<text>*)
+#
+# Output to stderr with final line break.
+#
+# Arguments : arbitrary text including `-'.
+#
+echo2()
+{
+  cat >&2 <<EOF
+$@
+EOF
+} # echo2()
+
+
+error_no_groffer='no';
+error_no_groffer() {
+  if test _"$error_no_groffer" = _yes
+  then
+    return;
+  fi;
+  error_no_groffer='yes';
+  echo2 "$name: groffer is not available.";
+}
+
+
+error_no_options='no';
+error_no_options() {
+  if test _"$error_no_options" = _yes
+  then
+    return;
+  fi;
+  error_no_groffer='yes';
+  echo2 "$name: groffer options are not allowed.";
+}
+
+
+usage_with_groffer() {
+  cat <<EOF
+usage: $Name [option]... [--] [filespec]...
+
+-h | --help     print usage information
+-v | --version  print version information
+
+All other options are arbitrary options of "groffer"; the options
+override the behavior of this program.
+
+"filespec"s are the same as in "groffer": either the names of
+existing, readable files or "-" for standard input or a search pattern
+for man pages.  No "filespec" assumes standard input automatically.
+EOF
+}
+
+usage_without_groffer() {
+  cat <<EOF
+usage: $Name [option]... [--] [filespec]...
+
+-h | --help     print usage information
+-v | --version  print version information
+
+No other options are allowed because "groffer" is not available.
+
+The only "filespec"s allowed are the names of existing, readable files
+or "-" for standard input.  No "filespec" assumes standard input
+automatically.
+EOF
+}
+
+
+where_is_prog() {
+  for p in `echo $PATH|sed "s/:/ /g"`
+  do
+    f="${p}/$1";
+    if test -f "$f" && test -x "$f"
+    then
+      echo1 "$f";
+      return;
+    fi;
+  done;
+}
+
+
+########################################################################
+
+export NULL_DEV;
+if test -c /dev/null
+then
+  NULL_DEV='/dev/null';
+else
+  NULL_DEV='NUL';
+fi;
+
+name="$(echo1 "$0" | sed 's|^.*//*\([^/]*\)$|\1|')";
+
+case "$name" in
+roff2[a-z]*)
+  mode="$(echo1 "$name" | sed 's/^roff2//')";
+  ;;
+*)
+  echo2 "wrong program name: $name";
+  exit 1;
+  ;;
+esac;
+
+groff_version="$(groff --version 2>$NULL_DEV)";
+if test $? -gt 0
+then
+  echo2 "$name error: groff does not work.";
+  exit 1;
+fi;
+groffer_version="$(groffer --version 2>$NULL_DEV)";
+if test $? -gt 0
+then
+  has_groffer='no';
+else
+  has_groffer='yes';
+fi;
+
+if test _"${has_groffer}" = _yes
+then
+  for i
+  do
+    case $i in
+    -v|--v|--ve|--ver|--vers|--versi|--versio|--version)
+      echo1 "$name in $groffer_version";
+      exit 0;
+      ;;
+    -h|--h|--he|--hel|--help)
+      usage_with_groffer;
+      exit 0;
+      ;;
+    esac;
+  done;
+  groffer --to-stdout --$mode "$@";
+else				# not has_groffer
+  reset=no;
+  double_minus=no;
+  for i
+  do
+    if test _"${reset}" = _no
+    then
+      set --;
+      reset=yes;
+    fi;
+    if test _"${double_minus}" = _yes
+    then
+      set -- "$@" "$i";
+      continue;
+    fi;
+    case "$i" in
+    --)
+      double_minus=yes;
+      continue;
+      ;;
+    -)
+      set -- "$@" '-';
+      continue;
+      ;;
+    -v|--v|--ve|--ver|--vers|--versi|--versio|--version)
+      echo1 "$name in $groff_version";
+      exit 0;
+      ;;
+    -h|--h|--he|--hel|--help)
+      usage_without_groffer;
+      exit 0;
+      ;;
+    -*)
+      error_no_groffer;
+      error_no_options;
+      ;;
+    *)
+      if test -f "$i" && test -r "$i"
+      then
+        set -- "$@" "$i";
+      else
+        error_no_groffer;
+        echo2 "$i is not an existing, readable file.";
+      fi;
+      continue;
+      ;;
+    esac;
+  done;				# for i
+
+  if test $# -eq 0
+  then
+    set -- '-';
+  fi;
+  has_stdin=no;
+  for i
+  do
+    case "$i" in
+    -)
+      has_stdin=yes;
+      break;
+      ;;
+    esac;
+  done;
+
+  if test _$has_stdin = _yes
+  then
+    umask 0077;
+    tempdir='';
+    for d in "${GROFF_TMPDIR}" "${TMPDIR}" "${TMP}" "${TEMP}" \
+           "${TEMPDIR}" "${HOME}"'/tmp' '/tmp' "${HOME}" '.'
+    do
+      if test _"$d" = _ || ! test -d "$d" || ! test -w "$d"
+      then
+        continue;
+      fi;
+      case "$d" in
+      */)
+        tempdir="$d";
+        ;;
+      *)
+        tempdir="$d"'/';
+        ;;
+      esac;
+    done;
+    if test _$tempdir = _
+    then
+      echo2 "${name}: could not find a temporary directory."
+      exit 1;
+    fi;
+    stdin=${tempdir}${name}_$$;
+    if test -e "$stdin"
+    then
+      rm -f "$stdin";
+      n=0;
+      f="${stdin}_$n";
+      while test -e "$f"
+      do
+	rm -f "$f";
+        if ! test -e "$f"
+        then
+          break;
+        fi;
+        n="$(expr $n + 1)";
+        f="${stdin}_$n";
+      done;
+      stdin="$f";
+    fi;
+    reset=no;
+    for i
+    do
+      if test _"${reset}" = _no
+      then
+        set --;
+        reset=yes;
+      fi;
+      case "$i" in
+      -)
+        set -- "$@" "$stdin";
+        ;;
+      *)
+        set -- "$@" "$i";
+        ;;
+      esac;
+    done;
+    cat>"$stdin";
+  fi;				# if has_stdin
+
+  case "$mode" in
+  x)
+    groff_options='-TX75-12 -Z';
+    ;;
+  text)
+    groff_options='-Tlatin1';
+    ;;
+  pdf)
+    ps2pdf="$(where_is_prog ps2pdf)";
+    if test _"$ps2pdf" = _
+    then
+      ps2pdf="$(where_is_prog gs)";
+      if test _"$ps2pdf" = _
+      then
+        echo2 "$name: cannot transform to pdf format.";
+        exit 1;
+      fi;
+      ps2pdf="$ps2pdf -q -dNOPAUSE -dBATCH -sDEVICE=pdfwrite '-sOutputFile=- -c save pop -f -";
+    else
+      ps2pdf="$ps2pdf -";
+    fi;
+    grog="$(grog -Tps "$@")";
+    eval $grog | ${ps2pdf};
+    exit $?;
+    ;;
+  *)
+    groff_options="-T$mode";
+    ;;
+  esac;
+  grog="$(grog $groff_options "$@")";
+  eval $grog;
+  exit $?;
+fi;				# not has_groffer


From MAILER-DAEMON Sun Aug 11 04:32:33 2013
Received: from list by lists.gnu.org with archive (Exim 4.71)
	id 1V8R4i-0006pq-Mw
	for mharc-groff-commit@gnu.org; Sun, 11 Aug 2013 04:32:32 -0400
Received: from eggs.gnu.org ([2001:4830:134:3::10]:52201)
	by lists.gnu.org with esmtp (Exim 4.71) (envelope-from <wl@gnu.org>)
	id 1V8R3K-0006jD-Tg
	for groff-commit@gnu.org; Sun, 11 Aug 2013 04:31:27 -0400
Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71)
	(envelope-from <wl@gnu.org>) id 1V8R2z-0003Ot-FQ
	for groff-commit@gnu.org; Sun, 11 Aug 2013 04:31:06 -0400
Received: from vcs.savannah.gnu.org ([140.186.70.72]:59806)
	by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from <wl@gnu.org>)
	id 1V8R2z-0003Oh-3f
	for groff-commit@gnu.org; Sun, 11 Aug 2013 04:30:45 -0400
Received: from wl by vcs.savannah.gnu.org with local (Exim 4.72)
	(envelope-from <wl@gnu.org>) id 1V8R2y-0002oL-S5
	for groff-commit@gnu.org; Sun, 11 Aug 2013 08:30:44 +0000
Date: Sun, 11 Aug 2013 08:30:44 +0000
Message-Id: <E1V8R2y-0002oL-S5@vcs.savannah.gnu.org>
To: groff-commit@gnu.org
From: Werner LEMBERG <wl@gnu.org>
X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6.x
X-Received-From: 140.186.70.72
X-Mailman-Approved-At: Sun, 11 Aug 2013 04:32:30 -0400
Subject: [Groff-commit] groff/contrib/RUNOFF ChangeLog Makefile.sub gro...
X-BeenThere: groff-commit@gnu.org
X-Mailman-Version: 2.1.14
Precedence: list
List-Id: <groff-commit.gnu.org>
List-Unsubscribe: <https://lists.gnu.org/mailman/options/groff-commit>,
	<mailto:groff-commit-request@gnu.org?subject=unsubscribe>
List-Archive: <http://lists.gnu.org/archive/html/groff-commit>
List-Post: <mailto:groff-commit@gnu.org>
List-Help: <mailto:groff-commit-request@gnu.org?subject=help>
List-Subscribe: <https://lists.gnu.org/mailman/listinfo/groff-commit>,
	<mailto:groff-commit-request@gnu.org?subject=subscribe>
X-List-Received-Date: Sun, 11 Aug 2013 08:31:27 -0000

CVSROOT:	/sources/groff
Module name:	groff
Changes by:	Werner LEMBERG <wl>	13/08/11 08:30:44

Added files:
	contrib/RUNOFF : ChangeLog Makefile.sub groff_filenames.man 
	                 runoff.man 

Log message:
	Revert accidental removal of files in previous commit.

CVSWeb URLs:
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/RUNOFF/ChangeLog?cvsroot=groff&rev=1.7
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/RUNOFF/Makefile.sub?cvsroot=groff&rev=1.3
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/RUNOFF/groff_filenames.man?cvsroot=groff&rev=1.5
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/RUNOFF/runoff.man?cvsroot=groff&rev=1.5

Patches:
Index: ChangeLog
===================================================================
RCS file: ChangeLog
diff -N ChangeLog
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ ChangeLog	11 Aug 2013 08:30:42 -0000	1.7
@@ -0,0 +1,48 @@
+2013-07-31  Bernd Warken  <groff-bernd.warken-72@web.de>
+
+	Fix RUNOFF
+
+2013-06-17  Bernd Warken  <groff-bernd.warken-72@web.de>
+
+	Remove files *~
+
+2013-06-17  Bernd Warken  <groff-bernd.warken-72@web.de>
+
+	* groff_filenames.man: Corrections.
+
+2013-06-17  Bernd Warken  <groff-bernd.warken-72@web.de>
+
+	* groff_filenames.man: Extension.
+
+2013-05-14  Bernd Warken  <groff-bernd.warken-72@web.de>
+
+	* runoff.man: Major rewrite, due to good documentation of 1974,
+	especially for text lines.
+
+2013-05-05  Bernd Warken  <groff-bernd.warken-72@web.de>
+
+	New `groff' project: `RUNOFF', which is the predecessor of `roff'.
+
+	* ChangeLog: New file for the `contrib' source.
+
+	* Makefile.sub: New `make' file, so far only for 2 man-files.
+
+	* runoff.man: New file which documents the `RUNOFF' language from
+	the 1960s up to the 1980s.
+
+	* groff_filenames.man: New file about the file name extensions
+	since `RUNOFF'.
+
+########################################################################
+
+Copyright 2013
+  Free Software Foundation, Inc.
+
+Copying and distribution of this file, with or without modification,
+are permitted in any medium without royalty provided the copyright
+notice and this notice are preserved.
+
+Local Variables:
+version-control: never
+coding: utf-8
+End:

Index: Makefile.sub
===================================================================
RCS file: Makefile.sub
diff -N Makefile.sub
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ Makefile.sub	11 Aug 2013 08:30:43 -0000	1.3
@@ -0,0 +1,41 @@
+# Makefile.sub for `RUNOFF' (integration into the `groff' source tree)
+
+# File position: <groff-source>/contrib/RUNOFF/Makefile.sub
+
+# Copyright (C) 2013
+#   Free Software Foundation, Inc.
+#
+# Written by Bernd Warken <groff-bernd.warken-72@web.de>.
+
+# Last update: 6 May 2013
+
+# This file is part of `RUNOFF' 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/>.
+
+########################################################################
+
+MAN7=\
+  runoff.n \
+  groff_filenames.n
+
+MOSTLYCLEANADD=$(MAN7)
+
+########################################################################
+# Emacs settings
+########################################################################
+#
+# Local Variables:
+# mode: makefile
+# End:

Index: groff_filenames.man
===================================================================
RCS file: groff_filenames.man
diff -N groff_filenames.man
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ groff_filenames.man	11 Aug 2013 08:30:43 -0000	1.5
@@ -0,0 +1,929 @@
+.TH GROFF_FILENAMES @MAN7EXT@ "@MDATE@" "Groff Version @VERSION@"
+.SH NAME
+groff_filenames \- filename extensions for RUNOFF, roff and groff
+.
+.\" The .SH was moved to this place in order to appease `apropos'.
+.
+.\" --------------------------------------------------------------------
+.\" Legalese
+.\" --------------------------------------------------------------------
+.
+.de authors
+This file was written by Bernd Warken
+.MT groff-bernd.warken-72@web.de
+.ME .
+..
+.
+.
+.de copying
+Copyright \(co 2013
+.RS
+.ft CI
+Free Software Foundation, Inc.
+.ft R
+.RE
+.
+.
+.P
+Last update: 5 May 2013
+.
+.
+.P
+This file is part of
+.ft CI
+groff\\fR, a free software project.
+.
+.P
+You can redistribute it and/or modify it under the terms of the
+.nh
+.ft CI
+GNU General Public License
+.ft R
+.hy
+as published by the
+.nh
+.ft CI
+Free Software Foundation (FSF)\\fR,
+.hy
+either version 3 of the License, or (at your option) any later version.
+.
+.P
+You should have received a copy of the
+.nh
+.ft CI
+GNU General Public License
+.ft R
+.hy
+along with
+.ft CI
+groff\\fR,
+see the files
+.nh
+.ft CB
+COPYING
+.ft R
+and
+.ft CB
+LICENSE
+.ft R
+.hy
+in the top directory of the
+.ft CI
+groff
+.ft R
+source package.
+.
+.P
+You can also visit
+.UR http://\\:www.gnu.org/\\:licenses
+.UE .
+..
+.
+.\" --------------------------------------------------------------------
+.\" Setup
+.\" --------------------------------------------------------------------
+.
+.ds1 Ellipsis "\&.\|.\|.\&"
+.
+.\" --------------------------------------------------------------------
+.\" Macro definitions
+.\" --------------------------------------------------------------------
+.
+.\" --------------------------------------------------------------------
+.\" .FONT (<font name> <text> [<font name> <text> ...])
+.\"
+.\" Print in different fonts: R, I, B, CR, CI, CB
+.\"
+.de1 FONT
+.  if (\\n[.$] = 0) \{\
+.	nop \&\f[]\&
+.	return
+.  \}
+.  ds result \&
+.  while (\\n[.$] >= 2) \{\
+.	as result \,\f[\\$1]\\$2\f[]
+.	shift 2
+.  \}
+.  if (\\n[.$] = 1) .as result \,\f[\\$1]
+.  nh
+.  nop \\*[result]\&
+.  hy
+..
+.
+.\" --------------------------------------------------------------------
+.\" End of macro definitions
+.\" --------------------------------------------------------------------
+.
+.
+.\" --------------------------------------------------------------------
+.SH DESCRIPTION
+.\" --------------------------------------------------------------------
+.
+Since the evolution of
+.FONT CI RUNOFF
+in the 1960s and
+.FONT CI roff
+in the 1970s, a whole bunch of filename extensions for
+.FONT CI RUNOFF
+and
+.FONT CI roff
+files were used.
+.
+.
+.P
+The
+.FONT CI roff
+extensions refer to preprocessors or macro packages.
+.
+These extensions are fixed in all
+.FONT CI Unix R \-like
+operating systems.
+.
+.
+.P
+Later on,
+.FONT CR groff
+added some more extensions.
+.
+We will now write a
+.I man\-page about these filename extensions.
+.
+.
+.\" --------------------------------------------------------------------
+.SH HISTORICAL RUNOFF LANGUAGE
+.\" --------------------------------------------------------------------
+.
+The first text language that used the
+.FONT CB .COMMAND
+structure for defining commands is said to be the
+.FONT CI MEMO
+language with programs
+.FONT CB MODIFY
+and
+.FONT CB DITTO R .
+.
+It was used at
+.FONT CR MIT
+under the operating system
+.FONT CR CTSS
+in the years 1960\-63.
+.
+But there is no open documentation for this old text system, but it
+seems that there is 1 book about it in the non-public library at
+.FONT CB MIT R .
+.
+.
+.P
+The letter
+.FONT CB m
+taken from
+.FONT CI MEMO R / MODIFY
+is still active as the option
+.FONT CB -m
+for declaring a macro package in
+.FONT CB troff R / CB nroff R .
+.
+.
+.P
+The first documented
+.FONT CB .COMMAND
+text language was
+.FONT CI RUNOFF R ,
+see
+.BR runoff (@MAN7EXT@).
+.
+.
+.\" --------------------------------------------------------------------
+.SS RUNOFF Files
+.\" --------------------------------------------------------------------
+.
+All available
+.FONT CI RUNOFF
+files are now kept in the internet at an archive on
+.FONT CI github R .
+.
+Use the command-line call
+.RS
+.EX
+.FONT CR "$ " CB "git clone git@github.com:RUNOFF/RUNOFF.git"
+.EE
+.RE
+for getting this archive (without the leading dollar).
+.
+.
+.TP
+.FONT I <name> CB .RUNOFF
+.TQ
+.FONT I <name> CB .runoff
+were the oldest naming for files in the original
+.FONT CI RUNOFF
+format of the 1960s at
+.FONT CR "IBM 7090"
+and
+.FONT CR 7094
+with the operating system
+.FONT CR CTSS R .
+.
+.
+.TP
+.FONT I <name> CB .RUN
+.TQ
+.FONT I <name> CB .run
+This abbreviation was used for
+.FONT CI RUNOFF
+files on the
+.FONT CR CTSS
+and
+.FONT CR Multics
+operating system in the 1960s and later on.
+.
+.
+.TP
+.FONT I <name> CB .RNO
+.TQ
+.FONT I <name> CB .rno
+was used for normal
+.FONT CI RUNOFF
+text files, mostly on the
+.FONT CR "PDP10\-10 archive" R .
+.
+.
+.TP
+.FONT I <name> CB .RNH
+.TQ
+.FONT I <name> CB .rnh
+was used for help files written in the
+.FONT CI RUNOFF
+language on the
+.FONT CR "PDP10\-10 archive" R .
+.
+.
+.P
+.FONT CI RUNOFF
+files with the extensions
+.FONT CB .rnh R ,
+.FONT CB .rno R ,
+and
+.FONT CB .run
+are still available in the internet at several sites, mostly at the
+.FONT CR "DEC PDP\-10 archive" R .
+.
+See
+.nh
+.UR http://\:pdp\-10.trailing\-edge.com/\:cgi-bin/\:searchbyname?name=*.rnh
+RNH
+.UE ,
+.UR http://\:pdp\-10.trailing\-edge.com/\:cgi-bin/\:searchbyname?name=*.rno
+RNO
+.UE ,
+and
+.UR http://\:pdp\-10.trailing\-edge.com/\:cgi-bin/\:searchbyname?name=*.run
+RUN
+.UE  .
+.hy
+.
+.
+.\" --------------------------------------------------------------------
+.SS Processed RUNOFF Text Files
+.\" --------------------------------------------------------------------
+.
+Files written in the
+.FONT CI RUNOFF
+language were processed by the program
+.FONT CB RUNOFF R .
+.
+Only text files were produced by this step, because graphics was not
+available in the 1960s.
+.
+Today we would use the file name extension
+.FONT CI * CB .txt R .
+.
+That was not done in these early times.
+.
+Instead the following extensions were taken:
+.
+.
+.TP
+.FONT I <name> CB .DOC
+.TQ
+.FONT I <name> CB .doc
+Very often this naming was used for the output of the
+.FONT CB RUNOFF
+program.
+.
+It contained
+.I filled
+and
+.I hyphenated
+text, suitable for tty mode.
+.
+The extension
+.FONT CB .doc
+was later on taken by
+.FONT CR Microsoft
+for their
+.IR "office files" .
+.
+.
+.TP
+.FONT I <name> CB .MEM
+.TP
+.FONT I <name> CB .mem
+This often used extension was taken for
+.FONT CI RUNOFF
+files to refer to the ancient
+.FONT CI MEMO
+language.
+.
+.
+.TP
+.FONT I <name> CB .HLP
+.TQ
+.FONT I <name> CB .hlp
+The formatting of
+.FONT CI * CB .rnh
+files (help files) was stored under this extension.
+.
+.
+.P
+This ends the description of
+.FONT CI RUNOFF .R .
+.
+All following parts of this document refer to the
+.FONT CI roff
+language and the used file name extensions thereof.
+.
+.
+.\" --------------------------------------------------------------------
+.SH COMPRESSION OF ROFF FILES
+.\" --------------------------------------------------------------------
+.
+Each
+.FONT CI roff
+file can be optionally
+.IR compressed .
+.
+That means that the
+.I total filename
+ends with a
+.IR "compressor name" .
+.
+So the whole filename has the structure
+.IR <name> \f[CB].\fP <extension>[ \f[CB].\fP <compression>] .
+.
+.
+.P
+Mostly known are the
+.I compressor extensions
+.FONT CB .Z R ,
+.FONT CB .gz R ,
+and
+.FONT CB .bzip2 R .
+.
+Relatively new is
+.FONT CB .xz R .
+.
+.
+.P
+From now on, we will ignore the
+.I compressions
+and only comment the structure
+.IB <name> . <extension>\fR.\fP
+.
+.
+.\" --------------------------------------------------------------------
+.SH MAN\-PAGES
+.\" --------------------------------------------------------------------
+.
+The
+.FONT CR Unix
+.FONT CI "manual pages"
+are shortly named
+.FONT CI "man\-pages" R .
+.
+The
+.FONT CI man\-page
+style is the best known part of the
+.FONT CI roff
+language.
+.
+.
+.P
+The extensions for
+.FONT CI man
+should be better documented.
+.
+So this is documented here.
+.
+.
+.P
+Files written in the
+.FONT CI man
+language use the following extension:
+.IB * . <section>[<group>] .
+.
+.
+.\" --------------------------------------------------------------------
+.SS Man-page Sections
+.\" --------------------------------------------------------------------
+.
+The traditional
+.FONT I "man\-page " CI <section>
+is a digit from
+.FONT CB 1
+to
+.FONT CB 8 R .
+.
+.
+.TP
+.FONT I <name> CB .1
+.TQ
+.FONT I <name> CB .2
+.TQ
+.FONT I <name> CB .3
+.TQ
+.FONT I <name> CB .4
+.TQ
+.FONT I <name> CB .5
+.TQ
+.FONT I <name> CB .6
+.TQ
+.FONT I <name> CB .7
+.TQ
+.FONT I <name> CB .8
+Classic man\-page
+.IR sections .
+.
+.
+.P
+Linux added the section number
+.FONT CB 9
+for kernel man\-pages.
+.
+.
+.TP
+.FONT I <name> CB .9
+.I Linux
+kernel man-pages
+.
+.
+.P
+In older commercial
+.FONT CI Unix
+systems, the 3 characters
+.FONT CB l R ,
+.FONT CB n R ,
+and
+.FONT CB o
+were also used as
+.I section
+names.
+.
+This is today
+.IR deprecated ,
+but there are still documents in this format.
+.
+.
+.TP
+.FONT I <name> CB .l
+.TQ
+.FONT I <name> CB .n
+.TQ
+.FONT I <name> CB .o
+.I Deprecated
+old
+.IR "man\-page sections" .
+.
+.
+.\" --------------------------------------------------------------------
+.SS Man\-page Group Extensions
+.\" --------------------------------------------------------------------
+.
+The
+.I <group>
+extension in
+.FONT CB . I <section>[<group>]
+is optional, but it can be any string of word characters.
+.
+Usually programmers use a group name that is already used, e.g.
+.FONT CB x
+for
+.FONT CI "X Window System"
+documents or
+.FONT CB tk
+to refer to the
+.FONT CI tk
+programming language.
+.
+.
+.P
+Examples:
+.
+.
+.TP
+.FONT CB groff.1
+is the man-page for
+.FONT CB groff
+in
+.I section
+.FONT CB 1
+without a
+.I group
+.
+.
+.TP
+.FONT CB xargs.1posix.gz
+is the man\-page for the program
+.FONT CB xargs
+in
+.I section
+.FONT CB 1
+and
+.I group
+.FONT CB posix R ;
+moreover it is
+.I compressed
+with
+.FONT CB gz
+.FONT R ( CB gzip R ).
+.
+.
+.TP
+.FONT CB config.5ssl
+.FONT CI "OpenSSL CONF"
+library configuration files from
+.I section
+.FONT CB 5
+with
+.I group
+.FONT CB ssl R .
+.
+.
+.TP
+.FONT CB dpkg-reconfigure.8cdebconf
+man\-page for the program
+.FONT CB dpkg\-reconfigure
+in
+.I section
+.FONT CB 8
+and
+.I group
+.FONT CB cdebconf R .
+.
+.
+.\" --------------------------------------------------------------------
+.SS Source of Man\-pages
+.\" --------------------------------------------------------------------
+.
+There are 2
+.FONT CI roff
+languages for writing man\-pages:
+.FONT CB man
+and
+.FONT CB mdoc R .
+.
+.
+.P
+The names of these 2 styles are taken as
+.I extensions
+for the source code files of man\-pages in the
+.FONT CI groff
+package.
+.
+.
+.TP
+.FONT I <name> CB .man
+.I traditional
+Unix\-like man\-page format.
+.
+.
+.TP
+.FONT I <name> CB .mdoc
+additional BSD man-page format.
+.
+.
+.TP
+.FONT I <name> CB .mandoc
+Files using this extension recognize both man\-page formats in
+.FONT CB groff
+and other processors.
+.
+.
+.TP
+FONT I <name> CB .n
+A temporary man-page file produced by a run of
+.B make
+in the
+.CB groff
+source package.
+.
+.
+.\" --------------------------------------------------------------------
+.SH TRADITIONAL TROFF EXTENSIONS
+.\" --------------------------------------------------------------------
+.
+.\" --------------------------------------------------------------------
+.SS Files Using Macro Packages
+.\" --------------------------------------------------------------------
+.
+The
+.FONT CI "classical roff"
+languages were interpreted by the
+.FONT CB "traditional troff"
+and
+.FONT CB "nroff"
+programs.
+.
+.
+.P
+There were several
+.FONT CI roff
+languages, each represented by a
+.IR "macro-package" .
+.
+Each of these provided a suitable file name
+.IR extension :
+.
+.
+.TP
+.FONT I <name> CB .me
+.FONT CI roff
+file using the
+.FONT CB me
+.IR "macro package" .
+.
+.
+.TP
+.FONT I <name> CB .mm
+.FONT CI roff
+file using the
+.FONT CB mm
+.I macro package
+.
+.
+.TP
+.FONT I <name> CB .ms
+.FONT CI roff
+file using the
+.FONT CB ms
+.I macro package
+.
+.
+.P
+All of these classical
+.FONT CI roff
+languages and their extensions are still very active in
+.BR groff .
+.
+.
+.\" --------------------------------------------------------------------
+.SS Source Code for Macro Packages (TMAC Files)
+.\" --------------------------------------------------------------------
+.
+In traditional
+.FONT CI roff
+the source code for the macro packages was stored in
+.FONT CI TMAC
+files.
+.
+Their file names have the form:
+.
+.
+.TP
+.FONT CB tmac. I <package> R ,
+.I <package>
+is the name of the macro package without the leading
+.FONT CB m
+character, wich is reintegrated by the option
+.FONT CB -m R .
+.
+.
+.P
+For example,
+.FONT CB tmac.an
+is the source for the
+.FONT CB man
+macro package.
+.
+.
+.P
+In the
+.FONT CB groff
+source, more suitable file names were integrated, see later on.
+.
+.
+.\" --------------------------------------------------------------------
+.SS Preprocessors
+.\" --------------------------------------------------------------------
+.
+Moreover, the following
+.I preprocessors
+were used as filename extension:
+.
+.
+.TP
+.FONT I <name> CB .chem
+for the integration of chemical formulas
+.
+.
+.TP
+.FONT I <name> CB .eqn
+for the mathematical use of equations
+.
+.
+.TP
+.FONT I <name> CB .pic
+graphical tool
+.
+.
+.TP
+.FONT I <name> CB .tbl
+for tables with
+.FONT CI tbl
+.
+.
+.TP
+.FONT I <name> CB .ref
+for files using the
+.FONT CB prefer
+.I preprocesor
+.
+.
+.\" --------------------------------------------------------------------
+.SS Classical Roff Files
+.\" --------------------------------------------------------------------
+.
+.TP
+.FONT I <name> CB .t
+.TQ
+.FONT I <name> CB .tr
+for files using the
+.FONT CI roff
+language of any kind
+.
+.
+.\" --------------------------------------------------------------------
+.SH NEW GROFF EXTENSIONS
+.\" --------------------------------------------------------------------
+.
+.FONT CI "GNU roff"
+.FONT CB groff
+is the actual
+.FONT CI roff
+standard, both for classical
+.FONT CI roff
+and new extensions..
+.
+So even the used new extensions in the source code should be regarded
+as actual standard.
+.
+The following extensions are used instead of classical
+.FONT CB .t
+or
+.FONT CB .tr R :
+.
+.
+.TP
+.FONT I <name> CB .groff
+.TQ
+.FONT I <name> CB .roff
+general ending for files using the
+.FONT CI groff
+.I language
+.
+.
+.\" --------------------------------------------------------------------
+.SS Source Code for Macro Packages (TMAC Files)
+.\" --------------------------------------------------------------------
+.
+As the classical form
+.FONT CB tmac. I <package_without_m> R ,
+of the
+.FONT CI TMAC
+file names is quite strange,
+.
+CI groff
+added the following structures:
+.
+.
+.TP
+.FONT I <package_without_m> CB .tmac
+.TQ
+.FONT CB m I <package> CB .tmac
+.TQ
+.FONT CB groff_m I <package> CB .tmac
+.
+.
+.\" --------------------------------------------------------------------
+.SS Files Using new Macro Packages
+.\" --------------------------------------------------------------------
+.
+.FONT CI Groff
+uses the following new macro packages:
+.
+.
+.TP
+.FONT I <name> CB .mmse
+file with swedish
+.FONT CB mm
+.I makros
+for
+.B groff
+.
+.
+.TP
+.FONT I <name> CB .mom
+files written in the
+.FONT CI "groff macro package"
+.FONT CB mom
+.
+.
+.TP
+.FONT I <name> CB .www
+files written in
+.FONT CB HTML R \-like
+.FONT CI groff
+.IR macros .
+.
+.
+.\" --------------------------------------------------------------------
+.SS Preprocessors and Postprocessors
+.\" --------------------------------------------------------------------
+.
+.TP
+.FONT I <name> CB .hbtbl
+a new
+.FONT CI tbl
+format.
+.
+See
+.BR groff_hdtbl (@MAN7EXT@).
+.
+.
+.TP
+.FONT I <name> CB .grap
+files written for the graphical
+.FONT CB grap
+processor.
+.
+.
+.TP
+.FONT I <name> CB .grn
+for including
+.BR gremlin (@MAN1EXT@),
+pictures, see
+.BR grn (@MAN1EXT@).
+.
+.
+.TP
+.FONT I <name> CB .pdfroff
+transform this file with
+.FONT CB pdfroff
+of the
+.FONT CI groff
+system
+.
+.
+.\" --------------------------------------------------------------------
+.SH "SEE ALSO"
+.\" --------------------------------------------------------------------
+.
+.
+.TP
+History and future
+.BR runoff (@MAN7EXT@),
+.BR roff (@MAN7EXT@),
+.BR man\-pages (@MAN7EXT@),
+.BR groff_diff (@MAN7EXT@),
+.BR groff (@MAN7EXT@)
+.
+.
+.TP
+.I Compression
+.BR uncompress (1posix),
+.BR gzip2 (@MAN1EXT@),
+.BR bzip2 (@MAN1EXT@),
+.BR xz (@MAN1EXT@)
+.
+.
+.\" --------------------------------------------------------------------
+.SH "AUTHORS"
+.\" --------------------------------------------------------------------
+.
+.authors
+.
+.
+.\" --------------------------------------------------------------------
+.SH "COPYING"
+.\" --------------------------------------------------------------------
+.
+.copying
+.
+.
+.\" --------------------------------------------------------------------
+.\" Emacs settings
+.\" --------------------------------------------------------------------
+.
+.\" Local Variables:
+.\" mode: nroff
+.\" End:

Index: runoff.man
===================================================================
RCS file: runoff.man
diff -N runoff.man
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ runoff.man	11 Aug 2013 08:30:43 -0000	1.5
@@ -0,0 +1,11247 @@
+.\" t
+.TH RUNOFF @MAN7EXT@ "@MDATE@" "Groff Version @VERSION@"
+.SH NAME
+RUNOFF \[em] the predecessor of the \f[CI]roff\f[] langugage
+.
+.\" The .SH was moved to this place in order to appease `apropos'.
+.
+.\" --------------------------------------------------------------------
+.\" Legalese
+.\" --------------------------------------------------------------------
+.
+.de authors
+This file was written by Bernd Warken
+.MT groff\-bernd.warken\-72@web.de
+.ME .
+..
+.
+.
+.de copying
+Copyright \(co 2013
+.RS
+.ft CI
+Free Software Foundation, Inc.
+.ft R
+.RE
+.
+.P
+Last update: 14 May 2013
+.
+.P
+This file is part of
+.ft CI
+groff\\f[R], a free software project.
+.
+.P
+You can redistribute it and/or modify it under the terms of the
+.nh
+.ft CI
+GNU General Public License
+.ft R
+.hy
+as published by the
+.nh
+.ft CI
+Free Software Foundation (FSF)\\f[R],
+.hy
+either version 3 of the License, or (at your option) any later version.
+.
+.P
+You should have received a copy of the
+.nh
+.ft CI
+GNU General Public License
+.ft R
+.hy
+along with
+.ft CI
+groff\\f[R],
+see the files
+.nh
+.ft CB
+COPYING
+.ft R
+and
+.ft CB
+LICENSE
+.ft R
+.hy
+in the top directory of the
+.ft CI
+groff
+.ft R
+source package.
+.
+.P
+You can also visit
+.UR http://\\:www.gnu.org/\\:licenses
+.UE .
+..
+.
+.
+.\" --------------------------------------------------------------------
+.\" Setup
+.\" --------------------------------------------------------------------
+.
+.ds1 Ellipsis "\&.\|.\|.\&\"
+.
+.
+.\" --------------------------------------------------------------------
+.\" Macro definitions
+.\" --------------------------------------------------------------------
+.
+.\" --------------------------------------------------------------------
+.\" .FONT (<font name> <text> [<font name> <text> ...])
+.\"
+.\" Print in different fonts: R, I, B, CR, CI, CB
+.\"
+.de1 FONT
+.  if (\\n[.$] = 0) \{\
+.	nop \&\f[P]\&
+.	return
+.  \}
+.  ds result \&
+.  while (\\n[.$] >= 2) \{\
+.	as result \,\f[\\$1]\\$2
+.	if !"\\$1"P" .as result \f[P]
+.	shift 2
+.  \}
+.  if (\\n[.$] = 1) .as result \,\f[\\$1]
+.  nh
+.  nop \\*[result]\&
+.  hy
+..
+.
+.\" --------------------------------------------------------------------
+.\" .Topic  ([<indent>])
+.\"
+.\" A bulleted paragraph
+.\"
+.de Topic
+.  ie \\n[.$]=0 \
+.    ds @indent 2m\"
+.  el \
+.    ds @indent \\$1\"
+.  IP \[bu] \\*[@indent]
+.  rm @indent
+..
+.
+.\" --------------------------------------------------------------------
+.\" .UL (<text to underline> [<append>])
+.\"
+.\" Underline $1 and append $2 without underline
+.\"
+.de UL
+.  if t \}\
+.    nop \Z'\\$1'\v'.25m'\D'l \w'\\$1'u 0'\v'-.25m'\\$2
+.    return
+.  \}
+.  ul 1
+\\$1\c
+\\$2
+..
+.
+.\" --------------------------------------------------------------------
+.\" .TableHDTBL - table using hdtbl for troff
+.\"
+.de1 TableHDTBL eHDTBL
+.
+This list of commands is a table over 5 pages.
+.
+.
+.bp
+.
+.\" use groff_hdtbl
+.\" mso hdtbl.tmac
+.
+.
+.\" --------------------------------------------------------------------
+.\" hdtbl Table: List of Commands (Alphabetical) page 1/5
+.\" --------------------------------------------------------------------
+.
+.hy
+.fi
+.
+.TBL cols=3
+.TR hl=d ".TH colspan=2 Command or Abbreviation" ".TH Related Commands"
+.\" TR hl=d ".TD colspan=2 Command or Abbreviation" ".TD Related Commands"
+.
+.
+.nf
+.nh
+.
+.
+.\" A ==================================================================
+.
+.TR
+.TD
+.FONT CB ".AP"
+.TD
+.FONT R "(=" CB ".AUTOPARAGRAPH" R ")"
+.TD
+.
+.
+.TR
+.TD
+.FONT CB ".APPENDIX " I "text"
+.TD
+.FONT R "(=" CB ".AX" R ")"
+.TD
+.FONT CB ".NUMBER APPENDIX " I "a"
+.
+.TR
+.TD
+.FONT CB ".AX"
+.TD
+.FONT R "(=" CB ".APPENDIX" R ")"
+.TD
+.
+.TR hl=d
+.TD
+.FONT CB ".AUTOPARAGRAPH"
+.TD
+.FONT R "(=" CB ".AP" R ")"
+.TD
+.FONT CB ".NOAUTOPARAGRAPH"
+.br
+.FONT R "(" CB ".NAP" R ")"
+.
+.\" B ==================================================================
+.
+.TR
+.TD
+.FONT CB ".B"
+.TD
+.FONT R "(=" CB ".BLANK" R ")"
+.TD
+.
+.TR
+.TD
+.FONT CB ".BLANK" I " n"
+.TD
+.FONT  R "(=" CB ".B" R ")"
+.TD
+.FONT CB ".SKIP" I " n"
+.br
+.FONT R "(" CB ".S" R ")"
+.
+.TR
+.TD
+.FONT CB ".BR"
+.TD
+.FONT R "(=" CB ".BREAK" R ")"
+.TD
+.
+.TR hl=d
+.TD
+.FONT CB ".BREAK"
+.TD
+.FONT R "(" CB ".BR" R ")"
+.TD
+.
+.
+.\" C ==================================================================
+.
+.TR
+.TD
+.FONT CB ".C"
+.TD
+.FONT R "(=" CB ".CENTRE" R ")"
+.TD
+.
+.TR
+.TD
+.FONT CB ".CENTER"
+.TD
+.FONT R "(=" CB ".CENTRE" R ")"
+.TD
+.
+.TR
+.TD
+.FONT CB ".CENTRE" I " n" CB ";" I "text"
+.TD
+.FONT R "(=" CB ".C" R ")"
+.TD
+.
+.TR
+.TD
+.FONT CB ".CH"
+.TD
+.FONT R "(=" CB ".CHAPTER" R ")"
+.TD
+.
+.TR
+.TD
+.FONT CB ".CHAPTER" I " text"
+.TD
+.FONT R "(=" CB ".CH" R ")"
+.TD
+.FONT CB ".NUMBER CHAPTER" I " n"
+.
+.TR hl=d
+.TD
+.FONT CB ".COMMENT" I " text"
+.TD
+.TD
+.
+.
+.\" D ==================================================================
+.
+.TR
+.TD
+.FONT CB ".DO INDEX" I " text"
+.TD
+.FONT R "(=" CB ".DX" R ")"
+.TD
+.FONT CB ".PRINT INDEX"
+.br
+.FONT R "(" CB ".PX" R ")"
+.
+.TR hl=d
+.TD
+.FONT CB ".DX"
+.TD
+.FONT R "(=" CB ".DO INDEX" R ")"
+.TD
+.
+.
+.\" E ==================================================================
+.
+.TR
+.TD
+.FONT CB ".ELS"
+.TD
+.FONT R "(=" CB ".END LIST" R ")"
+.TD
+.
+.TR
+.TD
+.FONT CB ".EN"
+.TD
+.FONT R "(=" CB ".END NOTE" R ")"
+.TD
+.
+.TR
+.TD
+.FONT CB ".END LIST"
+.TD
+.FONT R "(=" CB ".ELS" R ")"
+.TD
+.FONT CB ".LIST " I "n"
+.br
+.FONT R "(" CB ".LS" R ")"
+.
+.TR
+.TD
+.FONT CB ".END LITERAL"
+.TD
+.FONT R "(=" CB ".ELI" R ")"
+.TD
+.FONT CB ".LITERAL"
+.FONT R "(" CB ".LIT" R ")"
+.
+.TR
+.TD
+.FONT CB ".END NOTE"
+.TD
+.FONT R "(=" CB ".EN" R ")"
+.TD
+.FONT CB ".NOTE " I "text"
+.br
+.FONT R "(" CB ".NT" R ")"
+.
+.TR hl=d
+.TD
+.FONT CB ".END SUBPAGE"
+.TD
+.TD
+.FONT CB ".SUBPAGE"
+.
+.
+.\" F ==================================================================
+.
+.TR
+.TD
+.FONT CB ".F"
+.TD
+.FONT R "(=" CB ".FILL" R ")"
+.TD
+.
+.TR
+.TD
+.FONT CB ".FG"
+.TD
+.FONT R "(=" CB ".FIGURE" R ")"
+.TD
+.
+.
+.ETB
+.
+.
+.bp
+.\" --------------------------------------------------------------------
+.\" hdtbl Table: List of Commands (Alphabetical) page 2/5
+.\" --------------------------------------------------------------------
+.
+.fi
+.hy
+.
+.TBL cols=3
+.TR hl=d ".TH colspan=2 Command or Abbreviation" ".TH Related Commands"
+.
+.
+.nf
+.nh
+.
+.
+.\" F2 =================================================================
+.
+.TR
+.TD
+.FONT CB ".FIGURE" I " n"
+.TD
+.FONT R "(=" CB ".FG" R ")"
+.TD
+.
+.TR
+.TD
+.FONT CB ".FILL"
+.TD
+.FONT R "(=" CB ".F" R ")"
+.TD
+.FONT CB ".NOFILL"
+.br
+.FONT R "(" CB ".NF" R ")"
+.
+.TR
+.TD
+.FONT CB ".FIRST TITLE" I " text"
+.TD
+.FONT R "(=" CB ".FT" R ")"
+.TD
+.FONT CB ".TITLE" I " text"
+.
+.TR
+.TD
+.FONT CB ".FLAGS CAPITALIZE"
+.TD
+.FONT R "(=" CB ".FL CAPITALIZE" R ")"
+.TD
+.FONT CB ".NO FLAGS CAPITALIZE"
+.br
+.FONT R "(" CB ".NFL" R ")"
+.
+.TR
+.TD
+.FONT CB ".FLAGS HYPHENATE"
+.TD
+.FONT R "(=" CB ".FL HYPHENATE" R ")"
+.TD
+.FONT CB ".NO FLAGS HYPHENATE"
+.br
+.FONT R "(" CB ".NFH" R ")"
+.
+.TR
+.TD
+.FONT CB ".FN"
+.TD
+.FONT R "(=" CB ".FOOTNOTE" R ")"
+.TD
+.
+.TR
+.TD
+.FONT CB ".FOOTNOTE" I " n"
+.TD
+.FONT R "(=" CB ".FN" R ")"
+.TD
+.
+.TR hl=d
+.TD
+.FONT CB ".FT"
+.TD
+.FONT R "(=" CB ".FIRST TITLE" R ")"
+.TD
+.
+.
+.\" G ==================================================================
+.\" H ==================================================================
+.
+.TR
+.TD
+.FONT CB ".HD"
+.TD
+.FONT R "(=" CB ".HEADER" R ")"
+.TD
+.
+.TR
+.TD
+.FONT CB ".HEADER" I " arg"
+.br
+.FONT R "[" I "arg" R "=" CB "UPPER" R ", " CB "LOWER" R ", or " CB "MIXED]"
+.TD
+.FONT R "(=" CB ".HD" R ")"
+.TD
+.FONT CB ".NOHEADER "
+.br
+.FONT R "(" CB ".NHD" R ")"
+.
+.TR
+.TD
+.FONT CB ".HEADER LEVEL" I " n text"
+.TD
+.FONT R "(=" CB ".HL" R ")"
+.TD
+.
+.TR
+.TD
+.FONT CB ".HL"
+.TD
+.FONT R "(=" CB ".HEADER LEVEL" R ")"
+.TD
+.
+.TR
+.TD
+.FONT CB ".HY"
+.TD
+.FONT R "(=" CB ".HYPHENATION" R ")"
+.TD
+.
+.TR hl=d
+.TD
+.FONT CB ".HYPHENATION"
+.TD
+.FONT R "(=" CB ".HY" R ")"
+.TD
+.FONT CB ".NO HYPHENATION"
+.br
+.FONT R "(" CB ".NHY" R ")"
+.
+.
+.\" I ==================================================================
+.
+.TR
+.TD
+.FONT CB ".I"
+.TD
+.FONT R "(=" CB ".INDENT" R ")"
+.TD
+.
+.TR
+.TD
+.FONT CB ".INDENT" I " n"
+.TD
+.FONT R "(=" CB ".I" R ")"
+.TD
+.
+.TR hl=d
+.TD
+.FONT CB ".INDEX" I " text"
+.TD
+.FONT R "(=" CB ".X" R ")"
+.TD
+.
+.
+.\" J ==================================================================
+.
+.TR
+.TD
+.FONT CB ".J"
+.TD
+.FONT R "(=" CB ".JUSTIFY" R ")"
+.TD
+.
+.TR hl=d
+.TD
+.FONT CB ".JUSTIFY"
+.TD
+.FONT R "(=" CB ".J" R ")"
+.TD
+.FONT CB ".NOJUSTIFY"
+.br
+.FONT R "(" CB ".NJ" R ")"
+.
+.
+.\" K ==================================================================
+.\" L ==================================================================
+.
+.TR
+.TD
+.FONT CB ".LC"
+.TD
+.FONT R "(=" CB ".LOWER CASE" R ")"
+.TD
+.
+.TR
+.TD
+.FONT CB ".LE"
+.TD
+.FONT R "(=" CB ".LIST ELEMENT" R ")"
+.TD
+.
+.TR
+.TD
+.FONT CB ".LEFT MARGIN" I " n"
+.TD
+.FONT R "(=" CB ".LM" R ")"
+.TD
+.FONT CB ".RIGHT MARGIN" I " n"
+.br
+.FONT R "(" CB ".RM" R ")"
+.
+.TR
+.TD
+.FONT CB ".LIST" I " n"
+.TD
+.FONT R "(=" CB ".LS" R ")"
+.TD
+.FONT CB ".END LIST"
+.br
+.FONT R "(" CB ".ELS" R ")"
+.
+.ETB
+.
+.
+.bp
+.\" --------------------------------------------------------------------
+.\" hdtbl Table: List of Commands (Alphabetical) page 3/5
+.\" --------------------------------------------------------------------
+.
+.fi
+.hy
+.
+.TBL cols=3
+.TR hl=d ".TH colspan=2 Command or Abbreviation" ".TH Related Commands"
+.
+.
+.nf
+.nh
+.
+.\" L2 =================================================================
+.
+.TR
+.TD
+.FONT CB ".LIST ELEMENT;" I "text"
+.TD
+.FONT R "(=" CB ".LE" R ")"
+.TD
+.FONT CB ".END LIST"
+.br
+.FONT R "(" CB ".ELS" R ")"
+.
+.TR
+.TD
+.FONT CB ".LIT"
+.TD
+.FONT R "(=" CB ".LITERAL" R ")"
+.TD
+.
+.TR
+.TD
+.FONT CB ".LITERAL"
+.TD
+.FONT R "(=" CB .LIT R ")"
+.TD
+.FONT CB ".END LITERAL"
+.FONT R ( CB .ELI R )
+.
+.TR
+.TD
+.FONT CB ".LM"
+.TD
+.FONT R "(=" CB ".LEFT MARGIN" R ")"
+.TD
+.
+.TR
+.TD
+.FONT CB ".LOWER CASE"
+.TD
+.FONT R "(=" CB ".LC" R ")"
+.TD
+.FONT CB ".UPPER CASE"
+.br
+.FONT R "(" CB ".UC" R ")"
+.
+.TR hl=d
+.TD
+.FONT CB ".LS"
+.TD
+.FONT R "(=" CB ".LIST" R ")"
+.TD
+.
+.
+.\" M ==================================================================
+.\" N ==================================================================
+.
+.TR
+.TD
+.FONT CB ".NAP"
+.TD
+.FONT R "(=" CB ".NOAUTOPARAGRAPH" R ")"
+.TD
+.
+.TR
+.TD
+.FONT CB ".NF"
+.TD
+.FONT R "(=" CB ".NOFILL" R ")"
+.TD
+.
+.TR
+.TD
+.FONT CB ".NFC"
+.TD
+.FONT R "(=" CB ".NO FLAGS CAPITALIZE" R ")"
+.TD
+.
+.TR
+.TD
+.FONT CB ".NFH"
+.TD
+.FONT R "(=" CB ".NO FLAGS HYPHENATE" R ")"
+.TD
+.
+.TR
+.TD
+.FONT CB ".NFL"
+.TD
+.FONT R "(=" CB ".NO FLAGS CAPITALIZE"
+.br
+and
+.br
+.FONT CB ".NO FLAGS HYPHENATE" R ")"
+.TD
+.
+.TR
+.TD
+.FONT CB ".NHD"
+.TD
+.FONT R "(=" CB ".NO HEADER" R ")"
+.TD
+.
+.TR
+.TD
+.FONT CB ".NHY"
+.TD
+.FONT R "(=" CB ".NO HYPHENATION" R ")"
+.TD
+.
+.TR
+.TD
+.FONT CB ".NJ"
+.TD
+.FONT R "(=" CB ".NO JUSTIFY" R ")"
+.TD
+.
+.TR
+.TD
+.FONT CB ".NM"
+.TD
+.FONT R "(=" CB ".NUMBER" R ")"
+.TD
+.
+.TR
+.TD
+.FONT CB ".NNM"
+.TD
+.FONT R "(=" CB ".NO NUMBER" R ")"
+.TD
+.
+.TR
+.TD
+.FONT CB ".NOAUTOPARAGRAPH"
+.TD
+.FONT R "(=" CB ".NAP" R ")"
+.TD
+.FONT CB ".AUTOPARAGRAPH"
+.br
+.FONT R "(" CB ".AP" R ")"
+.br
+.FONT CB ".PARAGRAPH" I " h" CB "," I "v" CB "," I "t"
+.br
+.FONT R "(" CB ".P" R ")"
+.
+.TR
+.TD
+.FONT CB ".NOFILL"
+.TD
+.FONT R "(=" CB ".NF" R ")"
+.TD
+.FONT CB ".FILL"
+.br
+.FONT R "(" CB ".F" R ")"
+.
+.TR
+.TD
+.FONT CB ".NO FLAGS CAPITALIZE"
+.TD
+.FONT R "(=" CB ".NFL" R ")"
+.TD
+.FONT CB ".FLAGS CAPITALIZE"
+.br
+.FONT R ( CB ".FL CAPITALIZE" R )
+.
+.TR
+.TD
+.FONT CB ".NO FLAGS HYPHENATE"
+.TD
+.FONT R "(=" CB ".NFH" R ")"
+.TD
+.FONT CB ".FLAGS HYPHENATE"
+.
+.TR
+.TD
+.FONT CB ".NOHEADER"
+.TD
+.FONT R "(=" CB ".NHD" R ")"
+.TD
+.FONT CB ".HEADER " I "arg"
+.br
+.FONT R "(" CB ".HD" R ")"
+.
+.ETB
+.
+.
+.bp
+.\" --------------------------------------------------------------------
+.\" hdtbl Table: List of Commands (Alphabetical) page 4/5
+.\" --------------------------------------------------------------------
+.
+.fi
+.hy
+.
+.TBL cols=3
+.TR hl=d ".TH colspan=2 Command or Abbreviation" ".TH Related Commands"
+.
+.
+.nf
+.nh
+.
+.\" N2 =================================================================
+.
+.TR
+.TD
+.FONT CB ".NO HYPHENATION"
+.TD
+.FONT R "(=" CB ".NHY" R ")"
+.TD
+.FONT CB ".HYPHENATION"
+.br
+.FONT R "(" CB ".HY" R ")"
+.
+.TR
+.TD
+.FONT CB ".NOJUSTIFY"
+.TD
+.FONT R "(=" CB ".NJ" R ")"
+.TD
+.FONT CB ".JUSTIFY"
+.br
+.FONT R "(" CB ".J" R ")"
+.
+.TR
+.TD
+.FONT CB ".NONUMBER"
+.TD
+.FONT R "(=" CB ".NNM" R ")"
+.TD
+.FONT CB ".NUMBER " I "n"
+.br
+.FONT R "(" CB ".NM" R ")"
+.
+.TR
+.TD
+.FONT CB ".NOPERIOD"
+.TD
+.FONT R "(=" CB ".NPR" R ")"
+.TD
+.FONT CB ".PERIOD"
+.br
+.FONT R "(" CB ".PR" R ")"
+.
+.TR
+.TD
+.FONT CB ".NOTE" I " text"
+.TD
+.FONT R "(=" CB ".NT" R ")"
+.TD
+.FONT CB ".END NOTE"
+.br
+.FONT R "(" CB ".EN" R ")"
+.
+.TR
+.TD
+.FONT CB ".NPR"
+.TD
+.FONT R "(=" CB ".NO PERIOD" R ")"
+.TD
+.
+.TR
+.TD
+.FONT CB ".NT"
+.TD
+.FONT R "(=" CB ".NOTE" R ")"
+.TD
+.
+.TR
+.TD
+.FONT CB ".NUMBER APPENDIX" I " a"
+.TD
+.TD
+.FONT CB ".APPENDIX" I " text"
+.
+.TR hl=d
+.TD
+.FONT CB ".NUMBER CHAPTER " I "n"
+.TD
+.TD
+.FONT CB ".CHAPTER text"
+.
+.
+.\" P ==================================================================
+.
+.TR
+.TD
+.FONT CB ".P"
+.TD
+.FONT R "(=" CB ".PARAGRAPH" R ")"
+.TD
+.
+.TR
+.TD
+.FONT CB ".PAGE"
+.TD
+.FONT R "(=" CB ".PG" R ")"
+.TD
+.
+.TR
+.TD
+.FONT CB ".PAGE SIZE"
+.TD
+.FONT R "(=" CB ".PAPER SIZE" R ")"
+.TD
+.
+.TR
+.TD
+.FONT CB ".PAPER SIZE" I " v" CB "," I "h"
+.br
+.FONT R "(=" CB ".PS" R ", " CB ".PAGE SIZE" R ")"
+.TD
+.TD
+.
+.TR
+.TD
+.FONT CB ".PERIOD"
+.TD
+.FONT R "(=" CB ".PR" R ")"
+.TD
+.FONT CB ".NOPERIOD"
+.br
+.FONT R "(" CB ".NPR" R ")"
+.
+.TR
+.TD
+.FONT CB ".PG"
+.TD
+.FONT R "(=" CB ".PAGE" R ")"
+.TD
+.
+.TR
+.TD
+.FONT CB ".PITCH"
+.TD
+.FONT R "(=" CB ".PIT" R ")"
+.TD
+.
+.TR
+.TD
+.FONT CB ".PRINT INDEX"
+.TD
+.FONT R "(=" CB ".PX" R ")"
+.TD
+.FONT CB ".DO INDEX" I " text"
+.FONT R "(" CB ".DX" R ")"
+.
+.TR
+.TD
+.FONT CB ".PS"
+.TD
+.FONT R "(=" CB ".PAPER SIZE" R ")"
+.TD
+.
+.TR hl=d
+.TD
+.FONT CB ".PX"
+.TD
+.FONT R "(=" CB ".PRINT INDEX" R ")"
+.TD
+.
+.
+.\" R ==================================================================
+.
+.TR
+.TD
+.FONT CB ".RIGHT MARGIN " I "n"
+.TD
+.FONT R "(=" CB ".RM" R ")"
+.TD
+.
+.TR hl=d
+.TD
+.FONT CB ".RM"
+.TD
+.FONT R "(=" CB ".RIGHT MARGIN" R ")"
+.TD
+.
+.
+.\" S ==================================================================
+.
+.TR
+.TD
+.FONT CB ".S"
+.TD
+.FONT R "(=" CB ".SKIP" R ")"
+.TD
+.
+.ETB
+.
+.
+.bp
+.\" --------------------------------------------------------------------
+.\" hdtbl Table: List of Commands (Alphabetical) page 5/5
+.\" --------------------------------------------------------------------
+.
+.fi
+.hy
+.
+.TBL cols=3
+.TR hl=d ".TH colspan=2 Command or Abbreviation" ".TH Related Commands"
+.
+.
+.nf
+.nh
+.
+.\" S2 =================================================================
+.
+.TR
+.TD
+.FONT CB ".SD"
+.TD
+.FONT R "(=" CB ".STANDARD" R ")"
+.TD
+.
+.TR
+.TD
+.FONT CB ".SKIP" I " n"
+.TD
+.FONT R "(=" CB ".S" R ")"
+.TD
+.FONT CB ".BLANK" I " n"
+.br
+.FONT R "(" CB ".B" R ")"
+.
+.TR
+.TD
+.FONT CB ".SP"
+.TD
+.FONT R "(=" CB ".SPACING" R ")"
+.TD
+.
+.TR
+.TD
+.FONT CB ".SPACING" I " n"
+.TD
+.FONT R "(=" CB ".SP" R ")"
+.TD
+.
+.TR
+.TD
+.FONT CB ".ST"
+.TD
+.FONT R "(=" CB ".SUBTITLE" R ")"
+.TD
+.
+.TR
+.TD
+.FONT CB ".SUBPAGE"
+.TD
+.TD
+.FONT CB ".END SUBPAGE"
+.
+.TR hl=d
+.TD
+.FONT CB ".SUBTITLE" I " text"
+.TD
+.FONT R "(=" CB ".ST" R ")"
+.TD
+.
+.
+.\" T ==================================================================
+.
+.TR
+.TD
+.FONT CB ".T"
+.TD
+.FONT R "(=" CB ".TITLE" R ")"
+.TD
+.
+.TR
+.TD
+.FONT CB ".TAB STOPS" I " n,n, \*[Ellipsis] ,n"
+.TD
+.FONT R "(=" CB ".TS" R ")"
+.TD
+.
+.TR
+.TD
+.FONT CB ".TEST PAGE" I " n"
+.TD
+.FONT R "(=" CB ".TP" R ")"
+.TD
+.
+.TR
+.TD
+.FONT CB ".TITLE" I " text"
+.TD
+.FONT R "(=" CB ".T" R ")"
+.TD
+.
+.TR
+.TD
+.FONT CB ".TP"
+.TD
+.FONT R "(=" CB ".TEST PAGE" R ")"
+.TD
+.
+.TR hl=d
+.TD
+.FONT CB ".TS"
+.TD
+.FONT R "(=" CB ".TAB STOPS" R ")"
+.TD
+.
+.
+\" U ==================================================================
+.
+.TR
+.TD
+.FONT CB ".UC"
+.TD
+.FONT R "(=" CB ".UPPER CASE" R ")"
+.TD
+.
+.TR
+.TD
+.FONT CB ".UPPER CASE"
+.TD
+.FONT R "(=" CB ".UC" R ")"
+.TD
+.FONT CB ".LOWER CASE"
+.br
+.FONT R "(" CB ".LC" R ")"
+.
+.
+\" U ==================================================================
+.
+.TR
+.TD
+.FONT CB ".X"
+.TD
+.FONT R "(=" CB ".INDEX" R ")"
+.TD
+.
+.
+.ETB
+.
+.
+.fi
+.hy
+.
+.bp
+.
+.
+.eHDTBL
+.\" end of .de1 TableHDTBL
+.\" --------------------------------------------------------------------
+.
+.
+.\" --------------------------------------------------------------------
+.\" End of macro definitions.
+.\" --------------------------------------------------------------------
+.
+.
+.\" --------------------------------------------------------------------
+.SH DESCRIPTION
+..\" --------------------------------------------------------------------
+.
+.FONT CI RUNOFF
+is a language for creating documents.
+.
+This was the first document language at all.
+.
+It is the ancestor of
+.FONT CI roff R .
+.
+.
+.P
+See section
+.FONT CB "SEE ALSO"
+at the end of this document for internet addresses.
+.
+.
+.\" --------------------------------------------------------------------
+.SH HISTORY
+.\" --------------------------------------------------------------------
+.
+The first text processing language was
+.FONT CI DITTO
+at the
+.FONT CI CTSS
+computer at
+.FONT CI MIT R .
+.
+But now there isn't any documentation about the corresponding programs
+nor files written in the
+.FONT CI DITTO
+language.
+.
+.
+.P
+So
+.FONT CI RUNOFF
+can regarded as the oldest text processing language, because there is
+enough documentation and files written inb this language.
+.
+.
+.P
+.FONT CI RUNOFF
+was built by
+.FONT CI "Jerome H. Saltzer"
+in 1963 and 1964 at
+.FONT CR \%MIT
+using the operating system
+.FONT CR CTSS
+on computers
+.FONT CR "IBM 7090"
+and 
+.FONT CR 7094
+at the
+.FONT CI MIT
+in Boston.
+.
+.
+.P
+At the
+.FONT CI Unix
+operating system, the
+.FONT CI RUNOFF
+language was the base for the generation of the text generator language
+.IR \%roff .
+.
+Today
+.I \%roff
+is maintained by
+.IR \%GNU\~troff ,
+the program 
+.BR \%groff (@MAN1EXT@)
+and its language
+.BR \%groff (@MAN7EXT@).
+.
+So
+.FONT CI RUNOFF
+is the ancestor for
+.IR \%groff .
+.
+.
+.\" --------------------------------------------------------------------
+.SS Old RUNOFF Documentation
+.\" --------------------------------------------------------------------
+.
+Look at section
+.FONT CR "SEE ALSO"
+for the internet connections to these documents.
+.
+.
+.P
+All started at the operating system called
+.I \%CTSS
+in the early 1960s at the
+.IR \%MIT .
+.
+.
+.P
+There was a first documentation in 1964 by
+.FONT CI Saltzer
+who created the
+.FONT CI RUNOFF
+language.
+.
+He published a documentation titled
+.FONT CI "Jerome H. Saltzer \(em TYPSET and RUNOFF, Memorandum editor and \
+type\-out commands" R .
+.
+.
+.P
+In december 1966,
+.FONT CI Saltzer
+published an updated documentation
+.FONT CI "Jerome H. Saltzer \(em Manuscript Typing and Editing" R .
+.
+This article can be regarded as the documentation of the original
+.FONT CI RUNOFF R .
+.
+.
+.P
+Moreover
+.FONT CI Saltzer
+published another document in 1965.
+.
+It's titled
+.FONT CI "Jerome H. Saltzer \(em Experimental Additions to the RUNOFF Command"
+.
+We integrate the
+.I "control words"
+in this documentation in a section about
+.I \%Experimental
+.IR \%Additions .
+.
+.
+.P
+In later years, many people worked with the operating system
+.FONT CI Multics R .
+.
+There
+.FONT CI RUNOFF
+was further developed.
+.
+.
+.P
+There is a good documentation of 1973 titled
+.FONT CI "Larry Barnes \(em RUNOFF: \
+A Program for the Preparation of Documents" R .
+.
+The
+.FONT CI RUNOFF
+was here further developed.
+.
+We use this document as well.
+.
+.
+.P
+Another good document comes from 1974 at the
+.FONT CR "DEC RSTS" R .
+.
+It is titled
+.FONT CI "RUNOFF User's Guide" R .
+.
+It contains the best description of the text lines.
+.
+We are glad to use that.
+.
+.
+.P
+The latest
+.FONT CI RUNOFF
+documentation is file
+.FONT CB RUNOFF.DOC
+from 
+.FONT CR PDP\-11
+at 1981, see
+.FONT CR "SEE ALSO" R .
+.
+The content of this document is also included in this document,
+although it has some errors.
+.
+.
+.P
+There is still more documentation by the
+.FONT CR "DEC PDP\-10 archive" R .
+.
+So far this information is not yet included in this document, but it
+will be done later on.
+.
+.
+.\" --------------------------------------------------------------------
+.SS Early Environment 1963\-66 (CTSS)
+.\" --------------------------------------------------------------------
+.
+.FONT CI Saltzer
+originally worked on
+.IR \%MIT 's
+.I \%CTSS time-sharing operating
+.IR \%system .
+.
+There he had an editor
+.FONT CB TYPSET
+that he also documented in the documentation cited above.
+.
+This editor was an ancestor for
+.BR \%ed (@MAN1EXT@).
+.
+.
+.P
+To use his
+.FONT CI RUNOFF
+language, he programmed a tool that he called
+.FONT CB RUNOFF R .
+.
+.
+.P
+There is still an emulator and the old source files for
+.FONT CB RUNOFF
+and
+.FONT CB TYPSET
+at
+.nh
+.UR http://\:www.cozx.com/\:~dpitts/\:ibm7090.html 
+.FONT CR "IBM 7090 CTSS"
+.UE .
+.hy
+.
+.
+.\" --------------------------------------------------------------------
+.SS The original RUNOFF program 1963-66
+.\" --------------------------------------------------------------------
+.
+The original
+.FONT CB RUNOFF
+program is also documented in the documentation of 1966 above.
+.
+.
+.P
+.FONT CI Saltzer
+uses upper case
+.FONT CB RUNOFF
+to denote his program.
+.
+So we will also use 
+.FONT CB RUNOFF
+to refer to the original program of 1963-66.
+.
+.
+.P
+This program has mainly the task to adjust a printer of that time and
+then print a
+.FONT CI RUNOFF
+document with this configuration.
+.
+Today this does not make much sense, but some parts are still
+available in the options of
+.BR \%groff (@MAN1EXT@),
+but under different names.
+.
+So we will not build this ancient program, but we will document its
+old command line here.
+.
+A lower case program
+.FONT CB runoff
+will be something different.
+.
+.
+.P
+.FONT CB RUNOFF
+is a command used to type out files of the
+.FONT CI RUNOFF
+language in manuscript format.
+.
+.I Control words
+(command names) scattered in the text may be used to provide detailed
+control over the format.
+.
+Input files may be prepared by the context editor
+.FONT CB TYPSET
+which does not exist today.
+.
+.
+.\" --------------------------------------------------------------------
+.SS Usage of RUNOFF Program
+\" --------------------------------------------------------------------
+.
+.SY RUNOFF
+.I \%filespec
+.RI [ "parameter \*[Ellipsis]" ]
+.YS
+.
+.
+.TP
+.I filespec
+is the primary name of a file to be typed out.
+.
+.TP
+.I parameter
+arguments are any number of the following parameters, in any order:
+.
+.
+.RS
+.
+.TP
+.FONT CB STOP
+Pause between pages.
+.
+.
+.TP
+.FONT CB NOWAIT
+Suppress the initial pause to load paper and the pause between pages
+(not necessary today).
+.
+.
+.TP
+.FONT CB PAGE I " n"
+Begin printing with the page numbered
+.IR n .
+.
+.
+.TP
+.FONT CB BALL I " n"
+Typewriter is using printing ball
+.IR n .
+If this parameter is omitted,
+.FONT CB RUNOFF
+assumes that the ball in use will properly print all
+.I CTSS characters
+in the file.
+.
+The number
+.I n
+is engraved on top of the printing ball.
+.
+.I CTSS characters
+not appearing on the ball being used will be printed as blanks, so
+that they may be drawn in.
+.
+This parameter does not make sense in our modern printers.
+.
+.RE
+.
+.
+.\" --------------------------------------------------------------------
+.SH BASIC RUNOFF LANGUAGE OF ALL TIMES
+.\" --------------------------------------------------------------------
+.
+Files written in the
+.FONT CI RUNOFF
+language are similar to modern
+.FONT CI roff
+files.
+.
+.
+.P
+They are both written in text mode.
+.
+So they can be manipulated with text editors like
+.BR emacs (1).
+.
+.
+.P
+In files written in the text languages
+.FONT CI RUNOFF
+or
+.FONT CI roff R ,
+there are command lines and text lines.
+.
+.
+.\" --------------------------------------------------------------------
+.SS Basic Command Lines
+.\" --------------------------------------------------------------------
+.
+All lines beginning with a period (dot)
+.FONT CB .
+are command lines in both languages
+.FONT CI RUNOFF
+and
+.FONT CI roff R .
+.
+The period is followed by the name of the command (1 or 2 words of
+arbitrary length, later one even more words), optionally followed by 1
+or more arguments.
+.
+.
+.P
+The inventor
+.FONT CI Saltzer
+called the command name
+.IR "control word" ,
+but we keep using
+.I command name
+as was done in later times.
+.
+.
+.P
+In
+.FONT CI roff R ,
+lines starting with a single quote
+.FONT CB '
+are also command lines, but that's not true for the
+.FONT CI RUNOFF
+language by default.
+.
+.
+.P
+But in
+.FONT CI RUNOFF R ,
+the period
+.FONT CB .
+at the beginning of a line can be changed into any character.
+.
+This can be done by the command
+.FONT CB ".FLAG CONTROL" R .
+.
+So the starting period is only one possible special character.
+.
+But in this man\-page, we use the period before a command name,
+because it is the default and helps recognizing commands directly.
+.
+.
+.P
+In
+.FONT CI RUNOFF R ,
+the command names were quite long, sometimes consisting even of
+several words.
+.
+This is the same in the
+.FONT CI mom
+language in
+.FONT CI groff R .
+.
+.
+.P
+Moreover, the
+.FONT CI RUNOFF
+commands can be appreviated by defined 2 letters words (or 3 later on).
+.
+Later on, the
+.FONT CI "classical roff"
+languages used only the 2-letter abbreviations as requests; but
+.FONT CI groff
+expanded these to arbitrary length.
+.
+.
+.P
+In
+.FONT CI RUNOFF R ,
+each
+.FONT CI "control word"
+(command name) can be written in upper or lower case.
+.
+That comes from the time where the computers had only upper case input.
+.
+This was not taken into
+.FONT CI roff R ,
+because there were not enough 2-letter requests.
+.
+.
+.P
+In
+.FONT CI RUNOFF R ,
+comments could be appended to a command line, see section
+.FONT CB Comments R .
+.
+.
+.P
+Lines beginning with a period but having unrecognizable format are
+treated as error.
+.
+.
+.P
+No lines beginning with a dot are printed unless the preceding line
+was a
+.I command line
+with control name
+.FONT CB .LITERAL R .
+.
+Then the the line is output or printed as is, special characters are
+output without their special meaning.
+.
+.
+.P
+Abbreviations for command names are normally based on the first two
+letters of a one word command or the first letter of the first two
+words of a multi\-word command.
+.
+Later on 3-letter abbreviations where used for command names of 3
+words.
+.
+.
+.P
+An example of a
+.I "control line"
+(command line) with a single
+.I "control word"
+with 2 arguments is a long name with upper case
+.IP
+.FONT CB .COMMAND I " arg1 arg2"
+.P
+or the same name in lower case
+.IP
+.FONT CB .command I " arg1 arg2"
+.P
+or an abbreviation with upper case
+.IP
+.FONT CB .CO I " arg1 arg2"
+.P
+or the same abbreviation with lower case
+.IP
+.FONT CB .co I " arg1 arg2"
+.
+.
+.P
+Another example of a
+.I "control line"
+(command line) with 2
+.I "control words"
+with 1 argument is a long name with upper case
+.IP
+.FONT CB ".WORD1 WORD2" I " arg"
+.P
+or the same name in lower case
+.IP
+.FONT CB ".word1 word2" I " arg"
+.P
+or an abbreviation with upper case
+.IP
+.FONT CB .WW I " arg"
+.P
+or the same abbreviation in lower case
+.IP
+.FONT CB .ww I " arg"
+.
+.
+.P
+These
+.I "control words"
+were renamed to
+.I requests
+and
+.I macros
+later on in
+.FONT CI roff R .
+.
+.
+In the 1973 document, the words
+.I macros
+and
+.I formats
+are used, but there isn't any documentation for these terms.
+.
+.
+.\" --------------------------------------------------------------------
+.SS Comments
+.\" --------------------------------------------------------------------
+.
+In
+.FONT CI roff R ,
+comments can be included by preceding the special character combination
+.FONT CB \[rs]\[rq] R .
+.
+.
+.P
+That was unknown in
+.FONT CI RUNOFF R .
+.
+There was only 1 method for including comments.
+.
+Command lines could be appended by comments.
+.
+.
+.P
+In the original
+.FONT CI RUNOFF
+language, a comment could be appended after the command arguments
+without using separators.
+.
+For example,
+.RS
+.FONT CB ".cmd1 cmd2 arg1 arg2 This is a comment"
+.RE
+.
+.
+.P
+In the newer
+.FONT CI RUNOFF
+languages (documented in 1974), they preceded the comments in command
+lines by the exclamation point (bang)
+.FONT CB ! R .
+.
+For example,
+.RS
+.FONT CB ".cmd1 cmd2 arg1 arg2 !This is a comment"
+.RE
+.
+.
+.\" --------------------------------------------------------------------
+.SS Basic Text Lines
+.\" --------------------------------------------------------------------
+.
+All lines that are not command lines are text lines in both languages.
+.
+.
+.P
+There are 2 modes of text lines in
+.FONT CI RUNOFF R .
+.
+The newer mode had upper and lower case in the source file.
+.
+This was similar to
+.FONT CI roff R .
+.
+.
+.P
+In the
+.FONT CI CTSS
+computer (early 1960s), there were only upper case input hardware.
+.
+So the
+.FONT CI RUNOFF
+files had only upper case ASCII characters in the original
+.FONT CI RUNOFF
+language.
+.
+.
+.P
+As the printers could print in upper and lower case, there were
+special characters as case-shifters.
+.
+That was also used in late
+.FONT CI RUNOFF
+files.
+.
+This process is very different from
+.FONT CI roff R .
+.
+.
+.P
+In the following sections, only the upper case text lines are documented.
+.
+.
+.P
+In
+.FONT CI RUNOFF
+and
+.FONT CI roff R ,
+there are special character combinations that can change the handling
+of the text.
+.
+But these special characters are totally different in both languages.
+.
+.
+.P
+One or more
+.I blank lines
+are not printed, but mean a
+.IR "line break" .
+.
+This can also be reached by the
+.FONT CB .BREAK
+.IR "control word" .
+.
+.
+.P
+In
+.IR groff ,
+blank lines are printed as lines of their own.
+.
+This is not a paragraph break, because a line is bigger than a
+paragraph break.
+.
+.
+.P
+A text line that starts with one or more space characters means
+.IR "begin a new paragraph" .
+.
+.
+.P
+In
+.IR groff ,
+this will start a new line and inserts the space characters at the
+beginning of the line.
+.
+.
+.\" --------------------------------------------------------------------
+.SS Appending several Lines in RUNOFF
+.\" --------------------------------------------------------------------
+.
+In the 1974 paper, it is documented that a command line can be
+appended by several text or command lines into a single line, each
+being separated by a
+.FONT CI semi-colon
+.FONT CB ; R .
+.
+.
+.P
+If the appended line is a command line, then it starts with a period.
+.
+That's regarded as enough for separation.
+.
+In this case, the separating semi\-colon can be omitted.
+.
+.
+.\" --------------------------------------------------------------------
+.SS Default Conditions (modes) in RUNOFF
+.\" --------------------------------------------------------------------
+.
+The starting case-mode (for output or printing) is lower case.
+.
+Each text line starts with that mode.
+.
+.
+.P
+Usually the text is
+.I filled
+and
+.I justified
+as it is processed.
+.
+That is, the program
+.I fills
+a line by adding successive words from the source text until one more
+word would cause the right margin to be exceeded.
+.
+The line is then
+.I justified
+by making the word spacings larger until the last word in the line
+exactly meets the right margin.
+.
+.
+.P
+The user may occasionally wish to reproduce the source text exactly,
+which is done by disabling
+.I filling
+and
+.I justification
+or by use of the
+.FONT CR .LITERAL
+command.
+.
+The program may be set to
+.I fill
+but not
+.IR justify ,
+in which case the output will be normal except that lines will not be
+justified to the right margin.
+.
+The program may also be set to
+.I justify
+but not
+.IR fill ,
+although this would probably produce peculiar results and is not
+recommended.
+.
+.
+.P
+When the
+.I fill mode
+is on, spaces and carriage returns occurring in the source text are
+treated only as word separators.
+.
+Multiple separators are ignored.
+.
+.
+.P
+Some of the commands cause a BREAK in the output.
+.
+A
+.I break
+means that the current line is output without justification, and the
+next word goes at the beginning of the next line.
+.
+This occurs at the end of paragraphs.
+.
+.
+.P
+The program will advance to new pages as necessary, placing the title
+(if given) and the page number at the top of each page.
+.
+The user may call explicitly for a
+.I page advance
+where desired, and may inhibit the occurrence of a
+.I page advance
+within specified material.
+.
+.
+.P
+By the documentation of 1974 and 1981, some special characters in text
+lines are initially disabled:
+.FONT CB < R " (" CB CAPITALIZE R ),
+.FONT CB > R " (" CB INDEX R ),
+.FONT CB = R " (" CB HYPHENATE R ),
+and
+.FONT CB % R " (" CB OVERSTRIKE R ).
+.
+.
+.P
+The other special characters seem to be enabled by default.
+.
+These should be:
+.FONT CB . R " (" CB CONTROL  R ),
+.FONT CB ! R " (" CB ENDFOOTNOTE R ),
+.FONT CB ^ R " (" CB UPPERCASE R ),
+.FONT CB \[rs] R " (" CB LOWERCASE R ),
+.FONT CB & R " (" CB UNDERLINE R ),
+.FONT CB # R " (" CB SPACE R ),
+and
+.FONT CB _ R " (" CB QUOTE R ).
+.
+.
+.P
+This can be changed by the commands
+.RS
+.FONT CB .FLAGS I " <mode>"
+.RE
+(enabling) and
+.RS
+.FONT CB ".NO FLAGS" I " <mode>"
+.RE
+(disabling).
+.
+Also, each special character can be set to another character by the
+.RS
+.FONT CB .FLAGS I " <mode> <some_character>"
+.RE
+command.
+.
+.
+.P
+The following informs about the
+.I <mode>
+arguments:
+.
+.
+.TP
+.FONT CB CONTROL
+default:
+.FONT CI period
+on first column (start command line):
+.FONT CB .
+.
+.TP
+.FONT CB ENDFOOTNOTE
+default:
+.FONT CI "exclamation character"
+on first column (end of footnote):
+.FONT CB !
+.
+.TP
+.FONT CB UPPERCASE
+upper case (single character) and case lock (2 characters), default:
+.FONT CB ^
+.
+.TP
+.FONT CB LOWERCASE
+lower case (single character) and case lock (2 characters), default:
+.FONT CB \[rs]
+.
+.TP
+.FONT CB UNDERLINE
+underlining word witout spaces, default:
+.FONT CB &
+.
+.TP
+.FONT CB SPACE
+quoted space (no filling and justifying), default:
+.FONT CB #
+.
+.TP
+.FONT CB QUOTE
+quoting character (output special character without specialization),
+default:
+.FONT CB _
+.
+.TP
+.FONT CB CAPITALIZE
+upper case for next character, default:
+.FONT CB <
+.
+.TP
+.FONT CB INDEX
+set following word into index, default:
+.FONT CB >
+.
+.TP
+.FONT CB OVERSTRIKE
+superimpose the surrounding characters, default:
+.FONT CB %
+.
+.TP
+.FONT CB HYPHENATE
+default:
+.FONT CB =
+.
+.TP
+.FONT CB ALL
+all but the 1st column characters
+.FONT CB .
+and
+.FONT CB !
+.
+.TP
+.FONT CB null
+same as
+.FONT CB ALL
+.
+.
+.P
+The following special characters are only documented in 1981, but it
+is not clear if they are initially enabled.
+.
+Also no
+.I <mode>
+for
+.FONT CB .FLAGS
+are documented:
+.FONT CB { R ,
+.FONT CB } R ,
+.FONT CB | R ,
+and
+.FONT CB Ctrl-N R .
+.
+.
+.P
+.FONT CI RUNOFF R 's
+ability to change most special characters is unique.
+.
+.FONT CI roff
+cannot do that.
+.
+.
+.\" --------------------------------------------------------------------
+.SH UPPER CASE TEXT LINES
+.\" --------------------------------------------------------------------
+.
+The original
+.FONT CI RUNOFF
+text lines are different from the
+.FONT CI roff
+language.
+.
+.
+.P
+As the early
+.FONT CI CTSS
+computers could only produce upper case characters as input, the text
+lines look very strange today.
+.
+This wasn't documented in the documentation of the 1960s.
+.
+But there are good documentations of 1974 and 1981 which contain also
+the old style.
+.
+.
+.\" --------------------------------------------------------------------
+.SS Case Changing of Text Lines
+.\" --------------------------------------------------------------------
+.
+In this section, the specification of case for files prepared on an
+upper case terminal is documented.
+.
+There are special characters that in printing act as case-shifters for
+ASCII characters into lower (ASCII code 97 to 122 decimal) or upper
+case (ASCII code 65 to 90 decimal).
+.
+.
+.P
+The lower case mode seems to be the default mode.
+.
+Also, according to existing old
+.FONT CI RUNOFF
+files, each text line starts with this default mode.
+.
+.
+.TP
+.FONT CI "single circumflex " CB ^
+The following ASCII character is shifted to
+.FONT CI "upper case" R .
+.
+The following from the document of 1981 seems to be wrong:
+.
+(It is also used to lock the
+.I case mode
+in
+.IR "upper case" ,
+and the
+.I underline mode
+to
+.UL "underline all text" ).
+
+.
+.
+.TP
+.FONT CI "single back\-slash " CB \[rs]
+The following ASCII character is shifted into lower case.
+.
+The following from the document of 1981 seems to be wrong:
+.
+(It is also used to lock the
+.I case mode
+in
+.IR "lower case" ,
+and disable underlining.)
+.
+.
+.TP
+.FONT CI "double circumflex " CB ^^
+The case mode is shifted into upper case.
+.
+.
+.TP
+.FONT CI "double back\-slash " CB \[rs]\[rs]
+The case mode is shifted into lower case.
+.
+.
+.P
+A common example with starting mode in lower case for these 4 special
+characters is:
+.
+.P
+.RS
+^HERE IS A ^SAMPLE ^SENTENCE IN ^^UPPER CASE\\ AND LOWER CASE.
+.RE
+.
+.P
+is printed as:
+.
+.RS
+Here is a Sample Sentence in UPPER CASE and lower case.
+.RE
+.
+.
+.\" --------------------------------------------------------------------
+.SS Further special Characters in Text Lines
+.\" --------------------------------------------------------------------
+.
+.TP
+.FONT CI "ampersand " CB &
+This is used for underscoring the next following character.
+.
+For example:
+.
+.RS
+.P
+.RS
+&s&o&f&t&w&a&r&e
+.RE
+.
+.P
+becomes:
+.RS
+.UL software
+.RE
+.
+.P
+in the output or printing.
+.RE
+.
+.
+.TP
+.FONT CI "circumflex and ampersand " CB ^&
+This is used for underscoring all following characters except for
+blanks.
+.
+One could say that by this character combination the underline mode is
+put on.
+.
+.
+.TP
+.FONT CI "back\-slash and ampersand " CB \[rs]&
+This is used for stopping the underscoring.
+.
+One could say that by this character combination the underline mode is
+put off.
+.
+.
+.RS
+.P
+For example:
+.RS
+^&PLATO\[rs]& was a very ^&wise \[rs]&man.
+.RE
+becomes
+.RS
+.UL PLATO
+was a very
+.UL wise
+man.
+.RE
+.
+.
+.P
+In
+.FONT CI groff R ,
+spaces are not underlined as well.
+.
+.RE
+.
+.
+.TP
+.FONT CI "number sign " CB #
+.FONT CI RUNOFF 
+interprets this character as a
+.FONT CI "quoted space" R .
+.
+It outputs exactly 1 space character, it is not justified or filled.
+.
+It cannot end a line.
+.
+In the text it is not treated as a
+.IR "word separator" .
+.
+.
+.TP
+.FONT CI "less\-than " CB <
+This character preceding a word capitalizes the entire word up to the
+first space character.
+.
+This is the same as preceding the word with
+.FONT CB ^^
+and ending it with
+.FONT CB \[rs]\[rs] R .
+.
+For example, if the current case mode is lower case, the following
+text line
+.RS
+.RS
+.FONT CB "<DIGITAL OF ^MAYNARD, <MA"
+.RE
+becomes
+.RS
+.FONT CB "DIGITAL of Maynard, MA"
+.RE
+in the output (printing).
+.
+This special character is initially disabled.
+.
+It can be activated by the command
+.FONT CB .FLAGS R .
+.
+.RE
+.
+.
+.TP
+.FONT CI "greater\-than " CB >
+This character enters the immediately following word (up to the first
+space character) into the index, including all case shifters in the
+word.
+.
+This special character is initially disabled.
+.
+It can be enabled by the command
+.FONT CB .FLAGS R .
+.
+.
+.TP
+.FONT CI "percent " CB %
+This is for
+.FONT CI superimposition
+of the surrounding characters, one character over the other.
+.
+For example, the combination
+.FONT CB /%=
+overstrikes the 2 characters
+.FONT CI slash
+and
+.FONT CI equal
+into the character
+.FONT CB \[!=]
+(unequal).
+.
+In underlining, superimposition cannot be done.
+.
+This special character is initially disabled.
+.
+So a percent character is output as is.
+.
+This character can be enabled by the command
+.FONT CB .FLAGS R .
+.
+.
+.\" --------------------------------------------------------------------
+.SS Special Characters in Text Lines of 1981
+.\" --------------------------------------------------------------------
+.
+.TP
+.FONT CB = CI " equals\-sign " I  "\[em] hypenation disable"
+If
+.FONT CB ".FLAGS HYPHENATE"
+has been engaged, the
+.I equals
+character
+.FONT CB =
+used to disable
+.I hyphenation
+for the word it precedes.
+.
+.
+.TP
+.FONT CB { CI " left\-brace " I "\[em] Reverse half\-linefeed"
+If the output device type is no
+.FONT CB N R ,
+then the
+.I left
+and
+.I right braces
+are used for
+.I superscripting
+and
+.IR subscripting .
+.
+The
+.I left\-brace
+.FONT R ( CB { CR " 173 octal" R )
+produces a
+.IR "reverse half\-linefeed" .
+When combined with the
+.I right brace
+.FONT R ( CB } CR " 175 octal" R )
+scripting is created; e.g.
+.FONT CB {super}
+becomes
+.EQ
+"" sup superscript
+.EN
+and
+.FONT CB }sub{
+becomes
+.EQ
+"" sub subscript
+.EN
+.
+.
+.TP
+.FONT CB } CR " right\-brace " I "forward half\-linefeed"
+As described above, the
+.I right brace
+.FONT R ( CB } CR " 175 octal" R )
+when coupled with the
+.I left brace
+will produce scripting.
+.
+This will only occur when a scripting output device is selected.
+.
+.
+.TP
+.FONT CB | CR " vertical\-bar " I "Engage/disengage alternate character set"
+The
+.I vertical bar
+.FONT R ( CB | R , CR " 174 octal" R )
+acts as an on/off switch.
+.
+It will alternately transmit a
+.I shift\-out
+and a
+.I shift\-in
+character to change the selected character set; e.g.
+.FONT CB |ABC|
+becomes
+.FONT CI Ctrl\-N CB ABC CI Ctrl\-O R .
+.
+.
+.\" --------------------------------------------------------------------
+.SS Escape Sequences in Text Lines
+.\" --------------------------------------------------------------------
+.
+The
+.FONT CI "escape character"
+in
+.FONT CI RUNOFF
+(also called
+.FONT CI "quote character" R )
+is the
+.FONT CI "sub character " CB _ R .
+.
+Using this character as a prefix before a special character, outputs
+the special character as it is without its speciality, no formatting
+is done by it.
+.
+.
+.TP
+.FONT CB _^
+outputs the special character
+.FONT CB ^
+.
+.
+.TP
+.FONT CB _\[rs]
+outputs the special character
+.FONT CB \[rs]
+.
+.
+.TP
+.FONT CB _&
+outputs the special character
+.FONT CB &
+.
+.
+.TP
+.FONT CB _#
+outputs the special character
+.FONT CB #
+.
+.
+.TP
+.FONT CB _<
+outputs the special character
+.FONT CB <
+.
+.
+.TP
+.FONT CB _>
+outputs the special character
+.FONT CB >
+.
+.
+.TP
+.FONT CB _%
+outputs the special character
+.FONT CB %
+.
+.
+.TP
+.FONT CB __
+outputs the special character
+.FONT CB _
+.
+.
+.\" --------------------------------------------------------------------
+.SH COMMAND NAMES (CONTROL WORDS) IN THE ORIGINAL RUNOFF LANGUAGE OF 1966
+.\" --------------------------------------------------------------------
+.
+The documentation for
+.I "control words"
+in this paragraph are taken from the
+.FONT CI RUNOFF
+documentation of 1966.
+.
+Often this documentation refers to the
+.FONT CB RUNOFF
+program that doesn't exist any more.
+.
+When the
+.FONT CI RUNOFF
+language will be implemented for
+.BR \%groff (@MAN1EXT@)
+these documentations must be adjusted.
+.
+.
+.TP
+.FONT CB .ADJUST
+.TQ
+.FONT CB .AD
+Enable
+.I fill
+mode.
+.
+The next line is the first one affected.
+.
+This is the default mode.
+.
+.
+.TP
+.FONT CB .APPEND I " file"
+.TQ
+.FONT CB .AP I " file"
+Take as the next input line the first line of
+.IR \%file .
+.
+Note that the whole of 
+.I \%file
+is appended, and that the appending is an irreversible process \[em] that
+is, once
+.FONT CB RUNOFF
+encounters the
+.FONT CB .APPEND
+.I "control line"
+it will switch to the file
+.I \%file
+and continue from the first line of
+.IR \%file .
+.
+All lines following the
+.FONT CB .APPEND
+.I "control line"
+will not be processed by
+.FONT CB RUNOFF R .
+.
+The file
+.I \%file
+may, of course, itself call for appending of still another file, and
+so on.
+.
+.
+.TP
+.FONT CB ".BEGIN PAGE"
+.TQ
+.FONT CB .BP
+Print out this page, start next line on a new page.
+.
+.
+.TP
+.FONT CB .BREAK
+.TQ
+.FONT CB .BR
+The lines before and after the
+.FONT CB .BREAK
+.I "control word"
+will not be run together by the
+.FONT CI fill
+mode of operation.
+.
+.
+.TP
+.FONT CB .CENTER
+.TQ
+.FONT CB .CD
+The following line is to be centered between the left and right
+margins.
+.
+.
+.TP
+.FONT CB ".DOUBLE SPACE"
+.TQ
+.FONT CB .DS
+Copy is to be double spaced.
+.
+This mode  takes  effect after the next line.
+.
+.
+.TP
+.FONT CB .FILL
+.TQ
+.FONT CB .FI
+Enable
+.IR "fill mode" .
+.
+That means: Lengthen short lines by moving words from the following
+line; trim long lines by moving words to the following line.
+.
+This is the default mode.
+.
+.FONT CB .NOFILL
+disables the
+.I fill
+mode.
+.
+.
+.TP
+.FONT CB .HEADER I " word1 word2 \*[Ellipsis]"
+.TQ
+.FONT CB .HE I " word1 word2 \*[Ellipsis]"
+All of the line after the first blank is used as a header line, and
+appears at the top of each page, along with the page number, if
+specified.
+.
+.
+.TP
+.FONT CB ".HEADING MODE" I " arg"
+.TQ
+.FONT CB .HM I " arg"
+This
+.I control sequence
+alters the mode of the running head to that specified by the parameter
+.IR \%arg .
+.
+Any of the following parameters are allowed for
+.IR \%arg:
+.
+.
+.\"  --------------------------------------------------------------------
+.RS
+.
+.
+.TP
+.FONT CB CENTER
+The header will be centered on the page.
+.
+.
+.TP
+.FONT CB MARGIN
+The header will be adjusted against the right margin of the page.
+.
+.
+.TP
+.FONT CB FACING
+On even\-numbered pages, the header will be adjusted against the left
+margin, on odd numbered pages against the right.
+.
+.
+.TP
+.FONT CB OPPOSED
+The header will be adjusted against the opposite margin from the page
+number.
+.
+In the absence of a
+.FONT CB ".HEADING MODE"
+.IR "control sequence" ,
+the default option is
+.FONT CB OPPOSED R .
+.
+.
+.RE
+.\"  --------------------------------------------------------------------
+.
+.
+.TP
+.FONT CB .INDENT I " n"
+.TQ
+.FONT CB .IN I " n"
+The argument
+.I \%n
+is a number.
+.
+Set the number of spaces to be inserted at the beginning of each line
+to
+.IR \%n .
+.
+Indent is preset to 0.
+.
+.
+.TP
+.FONT CB ".LINE LENGTH" I " n"
+.TQ
+.FONT CB .LL I " n"
+The argument
+.I \%n
+is a positive number.
+.
+Set the line length to
+.IR \%n .
+.
+The line length is preset to 60.
+.
+.
+.TP
+.FONT CB .LITERAL
+.TQ
+.FONT CB .LI
+The following line is not a
+.IR "control word" ,
+despite the fact that it begins with a period.
+.
+.
+.TP
+.FONT CB .NOFILL
+.TQ
+.FONT CB .NF
+Disable
+.IR "fill mode" .
+.
+That means: Print all lines exactly as they appear without right
+adjustment or filling out.
+.
+In
+.I NOFILL
+mode each input line produces one output line; further blank lines are
+output in this mode.
+.
+Use the
+.FONT CB .FILL
+.I control word
+to restart
+.IR filling .
+.
+.
+.TP
+.FONT CB .NOJUST
+.TQ
+.FONT CB .NJ
+Disable
+.IR "fill mode" .
+.
+.
+.TP
+.FONT CB ".ODD PAGE"
+.TQ
+.FONT CB .OP
+This
+.I "control word"
+causes the current page to be printed out, and the next page to be
+numbered with the next higher odd page number.
+.
+.
+.TP
+.FONT CB .PAGE R " [" I n R ]
+.TQ
+.FONT CB .PA R " [" I n R ]
+Print page numbers.
+.
+(The first page is not given a page number.
+.
+It has instead a two\-inch top margin.
+.
+See also
+.FONT CB "Manuscript Conventions" R ,
+below.)
+.
+If argument
+.I \%n
+is present, insert a page break and number the next page
+.IR \%n .
+Note that
+.FONT CB RUNOFF
+does not output or print completely empty pages.
+.
+.
+.TP
+.FONT CB ".PAGING MODE" I " arg1 arg2 \*[Ellipsis]"
+.TQ
+.FONT CB .PM I " arg1 arg2 \*[Ellipsis]"
+This
+.I control sequence
+alters the mode of page numbering to that specified by the arguments.
+.
+The arguments may be in any order, and must be selected from the
+following list:
+.
+.
+.\"  --------------------------------------------------------------------
+.RS
+.
+.
+.TP
+.FONT CB MARGIN
+Page numbers will be adjusted against the right margin.
+.
+.
+.TP
+.FONT CB FACING
+Odd page numbers are adjusted against the right margin, even page
+numbers are adjusted against the left margin.
+.
+.
+.TP
+.FONT CB CENTER
+Page numbers are centered between the right and left margin.
+.
+.
+.TP
+.FONT CB TOP
+Page numbers are placed on the fourth line from the top of the page.
+.
+.
+.TP
+.FONT CB BOTTOM
+Page numbers are placed on the fourth line from the bottom of the
+page.
+.
+.
+.TP
+.FONT CB OFF
+Page numbers are discontinued.
+.
+.
+.TP
+.FONT CB PREFIX I " \(dqstring\(dq"
+The string of characters between quotation marks is prefixed to the
+page number.
+.
+The quotation marks may be next to each other, in which case no prefix
+is used.
+.
+.
+.TP
+.FONT CB ROMANU
+Page numbers will be printed in upper case Roman numerals.
+.
+.
+.TP
+.FONT CB ROMANL
+Page numbers will be printed in lower case Roman numerals.
+.
+.
+.TP
+.FONT CB ARABIC
+Page numbers will be printed in Arabic.  (This is the normal mode.)
+.
+.
+.TP
+.FONT CB SET I " n"
+Set the next page number to be the positive number
+.IR \%n .
+.
+.
+.TP
+.FONT CB SKIP I " n"
+Skip
+.I \%n
+page numbers.
+.
+.
+.P
+If in a single use of
+.FONT CB ".PAGING MODE"
+several arguments specify competing functions, the last one specified
+takes precedence.
+.
+When the
+.FONT CB ".PAGING MODE"
+sequence appears in text at point A, all text up to A (and probably
+some text after A) will appear on a page controlled by the previous
+paging mode.
+.
+The new
+.I paging mode
+will take effect on the next page.
+.
+Then there is no danger of getting page numbers both at the top and
+bottom of the same page.
+.
+.
+.P
+Use of the
+.FONT CB .TOP
+parameter may conflict with the
+.I \%heading
+.IR \%mode .
+.
+If a heading and a page number should be printed in the same column,
+the page number will take precedence.
+.
+In the absence of a
+.FONT CB ".PAGING MODE"
+.I control
+.IR sequence ,
+the default options are:
+.FONT CB "TOP MARGIN PREFIX \(dqPAGE\(dq" R .
+.
+.
+.RE
+.\"  --------------------------------------------------------------------
+.
+.
+.TP
+.FONT CB ".PAPER LENGTH" I " n"
+.TQ
+.FONT CB .PL I " n"
+This
+.I control word
+is used for running off a documentation file on non\-standard paper.
+.
+The number
+.I \%n
+is a line count, figured at 6 lines per inch.
+.
+If this
+.I control word
+is not given,
+.I n
+is assumed to be 66, for 11\-inch paper.
+.
+.
+.TP
+.FONT CB ".SINGLE SPACE"
+.TQ
+.FONT CB .SS
+Copy is to be single spaced.
+.
+This mode takes effect after the next line.
+.
+(The normal mode is single space.)
+.
+.
+.TP
+.FONT CB .SPACE R " [" I n R ]
+.TQ
+.FONT CB .SP  R " [" I n R ]
+Insert
+.I \%n
+vertical spaces (carriage returns) in the copy.
+.
+If
+.I \%n
+carries spacing to the bottom of a page, spacing is stopped.
+.
+If
+.I \%n
+is absent or 0, one space is inserted.
+.
+.
+.TP
+.FONT CB .UNDENT I " n"
+.TQ
+.FONT CB .UN I " n"
+In an indented region, this
+.I control word
+causes a break, and the next line only will be indented n spaces fewer
+than usual.
+.
+This
+.I "control word"
+is useful for typing indented numbered paragraphs.
+.
+.
+.\" --------------------------------------------------------------------
+.SH RUNOFF ADDITIONS 1973
+.\" --------------------------------------------------------------------
+.
+Here are described only the additional
+.I control words
+that are documented in the 1973 documentation.
+.
+.\" --------------------------------------------------------------------
+.SS Formats
+.\" --------------------------------------------------------------------
+.
+.
+.TP
+.FONT CB .FORMAT I " name"
+This command causes subsequent text to be output under the control of
+tne specified format (see below at
+.FONT CB ".DEFINE FORMAT" R ).
+.
+Each following logical line will be fit into the format until a
+.FONT CB .FILL
+or
+.FONT CB .NOFILL
+command 1s encountered.
+.
+.
+.TP
+.FONT CB ".DEFINE FORMAT" I " <name> <pos> <field_ definition> \
+\*[Ellipsis]"
+.TQ
+.FONT CB ".END FORMAT"
+These commands define a format for use in producing tables, etc.
+.
+.
+.RS
+.
+.
+.TP
+.I <name>
+identifies the format.
+.
+It can be activated by the
+.FONT CB .FORMAT
+.IR command .
+.
+.
+.TP
+.I <pos>
+is the position and may be one of
+.FONT CB .LEFT R ,
+.FONT CB .RIGHT R ,
+or
+.FONT CB .CENTER R ,
+and determines the overall positlon of the format with respect to the
+margins.
+.
+.
+.TP
+.I <field_definition>
+There can be several arguments of this type.
+.
+Each has the form:
+.
+.
+.RS
+.
+.FONT CI <type> CB ( CI "<letter> \*[Ellipsis] <letter>" CB )
+.
+.P
+where the
+.FONT CI <type>
+is one of
+.
+.TP
+.FONT CB L
+for left,
+.
+.TP
+.FONT CB R
+for riqht,
+.
+.TP
+.FONT CB C
+for center,
+.
+.TP
+.FONT CB F
+for
+.FONT CI fill R ,
+or
+.FONT CB J
+for
+.FONT CI justify R .
+.
+.
+.P
+The first three types define fixed fields; the text to be formatted
+must fit within the allocated space.
+.
+The latter types define variable fields; the text will be handled as
+in normal fill mode processing.
+.
+.
+.P
+A picture showing the manner in which text should be output follows
+the
+.FONT CB ".DEFINE FORMAT"
+command; following the picture should be an
+.FONT CB ".END FORMAT"
+command.
+.
+The following lines give an example:
+.
+.
+.RS
+.  ft CB
+.  nf
+.  nh
+.    nop ".DEFINE FORMAT SUMMARY L(A) F(C) C(B)"
+.    nop "AAAA	CCCCCCCCCCCCCCCCCCCCCCCCC	BBBBBBB"
+.    nop "	CCCCCCCCCCCCCCCCCCCCCCCCC		"
+.    nop ".END FORMAT"
+.  hy
+.  fi
+.  ft
+.RE
+.
+.
+.P
+The first field of text is left justified; the second is centered; the
+third is subjected to
+.I fill mode
+processing without justification.
+.
+After the first line of output is generated using this format, all
+subsequent lines are produced using the last picture 1ine.
+.
+(Strictly speaking the third line is unnecessary.)
+.
+.
+.P
+Text for formatted processing consists of a logical line (or
+paragraph).
+.
+Each field except the last must be separated by
+.IR tab .
+.
+The
+.I tab character
+is displayed here as backslash character
+.FONT R ( CB \[rs] R ).
+.
+.
+.P
+The first field of text is
+.FONT CB A R ,
+the second
+.FONT CB B R ,
+etc.
+.
+Typical input for our example might be:
+.
+.
+.RS
+.nf
+.nh
+|A\\YES\\/THIS IS SOME TEXT
+TO BE FILLED.
+.hy
+.fi
+.RE
+.
+.
+.P
+The characters 1n the picture lines were 1nterpreted as follows.
+.
+Contiguous sequences of letters determine the fie1d positions;
+non\-alphabetic characters are output literally.
+.
+(Note:
+.FONT CB Q.QQ
+wi11 not work, put the period
+.RB \[dq] . \[dq]
+in the text.
+.
+A sequence of characters written between double quotes is considered
+literal text.
+.
+The
+.I double quotes
+are not output, and there is no way to use
+.I double quote
+as a
+.IR literal .
+.
+.
+.\" --------------------------------------------------------------------
+.SS Hyphenation Processing
+.\" --------------------------------------------------------------------
+.
+.TP
+.FONT CB .HYPHENATE
+Enable
+.IR "hyphenation mode" .
+.
+This is the default when starting up.
+.
+The
+.FONT CB RUNOFF
+program used a small
+.I glossary
+for splitting.
+.
+In
+.I hyphenation mode
+.FONT CB RUNOFF
+would try to find a word 1n the glossary which is the same (except for
+the endings
+.FONT CB \-S R ,
+.FONT CB \-ES R ,
+.FONT CB \-ED R ,
+and
+.FONT CB \-E R )
+as the word at the end of the line of text.
+.
+When running in
+.BR groff (1)
+there are
+.I glossaries
+being much more complete than in
+.BR RUNOFF .
+.
+.
+.TP
+.FONT CB .NOHYPHEN
+Disable
+.IR "hyphenation mode" .
+.
+.
+.TP
+.FONT CB .GLOSSARY I " word"
+This command inserts words into the
+.I glossary
+for use in
+.IR hyphenation .
+.
+Each word should have the form
+.FONT CB hy\[hy]phen\[hy]ate
+and be separated by spaces.
+.
+.
+.TP
+.FONT CB ".HYPHENATION BREAK" I " n"
+This command set the parameter which determines the allowable number
+of spaces to te inserted in a line before
+.FONT CB RUNOFF
+tried to hyphenate the last word.
+.
+Each space counts ten points.
+.
+If more than
+.I n
+points per word would have to be inserted, then
+.I hyphenation
+will be attempted.
+.
+The initial setting of this parameter is 5 (one\-half space per word).
+.
+.
+.\" --------------------------------------------------------------------
+.SS Margin Controls
+.\" --------------------------------------------------------------------
+.
+There are two types of margins involved in
+.FONT CI RUNOFF R .
+.
+.
+.TP
+(1)
+The physical margins.
+.
+These are determined by the nature of the printing device.
+.
+The margins outline the area where it is physically possible to print
+characters.
+.
+.
+.TP
+(2)
+.
+The logical margins.
+.
+These can be set bv the user as he wishes.
+.
+(Limits are imposed by the physical margins.)
+.
+They are initialized for standard 8.5\[dq] by 11\[dq] printing.
+.
+.
+.P
+Commands concerning vertical and horizontal margins are:
+.
+.
+.TP
+.FONT CB ".PAGE LAYOUT TM, EM, TOL"
+This sets the vertical logical margins and vertical tolerence.
+.
+Parameters are top margin, bottom margin and tolerance.
+.
+The tolerance is used to determine where to break between pages on
+page overflows.
+.
+If
+there is a line break within
+.I TCL lines
+of the bottom,
+.FONT CB RUNOFF
+will break the page there; otherwise it will fill the page completely.
+.
+.
+.TP
+.FONT CB ".LINE LAYOUT LM, RM, NO, CS"
+This sets the logical left and right margin, the number of columns,
+and the number of spaces to insert between columns.
+.
+These margins are used for the page headings.
+.
+To adjust the relative
+text position, use the subsequent commands.
+.
+.
+.TP
+.FONT CB ".REDUCE MARGIN LM, RM"
+.TQ
+.FONT CB ".EXPAND MARGIN LM, RM"
+.TQ
+.FONT CB ".END REDUCTION"
+These commands enable the user to indent a certain portion of his text
+using the first command, or
+.FONT CB .UNDENT
+his text using the second command.
+.
+In either case the original margins are restored by the third command.
+.
+The use of several
+.FONT CB ".REDUCE MARGIN"
+commends before the corresponding
+.FONT CB ".END REDUCTION"
+commands succesively indents the text more, and more.
+.
+Thus these commands are 1ike brackets (i.e. recursive).
+.
+.FONT CB LM
+is added to the left logical margin and
+.FONT CB RM
+is subtracted from the right logical margin in the first command.
+.
+Just
+the opposite is done on the second command.
+.
+Negative numbers are permitted.
+.
+These commands do not effect the position of page headings.
+.
+.
+.TP
+.FONT CB ".LAYOUT PLM, PRM, PTM, PBM, LL, LO"
+This command defines the physical margins in the followinq complex
+manner.
+.
+(It should only be used for non\-standard devices, normally this
+command should not be necessary.)
+.
+The parameters are the physical left margin (in spaces), the physical
+right margin, the physical top 1ine, the physical bottom line, the
+line lenqth, and line origin.
+.
+The first four parameters define the physical 1imits of the printing
+device.
+.
+The final two parameters define the length of the logical line and its
+origin with respect to the left edge of the paper.
+.
+Printing starts at column
+.FONT CB "LO + LM" R ,
+and ends at
+.FONT CB "LO + RM" R ,
+where
+.FONT CB LM
+and
+.FONT CB RM
+are the logical margins established by
+.FONT CB ".LINE LAYOUT" R .
+.
+When using the
+.FONT CI "facing feature"
+(see
+.FONT CB ".PAGING MODE" R ),
+the logical left margin is
+.FONT CB "LL \[em] RM"
+on even pages, and the right margin is
+.
+.FONT CB "LL \[em] LM" R .
+.
+The parameters for the layout command must satisfy:
+.
+.RS
+.RS
+.nh
+.nf
+.ft CB
+.nop "min(LO + LL \[em] PLM, PRM \[em] LO) > max(PLM \[em] LO, \
+LO + LL \[em] PRM)\f[],\f[CB]"
+.nop LL > 25\f[], and \f[CB]PBM \[em] PTM > 6\f[]
+.fi
+.hy
+.RE
+.
+.
+.P
+This command sets
+.FONT CB LM
+to 15,
+.FONT CB RM
+to
+.FONT CB "LL \[em] 10" R ,
+.FONT CB TM
+to
+.FONT CB PTM R ,
+and
+.cb BM
+to
+.FONT CB "PBM \[em] 6" R .
+.
+(These margin settings produce the standard 1.5 inch left, and 1 inch
+right, too, and bottom margins.)
+.
+.RE
+.
+.
+.P
+Initially
+.FONT CB RUNOFF
+sets the margins for
+.I teletype
+output to:
+.
+.
+.RS
+.RS
+.nh
+.nf
+.ft CB
+.nop .LAYOUT 6, 89, 6, 66, 8S, 0
+.nop .LINE LAYOUT 15, 75
+.nop .FILL
+.ft
+.fi
+.hy
+.RE
+.RE
+.
+.
+.P
+The printer layout is:
+.
+.RS
+.RS
+.nh
+.nf
+.ft CB
+.nop ".layout 5, 137, 6, 66, 85, 15"
+.nop ".page layout 6, 60, 4"
+.ft
+.fi
+.hy
+.RE
+.RE
+.
+.P
+The logical margins must satisfy:
+.
+.RS
+.RS
+.nh
+.nf
+.ft CB
+.nop min(LL, PRM \[em] LO, LO \[em] LL \[em] PLM) >= RM >
+.nop "     LM >= max(0, PLM \[em] LO, LO + LL \[em] PRM)" \f[],\f[CB]
+.nop "PBM >= BM > TM >= PTM" "\f[], and\f[CB]"
+.nop BM \[em] TM > TOL\f[].
+.fi
+.hy
+.RE
+.RE
+.
+.
+.\" --------------------------------------------------------------------
+.SS Paragraph Formatting
+.\" --------------------------------------------------------------------
+.
+.TP
+.FONT CB ".PARAGRAPH SPACING" I " n"
+.
+This specifies how many lines are to be inserted between paragraphs.
+.
+Initial setting = 1.
+.
+.
+.TP
+.FONT CB ".PARAGRAPH INDENTATION" I " n"
+This specifies how many additional spaces to insert at the beginning
+of a paragraph.
+.
+Initial setting = 5.
+.
+.
+.TP
+.FONT CB ".PARAGRAPH UNDENTATION" I " n"
+This command is the same as
+.FONT CB ".PARAGRAPH INDENTATION" I " \-n" R .
+.
+That is,
+.I n
+fewer spaces are inserted at the beginning of the paragraph.
+.
+.
+.\" --------------------------------------------------------------------
+.SS Special Line Justification and Control
+.\" --------------------------------------------------------------------
+.
+These commands pertain to the next logical line.
+.
+The end of the line should be designated with a break.
+.
+.
+.TP
+.FONT CB .CENTER
+.
+Center the next line.
+.
+.
+.TP
+.FONT CB .INDENT I " n"
+.
+Indent the next line
+.I n
+spaces.
+.
+If
+.I n
+is not provided, 5 is assumed.
+.
+.
+.TP
+.FONT CB .UNDENT I " n"
+.
+Start the next line
+.I n
+spaces to the left of the normal margin.
+.
+This command is the same as
+.FONT CB .INDENT I " \-n" R .
+.
+.
+.TP
+.FONT CB .MARGIN
+Justify the next 1ine against the right hand margin.
+.
+.
+.\" --------------------------------------------------------------------
+.SS Heading and Paging
+.\" --------------------------------------------------------------------
+.
+.TP
+.FONT CB .HEADER I " XXXXXXX"
+.FONT CB RUNOFF
+accepts a heading to go on the first line of
+each paqe.
+.
+The heading strinq is assured to start at the first non\-blank
+character after thd control word and end at carriage return.
+.
+.
+.TP
+.FONT CB ".HEADING MODE" I " <param>"
+.I <param>
+determines the position of the heading on the 11ne.
+.
+.I <param>
+may be any of the following.
+.
+.
+.RS
+.
+.TP
+.FONT CB CENTER
+The header will be centered on the 1ine.
+.
+.
+.TP
+.FONT CB MARGIN
+The header will be adjusted against the riqht margin.
+.
+.
+.TP
+.FONT CB PAGING
+On even numbered pages the header is adjusted against the right
+margin.
+.
+On odd pages it is adjusted against the left mergin.
+.
+.
+.TP
+.FONT CB OPPOSED
+The header will be adjusted against the opposite margin from the
+page numter.
+.
+This is the initial mode.
+.
+.RE
+.
+.
+.TP
+.FONT CB ".PAGING MODE" I " <param>"
+.
+This command determines the placing of the page number.
+.
+All parameters are optional.
+.I <param>
+may be anyone or more of the following oommands.
+.
+In case of conflict the latest command wins.
+.
+.RS
+.
+.TP
+.FONT CB CENTER
+The page numbers are centered between the logical margins.
+.
+.TP
+.FONT CB MARGIN
+The page number is adjusted against the right margin.
+.
+.TP
+.FONT CB FACING
+On even numbered pages the number will be adjusted against the right
+margin.
+.
+On odd numbered pages tne number will be adjusted against the
+left margin.
+.
+.TP
+.FONT CB TOP
+Page numbers are placed on the first line.
+.
+.TP
+.FONT CB BOTTOM
+Page numbers are placed on the last line.
+.
+.TP
+.FONT CB OFF
+Printing page numbers is discontinued.
+.
+.TP
+.FONT CB .PREFIX I " <string>"
+.TQ
+.FONT CB .SECTION I " <string>"
+.TQ
+.FONT CB .SUFFIX I " <string>"
+The strings of characters between quotation marks are used to form the
+page string, which has the form:
+.
+.RS
+.I <prefix><section><page number><suffix>
+.
+.P
+Any or all of these strings mav be null.
+.
+The section string is considered to be part of the page number for
+purposes of indexing.
+.
+.RE
+.P
+Initial mode is:
+.
+.RS
+.RS
+.ft CB
+.nop ".PAGING MODE TOP MARGIN PREFIX \[dq]Page\[dq]"
+.nop ".PAGING MODE SECTION \[dq]\[dq] SUFFIX \[dq]\[dq]"
+.RE
+.RE
+.
+.
+.P
+If neither page number nor heading is used, the text will start on the
+first logical line.
+.
+Otherwise it will start on the fourth logical line.
+.
+If the page number is at the bottom, text will end on the fourth line
+from the bottom.
+.
+If the paging and headinq mode conflict, the page string overwrites
+the heading.
+.
+.RE
+.
+.
+.TP
+.FONT CB ".ODD PAGE"
+This
+.FONT CI "control word"
+causes the ourrent page to be printed out and the next page to be
+started with the next higher odd number.
+.
+.
+.TP
+.FONT CB .PAGE I " n"
+If
+.I n
+is present, insert a page break and start numbering the next pege
+with
+.IR n .
+Otherwise, turn the
+.I paging mode
+on and do not insert a page break.
+.
+.
+.TP
+.FONT CB .EJECT I " n"
+Insert a page break if either there are fewer than
+.I n
+lines left on the page or
+.I n
+is not present.
+.
+.
+.\" --------------------------------------------------------------------
+.SS Lines and Spacing
+.\" --------------------------------------------------------------------
+.
+.TP
+.FONT CB ".SINGLE SPACE"
+Sing1e space all 1ines within paragraphs.
+.
+This is the initial state.
+.
+.
+.TP
+.FONT CB ".DOUBLE SPACE"
+Double space all lines within paragraphs.
+.
+.
+.TP
+.FONT CB .SPACE I " n"
+Output
+.I n
+1ine spaces.
+.
+If
+.I n
+is not provided, 1 is assumed.
+.
+In case of page overflow all remaining blank 1ines to be output are
+deleted.
+.
+.
+.TP
+.FONT CB ".FIGURE SPACING" I " n"
+This command is equivalent to
+.FONT CB .EJECT I " n"
+followed by
+.FONT CB .SPACE
+.IR n .
+.
+These commands provide the only means of creatinq blank 11nes.
+.
+.
+.TP
+.FONT CB .BREAK
+The lines before and after this command will not be run together in
+.IR "fill mode" .
+.
+A simpler way to get a line break is to insert one or more blank lines
+in the text.
+.
+.
+.TP
+.FONT CB ".BEGIN GROUP"
+.TQ
+.FONT CB ".END GROUP"
+The output lines enclosed between these two commands are forced to lie
+on a page.
+.
+Thus this command acts in a manner similar to
+.FONT CB .EJECT I " n" R ,
+where
+.I n
+has the 'right' value.
+.
+.
+.\" --------------------------------------------------------------------
+.SS Miscellanous
+.\" --------------------------------------------------------------------
+.
+.TP
+.FONT CB .UNDERLINE
+The following 1ine is underlined.
+.
+.
+.TP
+.FONT CB .LITERAL
+The next line is taken as part of text whether or not
+it begins with dot.
+.
+.
+.TP
+.FONT CB .ESCAPE I <char>
+.TQ
+.FONT CB .SHIFT I <char>
+.TQ
+.FONT CB ".TAB CHARACTER" I <char>
+The given character becomes the
+.IR escape ,
+.IR shift ,
+or
+.I tab
+character.
+.
+The parameter for the
+.FONT CB .SHIFT
+and
+.FONT CB ".TAB CHARACTER"
+commands may be null, if no
+.I shift
+or
+.I tab
+character is desired.
+.
+.
+.TP
+.FONT CB ".DEFINE COMMAND" I " <name>"
+.TQ
+.FONT CB ".END COMMAND"
+.TQ
+.FONT CB .CALL I " <name>"
+These commands give the user the opportunity to combine text and
+control lines to form his own commands.
+.
+All text and command lines between the first and second commands is
+stored away under
+.IR name .
+.
+When the third command is executed, the stored string is read and the
+commands within the string are executed.
+.
+Recursion is not permitted.
+.
+.
+.TP
+.FONT CB .INDEX I " <phrase>, <phrase>"
+.
+.FONT CB RUNOfF
+saves the first phrase in the main index table and the second phrase
+(if any) in a sub\-index table associated with the first phrase.
+.
+.RS
+.
+The index is formatted and output after the last page of text.
+.
+Two built\-in but redefinable formats,
+.FONT CI RINDEX
+and
+.FONT CI SINDEX R ,
+are used to format the index as shown in the following example.
+.
+.RS
+.nh
+.nf
+.FONT CB "Algorithms, 40, 78," R "             \[rs]\[dq] uses " I RINDEX
+.FONT CB "  analysis of, 27, " R "             \[rs]\[dq] uses " I SINDEX
+.fi
+.hy
+.RE
+.
+.
+The following lines give the initial definitions for the indexing
+formats.
+.
+.
+.RS
+.nh
+.nf
+.ft CB
+.nop ".define format RINDEX f(A)"
+.nop "AAAAAAAAAAAAAAAAAAAAAAAAAAA"
+.nop "    AAAAAAAAAAIAAAAAAAAAAAA"
+.nop ".end format"
+.nop ".define format SINDEX f(A)"
+.nop "  AAAAAAAAAAAAAAAAAAAAAAAAA"
+.nop "    AAAAAAAAAAIAAAAAAAAAAAA"
+.nop ".end format"
+.ft
+.fi
+.hy
+.RE
+.
+.
+In order to get an index output in two columns,
+.RS
+.P
+.FONT CB ".LINE LAYOUT 15, 75, 2, 4"
+.P
+should be the last line of the input.
+.RE
+.
+.RE
+.
+.
+.\" --------------------------------------------------------------------
+.SH RUNOFF DOCUMENTATION 1974
+.\" --------------------------------------------------------------------
+.
+This document is the best documentation about text lines.
+.
+Parts of that is used in the document of 1981.
+.
+The documentation of text lines is the best at all.
+.
+This is reguarded above.
+.
+.
+.P
+The documentation of commands will be including later on.
+.
+.
+.\" --------------------------------------------------------------------
+.SH RUNOFF COMMAND ADDITIONS 1981
+.\" --------------------------------------------------------------------
+.
+The following
+.I commands
+will be recognized if they are at the beginning of a line started with
+a period.
+.
+Any line in the source file beginning with a period is assumed to be
+one of these
+.IR commands .
+.
+If it is not, an
+.I error diagnostic
+will be typed and the line will be ignored.
+.
+Some
+.I commands
+take one or more decimal numeric arguments.
+.
+These are separated from the
+.I command
+by a
+.FONT CR space R .
+.
+More than one
+.I command
+may be entered on a single line by separating the
+.I commands
+with a
+.FONT CI semicolon
+.FONT R ` CB ; R '
+or a
+.FONT CI period
+.FONT R ` CB . R '.
+.
+.
+.P
+.I Multi\-word commands
+may appear in any form.
+.
+Thus,
+.FONT CB ".NO HEADER"
+and
+.FONT CB .NOHEADER
+are both legal.
+.
+.
+.P
+Many
+.I commands
+may be abbreviated.
+.
+Standard
+.I abbreviations
+are given below each
+.IR command .
+.
+.
+.\" --------------------------------------------------------------------
+.SS Text Formatting Commands
+.\" --------------------------------------------------------------------
+.
+.TP
+.FONT CB .BREAK
+.TQ
+.FONT CB .BR
+causes a
+.IR break ,
+i.e. the current line will be output with no
+.IR justification ,
+and the next word of the source text will be placed at the beginning
+of the next line.
+.
+.
+.TP
+.FONT CB .SKIP CI " n"
+.TQ
+.FONT CB .SK CI " n"
+.TQ
+.FONT CB .S CI " n"
+causes a BREAK after which
+.CI n
+is multiplied by the number of
+.I spaces
+between lines.
+.
+The result is the number of lines
+.IR skipped .
+.
+Output is advanced to the top of the next page if there is no room on
+the current page.
+.
+If the current page is empty,
+.FONT CB .SKIP
+does nothing.
+.
+.
+.TP
+.FONT CB .BLANK I " n"
+.TQ
+.FONT CB .B I " n"
+causes the current line to be output with no
+.IR justification ,
+skips
+.FONT CI n
+line spaces, and then starts output of the current source text.
+.
+.FONT CB .BLANK
+is like
+.FONT CB .SKIP R ,
+except that the
+.I space
+to be left is independent of line spacing.
+.
+If the page is empty,
+.FONT CB .BLANK
+does nothing.
+.
+.
+.TP
+.FONT CB .FIGURE I " n"
+.TQ
+.FONT CB .FG I " n"
+leaves
+.I n
+lines blank to make room for a figure or diagram.
+.
+If fewer than
+.I n
+lines remain on the current page, text continues to
+.I fill
+this page, then the page is advanced and
+.I n
+blank lines are left at the top of the next page.
+.
+.
+.TP
+.FONT CB .INDENT I " n"
+.TQ
+.FONT CB .I I " n"
+causes a
+.CI break
+and sets the next line to begin
+.I n
+spaces to the right of the left margin.
+.
+The
+.I n
+can be negative to allow beginning a line to the left of the left
+margin.
+.
+However, a line cannot begin to the left of column 0.
+.
+If
+.I n
+is not supplied, the current paragraph indent is used.
+.
+.
+.TP
+.FONT CB .PARAGRAPH I " n, v, t"
+.FONT CB .P I " n, v, t"
+causes a
+.I break
+and formats the output paragraphs.
+.
+The
+.I n
+is optional and, if present, sets the number of spaces the paragraph
+is to be indented.
+.
+The default value for
+.I n
+is
+.FONT CB 5
+.RI ( n
+can also have a negative value).
+.
+.I v
+is the vertical spacing between paragraphs.
+.
+.I v
+can range from
+.FONT CB 0
+to
+.FONT CB 5 R .
+.
+.FONT R ( CB 1
+is
+.IR "single spacing" ,
+.FONT CB 2
+is
+.IR "double spacing" ,
+etc.)
+.
+.I t
+causes an automatic
+.FONT CI ".TEST PAGE"
+(see the
+.FONT CB ".TEST PAGE"
+.IR command ).
+.
+.
+.TP
+.FONT CB .CENTER I " n" CB ; I text
+.TQ
+.FONT CB .CENTRE I " n" CB ; I text
+.TQ
+.FONT CB .C I " n" CB ; I text
+causes a
+.I break
+and centers the following text in the source file.
+.
+The centering is over column
+.FONT CB ( I n CB " + " I "left margin" CB )/2 R .
+If
+.I n
+is not given, it is assumed to be the
+.
+.IR "right margin" .
+.
+.
+.RS
+.P
+.ce
+NOTE
+.
+.P
+.FONT CB .CENTER R ,
+.FONT CB ".RIGHT MARGIN" R ,
+.FONT CB ".LEFT MARGIN" R ,
+.FONT CB ".PAGE SIZE" R ,
+and
+.FONT CB .STANDARD
+take both relative and absolute values.
+.
+Relative values are expressed as
+.FONT CB + I n
+or
+.FONT CB \- I n R ,
+while absolute values of
+.I n
+are unsigned.
+.RE
+.
+.
+.TP
+.FONT CB .FOOTNOTE I " n"
+.TQ
+.FONT CB .FN I " n"
+saves
+.I n
+lines at the bottom of the current page for a
+.IR footnote .
+.
+The
+.I n
+is multiplied by the number of spaces set with the
+.FONT CB .SPACING
+command.
+.
+If insufficient room remains on the current page, space is allocated
+at the bottom of the following page.
+.
+The text of the
+.I footnote
+should begin on the line following the
+.FONT CB .FOOTNOTE
+command.
+.
+.IR Indentation ,
+.IR "case lock" ,
+.IR justify ,
+.IR margins ,
+.IR spacing ,
+and
+.I fill
+are preserved around footnotes.
+.
+However,
+.I commands
+that affect page formatting are illegal in a
+.IR footnote .
+.
+.I Tab stops
+are illegal because they are not preserved.
+.
+A footnote within a footnote is also illegal.
+.
+.
+.P
+The actual space taken by a footnote can be more or less than
+specified by
+.IR n .
+If necessary
+.FONT CR adjust
+.I n
+after examining a draft printout.
+.
+.
+.P
+The
+.I footnote
+is terminated with a line beginning with an exclamation point (the
+remainder of which is ignored).
+.
+.
+.TP
+.FONT CB .NOTE I " text"
+.TQ
+.FONT CB .NT I " text"
+starts an
+.IR "indented note" .
+.
+This command
+.I blanks
+.FONT CB 2 R ,
+reduces both
+.IR margins ,
+.I centers
+the text (if no text is given, it centers the word
+.FONT CB NOTE R ),
+and then
+.I blanks
+.FONT CB 1 R .
+.
+At this point you enter the text of the
+.IR note .
+.
+If the left margin is at
+.FONT CB 0 R ,
+the
+.I margin reduction
+is
+.FONT CB 15 R ,
+otherwise it is
+.FONT CB 5 R .
+.
+.
+.TP
+.FONT CB ".END NOTE"
+.TQ
+.FONT CB .EN
+terminates the
+.FONT CB .NOTE
+command,
+.I blanks
+.CONT CB 2 R ,
+and reverts the margins and spacing modes to their settings before the
+last
+.FONT CB .NOTE
+command.
+.
+.
+.TP
+.FONT CB .LIST I " n"
+.FONT CB .LS I " n"
+starts an indented list with
+.I n
+spacing, moves the left margin
+.FONT CB 9
+spaces to the right for the first
+.FONT CB .LIST
+command, and
+.FONT CB 4
+more spaces for each subsequent nested
+.FONT CB .LIST R .
+.
+The normal
+.I fill
+and
+.I justify modes
+remain in effect.
+.
+Therefore, you must disengage them just after the
+.FONT CB .LS
+command if you want a ragged right.
+.
+.
+.TP
+.FONT CB ".LIST ELEMENT;" I " text"
+.TQ
+.FONT CB .LE; I " text"
+starts an item in the list, used in conjunction with the
+.FONT CB .LIST
+comand.
+.
+The elements are numbered sequentially and the number is given a
+negative indent so that the list lines up.
+.
+The number is followed by a
+.I period
+and two
+.I spaces
+so that the indent will be by 
+.FONT CB \-4 R .
+.
+The
+.I list elements
+are separated by the standard paragraph spacing and
+.FONT CI "TEST PAGE" R .
+.
+If you want to type the text on the same line as the command, you must
+separate the text from the command with any number of intervening
+.I spaces
+or
+.IR tabs ,
+or (optionally) one
+.IR semicolon .
+.
+.
+.TP
+.FONT CB ".END LIST"
+.TQ
+.FONT CB .ELS
+terminates the
+.FONT CB .LIST
+command and returns to settings before the last
+.FONT CB .LIST
+command.
+.
+.
+.TP
+.FONT CB .COMMENT I " text"
+.TQ
+.FONT CB .; I " text"
+causes the line to be ignored.
+.
+The text is not printed in the output file, but rather is used as a
+.I comment
+line in the source text.
+.
+.
+.\" --------------------------------------------------------------------
+.SS Page Formatting Commands
+.\" --------------------------------------------------------------------
+.
+.TP
+.FONT CB .PAGE
+.FONT CB .PG
+causes a
+.I break
+and an
+.I advance
+to a new page.
+.
+If the current page is empty, this
+.I command
+does not
+.I advance
+the page.
+.
+Just like an
+.IR "automatic page advance" ,
+this
+.I command
+prints the
+.I title
+(if given) and
+.I page numbers
+on every page.
+.
+.
+.TP
+.FONT CB ".TEST PAGE" I " n"
+.TQ
+.FONT CB .TP I " n"
+causes a
+.I break
+followed by a
+.IR "conditional page advance" .
+.
+It skips to the next page if fewer than
+.I n
+lines are left on the page.
+.
+This capability is to ensure that the following
+.I n
+lines are all output on the same page.
+.
+This
+.I command
+has the form
+.I t
+as an optional argument to the
+.FONT CB .PARAGRAPH
+command.
+.
+.
+.TP
+.FONT CB .NUMBER I " n"
+.TQ
+.FONT CB .NM I " n"
+starts page numbering.
+.
+This is the default so there is no reason to issue this command unless
+page numbering is disengaged.
+.
+If
+.I resumption
+of page numbering is desired at a certain page, specify
+.IR n .
+.
+.
+.TP
+.FONT CB .NONUMBER
+.FONT CB .NNM
+disengages page numbering.
+.
+However, pages continue to be counted, so that the normal page number
+can appear if page numbering is re\-entered with the
+.FONT CB .NUMBER
+command.
+.
+.
+.TP
+.FONT CB .CHAPTER I " text"
+.TQ
+.FONT CB .CH I " text"
+starts a new chapter using the text as the title of the chapter.
+.
+This
+.I command
+acts as if the following
+.I command string
+were entered:
+.
+.
+.P
+.EX
+.nop ".BREAK;.PAGE;.BLANK 12;.CENTER;CHAPTER n"
+.EE
+.P
+The
+.I n
+is incremented by
+.FONT CB 1
+automatically.
+.
+After the CHAPTER
+.I n
+is typed on the page,
+.
+.
+.P
+.EX
+.nop .BLANK 2;.CENTER;text;.BLANK 3
+.EE
+.P
+occurs.
+.
+This
+.I command
+then resets the
+.IR case ,
+.IR margins ,
+.IR spacing ,
+and
+.IR "justify/fill modes" .
+.
+It also clears any
+.I subtitles
+and sets the
+.I chapter name
+as the
+.IR title .
+.
+.
+.TP
+.FONT CB ".NUMBER CHAPTER " I " n"
+supplies a number
+.I n
+to be used in a subsequent
+.FONT CB .CHAPTER
+command.
+.
+.FONT CB ".NUMBER CHAPTER"
+would be used when a
+.I chapter
+of a document occupies a source file of its own.
+.
+In such a case,
+.FONT CB ".NUMBER CHAPTER"
+would be the first command of the source file.
+.
+.
+.TP
+.FONT  CB ".HEADER LEVEL" I " n text"
+.TQ
+.FONT CB .HL I " n text"
+starts a section at the level specified and takes the following text
+as the header.
+.
+.I n
+can range from
+.FONT CB 1
+to
+.FONT CB 5 R .
+.
+The sections are incremented by
+.FONT CB 1
+automatically, and the number is output in the form
+.FONT I i CB . I j CB . I k CB . I l CB . I m R .
+If this is a chapter oriented document, the
+.I i
+is the chapter number.
+.
+Otherwise, it is the number of the
+.FONT CB ".HL 1"
+level.
+.
+This command acts as a
+.
+.P
+.EX
+.FONT CB ".BREAK;.TEST PAGE 9;.BLANK 3"
+.EE
+.
+.P
+followed by the
+.IR "section number" ,
+two
+.IR spaces ,
+and the
+.IR "section name" .
+.
+.FONT CI "HEADER LEVELS " CB 1
+and
+.FONT CB 2
+end with a
+.IR break .
+.FONT CI "HEADER LEVELS"
+.FONT CB 3 R ", " CB 4 R ,
+and
+.FONT CB 5
+end with a space\-dash\-space combination (#\-#).
+.
+.
+.TP
+.FONT CB .TITLE I " text"
+.TQ
+.FONT CB .T I " text"
+takes the remaining text as the title and outputs it on every page at
+line
+.FONT CB 0 R .
+.
+The default is no title.
+.
+If a
+.I title
+is desired, this
+.I command
+must be entered in the source file.
+.
+.
+.TP
+.FONT CB ".FIRST TITLE" I " text"
+.TQ
+.FONT CB ".FT" I " text"
+Same as
+.FONT CB .TITLE R ,
+but used to specify the title to be printed on the first page of the
+document.
+.
+This command must precede all text in the source file.
+.
+Use of the
+.FONT CB ".FIRST TITLE"
+command is the only way to print a title line on the first page of the
+document.
+.
+.
+.TP
+.FONT CB .SUBTITLE I " text"
+.TQ
+.FONT CB .SUBTTL I " text"
+.TQ
+.FONT CB .ST I " text"
+takes the remaining text as the
+.I subtitle
+and outputs it on every page.
+.
+It appears directly under the title.
+.
+The
+.I subtitle
+is not
+.IR indented ,
+but
+.I indentation
+can be achieved by typing leading spaces.
+.
+.
+.TP
+.FONT CB .INDEX I " text"
+.TQ
+.FONT CB .X I " text"
+takes the remaining text on the line as a keyword and adds it, along
+with the current
+.IR "page number" ,
+to the internal index buffer.
+.
+The command does not cause a
+.IR break .
+.
+It should appear immediately before the item to be
+.IR indexed .
+.
+A keyword may be
+.I indexed
+more than once.
+.
+.
+.TP
+.FONT CB ".DO INDEX" I " text"
+.TQ
+.FONT CB ".DX" I " text"
+forces a new page, centers the text, if given, otherwise it centers
+the word
+.FONT CI "INDEX" R .
+.
+This command prints the entire contents of the index buffer.
+.
+Entries are printed in alphabetic order and are set against the left
+margin.
+.
+Regular line spacing is used, except that a blank line is left between
+entries of different first letters.
+.
+The page number of each entry is placed on the same line as the entry
+and in the middle of the page.
+.
+Additional page numbers for multiple entries follow, separated by
+commas.
+.
+The index buffer is left empty.
+.
+.
+.TP
+.FONT CB ".PRINT INDEX"
+.TQ
+.FONT CB ".PX"
+forces a new page after which it prints the entire contents of the
+index buffer.
+.
+Entries are printed in alphabetical order and are set against the left
+margin.
+.
+Regular line spacing is used, except that a blank line is left between
+entries of different first letters.
+.
+The number of the first page on which each entry appeared is put on
+the same line as the entry, beginning at the middle of the line
+(midway betweeen the left and right margins).
+.
+Additional page numbers for multiple entries follow, separated by
+commas.
+.
+The index buffer is left empty.
+.
+.
+.P
+.FONT CB ".PRINT INDEX"
+and
+.FONT CB ".DO INDEX"
+perform the same task.
+.
+The only difference is that
+.FONT CB ".PRINT INDEX"
+does not interrupt the normal chapter and page sequencing.
+.
+.
+.TP
+.FONT CB .SUBPAGE
+executes a
+.FONT CB .PAGE
+with page numbering suspended.
+.
+The page number is unchanged, but letters are appended to the page
+number.
+.
+This permits insertion of additional pages within an existing document
+without changing the existing page numbering.
+.
+.
+.TP
+.FONT CB ".END SUBPAGE"
+disengages the
+.FONT CB .SUBPAGE
+command by executing a
+.FONT CB .PAGE
+command with page numbering resumed.
+.
+.
+.TP
+.FONT CB .APPENDIX I " text"
+.TP
+.FONT CB .AX I " text"
+starts a new appendix using the text as the title of the appendix.
+.
+This command acts as if the following command string were entered:
+.
+.RS
+.P
+.EX
+.nop ".BREAK;.PAGE;.BLANK 12;.CENTER;APPENDIX a"
+.EE
+.RE
+.P
+The a is a letter that is incremented alphabetically automatically.
+.
+After the
+.FONT CB "APPENDIX A"
+is typed on the page,
+.
+.RS
+.P
+.EX
+.nop .BLANK 2;.CENTER;text;.BLANK 3
+.EE
+.RE
+.
+.P
+occurs.
+.
+This command then resets the
+.IR case ,
+.IR margins ,
+.IR spacing ,
+and
+.IR justify/fill
+modes.
+.
+It also clears any subtitles and sets the appendix name as the title.
+.
+.
+.TP
+.FONT CB ".NUMBER APPENDIX" I " a"
+supplies a letter
+.I a
+to be used as the letter for a subsequent
+.FONT CB .APPENDIX
+command.
+.
+.
+.TP
+.FONT CB .HEADER I " arg"
+.TQ
+.FONT CB .HD I " arg"
+causes the page header
+.RI ( title ,
+.IR subtitle ,
+and
+.IR "page number" )
+to be printed.
+.
+.I arg should be
+.FONT CB UPPER
+to specify
+.I upper case characters
+for the title text,
+.FONT CB LOWER
+to specify
+.IR "lower case" ,
+or
+.FONT CB MIXED R .
+.
+The initial setting is
+.FONT CB ".HEADER UPPER" R .
+.
+.
+.TP
+.FONT CB .NOHEADER
+.TP
+.FONT CB .NHD
+causes the page header
+.RI ( title ,
+.IR subtitle ,
+and
+.IR "page number" )
+to be omitted.
+.
+The header lines are completely omitted, so that text begins at the
+top of the page with no
+.IR "top margin" .
+.
+.
+.\" --------------------------------------------------------------------
+.SS Mode Setting Commands
+.\" --------------------------------------------------------------------
+.
+.TP
+.FONT CB .JUSTIFY
+.TQ
+.FONT CB .J
+causes a break and sets subsequent output lines to be justified
+(initial setting).
+.
+The
+.I command
+increases the spaces between words until the last word exactly meets
+the right margin.
+.
+.
+.TP
+.FONT CB .NOJUSTIFY
+.TQ
+.FONT CB .NJ
+causes a
+.I break
+and prevents
+.I justification
+of subsequent output lines to make a ragged right margin.
+.
+.
+.TP
+.FONT CB .FILL
+.TQ
+.FONT CB .F
+causes a break and specifies that subsequent output lines be filled
+(inital setting).
+.
+Sets the justification mode to be that specified by the last
+appearance of
+.FONT CB  .JUSTIFY
+or
+.FONT CB .NOJUSTIFY R .
+.
+.FONT CB .FILL
+adds successive words from the source text until the adding of one
+more word will exceed the right margin.
+.
+It stops before putting the last word in.
+.
+(If
+.I hyphenation
+has not been disabled,
+.FONT CB RNO
+will attempt to
+.I break
+words which cause line overflow into syllables.)
+.
+.
+.TP
+.FONT CB .NOFILL
+.TP
+.FONT CB .NF
+disengages the
+.I fill
+and
+.IR "justify modes" .
+.
+This
+.I command
+is used to permit typing a table.
+.
+.
+.RS
+.
+.
+.P
+.ce
+NOTE
+.
+.P
+1. The
+.I nofill\-nojustify mode
+need be used only where there are several lines of material to be
+copied exactly.
+.
+A single line example will not require using these commands if there
+are breaks before and after.
+.
+.
+.P
+2. Normally
+.FONT CB .FILL
+and
+.FONT CB .NOFILL
+are used to turn both
+.I filling
+and
+.I justification
+on and off.
+.
+It is usually desirable to do both.
+.
+A subsequent appearance of a
+.I justification command
+will override the
+.I fill command
+however.
+.
+.
+.P
+3. Because of the action of
+.FONT CB .FILL R ,
+a single occurrance of
+.FONT CB .NOJUSTIFY
+will cause the remainder of the file to be
+.IR unjustified ,
+with
+.I filling
+as specified.
+.
+In order to
+.I justify
+but
+.I not fill
+(not recommended), a
+.FONT CB .JUSTIFY
+command must follow every
+.FONT CB .NOFILL
+command.
+.
+.
+.RE
+.
+.
+.TP
+.FONT CB ".UPPER CASE"
+.TQ
+.FONT CB .UC
+sets the output mode to
+.IR "upper case" .
+.
+This comand acts the same as typing two
+.CI circumflexes
+.FONT CB ^^ R .
+.
+This is the default mode.
+.
+There is no need to type this command unless the mode was previously
+altered to
+.IR "lower case" .
+.
+.
+.TP
+.FONT CB ".LOWER CASE"
+.TQ
+.FONT CB .LC
+sets the typeout mode to
+.IR "lower case" .
+This command acts the same as typing two
+.I back\-slashes
+.FONT CB \[rs]\[rs] R .
+.
+.
+.TP
+.FONT CB ".FLAGS CAPITALIZE"
+.TQ
+.FONT CB ".FL CAPITALIZE"
+enables the
+.CI less\-than
+.FONT CB <
+character to
+.I capitalize
+the entire word it precedes.
+.
+It then returns the file to the current case mode.
+.
+This
+.I special character
+is usually
+.FONT CR off
+and must be typed at the very beginning of the source text to enable
+this character.
+.
+Typing a space or another
+.FONT CI "less\-than " CB <
+returns the file to the current
+.IR "case lock" .
+.
+.
+.TP
+.FONT CB ".NO FLAGS CAPITALIZE"
+.TQ
+.FONT CB .NFC
+disengages the
+.FONT CB "FLAG CAPITALIZE"
+command (inital setting).
+.
+.
+.TP
+.FONT CB .HYPHENATION
+.TQ
+.FONT CB .HY
+engages
+.I hyphenization
+(initial setting).
+.
+.
+.TP
+.FONT CB ".NO HYPHENATION"
+.TQ
+.FONT CB .NHY
+disengages
+IR hyphenization .
+.
+.
+.TP
+.FONT CB ".FLAGS HYPHENATE"
+.TQ
+.FONT CB ".FL HYPHENATE"
+enables the
+.I equals character
+.FONT CB =
+to disengage
+.I hyphenization
+for the word it precedes.
+.
+This
+.I special character
+is initially
+.FONT CR off
+and must be typed at the beginning of the source file to enable this
+character.
+.
+The
+.FONT CI "FLAGS HYPHENATE"
+.I character
+is used to disengage
+.I hyphenization
+for words improperly
+.I hyphenated
+by the
+.IR "hyphenization algorithm" .
+.
+.
+.TP
+.FONT CB ".NO FLAGS HYPHENATE"
+.TQ
+.FONT CB .NFH
+disengages the
+.FONT CB ".FLAGS HYPHENATE"
+command (initial setting).
+.
+.
+.TP
+.FONT CB .NFL
+disengages the
+.FONT CB ".FLAGS CAPITALIZE"
+and the
+.FONT CB ".FLAGS HYPHENATE"
+commands (initial setting).
+.
+.
+.TP
+.FONT CB .PERIOD
+.TQ
+.FONT CB .PR
+enables printing of two
+.I spaces
+after every
+.I period
+.FONT CB .
+that is followed by at least one
+.I separator character
+(initial setting).
+.
+.
+.TP
+.FONT CB .NOPERIOD
+.TQ
+.FONT CB .NPR
+disengages conversion of
+.I period/separator
+to
+.IR "period/two spaces" .
+.
+.
+.TP
+.FONT CB .LITERAL
+.TQ
+,FONT CB .LIT
+disengages
+.I fill/justify
+to permit printing of text exactly as entered in source file.
+.
+.
+.TP
+.FONT CB ".END LITERAL"
+.TQ
+.FONT CB .ELI
+used after
+.FONT CB .LITERAL
+command to re\-engage
+.IR fill/justify .
+.
+.
+.\" --------------------------------------------------------------------
+.SS Parameter Setting Commands
+.\" --------------------------------------------------------------------
+.
+.TP
+.FONT CB ".LEFT MARGIN" I " n"
+.TQ
+.FONT CB .LM I " n"
+sets the left margin to
+.IR n .
+.
+The
+.I n
+must be less than the right margin but not less than
+.FONT CB 0 R .
+The initial setting is
+.FONT CB 0 R .
+If
+.I n
+is not supplied,
+.FONT CB 0
+is used.
+.
+.
+.TP
+.FONT CB ".RIGHT MARGIN" I " n"
+.TQ
+.FONT CB .RM I " n"
+sets the right margin
+.IR n .
+The
+.I n
+must be greater than the left margin.
+.
+The initial setting is
+.FONT CB 60 R .
+.
+If
+.I n
+is not supplied, the current page width (set with the
+.FONT CB ".PAGE SIZE"
+command) is used.
+.
+.
+.TP
+.FONT CB ".PAPER SIZE" I " n" CB , I m
+.TP
+.FONT CB ".PAGE SIZE" I " n" CB , I m
+.TP
+.FONT CB ".PS" I " n" CB , I m
+sets the size of the page
+.I n
+lines by
+.I m
+columns and sets the right margin to
+.IR m .
+The default setting is
+.FONT CB 58,60 R .
+.
+.
+.TP
+.FONT CB .PITCH I " n" CB , I m
+.TQ
+.FONT CB .PIT I " n" CB , I m
+sets the horizontal and vertical pitch on a supporting output device.
+.
+The horizontal pitch is
+.I n
+and is specified as characters per inch.
+.
+The value must divide evenly into
+.FONT CB 60
+for
+.FONT CI "Anderson\-Jacobson devices"
+and into
+.FONT CB 120
+for
+.FONT CI "Diablo devices" R .
+.
+The default is
+.FONT CB 12 R .
+.
+.
+.P
+The vertical pitch is
+.I m
+and is specified as lines per inch.
+.
+.I m
+must divide evenly into
+.FONT CB 48 R .
+.
+The default is the hardware setting.
+.
+.I n
+and
+.I m
+may be set independently.
+.
+.
+.TP
+.FONT CB .SPACING I " n"
+.TQ
+.FONT CB .SP I " n"
+sets the number of spaces between lines.
+.
+The
+.I n
+can range from
+.FONT CB 1
+to
+.FONT CB 5 R .
+.
+The default setting is
+.FONT CB 1 R .
+.
+.FONT CB ".SPACING 1"
+is like
+.I single spacing
+on a typewriter and
+.FONT CB ".SPACING 2"
+is like
+.IR "double spacing" .
+.FONT CB ".SPACING 2"
+puts one
+.I blank line
+between lines of text.
+.
+.
+.TP
+.FONT CB .STANDARD I " n"
+.TQ
+.FONT CB .SD I " n"
+returns all parameters, except the pitch settings, to their initial
+settings and sets
+.I n
+as the page width.
+.
+If
+.FONT CB ".STANDARD 60"
+is specified, margins are reset
+.FONT CB ".LM 0" R ,
+.FONT CB ".RM 60" R ,
+.FONT CB ".PAGE SIZE 58,60" R ,
+.FONT CB ".SPACING 1" R ,
+.FONT CB "PARAGRAPH INDENT 5" R ,
+and
+.I fill
+and
+.I justify
+are enabled.
+.
+.FONT CB ".STANDARD 70"
+sets right margin to
+.FONT CB 70
+and
+.I page size
+to
+.FONT CB 58,70 R .
+.
+.
+.TP
+.FONT CB ".TAB STOPS" I " n" CB , I n CB , I \*[Ellipsis]
+.TQ
+.FONT CB ".TS" I " n" CB , I n CB , I \*[Ellipsis]
+sets tabs.
+.
+The
+.I  n
+must be greater than
+.FONT CB 0
+and listed in ascending order.
+.
+If tabs already exist, the issuing of another
+.FONT CB ".TAB STOPS"
+command clears all previous
+.I tabs
+before setting new ones.
+.
+The
+.I default tabs
+are set at eight\-column intervals to match the
+.FONT CR Digital
+hardware standard.
+.
+These
+.I tabs
+are at columns
+.FONT CB 8 R ,
+.FONT CB 16 R ,
+.FONT CB 24 R ,
+.FONT CB 32 R ,
+.FONT CB 40 R ,
+.FONT CB 48 R ,
+.FONT CB 56 R ,
+.FONT CB 64 R ,
+.FONT CB 72 R ,
+and
+.FONT CB 80 R .
+.
+The tabs are converted to the appropriate number of non\-expandable
+spaces.
+.
+If there are no regular spaces to the left of the
+.IR tabs ,
+they will print out at the appropriate position, even if
+.I fill
+is on.
+.
+If
+.I literal
+is on, the
+.I tabs
+are not converted to
+.IR spaces ,
+but are output as
+.IR tabs .
+.
+.
+.TP
+.FONT CB .AUTOPARAGRAPH
+.TQ
+.FONT CB .AP
+causes any
+.I blank line
+or any line starting with a
+.I space
+or
+.I tab
+to be considered as the start of a new paragraph.
+.
+This command allows normally typed text to be
+.I justified
+without special commands.
+.
+It does not cause a paragraph if
+.I blank lines
+are followed by a command.
+.
+.
+.TP
+.FONT CB .NOAUTOPARAGRAPH
+.TQ
+.FONT CB .NAP
+disengages the
+.FONT CI AUTOPARAGRAPH
+mode.
+.
+.
+.\" --------------------------------------------------------------------
+.SS List of Commands (Alphabetical)
+.\" --------------------------------------------------------------------
+.
+.if t \{
+.ig endTBL
+.\}
+.
+.\" --------------------------------------------------------------------
+.\" Table using tbl for running in tty
+.\" --------------------------------------------------------------------
+.
+.nf
+.nh
+.
+.TS
+center,allbox,tab(@);
+cIw(1.5i) sw(1.5i) cIw(1.5i).
+Command or Abbreviation@Related Commands
+=
+.
+.T&
+l l l.
+\f[CB].AP\f[R]@(=\f[CB].AUTOPARAGRAPH\f[R])@
+\f[CB].APPENDIX\f[I] text \f[R]@(=\f[CB].AX\f[R])@\f[CB].NUMBER APPENDIX\f[I] a
+\f[CB].AX\f[R]@(=\f[CB].APPENDIX\f[R])@
+\f[CB].AUTOPARAGRAPH \f[R]@(=\f[CB].AP\f[R])@T{
+\f[CB].NOAUTOPARAGRAPH
+.br
+\f[R](\f[CB].NAP\f[R])
+T}
+_
+\f[CB].B\f[R]@(=\f[CB].BLANK\f[R])@
+\f[CB].BLANK \f[I]n \f[R]@(=\f[CB].B\f[R])@T{
+7\f[CB].SKIP \f[I]n
+.br
+\f[R](\f[CB].S\f[R])
+T}
+\f[CB].BR\f[R]@(=\f[CB].BREAK\f[R])@
+\f[CB].BREAK@\f[R](=\f[CB].BR\f[R])
+_
+\f[CB].C\f[R]@(=\f[CB].CENTRE\f[R])@
+\f[CB].CENTER\f[R]@(=\f[CB].CENTRE\f[R])@
+\f[CB].CENTRE \f[I]n\f[CB];\f[I]text \f[R]@(=\f[CB].C\f[R])@
+\f[CB].CH\f[R]@(=\f[CB].CHAPTER\f[R])@
+\f[CB].CHAPTER \f[I]text \f[R]@(=\f[CB].CH\f[R])@\f[CB].NUMBER CHAPTER \f[I]n
+\f[CB].COMMENT \f[I]text\f[R]@@
+_
+\f[CB].DO INDEX \f[I]text \f[R]@(=\f[CB].DX\f[R])@T{
+.
+\f[CB].PRINT INDEX
+.br
+\f[R](\f[CB].PX\f[R])
+T}
+.
+\f[CB].DX\f[R]@(=\f[CB].DO INDEX\f[R])@
+_
+\f[CB].ELS\f[R]@(=\f[CB].END LIST\f[R])@
+\f[CB].EN\f[R]@(=\f[CB].END NOTE\f[R])@
+.
+\f[CB].END LIST\f[R]@(=\f[CB].ELS\f[R])@T{
+\f[CB].LIST \f[I]n
+.br
+\f[R](\f[CB].LS\f[R])
+T}
+.
+\f[CB].END LITERAL \f[R]@(=\f[CB].ELI\f[R])@T{
+\f[CB].LITERAL
+.br
+\f[R](\f[CB].LIT\f[R])
+T}
+.
+\f[CB].END NOTE\f[R]@(=\f[CB].EN\f[R])@T{
+\f[CB].NOTE \f[I]text
+.br
+\f[R](\f[CB].NT\f[R])
+T}
+.
+\f[CB].END SUBPAGE\f[R]@@\f[CB].SUBPAGE
+_
+\f[CB].F\f[R]@(=\f[CB].FILL\f[R])@
+\f[CB].FG\f[R]@(=\f[CB].FIGURE\f[R])@
+\f[CB].FIGURE n \f[R]@(=\f[CB].FG\f[R])@
+.
+\f[CB].FILL \f[R]@(=\f[CB].F\f[R])@T{
+\f[CB].NOFILL
+.br
+\f[R](\f[CB].NF\f[R])
+T}
+.
+\f[CB].FIRST TITLE \f[I]text\f[R]@(=\f[CB].FT\f[R])@\f[CB].TITLE \f[I]text
+.
+\f[CB].FLAGS CAPITALIZE\f[R]@(=\f[CB].FL CAPITALIZE\f[R])@T{
+\f[CB].NO FLAGS CAPITALIZE
+.br
+\f[R](\f[CB].NFL\f[R])
+T}
+.
+\f[CB].FLAGS HYPHENATE \f[R]@(=\f[CB].FL HYPHENATE\f[R])@T{
+\f[CB].NO FLAGS HYPHENATE
+.br
+\f[R](\f[CB].NFH\f[R])
+T}
+.
+\f[CB].FN\f[R]@(=\f[CB].FOOTNOTE\f[R])@
+\f[CB].FOOTNOTE \f[I]n\f[R]@(=\f[CB].FN\f[R])@
+\f[CB].FT\f[R]@(=\f[CB].FIRST TITLE\f[R])@
+_
+\f[CB].HD\f[R]@(=\f[CB].HEADER\f[R])@
+.
+T{
+\f[CB].HEADER \f[I]arg\f[R]
+.br
+\f[R]  [\f[I]arg\f[R]=\f[CB]UPPER\f[R], \f[CB]LOWER\f[R], or \f[CB]MIXED]\f[R]
+T}@(=\f[CB].HD\f[R])@T{
+\f[CB].NOHEADER
+.br
+\f[R](\f[CB].NHD\f[R])
+T}
+.
+\f[CB].HEADER LEVEL \f[I]n text\f[R]@(=\f[CB].HL\f[R])@
+\f[CB].HL\f[R]@(=\f[CB].HEADER LEVEL\f[R])@
+\f[CB].HY\f[R]@(=\f[CB].HYPHENATION\f[R])@
+.
+\f[CB].HYPHENATION \f[R]@(=\f[CB].HY\f[R])@T{
+\f[CB].NO HYPHENATION
+.br
+\f[R](\f[CB].NHY\f[R])
+T}
+.
+_
+\f[CB].I\f[R]@(=\f[CB].INDENT\f[R])@
+\f[CB].INDENT \f[I]n\f[R]@(=\f[CB].I\f[R])@
+\f[CB].INDEX \f[I]text \f[R]@(=\f[CB].X\f[R])@
+_
+\f[CB].J\f[R]@(=\f[CB].JUSTIFY\f[R])@
+.
+\f[CB].JUSTIFY \f[R](\f[CB].J\f[R])@@T{
+\f[CB].NOJUSTIFY
+.br
+\f[R](\f[CB].NJ\f[R])
+T}
+.
+_
+\f[CB].LC\f[R]@(=\f[CB].LOWER CASE\f[R])@
+\f[CB].LE\f[R]@(=\f[CB].LIST ELEMENT\f[R])@
+.
+\f[CB].LEFT MARGIN \f[I]n\f[R]@(=\f[CB].LM\f[R])@T{
+\f[CB].RIGHT MARGIN \f[I]n
+.br
+\f[R](\f[CB].RM\f[R])
+T}
+.
+\f[CB].LIST \f[I]n\f[R]@(=\f[CB].LS\f[R])@T{
+\f[CB].END LIST
+.br
+\f[R](\f[CB].ELS\f[R])
+T}
+.
+\f[CB].LIST ELEMENT;\f[I]text\f[R]@(=\f[CB].LE\f[R])@T{
+\f[CB].END LIST
+.br
+\f[R](\f[CB].ELS\f[R])
+T}
+.
+\f[CB].LIT\f[R]@(=\f[CB].LITERAL\f[R])@
+.
+\f[CB].LITERAL\f[R]@(=\f[CB].LIT\f[R])@T{
+\f[CB].END LITERAL
+.br
+\f[R](\f[CB].ELI\f[R])
+T}
+.
+\f[CB].LM\f[R]@(=\f[CB].LEFT MARGIN\f[R])@
+.
+\f[CB].LOWER CASE\f[R]@(=\f[CB].LC\f[R])@T{
+\f[CB].UPPER CASE
+.br
+\f[R](\f[CB].UC\f[R])
+T}
+.
+\f[CB].LS\f[R]@(=\f[CB].LIST\f[R])@
+_
+\f[CB].NAP\f[R]@(=\f[CB].NOAUTOPARAGRAPH\f[R])@
+\f[CB].NF\f[R]@(=\f[CB].NOFILL\f[R])@
+\f[CB].NFC\f[R]@(=\f[CB].NO FLAGS CAPITALIZE\f[R])@
+\f[CB].NFH\f[R]@(=\f[CB].NO FLAGS HYPHENATE\f[R])@
+.
+\f[CB].NFL\f[R]@T{
+(=\f[CB].NO FLAGS CAPITALIZE
+.br
+.ce
+\f[R] and
+.br
+\f[CB].NO FLAGS HYPHENATE\f[R])
+T}@
+.
+\f[CB].NHD\f[R]@(=\f[CB].NO HEADER\f[R])@
+\f[CB].NHY\f[R]@(=\f[CB].NO HYPHENATION\f[R])@
+\f[CB].NJ\f[R]@(=\f[CB].NO JUSTIFY\f[R])@
+\f[CB].NM\f[R]@(=\f[CB].NUMBER\f[R])@
+\f[CB].NNM\f[R]@(=\f[CB].NO NUMBER\f[R])@
+.
+\f[CB].NOAUTOPARAGRAPH\f[R]@(=\f[CB].NAP\f[R])@T{
+\f[CB].AUTOPARAGRAPH \f[R](\f[CB].AP\f[R])
+.br
+\f[CB]\ .PARAGRAPH \f[I]n,v,t \f[R](\f[CB].P\f[R])
+T}
+.
+\f[CB].NOFILL\f[R]@=(\f[CB].NF\f[R])@T{
+\f[CB].FILL
+.br
+\f[R](\f[CB].F\f[R])
+T}
+.
+\f[CB].NO FLAGS CAPITALIZE\f[R]@(=\f[CB].NFL\f[R])@T{
+\f[CB].FLAGS CAPITALIZE
+.br
+\f[R](\f[CB].FL CAPITALIZE\f[R])
+T}
+.
+\f[CB].NO FLAGS HYPHENATE\f[R]@(=\f[CB].NFH\f[R])@T{
+\f[CB].FLAGS HYPHENATE
+.br
+\f[R](\f[CB].FL HYPHENATE\f[R])
+T}
+.
+\f[CB].NOHEADER\f[R]@(=\f[CB].NHD\f[R])@T{
+\f[CB].HEADER \f[I]arg
+.br
+\f[R](\f[CB].HD\f[R])
+T}
+.
+\f[CB].NO HYPHENATION \f[R]@(=\f[CB].NHY\f[R])@T{
+\f[CB].HYPHENATION
+.br
+\f[R](\f[CB].HY\f[R])
+T}
+.
+\f[CB].NOJUSTIFY \f[R]@(=\f[CB].NJ\f[R])@T{
+\f[CB].JUSTIFY
+.br
+\f[R](\f[CB].J\f[R])
+T}
+.
+\f[CB].NONUMBER \f[R]@(=\f[CB].NNM\f[R])@T{
+\f[CB].NUMBER \f[I]n
+.br
+\f[R](\f[CB].NM\f[R])
+T}
+.
+\f[CB].NOPERIOD \f[R]@(=\f[CB].NPR\f[R])@T{
+\f[CB].PERIOD
+.br
+\f[R](\f[CB].PR\f[R])
+T}
+.
+\f[CB].NOTE text \f[R]@(=\f[CB].NT\f[R])@T{
+\f[CB].END NOTE
+.br
+\f[R](\f[CB].EN\f[R])
+T}
+.
+\f[CB].NPR\f[R]@(=\f[CB].NO PERIOD\f[R])@
+\f[CB].NT\f[R]@(=\f[CB].NOTE\f[R])@
+\f[CB].NUMBER APPENDIX \f[I]a\f[R]@@\f[CB].APPENDIX text
+\f[CB].NUMBER CHAPTER \f[I]n\f[R]@@\f[CB].CHAPTER text
+_
+\f[CB].P\f[R]@(=\f[CB].PARAGRAPH\f[R])@
+\f[CB].PAGE\f[R]@(=\f[CB].PG\f[R])@
+\f[CB].PAGE SIZE\f[R]@(=\f[CB].PAPER SIZE\f[R])@
+.
+\f[CB].PAPER SIZE \f[I]v\f[CB],\f[I]h\f[R]@T{
+(=\f[CB].PS\f[R]
+.br
+\f[CB].PAGE SIZE\f[R])
+T}@
+.
+\f[CB].PARAGRAPH \f[I]h\f[CB],\f[I]v\f[CB],\f[I]t \f[R]@(=\f[CB].P\f[R])@
+\f[CB].SKIP \f[I]n\f[R]@(=\f[CB].S\f[R])@\f[CB].BLANK \f[I]n \f[R](\f[CB].B\f[R])
+\f[CB].SP\f[R]@(=\f[CB].SPACING\f[R])@
+\f[CB].SPACING \f[I]n \f[R]@(=\f[CB].SP\f[R])@
+.
+\f[CB].PERIOD\f[R]@(=\f[CB].PR\f[R])@T{
+\f[CB].NOPERIOD
+.br
+\f[R](\f[CB].NPR\f[R])
+T}
+.
+\f[CB].PG\f[R]@(=\f[CB].PAGE\f[R])@
+\f[CB].PITCH\f[R]@(=\f[CB].PIT\f[R])@
+
+.\f[CB].PRINT INDEX \f[R]@(=\f[CB].PX\f[R])@T{
+\f[CB].DO INDEX text
+.br
+\f[R](\f[CB].DX\f[R])
+T}
+.
+\f[CB].PS\f[R]@(=\f[CB].PAPER SIZE\f[R])@
+\f[CB].PX\f[R]@(=\f[CB].PRINT INDEX\f[R])@
+_
+\f[CB].RIGHT MARGIN \f[I]n \f[R]@(=\f[CB].RM\f[R])@
+\f[CB].RM\f[R]@(=\f[CB].RIGHT MARGIN\f[R])@
+_
+\f[CB].S\f[R]@(=\f[CB].SKIP\f[R])@
+\f[CB].SD\f[R]@(=\f[CB].STANDARD\f[R])@
+\f[CB].ST\f[R]@(=\f[CB].SUBTITLE\f[R])@
+\f[CB].SUBPAGE\f[R]@@\f[CB].END SUBPAGE
+\f[CB].SUBTITLE \f[I]text \f[R]@(=\f[CB].ST\f[R])@
+_
+\f[CB].T\f[R]@(=\f[CB].TITLE\f[R])@
+\f[CB].TAB STOPS \f[I]n,n, \*[Ellipsis] ,n \f[R]@(=\f[CB].TS\f[R])@
+\f[CB].TEST PAGE \f[I]n \f[R]@(=\f[CB].TP\f[R])@
+\f[CB].TITLE text\f[R]@(=\f[CB].T\f[R])@
+\f[CB].TP\f[R]@(=\f[CB].TEST PAGE\f[R])@
+\f[CB].TS\f[R]@(=\f[CB].TAB STOPS\f[R])@
+_
+\f[CB].UC\f[R]@(=\f[CB].UPPER CASE\f[R])@
+.
+\f[CB].UPPER CASE\f[R]@(=\f[CB].UC\f[R])@T{
+\f[CB].LOWER CASE
+.br
+\f[R](\f[CB].LC\f[R])
+T}
+.
+_
+\f[CB].X\f[R]@(=\f[CB].INDEX\f[R])@
+.
+.TE
+.
+.hy
+.fi
+.
+.
+.\" End of tbl ----------------------------------------------------------------
+.
+.
+.if t \{
+.  endTBL
+.\}
+.
+.
+.\" use groff_hdtbl
+.if t \{
+.  mso hdtbl.tmac
+.  TableHDTBL
+.\}
+.
+.
+.\" --------------------------------------------------------------------
+.SH EXPERIMENTAL ADDITIONS 1965
+.\" --------------------------------------------------------------------
+.
+.
+These
+.I "control words"
+are documented in
+.FONT CI Saltzer R 's
+documentation of 1965.
+.
+It is unsure whether they were really implemented.
+.
+.
+.P
+In this documentation, all
+.I control words
+are written in
+.IR "lower case" .
+.
+The writing in
+.I upper case
+is not mentioned, the same is true for
+.IR abbreviations .
+.
+So this documentation uses only
+.IR "lower case" . 
+.
+.
+.TP
+.FONT CB .FIGURE
+This
+.I control word
+turns control over to a 
+.I figure
+.IR processor ,
+which creates in
+.I core memory
+a representation of a
+.I flow diagram
+under the control of a few special
+.IR "control words" .
+When the
+.I control word
+.FONT CB ".END FIGURE"
+is encountered, the completed picture is printed immediately on the
+page being generated if there is room on that page; otherwise the
+.I figure
+will appear at the top of the next page.
+.
+.
+.RS
+.
+.
+.P
+Text following the
+.FONT CB ".END FIGURE"
+.I control word
+will be smoothly attached to text before the
+.FONT CB .FIGURE R .
+.
+No break is generated.
+.
+(Restriction: If a
+.I figure
+is being held for placement at the top of the next page, another
+.I figure
+may not be encountered before the first one is printed.)
+.
+.
+.P
+The only
+.I control words
+which are recognized when in the
+.I \%figure processor
+are the following three:
+.FONT CB .FRAME R ,
+.FONT CB .BOX R ,
+and
+.FONT CB ".END FIGURE" R .
+.
+.
+.RE
+.
+.
+.TP
+.FONT CB .FRAME I " m n"
+This
+.I control word
+intitalizes the
+.I figure  processor
+by giving the height and width of the figure to be produced.
+.
+.I m
+is
+the height, in lines; and
+.I n
+is the width, in characters.
+.
+(Note that a 1050 types 6 lines per inch, and 10 characters per inch.)
+.
+.
+.RS
+.
+.
+.P
+Any attempt to place items in the picture which extend beyond the
+boundaries will cause an error comment to be generated.
+.
+.I \%m
+and
+.I \%n
+must both be less than 100 and their product must be smaller than
+5400.
+.
+We may now think of the
+.I figure
+to be produced as an array of
+.I m
+times
+.I n
+elements.
+.
+.
+.RE
+.
+.
+.TP
+.FONT CB .BOX I " i j"
+The text on the lines following this
+.I control word
+will be placed in the
+.I figure
+such that the first character on the first line following the
+.FONT CB .BOX
+will appear in row
+.IR i ,
+character position
+-IR j .
+.
+The end of the text is indicated by a
+.FONT CB .BOX
+.I control word
+for another piece of text or the
+.FONT CB ".END FIGURE"
+.I control
+.IR word .
+.
+Temporarily, the text should not include underlined or overtyped
+characters.
+.
+.
+.TP
+.FONT CB ".END FIGURE"
+This
+.I control word
+causes control to return to the regular
+.I control processor
+of the
+.FONT CB .RUNOFF
+command, for the decision to print the picture.
+.
+Note that another
+.FONT CB .FIGURE
+.I control word
+may not appear until after this
+.I figure
+has been printed.
+.
+.
+.RS
+.P
+One further
+.I control word
+has been added which is intended to facilitate bringing out revised
+editions of a memorandum.
+.
+.
+.RE
+.
+.
+.TP
+.FONT CB .FLAG
+The next line to be printed after this
+.I control word
+is encountered will have an asterisk placed two spaces to the right of
+the right margin, as illustrated.
+.
+.
+.TP
+.FONT CB .DEFINE I " symbol"
+.
+This
+.I control word
+defines  the  value  of  the  symbol
+.I symbol
+to be the number of the page currently being printed.
+.
+The symbol may be used later with the
+.FONT CB .USE
+.I control word
+to cause printing of the page number in text.
+.
+The characters in the symbol must be mappable into the six\-bit
+character set, and all symbols must be six of fewer characters.
+.
+.
+.TP
+.FONT CB .USE I " symbol"
+The value of the symbol
+.I symbol
+is inserted into the text with a single blank preceding and no blank
+following.
+.
+If the symbol has not been previously defined, its value is
+.FONT CB 0 R .
+Text may continue following a blank typed after the symbol.
+.
+.
+.RS
+.
+.
+.P
+Here is an example of the use of these
+.I control
+.IR words .
+.
+.
+.RS
+.
+.
+.P
+In one area of text:
+.
+.
+.RS
+.
+.
+.P
+We now discuss the operation of the typewriter
+.FONT CB ".DEFINE REF1"
+coordinator module, which \*[Ellipsis]
+.
+.
+.RE
+.
+.
+.P
+In a later area of text:
+.
+.
+.RS
+.
+.
+.P
+As we saw in the discussion of the typewriter coordinator on page
+.FONT CB ".USE REF1" R ,
+the rest of \*[Ellipsis]
+.
+.
+.RE
+.
+.
+.P
+if the first area of text were on page 14, the later line would read:
+.
+.
+.RS
+.
+.
+.P
+As we saw in the discussion of the typewriter coordinator on page 14,
+the rest of \*[Ellipsis]
+.
+.
+.RE
+.RE
+.RE
+-
+.
+.\" --------------------------------------------------------------------
+.SS Further Study of Experimental Additions
+.\" --------------------------------------------------------------------
+.
+A number of suggestions have been made for extending the
+.I control word
+language of
+.FONT CI RUNOFF R ,
+and its capabilities.
+.
+These are listed here, primarily to elicit comment and discussion,
+both on the language which describes these operations and the less
+important problem of their implementation.
+-
+.
+.TP
+1.
+.
+Word division.
+.
+This is a whole are of study in itself.
+.
+.
+.TP
+2.
+.
+Automatic  footnote  insertion.
+.
+This was handled somewhat awkwardly in the
+.FONT CB .DITTO
+.IR command ,
+although the basic approach was probably reasonable.
+.
+.
+.TP
+3.
+.
+Automatic page references, perhaps via some symbolic reference scheme.
+.
+This would enable the page number in "as was described on page 32" to
+be inserted by the program.
+.
+The analogy with an assembly program should be hotly pursued for
+ideas.
+.
+.
+.TP
+4.
+.
+Special provision for printing facing pages.
+.
+This would require alternate running heads, placing page numbers
+alternately at right and left, and matching line counts on facing
+pages.
+.
+.
+.TP
+5.
+.
+Improved page\-division rules, to prevent the last line of a paragraph
+appearing alone at the top of a page, for example.
+.
+At present, copy must be run off to check by hand that awkward page
+divisions have not been made.
+.
+.
+.TP
+6.
+.
+Automatic generation of page numbers for a table of contents.
+.
+Again, the analogy of an assembly program symbol table appears
+fruitful.
+.
+.
+.TP
+7.
+.
+Automatic generations of an index.
+.
+The problem here is obtaining too many references to a given word,
+many irrelevant.
+.
+.
+.TP
+8.
+.
+Arrangement of tabulated data.
+.
+This problem may have already been partly approached with the
+above\-described figure generator, or the facilities already available
+in
+.IR RUNOFF ,
+but automatic setup of column widths and positions would be desirable.
+.
+One could include in this category the ability to call on other
+programs to computer numbers to place in tables, although this is
+going pretty far afield.
+.
+.
+.TP
+9.
+.
+Placing figures in a
+.I "cut"
+or
+.IR inset .
+.
+The control language is the most difficult problem here.
+.
+.
+.TP
+10.
+.
+Equation typing and  numbering.
+.
+Again, the control language appears formidable.
+.
+.
+.\" --------------------------------------------------------------------
+.SH "SEE ALSO"
+.\" --------------------------------------------------------------------
+.
+.PP
+.\" BR RUNOFF (@MAN1EXT@),
+.BR groff (@MAN1EXT@),
+.BR groff (@MAN7EXT@),
+.BR roff (@MAN7EXT@),
+.BR groff_filenames (@MAN7EXT@)
+.
+.
+.TP
+.FONT R "1964 " CR "Jerome H. Saltzer" R :
+.nh
+.FONT CI "Jerome H. Saltzer \[em] TYPSET and RUNOFF, Memorandum editor and \
+type\-out commands"
+.hy
+available at
+.UR \%http://\:mit.edu/\:Saltzer/\:www/\:publications/\:CC\-244.html
+.UE
+.
+.
+.TP
+.FONT R "1965 " CR "Jerome H. Saltzer" R :
+.nh
+.FONT CI "Jerome H. Saltzer \(em Experimental Additions to the RUNOFF Command"
+available at
+.UR http://\:web.mit.edu/\:afs/\:athena.mit.edu/\:user/\:other/\
+\:a/\:Saltzer/\:www/\:publications/\:PSN\-40.html
+.UE
+.hy
+.
+.
+.TP
+.FONT R "1966 " CR "Jerome H. Saltzer" R :
+.nh
+.FONT CI "Jerome H. Saltzer \[em] Manuscript Typing and Editing"
+.hy
+which is available in the internet at
+.UR http://\:mit.edu/\:Saltzer/\:www/\:publications/\:AH.9.01.html
+.I MIT html
+.UE
+or
+.UR \%http://\:web.mit.edu/\:Saltzer/\:www/\:publications/\:ctss\/\:AH.9.01.html
+.I CTSS html
+.UE
+or
+.UR \%http://\:web.mit.edu/\:Saltzer/\:www/\:publications/\:ctss/\:AH.9.01.pdf
+.I CTSS pdf
+.UE .
+.
+.
+.TP
+.FONT R "1973 " CR "Larry Barnes" R :
+.FONT CI "Larry Barnes \[em] RUNOFF: A Program for the Preparation of Documents"
+available as
+.UR http://\:www.textfiles.com/\:bitsavers/\:pdf/\:sds/\:9xx/\:940/\
+\:ucbProjectGenie/\:mcjones/\:R\-37_RUNOFF.pdf
+.I pdf
+.UE .
+.
+.
+.TP
+.
+.P
+There is still more documentation by the
+.FONT CR "DEC PDP\-10 archive" R .
+.
+So far this information is not yet included, but it will be done later
+on.
+.
+.
+.P
+The latest
+.FONT CI RUNOFF
+documentation is file
+.FONT CB RUNOFF.DOC
+from 
+.FONT CR PDP\-11
+at 1981, see
+.FONT CR "SEE ALSO" R .
+.
+The content of this document is also included in this document.
+.
+.
+.P
+Look at section
+.FONT CR "SEE ALSO"
+for the internet connections to the documents.
+.
+.
+.\" --------------------------------------------------------------------
+.SS Early Environment 1963\-66
+.\" --------------------------------------------------------------------
+.
+.FONT CI Saltzer
+originally worked on
+.IR \%MIT 's
+.I \%CTSS time-sharing operating
+.IR \%system .
+.
+There he had an editor
+.FONT CB TYPSET
+that he also documented in the documentation cited above.
+.
+This editor was an ancestor for
+.BR \%ed (@MAN1EXT@).
+.
+.
+.P
+To use his
+.FONT CI RUNOFF
+language, he programmed a tool that he called
+.FONT CB RUNOFF R .
+.
+.
+.P
+There is still an emulator and the old source files for
+.FONT CB RUNOFF
+and
+.FONT CB TYPSET
+at
+.nh
+.UR http://\:www.cozx.com/\:~dpitts/\:ibm7090.html 
+.FONT CR "IBM 7090 CTSS"
+.UE .
+.hy
+.
+.
+.\" --------------------------------------------------------------------
+.SS The original RUNOFF program 1963-66
+.\" --------------------------------------------------------------------
+.
+The original
+.FONT CB RUNOFF
+program is also documented in the documentation of 1966 above.
+.
+.
+.P
+.FONT CI Saltzer
+uses upper case
+.FONT CB RUNOFF
+to denote his program.
+.
+So we will also use 
+.FONT CB RUNOFF
+to refer to the original program of 1963-66.
+.
+.
+.P
+This program has mainly the task to adjust a printer of that time and
+then print a
+.FONT CI RUNOFF
+document with this configuration.
+.
+Today this does not make much sense, but some parts are still
+available in the options of
+.BR \%groff (@MAN1EXT@),
+but under different names.
+.
+So we will not build this ancient program, but we will document its
+old command line here.
+.
+A lower case program
+.FONT CB runoff
+will be something different.
+.
+.
+.P
+.FONT CB RUNOFF
+is a command used to type out files of the
+.FONT CI RUNOFF
+language in manuscript format.
+.
+.I Control words
+scattered in the text may be used to provide detailed control over the
+format.
+.
+Input files may be prepared by the context editor
+.FONT CB TYPSET
+which does not exist today.
+.
+.
+.\" --------------------------------------------------------------------
+.SS Usage of RUNOFF Program
+\" --------------------------------------------------------------------
+.
+.SY RUNOFF
+.I \%filespec
+.RI [ "parameter \*[Ellipsis]" ]
+.YS
+.
+.
+.TP
+.I filespec
+is the primary name of a file to be typed out.
+.
+.TP
+.I parameter
+arguments are any number of the following parameters, in any order:
+.
+.
+.RS
+.
+.TP
+.FONT CB STOP
+Pause between pages.
+.
+.
+.TP
+.FONT CB NOWAIT
+Suppress the initial pause to load paper and the pause between pages
+(not necessary today).
+.
+.
+.TP
+.FONT CB PAGE I " n"
+Begin printing with the page numbered
+.IR n .
+.
+.
+.TP
+.FONT CB BALL I " n"
+Typewriter is using printing ball
+.IR n .
+If this parameter is omitted,
+.FONT CB RUNOFF
+assumes that the ball in use will properly print all
+.I CTSS characters
+in the file.
+.
+The number
+.I n
+is engraved on top of the printing ball.
+.
+.I CTSS characters
+not appearing on the ball being used will be printed as blanks, so
+that they may be drawn in.
+.
+This parameter does not make sense in our modern printers.
+.
+.RE
+.
+.
+.\" --------------------------------------------------------------------
+.SH THE ORIGINAL RUNOFF LANGUAGE OF 1966
+.\" --------------------------------------------------------------------
+.
+A
+.FONT CI RUNOFF
+file consists of
+.I command lines
+and
+.IR "text lines" .
+.
+The
+.I command lines
+start with a period (dot)
+.RB \(dq . \(dq,
+all other lines are
+IR "text lines" . 
+.
+.
+.P
+.I Command lines
+are also called
+.I command lines
+by
+.FONT CI Saltzer R .
+.
+.
+.\" --------------------------------------------------------------------
+.SS Text Lines and Conditions
+.\" --------------------------------------------------------------------
+.
+.FONT CI RUNOFF
+.I text lines
+are different from the
+.FONT CI groff
+language.
+.
+.
+.P
+As the early
+.FONT CI CTSS
+computers could only produce upper case characters, the text lines
+look very strange today.
+.
+This wasn't documented in the documentation of the 1960s.
+.
+But there is a good documentation of 1981 which contains also the old
+style.
+.
+Have a look at chapter
+.FONT CI "RUNOFF ADDITIONS 1981"
+section
+.FONT CI "Case Information"
+in this document.
+.
+.
+.P
+One or more
+.I blank lines
+are not printed, but mean a
+.IR "line break" .
+.
+This can also be reached by the
+.FONT CB .BREAK
+.IR "control word" .
+.
+.
+.P
+In
+.IR groff ,
+blank lines are printed as lines of their own.
+.
+This is not a paragraph break, because a line is bigger than a
+paragraph break.
+.
+.
+.P
+A text line that starts with one or more space characters means
+.IR "begin a new paragraph" .
+.
+.
+.P
+In
+.IR groff ,
+this will start a new line and inserts the space characters at the
+beginning of the line.
+.
+.
+.\" --------------------------------------------------------------------
+.SS Command Lines
+.\" --------------------------------------------------------------------
+.
+A command line begins with a period (dot)
+.RB \(dq . \(dq.
+.
+Following the dot
+.FONT CB RUNOFF
+expects a
+.IR "command name" .
+.
+This is called
+.I control word 
+by
+.FONT CI Saltzer
+.BI
+.
+.
+.P
+These
+.I command names
+or
+.I control words
+were defined by
+.FONT CI Saltzer
+as 1 or 2 words of arbitrary length.
+.
+or an
+.I abbreviation
+of defined 2 characters.
+.
+The later
+.FONT CI roff
+language uses only 2\-character requests; but
+.FONT CI groff
+expanded these to arbitrary length.
+.
+Each
+.I control word
+(1 or two words) can be written in upper or lower case as you like.
+.
+.
+.P
+Some
+.FONT CI "control words"
+are followed by a
+.I space
+and the
+.I parameters
+for that
+.IR command ,
+followed optionally by a comment (Comments are not documented
+further).
+.
+.
+.P
+Lines beginning with a dot but having an unrecognizable format are
+treated as errors.
+.
+.
+.P
+No lines beginning with a dot are printed unless the preceding line
+was a
+.I control line
+.FONT CB .LITERAL R .
+.
+All commands are described below.
+.
+Abbreviations for command names are normally based on the first two
+letters of a one word command or the first letter of the first two
+words of a multi\-word command.
+.
+Commands which should close a logical line break do.
+.
+Information on abbreviations and whether commands cause line breaks
+will be found in the summary at the end of the manual.
+.
+In a command line
+.FONT CB RUNOFF
+will consider multiple blanks as a single blank (space), if a blank
+character 1s legal.
+.
+.
+A
+.FONT CI RUNOFF
+document contains text separated by so\-called
+.IR "control words" .
+.
+As these are full lines, a better name would be
+.I "control lines"
+as is used in the documentation for
+.BR \%groff (@MAN7EXT@),
+.
+.
+.P
+These are lines starting with a period
+.RB ( . )
+and directly followed by a command with or without arguments.
+.
+The command names are arbitrarily long, they can even consist of
+several words, possibly followed by arguments.
+.
+.
+.P
+The
+.I "control words"
+can be written in lower or upper case, just as wanted.
+.
+Moreover, each command name can be shortened to an abbreviation of 2
+characters.
+.
+When the command name has only 1 word, the first 2 characters are taken.
+.
+.I Command names
+with 2 words abbreviate to the first character of each word.
+.
+These abbreviations led later to the 2 character
+.I \%requests
+of
+.IR \%roff .
+.
+.
+.P
+An example of a
+.I "control line"
+with a single
+.I "control word"
+with 2 arguments is a long name with lower case
+.IP
+.FONT CB .command I " arg1 arg2"
+.P
+or a long name with upper case
+.IP
+.FONT CB .COMMAND I " arg1 arg2"
+.P
+or an abbreviation with lower case
+.IP
+.FONT CB .co I " arg1 arg2"
+.P
+or an abbreviation with upper case
+.IP
+.FONT CB .CO I " arg1 arg2"
+.
+.
+.P
+Another example of a
+.I "control line"
+with 2
+.I "control words"
+with 1 argument is a long name with lower case
+.IP
+.FONT CB ".word1 word2" I " arg"
+.P
+or a long name with upper case
+.IP
+.FONT CB ".WORD1 WORD2" I " arg"
+.P
+or an abbreviation with lower case
+.IP
+.FONT CB .ww I " arg"
+.P
+or an abbreviation with upper case
+.IP
+.FONT CB .WW I " arg"
+.
+.
+.P
+These
+.I "control words"
+were renamed to
+.I requests
+later on in
+.FONT CI roff R .
+.
+.
+In the 1973 document, the words
+.I macros
+and
+.I formats
+are used without any documentation.
+.
+.
+.\" --------------------------------------------------------------------
+.SS Control Words (Command Names, Requests)
+.\" --------------------------------------------------------------------
+.
+The documentation for
+.I "control words"
+in this paragraph are taken from the
+.FONT CI RUNOFF
+documentation of 1966.
+.
+Often this documentation refers to the
+.FONT CB RUNOFF
+program that doesn't exist any more.
+.
+When the
+.FONT CI RUNOFF
+language will be implemented for
+.BR \%groff (@MAN1EXT@)
+these documentations must be adjusted.
+.
+.
+.TP
+.FONT CB .ADJUST
+.TQ
+.FONT CB .AD
+Enable
+.I fill
+mode.
+.
+The next line is the first one affected.
+.
+This is the default mode.
+.
+.
+.TP
+.FONT CB .APPEND I " file"
+.TQ
+.FONT CB .AP I " file"
+Take as the next input line the first line of
+.IR \%file .
+.
+Note that the whole of 
+.I \%file
+is appended, and that the appending is an irreversible process \[em] that
+is, once
+.FONT CB RUNOFF
+encounters the
+.FONT CB .APPEND
+.I "control line"
+it will switch to the file
+.I \%file
+and continue from the first line of
+.IR \%file .
+.
+All lines following the
+.FONT CB .APPEND
+.I "control line"
+will not be processed by
+.FONT CB RUNOFF R .
+.
+The file
+.I \%file
+may, of course, itself call for appending of still another file, and
+so on.
+.
+.
+.TP
+.FONT CB ".BEGIN PAGE"
+.TQ
+.FONT CB .BP
+Print out this page, start next line on a new page.
+.
+.
+.TP
+.FONT CB .BREAK
+.TQ
+.FONT CB .BR
+The lines before and after the
+.FONT CB .BREAK
+.I "control word"
+will not be run together by the
+.FONT CI fill
+mode of operation.
+.
+.
+.TP
+.FONT CB .CENTER
+.TQ
+.FONT CB .CD
+The following line is to be centered between the left and right
+margins.
+.
+.
+.TP
+.FONT CB ".DOUBLE SPACE"
+.TQ
+.FONT CB .DS
+Copy is to be double spaced.
+.
+This mode  takes  effect after the next line.
+.
+.
+.TP
+.FONT CB .FILL
+.TQ
+.FONT CB .FI
+Enable
+.IR "fill mode" .
+.
+That means: Lengthen short lines by moving words from the following
+line; trim long lines by moving words to the following line.
+.
+This is the default mode.
+.
+.FONT CB .NOFILL
+disables the
+.I fill
+mode.
+.
+.
+.TP
+.FONT CB .HEADER I " word1 word2 \*[Ellipsis]"
+.TQ
+.FONT CB .HE I " word1 word2 \*[Ellipsis]"
+All of the line after the first blank is used as a header line, and
+appears at the top of each page, along with the page number, if
+specified.
+.
+.
+.TP
+.FONT CB ".HEADING MODE" I " arg"
+.TQ
+.FONT CB .HM I " arg"
+This
+.I control sequence
+alters the mode of the running head to that specified by the parameter
+.IR \%arg .
+.
+Any of the following parameters are allowed for
+.IR \%arg:
+.
+.
+.\"  --------------------------------------------------------------------
+.RS
+.
+.
+.TP
+.FONT CB CENTER
+The header will be centered on the page.
+.
+.
+.TP
+.FONT CB MARGIN
+The header will be adjusted against the right margin of the page.
+.
+.
+.TP
+.FONT CB FACING
+On even\-numbered pages, the header will be adjusted against the left
+margin, on odd numbered pages against the right.
+.
+.
+.TP
+.FONT CB OPPOSED
+The header will be adjusted against the opposite margin from the page
+number.
+.
+In the absence of a
+.FONT CB ".HEADING MODE"
+.IR "control sequence" ,
+the default option is
+.FONT CB .OPPOSED R .
+.
+.
+.RE
+.\"  --------------------------------------------------------------------
+.
+.
+.TP
+.FONT CB .INDENT I " n"
+.TQ
+.FONT CB .IN I " n"
+The argument
+.I \%n
+is a number.
+.
+Set the number of spaces to be inserted at the beginning of each line
+to
+.IR \%n .
+.
+Indent is preset to 0.
+.
+.
+.TP
+.FONT CB ".LINE LENGTH" I " n"
+.TQ
+.FONT CB .LL I " n"
+The argument
+.I \%n
+is a positive number.
+.
+Set the line length to
+.IR \%n .
+.
+The line length is preset to 60.
+.
+.
+.TP
+.FONT CB .LITERAL
+.TQ
+.FONT CB .LI
+The following line is not a
+.IR "control word" ,
+despite the fact that it begins with a period.
+.
+.
+.TP
+.FONT CB .NOFILL
+.TQ
+.FONT CB .NF
+Disable
+.IR "fill mode" .
+.
+That means: Print all lines exactly as they appear without right
+adjustment or filling out.
+.
+In
+.I NOFILL
+mode each input line produces one output line; further blank lines are
+output in this mode.
+.
+Use the
+.FONT CB .FILL
+.I control word
+to restart
+.IR filling .
+.
+.
+.TP
+.FONT CB .NOJUST
+.TQ
+.FONT CB .NJ
+Disable
+.IR "fill mode" .
+.
+.
+.TP
+.FONT CB ".ODD PAGE"
+.TQ
+.FONT CB .OP
+This
+.I "control word"
+causes the current page to be printed out, and the next page to be
+numbered with the next higher odd page number.
+.
+.
+.TP
+.FONT CB .PAGE R " [" I n R ]
+.TQ
+.FONT CB .PA R " [" I n R ]
+Print page numbers.
+.
+(The first page is not given a page number.
+.
+It has instead a two\-inch top margin.
+.
+See also
+.FONT CB "Manuscript Conventions" R ,
+below.)
+.
+If argument
+.I \%n
+is present, insert a page break and number the next page
+.IR \%n .
+Note that
+.FONT CB RUNOFF
+does not print completely empty pages.
+.
+.
+.TP
+.FONT CB ".PAGING MODE" I " arg1 arg2 \*[Ellipsis]"
+.TQ
+.FONT CB .PM I " arg1 arg2 \*[Ellipsis]"
+This
+.I control sequence
+alters the mode of page numbering to that specified by the arguments.
+.
+The arguments may be in any order, and must be selected from the
+following list:
+.
+.
+.\"  --------------------------------------------------------------------
+.RS
+.
+.
+.TP
+.FONT CB MARGIN
+Page numbers will be adjusted against the right margin.
+.
+.
+.TP
+.FONT CB FACING
+Odd page numbers are adjusted against the right margin, even page
+numbers are adjusted against the left margin.
+.
+.
+.TP
+.FONT CB CENTER
+Page numbers are centered between the right and left margin.
+.
+.
+.TP
+.FONT CB TOP
+Page numbers are placed on the fourth line from the top of the page.
+.
+.
+.TP
+.FONT CB BOTTOM
+Page numbers are placed on the fourth line from the bottom of the
+page.
+.
+.
+.TP
+.FONT CB OFF
+Page numbers are discontinued.
+.
+.
+.TP
+.FONT CB PREFIX I " \(dqstring\(dq"
+The string of characters between quotation marks is prefixed to the
+page number.
+.
+The quotation marks may be next to each other, in which case no prefix
+is used.
+.
+.
+.TP
+.FONT CB ROMANU
+Page numbers will be printed in upper case Roman numerals.
+.
+.
+.TP
+.FONT CB ROMANL
+Page numbers will be printed in lower case Roman numerals.
+.
+.
+.TP
+.FONT CB ARABIC
+Page numbers will be printed in Arabic.  (This is the normal mode.)
+.
+.
+.TP
+.FONT CB SET I " n"
+Set the next page number to be the positive number
+.IR \%n .
+.
+.
+.TP
+.FONT CB SKIP I " n"
+Skip
+.I \%n
+page numbers.
+.
+.
+.P
+If in a single use of
+.FONT CB ".PAGING MODE"
+several arguments specify competing functions, the last one specified
+takes precedence.
+.
+When the
+.FONT CB ".PAGING MODE"
+sequence appears in text at point A, all text up to A (and probably
+some text after A) will appear on a page controlled by the previous
+paging mode.
+.
+The new
+.I paging mode
+will take effect on the next page.
+.
+Then there is no danger of getting page numbers both at the top and
+bottom of the same page.
+.
+.
+.P
+Use of the
+.FONT CB TOP
+parameter may conflict with the
+.I \%heading
+.IR \%mode .
+.
+If a heading and a page number should be printed in the same column,
+the page number will take precedence.
+.
+In the absence of a
+.FONT CB ".PAGING MODE"
+.I control
+.IR sequence ,
+the default options are:
+.FONT CB "TOP MARGIN PREFIX \(dqPAGE\(dq" R .
+.
+.
+.RE
+.\"  --------------------------------------------------------------------
+.
+.
+.TP
+.FONT CB ".PAPER LENGTH" I " n"
+.TQ
+.FONT CB .PL I " n"
+This
+.I control word
+is used for running off a documentation file on non\-standard paper.
+.
+The number
+.I \%n
+is a line count, figured at 6 lines per inch.
+.
+If this
+.I control word
+is not given,
+.I n
+is assumed to be 66, for 11\-inch paper.
+.
+.
+.TP
+.FONT CB ".SINGLE SPACE"
+.TQ
+.FONT CB .SS
+Copy is to be single spaced.
+.
+This mode takes effect after the next line.
+.
+(The normal mode is single space.)
+.
+.
+.TP
+.FONT CB .SPACE R " [" I n R ]
+.TQ
+.FONT CB .SP  R " [" I n R ]
+Insert
+.I \%n
+vertical spaces (carriage returns) in the copy.
+.
+If
+.I \%n
+carries spacing to the bottom of a page, spacing is stopped.
+.
+If
+.I \%n
+is absent or 0, one space is inserted.
+.
+.
+.TP
+.FONT CB .UNDENT I " n"
+.TQ
+.FONT CB .UN I " n"
+In an indented region, this
+.I control word
+causes a break, and the next line only will be indented n spaces fewer
+than usual.
+.
+This
+.I "control word"
+is useful for typing indented numbered paragraphs.
+.
+.
+.\" --------------------------------------------------------------------
+.SH RUNOFF ADDITIONS 1973
+.\" --------------------------------------------------------------------
+.
+Here are described only the additional
+.I control words
+that are documented in the 1973 documentation.
+.
+.\" --------------------------------------------------------------------
+.SS Formats
+.\" --------------------------------------------------------------------
+.
+.
+.TP
+.FONT CB .FORMAT I " name"
+This command causes subsequent text to be output under the control of
+tne specified format (see below at
+.FONT CB ".DEFINE FORMAT" R ).
+.
+Each following logical line will be fit into the format until a
+.FONT CB .FILL
+or
+.FONT CB .NOFILL
+command 1s encountered.
+.
+.
+.TP
+.FONT CB ".DEFINE FORMAT" I " <name> <pos> <field_ definition> \
+\*[Ellipsis]"
+.TQ
+.FONT CB ".END FORMAT"
+These commands define a format for use in producing tables, etc.
+.
+.
+.RS
+.
+.
+.TP
+.I <name>
+identifies the format.
+.
+It can be activated by the
+.FONT CB .FORMAT
+.IR command .
+.
+.
+.TP
+.I <pos>
+is the position and may be one of
+.FONT CB LEFT R ,
+.FONT CB RIGHT R ,
+or
+.FONT CB CENTER R ,
+and determines the overall positlon of the format with respect to the
+margins.
+.
+.
+.TP
+.I <field_definition>
+There can be several arguments of this type.
+.
+Each has the form:
+.
+.
+.RS
+.
+.FONT CI <type> CB ( CI "<letter> \*[Ellipsis] <letter>" CB )
+.
+.P
+where the
+.FONT CI <type>
+is one of
+.
+.TP
+.FONT CB L
+for left,
+.
+.TP
+.FONT CB R
+for riqht,
+.
+.TP
+.FONT CB C
+for center,
+.
+.TP
+.FONT CB F
+fer fill, or
+.FONT CB J
+for justify.
+.
+.
+.P
+The first three types define fixed fields; the text to be formatted
+must fit within the allocated space.
+.
+The latter types define variable fields; the text will be handled as
+in normal fill mode processing.
+.
+.
+.P
+A picture showing the manner in which text should be output follows
+the
+.FONT CB ".DEFINE FORMAT"
+command; following the picture should be an
+.FONT CB ".END FORMAT"
+command.
+.
+The following lines give an example:
+.
+.
+.RS
+.  ft CB
+.  nf
+.  nh
+.    nop ".DEFINE FORMAT SUMMARY L(A) F(C) C(B)"
+.    nop "AAAA	CCCCCCCCCCCCCCCCCCCCCCCCC	BBBBBBB"
+.    nop "	CCCCCCCCCCCCCCCCCCCCCCCCC		"
+.    nop ".END FORMAT"
+.  hy
+.  fi
+.  ft
+.RE
+.
+.
+.P
+The first field of text is left justified; the second is centered; the
+third is subjected to
+.I fill mode
+processing without justification.
+.
+After the first line of output is generated using this format, all
+subsequent lines are produced using the last picture 1ine.
+.
+(Strictly speaking the third line is unnecessary.)
+.
+.
+.P
+Text for formatted processing consists of a logical line (or
+paragraph).
+.
+Each field except the last must be separated by
+.IR tab .
+.
+The
+.I tab character
+is displayed here as backslash character
+.FONT R ( CB \[rs] R ).
+.
+.
+.P
+The first field of text is
+.FONT CB A R ,
+the second
+.FONT CB B R ,
+etc.
+.
+Typical input for our example might be:
+.
+.
+.RS
+.nf
+.nh
+|A\\YES\\/THIS IS SOME TEXT
+TO BE FILLED.
+.hy
+.fi
+.RE
+.
+.
+.P
+The characters 1n the picture lines were 1nterpreted as follows.
+.
+Contiguous sequences of letters determine the fie1d positions;
+non\-alphabetic characters are output literally.
+.
+(Note:
+.FONT CB Q.QQ
+wi11 not work, put the period
+.RB \[dq] . \[dq]
+in the text.
+.
+A sequence of characters written between double quotes is considered
+literal text.
+.
+The
+.I double quotes
+are not output, and there is no way to use
+.I double quote
+as a
+.IR literal .
+.
+.
+.\" --------------------------------------------------------------------
+.SS Hyphenation Processing
+.\" --------------------------------------------------------------------
+.
+.TP
+.FONT CB .HYPHENATE
+Enable
+.IR "hyphenation mode" .
+.
+This is the default when starting up.
+.
+The
+.FONT CB RUNOFF
+program used a small
+.I glossary
+for splitting.
+.
+In
+.I hyphenation mode
+.FONT CB RUNOFF
+would try to find a word 1n the glossary which is the same (except for
+the endings
+.FONT CB \-S R ,
+.FONT CB \-ES R ,
+.FONT CB \-ED R ,
+and
+.FONT CB \-E R )
+as the word at the end of the line of text.
+.
+When running in
+.BR groff (1)
+there are
+.I glossaries
+being much more complete than in
+.BR RUNOFF .
+.
+.
+.TP
+.FONT CB .NOHYPHEN
+Disable
+.IR "hyphenation mode" .
+.
+.
+.TP
+.FONT CB .GLOSSARY I " word"
+This command inserts words into the
+.I glossary
+for use in
+.IR hyphenation .
+.
+Each word should have the form
+.FONT CB hy\[hy]phen\[hy]ate
+and be separated by spaces.
+.
+.
+.TP
+.FONT CB ".HYPHENATION BREAK" I " n"
+This command set the parameter which determines the allowable number
+of spaces to te inserted in a line before
+.FONT CB RUNOFF
+tried to hyphenate the last word.
+.
+Each space counts ten points.
+.
+If more than
+.I n
+points per word would have to be inserted, then
+.I hyphenation
+will be attempted.
+.
+The initial setting of this parameter is 5 (one\-half space per word).
+.
+.
+.\" --------------------------------------------------------------------
+.SS Margin Controls
+.\" --------------------------------------------------------------------
+.
+There are two types of margins involved in
+.FONT CI RUNOFF R .
+.
+.
+.TP
+(1)
+The physical margins.
+.
+These are determined by the nature of the printing device.
+.
+The margins outline the area where it is physically possible to print
+characters.
+.
+.
+.TP
+(2)
+.
+The logical margins.
+.
+These can be set bv the user as he wishes.
+.
+(Limits are imposed by the physical margins.)
+.
+They are initialized for standard 8.5\[dq] by 11\[dq] printing.
+.
+.
+.P
+Commands concerning vertical and horizontal margins are:
+.
+.
+.TP
+.FONT CB ".PAGE LAYOUT TM, EM, TOL"
+This sets the vertical logical margins and vertical tolerence.
+.
+Parameters are top margin, bottom margin and tolerance.
+.
+The tolerance is used to determine where to break between pages on
+page overflows.
+.
+If
+there is a line break within
+.I TCL lines
+of the bottom,
+.FONT CB RUNOFF
+will break the page there; otherwise it will fill the page completely.
+.
+.
+.TP
+.FONT CB ".LINE LAYOUT LM, RM, NO, CS"
+This sets the logical left and right margin, the number of columns,
+and the number of spaces to insert between columns.
+.
+These margins are used for the page headings.
+.
+To adjust the relative
+text position, use the subsequent commands.
+.
+.
+.TP
+.FONT CB ".REDUCE MARGIN LM, RM"
+.TQ
+.FONT CB ".EXPAND MARGIN LM, RM"
+.TQ
+.FONT CB ".END REDUCTION"
+These commands enable the user to indent a certain portion of his text
+using the first command, or
+.FONT CB .UNDENT
+his text using the second command.
+.
+In either case the original margins are restored by the third command.
+.
+The use of several
+.FONT CB ".REDUCE MARGIN"
+commends before the corresponding
+.FONT CB ".END REDUCTION"
+commands succesively indents the text more, and more.
+.
+Thus these commands are 1ike brackets (i.e. recursive).
+.
+.FONT CB LM
+is added to the left logical margin and
+.FONT CB RM
+is subtracted from the right logical margin in the first command.
+.
+Just
+the opposite is done on the second command.
+.
+Negative numbers are permitted.
+.
+These commands do not effect the position of page headings.
+.
+.
+.TP
+.FONT CB ".LAYOUT PLM, PRM, PTM, PBM, LL, LO"
+This command defines the physical margins in the followinq complex
+manner.
+.
+(It should only be used for non\-standard devices, normally this
+command should not be necessary.)
+.
+The parameters are the physical left margin (in spaces), the physical
+right margin, the physical top 1ine, the physical bottom line, the
+line lenqth, and line origin.
+.
+The first four parameters define the physical 1imits of the printing
+device.
+.
+The final two parameters define the length of the logical line and its
+origin with respect to the left edge of the paper.
+.
+Printing starts at column
+.FONT CB "LO + LM" R ,
+and ends at
+.FONT CB "LO + RM" R ,
+where
+.FONT CB LM
+and
+.FONT CB RM
+are the logical margins established by
+.FONT CB ".LINE LAYOUT" R .
+.
+When using the
+.FONT CI "facing feature"
+(see
+.FONT CB ".PAGING MODE" R ),
+the logical left margin is
+.FONT CB "LL \[em] RM"
+on even pages, and the right margin is
+.
+.FONT CB "LL \[em] LM" R .
+.
+The parameters for the layout command must satisfy:
+.
+.RS
+.RS
+.nh
+.nf
+.ft CB
+.nop "min(LO + LL \[em] PLM, PRM \[em] LO) > max(PLM \[em] LO, \
+LO + LL \[em] PRM)\f[],\f[CB]"
+.nop LL > 25\f[], and \f[CB]PBM \[em] PTM > 6\f[]
+.fi
+.hy
+.RE
+.
+.
+.P
+This command sets
+.FONT CB LM
+to 15,
+.FONT CB RM
+to
+.FONT CB "LL \[em] 10" R ,
+.FONT CB TM
+to
+.FONT CB PTM R ,
+and
+.cb BM
+to
+.FONT CB "PBM \[em] 6" R .
+.
+(These margin settings produce the standard 1.5 inch left, and 1 inch
+right, too, and bottom margins.)
+.
+.RE
+.
+.
+.P
+Initially
+.FONT CB RUNOFF
+sets the margins for
+.I teletype
+output to:
+.
+.
+.RS
+.RS
+.nh
+.nf
+.ft CB
+.nop .LAYOUT 6, 89, 6, 66, 8S, 0
+.nop .LINE LAYOUT 15, 75
+.nop .FILL
+.ft
+.fi
+.hy
+.RE
+.RE
+.
+.
+.P
+The printer layout is:
+.
+.RS
+.RS
+.nh
+.nf
+.ft CB
+.nop ".layout 5, 137, 6, 66, 85, 15"
+.nop ".page layout 6, 60, 4"
+.ft
+.fi
+.hy
+.RE
+.RE
+.
+.P
+The logical margins must satisfy:
+.
+.RS
+.RS
+.nh
+.nf
+.ft CB
+.nop min(LL, PRM \[em] LO, LO \[em] LL \[em] PLM) >= RM >
+.nop "     LM >= max(0, PLM \[em] LO, LO + LL \[em] PRM)" \f[],\f[CB]
+.nop "PBM >= BM > TM >= PTM" "\f[], and\f[CB]"
+.nop BM \[em] TM > TOL\f[].
+.fi
+.hy
+.RE
+.RE
+.
+.
+.\" --------------------------------------------------------------------
+.SS Paragraph Formatting
+.\" --------------------------------------------------------------------
+.
+.TP
+.FONT CB ".PARAGRAPH SPACING" I " n"
+.
+This specifies how many lines are to be inserted between paragraphs.
+.
+Initial setting = 1.
+.
+.
+.TP
+.FONT CB ".PARAGRAPH INDENTATION" I " n"
+This specifies how many additional spaces to insert at the beginning
+of a paragraph.
+.
+Initial setting = 5.
+.
+.
+.TP
+.FONT CB ".PARAGRAPH UNDENTATION" I " n"
+This command is the same as
+.FONT CB ".PARAGRAPH INDENTATION" I " \-n" R .
+.
+That is,
+.I n
+fewer spaces are inserted at the beginning of the paragraph.
+.
+.
+.\" --------------------------------------------------------------------
+.SS Special Line Justification and Control
+.\" --------------------------------------------------------------------
+.
+These commands pertain to the next logical line.
+.
+The end of the line should be designated with a break.
+.
+.
+.TP
+.FONT CB .CENTER
+.
+Center the next line.
+.
+.
+.TP
+.FONT CB .INDENT I " n"
+.
+Indent the next line
+.I n
+spaces.
+.
+If
+.I n
+is not provided, 5 is assumed.
+.
+.
+.TP
+.FONT CB .UNDENT I " n"
+.
+Start the next line
+.I n
+spaces to the left of the normal margin.
+.
+This command is the same as
+.FONT CB .INDENT I " \-n" R .
+.
+.
+.TP
+.FONT CB .MARGIN
+Justify the next 1ine against the right hand margin.
+.
+.
+.\" --------------------------------------------------------------------
+.SS Heading and Paging
+.\" --------------------------------------------------------------------
+.
+.TP
+.FONT CB .HEADER I " XXXXXXX"
+.FONT CB RUNOFF
+accepts a heading to go on the first line of
+each paqe.
+.
+The heading strinq is assured to start at the first non\-blank
+character after thd control word and end at carriage return.
+.
+.
+.TP
+.FONT CB ".HEADING MODE" I " <param>"
+.I <param>
+determines the position of the heading on the 11ne.
+.
+.I <param>
+may be any of the following.
+.
+.
+.RS
+.
+.TP
+.FONT CB CENTER
+The header will be centered on the 1ine.
+.
+.
+.TP
+.FONT CB MARGIN
+The header will be adjusted against the riqht margin.
+.
+.
+.TP
+.FONT CB PAGING
+On even numbered pages tne header is adjusted against the right
+margin.
+.
+On odd pages it is adjusted against the left mergin.
+.
+.
+.TP
+.FONT CB OPPOSED
+The header will be adjusted against the opposite margin from the
+page numter.
+.
+This is the initial mode.
+.
+.RE
+.
+.
+.TP
+.FONT CB ".PAGING MODE" I " <param>"
+.
+This command determines the placing of the page number.
+.
+All parameters are optional.
+.I <param>
+may be anyone or more of the following oommands.
+.
+In case of conflict the latest command wins.
+.
+.RS
+.
+.TP
+.FONT CB CENTER
+The page numbers are centered between the logical margins.
+.
+.TP
+.FONT CB MARGIN
+The page number is adjusted against the right margin.
+.
+.TP
+.FONT CB FACING
+On even numbered pages the number will be adjusted against the right
+margin.
+.
+On odd numbered pages tne number will be adjusted against the
+left margin.
+.
+.TP
+.FONT CB TOP
+Page numbers are placed on the first line.
+.
+.TP
+.FONT CB BOTTOM
+Page numbers are placed on the last line.
+.
+.TP
+.FONT CB OFF
+Printing page numbers is discontinued.
+.
+.TP
+.FONT CB PREFIX I " <string>"
+.TQ
+.FONT CB SECTION I " <string>"
+.TQ
+.FONT CB SUFFIX I " <string>"
+The strings of characters between quotation marks are used to form the
+page. string, which has the form:
+.
+.RS
+.I <prefix><section><page number><suffix>
+.
+.P
+Any or all of these strings mav be null.
+.
+The section string is considered to be part of the page number for
+purposes of indexing.
+.
+.RE
+.P
+Initial mode is:
+.
+.RS
+.RS
+.ft CB
+.nop ".PAGING MODE TOP MARGIN PREFIX \[dq]Page\[dq]"
+.nop ".PAGING MODE SECTION \[dq]\[dq] SUFFIX \[dq]\[dq]"
+.RE
+.RE
+.
+.
+.P
+If neither page number nor heading is used, the text will start on the
+first logical line.
+.
+Otherwise it will start on the fourth logical line.
+.
+If the page number is at the bottom, text will end on the fourth line
+from the bottom.
+.
+If the paging and headinq mode conflict, the page string overwrites
+the heading.
+.
+.RE
+.
+.
+.TP
+.FONT CB ".ODD PAGE"
+This
+.FONT CI "control word"
+causes the ourrent page to be printed out and the next page to be
+started with the next higher odd number.
+.
+.
+.TP
+.FONT CB .PAGE I " n"
+If
+.I n
+is present, insert a page break and start numbering the next pege
+with
+.IR n .
+Otherwise, turn the
+.I paging mode
+on and do not insert a page break.
+.
+.
+.TP
+.FONT CB .EJECT I " n"
+Insert a page break if either there are fewer than
+.I n
+lines left on the page or
+.I n
+is not present.
+.
+.
+.\" --------------------------------------------------------------------
+.SS Lines and Spacing
+.\" --------------------------------------------------------------------
+.
+.TP
+.FONT CB ".SINGLE SPACE"
+Sing1e space all 1ines within paragraphs.
+.
+This is the initial state.
+.
+.
+.TP
+.FONT CB ".DOUBLE SPACE"
+Double space all lines within paragraphs.
+.
+.
+.TP
+.FONT CB .SPACE I " n"
+Output
+.I n
+1ine spaces.
+.
+If
+.I n
+is not provided, 1 is assumed.
+.
+In case of page overflow all remaining blank 1ines to be output are
+deleted.
+.
+.
+.TP
+.FONT CB ".FIGURE SPACING" I " n"
+This command is equivalent to
+.FONT CB .EJECT I " n"
+followed by
+.FONT CB .SPACE
+.IR n .
+.
+These commands provide the only means of creatinq blank 11nes.
+.
+.
+.TP
+.FONT CB .BREAK
+The lines before and after this command will not be run together in
+.IR "fill mode" .
+.
+A simpler way to get a line break is to insert one or more blank lines
+in the text.
+.
+.
+.TP
+.FONT CB ".BEGIN GROUP"
+.TQ
+.FONT CB ".END GROUP"
+The output lines enclosed between these two commands are forced to lie
+on a page.
+.
+Thus this command acts in a manner similar to
+.FONT CB .EJECT I " n" R ,
+where
+.I n
+has the 'right' value.
+.
+.
+.\" --------------------------------------------------------------------
+.SS Miscellanous
+.\" --------------------------------------------------------------------
+.
+.TP
+.FONT CB .UNDERLINE
+The following 1ine is underlined.
+.
+.
+.TP
+.FONT CB .LITERAL
+The next line is taken as part of text whether or not
+it begins with dot.
+.
+.
+.TP
+.FONT CB .ESCAPE I <char>
+.TQ
+.FONT CB .SHIFT I <char>
+.TQ
+.FONT CB ".TAB CHARACTER" I <char>
+The given character becomes the
+.IR escape ,
+.IR shift ,
+or
+.I tab
+character.
+.
+The parameter for the
+.FONT CB .SHIFT
+and
+.FONT CB ".TAB CHARACTER"
+commands may be null, if no
+.I shift
+or
+.I tab
+character is desired.
+.
+.
+.TP
+.FONT CB ".DEFINE COMMAND" I " <name>"
+.TQ
+.FONT CB ".END COMMAND"
+.TQ
+.FONT CB .CALL I " <name>"
+These commands give the user the opportunity to combine text and
+control lines to form his own commands.
+.
+All text and command lines between the first and second commands is
+stored away under
+.IR name .
+.
+When the third command is executed, the stored string is read and the
+commands within the string are executed.
+.
+Recursion is not permitted.
+.
+.
+.TP
+.FONT CB .INDEX I " <phrase>, <phrase>"
+.
+.FONT CB RUNOfF
+saves the first phrase in the main index table and the second phrase
+(if any) in a sub\-index table associated with the first phrase.
+.
+.RS
+.
+The index is formatted and output after the last page of text.
+.
+Two built\-in but redefinable formats,
+.FONT CI RINDEX
+and
+.FONT CI SINDEX R ,
+are used to format the index as shown in the following example.
+.
+.RS
+.nh
+.nf
+.FONT CB "Algorithms, 40, 78," R "             \[rs]\[dq] uses " I RINDEX
+.FONT CB "  analysis of, 27, " R "             \[rs]\[dq] uses " I SINDEX
+.fi
+.hy
+.RE
+.
+.
+The following lines give the initial definitions for the indexing
+formats.
+.
+.
+.RS
+.nh
+.nf
+.ft CB
+.nop ".define format RINDEX f(A)"
+.nop "AAAAAAAAAAAAAAAAAAAAAAAAAAA"
+.nop "    AAAAAAAAAAIAAAAAAAAAAAA"
+.nop ".end format"
+.nop ".define format SINDEX f(A)"
+.nop "  AAAAAAAAAAAAAAAAAAAAAAAAA"
+.nop "    AAAAAAAAAAIAAAAAAAAAAAA"
+.nop ".end format"
+.ft
+.fi
+.hy
+.RE
+.
+.
+In order to get an index output in two columns,
+.RS
+.P
+.FONT CB ".LINE LAYOUT 15, 75, 2, 4"
+.P
+should be the last line of the input.
+.RE
+.
+.RE
+.
+.
+.\" --------------------------------------------------------------------
+.SH RUNOFF DOCUMENTATION 1974
+.\" --------------------------------------------------------------------
+.
+This document is the best documentation about text lines.
+.
+Parts of that is used in the document of 1981.
+.
+.
+.\" --------------------------------------------------------------------
+.SS Command Lines
+.\" --------------------------------------------------------------------
+.
+All lines beginning with a period (dot) are
+.FONT CI RUNOFF
+command lines.
+.
+All other lines are text lines.
+.
+.
+.P
+A command line consists of a period, following by a command, which can
+consist of one or more words, or a 2- or 3-letter abbreviation,
+followed by 0 or 1 or more arguments.
+.
+This can be followed by a comment, which is preceeded by an
+exclamation point (bang character)
+.FONT CB ! R .
+.
+In ancient 
+.FONT CI RUNOFF R ,
+The comment didn't need to be preceeded.
+.
+.
+.P
+In this document, several command or text lines can be appended into a
+multiple line if these parts are separated by a semi-colon
+.FONT CB ; R .
+.
+If 2 commands are appended, the semi-colon may be omitted, because the
+period is a sufficient separator.
+.
+.
+.\" --------------------------------------------------------------------
+.SS Text Lines
+.\" --------------------------------------------------------------------
+.
+.P
+There are 2 modes of text line structures:
+.
+.
+.TP
+.I ancient style
+This is the original style.
+.
+Due to very old hardware, there were only input methods for upper case
+characters.
+.
+But typewriters and printers were able to use both upper and lower case.
+.
+So the text lines are all in upper case with special characters that
+are case-shifters for the printing.
+.
+.
+.TP
+.I newer style
+By better hardware, it was possible to use input methods with both
+upper and lower case.
+.
+Here the text lines are like those in later
+.FONT CI roff
+and
+.FONT CI groff
+mode.
+.
+.
+.P
+This paragraph describes only the
+.I ancient style
+of text lines.
+.
+.
+.P
+This text is filled and justified such as with the later
+.FONT CI roff
+language.
+.
+Just as in
+.FONT CI roff R ,
+the filling, justification, and line break can be turned on or off by
+commands.
+.
+.
+.\" --------------------------------------------------------------------
+.SS Case Changing of Text Lines
+.\" --------------------------------------------------------------------
+.
+In this section, the specification of case for files prepared on an
+upper case terminal is documented.
+.
+There are special characters that in printing act as case-shifters for
+ASCII characters into lower (ASCII code 97 to 122 decimal) or upper
+case (ASCII code 65 to 90 decimal).
+.
+.
+.P
+The lower case mode seems to be the default mode.
+.
+Also, according to existing old
+.FONT CI RUNOFF
+files, each text line starts with this default mode.
+.
+.
+.TP
+.FONT CI "single circumflex " CB ^
+The following ASCII character is shifted into upper case.
+.
+.
+.TP
+.FONT CI "single back\-slash " CB \[rs]
+The following ASCII character is shifted into lower case.
+.
+.
+.TP
+.FONT CI "double circumflex " CB ^^
+The case mode is shifted into upper case.
+.
+.
+.TP
+.FONT CI "double back\-slash " CB \[rs]\[rs]
+The case mode is shifted into lower case.
+.
+.
+.P
+A common example with starting mode in lower case for these 4 special
+characters is:
+.
+.P
+.RS
+^HERE IS A ^SAMPLE ^SENTENCE IN ^^UPPER CASE\\ AND LOWER CASE.
+.RE
+.
+.P
+is printed as:
+.
+.RS
+Here is a Sample Sentence in UPPER CASE and lower case.
+.RE
+.
+.
+.\" --------------------------------------------------------------------
+.SS Further special Characters in Text Lines
+.\" --------------------------------------------------------------------
+.
+.TP
+.FONT CI "ampersand " CB &
+This is used for underscoring the next following character.
+.
+For example:
+.
+.RS
+.P
+.RS
+&s&o&f&t&w&a&r&e
+.RE
+.
+.P
+becomes:
+.RS
+.UL software
+.RE
+.
+.P
+in the output or printing.
+.RE
+.
+.
+.TP
+.FONT CI "circumflex and ampersand " CB ^&
+This is used for underscoring all following characters except for
+blanks.
+.
+.
+.\" --------------------------------------------------------------------
+.SH RUNOFF ADDITIONS 1981
+.\" --------------------------------------------------------------------
+.
+.\" --------------------------------------------------------------------
+.SS Source File Format
+.\" --------------------------------------------------------------------
+.
+The source file contains the textual material which will appear on the
+final copy, plus information to specify formatting.
+.
+Most importantly, upper and lower case information also may be
+supplied so that copy can be prepared on the terminal or other such
+device which can input only upper case letters.
+.
+All command information consists of regular
+.FONT CI ASCII
+printing characters so that a listing of the source file may be
+examined if the final copy is not exactly as desired.
+.
+.
+.P
+All material in the source file is taken to be source text except
+those lines beginning with a period.
+.
+A line beginning with a period is assumed to be a command, and must
+match one of those listed below.
+.
+The commands provide the formatting information, and control various
+optional modes of operation.
+.
+.
+.P
+Usually the text is
+.I filled
+and
+.I justified
+as it is processed.
+.
+That is, the program
+.I fills
+a line by adding successive words from the source text until one more
+word would cause the right margin to be exceeded.
+.
+The line is then
+.I justified
+by making the word spacings larger until the last word in the line
+exactly meets the right margin.
+.
+.
+.P
+The user may occasionally wish to reproduce the source text exactly,
+which is done by disabling
+.I filling
+and
+.I justification
+or by use of the
+.FONT CR .LITERAL
+command.
+.
+The program may be set to
+.I fill
+but not
+.IR justify ,
+in which case the output will be normal except that lines will not be
+justified to the right margin.
+.
+The program may also be set to
+.I justify
+but not
+.IR fill ,
+although this would probably produce peculiar results and is not
+recommended.
+.
+.
+.P
+When the
+.I fill mode
+is on, spaces and carriage returns occurring in the source text are
+treated only as word separators.
+.
+Multiple separators are ignored.
+.
+.
+.P
+Some of the commands cause a BREAK in the output.
+.
+A
+.I break
+means that the current line is output without justification, and the
+next word goes at the beginning of the next line.
+.
+This occurs at the end of paragraphs.
+.
+.
+.P
+The program will advance to new pages as necessary, placing the title
+(if given) and the page number at the top of each page.
+.
+The user may call explicitly for a
+.I page advance
+where desired, and may inhibit the occurrence of a
+.I page advance
+within specified material.
+.
+.
+.\" --------------------------------------------------------------------
+.SS Case Information of Text Lines
+.\" --------------------------------------------------------------------
+.
+The information in this section documents the style of the text lines
+that could only be upper case in the ancient
+.FONT CI CTSS
+computers of the early 1960s..
+.
+It seems as if this section documents the old
+.FONT CI RUNOFF
+style.
+.
+.
+.P
+Specification of
+.I case
+for files prepared on the terminal is done with two characters,
+circumflex 
+.FONT R ( CB ^ R , CI " 136 octal" R ),
+and
+.FONT CR back\-slash R " (" CB \[rs] R , CI " 134 octal" R ).
+The appearance of a circumflex causes the letter immediately following
+to be transmitted in upper case.
+.
+The appearance of a
+.FONT CR back\-slash
+causes the letter immediately following to be converted to lower case.
+.
+Any letter not preceded by one of these characters is transmitted in
+the current mode.
+.
+.
+.P
+The mode is initially
+.I "upper case"
+.FONT CB (wrong!) R .
+.
+(The initial mode seems to be
+.IR "lower case" .
+.
+That's the style used by the available
+.FONT CI RUNOFF
+files in the PDP-10 archive and by the example below.
+.
+And each newline seems to switch back to the initial mode, well:
+.IR "lower case" ). 
+.
+.
+.P
+The mode is changed by the occurrance of two successive
+.I case
+control characters.
+.
+Two
+.FONT CR circumflexes
+.FONT CB ^^
+cause the mode to be set to
+.IR "upper case" ,
+and two
+.FONT CR back\-slashes
+.FONT CB "\[rs]\[rs]"
+cause the mode to be set to
+.IR "lower case" .
+.
+.
+.P
+The use of the above corresponds to the use of the
+.FONT CR shift
+and
+.FONT CR shift\-lock
+keys on a typewriter.
+.
+Usually, typing appears in
+.IR "lower case" .
+To type one letter in
+.IR "upper case" ,
+the
+.FONT CR shift
+.I key
+is used.
+.
+The
+.FONT CR shift\-lock
+is set to type a series of
+.IR "upper case letters" ,
+after which it is released.
+.
+.
+.P
+The following shows the uses of the case control characters:
+.EX
+^HERE IS A ^SAMPLE ^SENTENCE IN ^^UPPER CASE\[rs]\[rs] AND LOWER CASE.  
+.EE
+becomes:
+.EX
+Here is a Sample Sentence in UPPER CASE and lower case.
+.EE
+.
+.
+.RS
+.P
+.ce
+NOTE
+.
+.P
+Case conversion takes place only on
+.FONT CI ASCII
+.I " codes"
+.FONT CR 101
+to
+.FONT CR "132 octal" R ,
+that is, the
+.I upper case
+letters.
+.
+Any actual
+.I lower case
+letters (codes
+.FONT CR 141
+to
+.FONT CR "172 octal" R )
+appearing in the source will be transmitted unchanged.
+.
+If the source is prepared on a device such as a
+.FONT CI DECwriter
+or model
+.FONT CI "37 Teletype"
+which produce letters of the proper
+.IR case ,
+the mode should be set to
+.I upper case
+at the beginning of the file and left unchanged for the remainder.
+.RE
+.
+.
+.P
+An additional character,
+.FONT CR less\-than
+.FONT R ( CR < R ,
+.FONT CR "074 octal" R ),
+capitalizes the entire word it precedes.
+.
+It then returns the file to the current
+.IR case .
+.
+This character is not engaged unless preceded by the
+.nh
+.FONT CB ".FLAGS CAPITALIZE"
+.hy
+.IR command .
+.
+Similarly, the
+.nh
+.FONT CB ".FLAGS HYPHENATE"
+.hy
+.I command
+engages the special character
+.FONT CR equals
+.FONT R ( CB = R , CR "075 octal" R ),
+which causes
+.I hyphenization
+to be suspended for the word it precedes.
+.
+.
+.\" --------------------------------------------------------------------
+.SS Special Characters
+.\" --------------------------------------------------------------------
+.
+.TP
+.FONT CB & CI " Ampersand    " CR Underscoring
+The character
+.FONT CI ampersand
+.FONT R ( CB & R ,
+.FONT CR "046 octal" R )
+is used to specify
+.UL underscoring .
+.
+The
+.FONT CI ampersand
+will cause the character following it to be
+.IR underscored ,
+e.g.
+.FONT CB &f&o&o
+becomes
+.UL \f[CB]foo\f[] .
+.
+.
+.P
+Underlining of a string of characters can also be specified in a
+manner similar to that of the
+.CI shift lock
+operations described above.
+;
+An appearance of
+.FONT CI ampersand
+preceded by
+.FONT CI circumflex
+.FONT CB ^&
+will cause underlining of all following characters except space.
+.
+An appearance of
+.CI ampersand
+preceded by
+.CI back\-slash
+.FONT CB \[rs]&
+will disable this mode.
+.
+.
+.TP
+.FONT CB # CR "  Number Sign  " I "Explicit space"
+It is occasionally necessary to include
+.I spaces
+in the text which should not be treated as
+.IR "word separators" .
+.
+For this purpose,
+.FONT CI RUNOFF
+treats the
+.I number\-sign
+character
+.FONT R ( CB # R ,
+.FONT CR "043 octal" R )
+as a
+.IR "quoted space" ;
+i.e.  it will print as exactly one
+.I space
+in the output, will never be expanded nor changed to a
+.IR "carriage return" .
+.
+.
+.TP
+.FONT CB _ CR "  Underline   " I "Quote next character"
+To allow the appearance of the
+.I special characters
+.FONT R ( CI ampersand
+used as a
+.IR "quote character" .
+.
+The character immediately following an
+.FONT CR underscore
+will be transmitted to the output with no formatting effect.
+.
+The
+.FONT CR underscore
+itself is thus another
+.IR "case requiring quoting" .
+.
+The following five cases occur:
+.FONT CB _& R ,
+.FONT CB _^ R ,
+.FONT CB _\[rs] R ,
+.FONT CB __ R ,
+.FONT CB _# R ,
+.FONT CB _{ R ,
+.FONT CB _} R ,
+and
+.FONT CB _| R .
+.
+.
+.TP
+.FONT CB ^ CI "   Circumflex   " I "Upper\-case shift or mode lock"
+As described above, the
+.FONT CI circumflex
+character
+.FONT CB ^
+is used to convert the letter following to
+.IR upper\-case .
+It is also used to lock the
+.I case mode
+in
+.IR "upper case" ,
+and the
+.I underline mode
+to
+.UL "underline all text" .
+.
+If it is to appear in the printed text, it must be preceded by the
+.I quote character
+.FONT CB _^ R .
+.
+.
+.TP
+.FONT CR \[rs] CI "  back\-slash  " I "lower\-case shift or mode unlock"
+As described above, the
+.FONT CI back\-slash
+character
+.FONT CB \[rs]
+is used to output the letter following in
+.IR lower\-case .
+.
+It is also used to lock the
+.I case mode
+in
+.IR lower\-case ,
+and to disable
+.IR underlining .
+.
+If it is to appear in the printed text, it must be preceded by the
+.I quote
+character
+.FONT CB _\[rs] R .
+.
+.
+.TP
+.FONT CB < CI "   less\-than   " I "Capitalize next word"
+If
+.FONT CB ".FLAGS CAPITALIZE"
+has been engaged, the
+.FONT CI less\-than
+character
+.FONT CB <
+is a special character used to capitalize the entire word it precedes.
+.
+If it is to appear in the printed text, it must be preceded by the
+.I quote
+character
+.FONT CB _< R .
+.
+.
+.TP
+.FONT CB = CR " equals\-sign " I  "hypenation disable"
+If
+.FONT CB ".FLAGS HYPHENATE"
+has been engaged, the
+.I equals
+character
+.FONT CB =
+used to disable
+.I hyphenation
+for the word it preceds.
+.
+If it is to appear in the printed text, it must be preceded by the
+.I quote
+character
+.FONT CB _= R .
+.
+.
+.TP
+.FONT CB { CR " left\-brace " I "Reverse half\-linefeed"
+If the output device type is no
+.FONT CB N R ,
+then the
+.I left
+and
+.I right braces
+are used for
+.I superscripting
+and
+.IR subscripting .
+.
+The
+.I left\-brace
+.FONT R ( CB { CR " 173 octal" R )
+produces a
+.IR "reverse half\-linefeed" .
+When combined with the
+.I right brace
+.FONT R ( CB } CR " 175 octal" R )
+scripting is created; e.g.
+.FONT CB {super}
+becomes
+.FONT CB {super} R ,
+and
+.FONT CB }sub{
+becomes
+.FONT CB }sub{ R .
+.
+.
+.TP
+.FONT CB } CR " right\-brace " I "forward half\-linefeed"
+As described above, the
+.I right brace
+.FONT R ( CB } CR " 175 octal" R )
+when coupled with the
+.I left brace
+will produce scripting.
+.
+This will only occur when a scripting output device is selected.
+.
+.
+.TP
+.FONT CB | CR " vertical\-bar " I "Engage/disengage alternate character set"
+The
+.I vertical bar
+.FONT R ( CB | R , CR " 174 octal" R )
+acts as an on/off switch.
+.
+It will alternatly transmit a
+.I shift\-out
+and a
+.I shift\-in
+character to change the selected character set; e.g.
+.FONT CB |ABC|
+becomes
+.FONT CI Ctrl\-N CB ABC CI Ctrl\-O R .
+.
+.
+.TP
+.FONT CI Ctrl\-N CR " Control-N " I "enchacement on/off;  red/black ribbon"
+If an
+.I Anderson-Jacobson output device
+is selected, a
+.FONT CI Control\-N
+.FONT R ( CI Ctrl\-N R ,
+.FONT CR "016 octal" R )
+will alternatly engage and disengage the print enchancement; e.g.
+.FONT CB NFOO CI Ctrl\-N
+becomes
+.FONT CB FOO R .
+.
+.
+.P
+If a
+.I Diablo output device
+is selected, a
+.FONT CI Control\-N
+will alternatly  select  the  red  and  black  ribbon color;  e.g.
+.FONT CB NFOO CI Ctrl\-N
+becomes
+.FONT CB FOO R .
+.
+.
+.\" --------------------------------------------------------------------
+.SS Special Characters Overview
+.\" --------------------------------------------------------------------
+.
+.P
+Below is a list of
+.FONT CI RUNOFF R 's
+special characters.
+.
+To appear in the text, each must be preceded by the
+.CI underscore
+character (itself a special character).
+.
+.
+.TP
+.FONT CB ^
+shift character for upper case
+.
+.TP
+.FONT CB \[rs]
+shift character for lower case
+.
+.TP
+.FONT  CB <
+flag character for upper case.
+.
+Only becomes a special character if
+.FONT CB ".FLAGS CAPITALIZE"
+is engaged.
+.
+.TP
+.FONT CB #
+quoted space character
+.
+.TP
+.FONT CB =
+flag character for disabling hyphenation.
+.
+Only becomes a
+.I special character
+if
+.FONT CB ".FLAGS HYPHENATE"
+is  engaged.
+.
+.TP
+.FONT CB &
+.FONT CR underscore
+.
+.TP
+.FONT CB _
+.I quote special character
+.
+.TP
+.FONT CB {
+.I reverse half\-linefeed
+for scripting
+.
+.TP
+.FONT CB }
+.I forward half\-linefeed
+for scripting
+.
+.TP
+.FONT CB |
+switch on/off the
+.I alternate character set
+.
+.TP
+.FONT CB ^n
+switch on/off the print enchancement or switch to the red/black ribbon
+color
+.
+.
+.\" --------------------------------------------------------------------
+.SS RUNOFF Commands
+.\" --------------------------------------------------------------------
+.
+The following
+.I commands
+will be recognized if they are at the beginning of a line started with
+a period.
+.
+Any line in the source file beginning with a period is assumed to be
+one of these
+.IR commands .
+.
+If it is not, an
+.I error diagnostic
+will be typed and the line will be ignored.
+.
+Some
+.I commands
+take one or more decimal numeric arguments.
+.
+These are separated from the
+.I command
+by a
+.FONT CR space R .
+.
+More than one
+.I command
+may be entered on a single line by separating the
+.I commands
+with a
+.FONT CI semicolon
+.FONT R ` CB ; R '
+or a
+.FONT CI period
+.FONT R ` CB . R '.
+.
+.
+.P
+.I Multi\-word commands
+may appear in any form.
+.
+Thus,
+.FONT CB ".NO HEADER"
+and
+.FONT CB .NOHEADER
+are both legal.
+.
+.
+.P
+Many
+.I commands
+may be abbreviated.
+.
+Standard
+.I abbreviations
+are given below each
+.IR command .
+.
+.
+.\" --------------------------------------------------------------------
+.SS Text Formatting Commands
+.\" --------------------------------------------------------------------
+.
+.TP
+.FONT CB .BREAK
+.TQ
+.FONT CB .BR
+causes a
+.IR break ,
+i.e. the current line will be output with no
+.IR justification ,
+and the next word of the source text will be placed at the beginning
+of the next line.
+.
+.
+.TP
+.FONT CB .SKIP CI " n"
+.TQ
+.FONT CB .SK CI " n"
+.TQ
+.FONT CB .S CI " n"
+causes a BREAK after which
+.CI n
+is multiplied by the number of
+.I spaces
+between lines.
+.
+The result is the number of lines
+.IR skipped .
+.
+Output is advanced to the top of the next page if there is no room on
+the current page.
+.
+If the current page is empty,
+.FONT CB .SKIP
+does nothing.
+.
+.
+.TP
+.FONT CB .BLANK I " n"
+.TQ
+.FONT CB .B I " n"
+causes the current line to be output with no
+.IR justification ,
+skips
+.FONT CI n
+line spaces, and then starts output of the current source text.
+.
+.FONT CB .BLANK
+is like
+.FONT CB .SKIP R ,
+except that the
+.I space
+to be left is independent of line spacing.
+.
+If the page is empty,
+.FONT CB .BLANK
+does nothing.
+.
+.
+.TP
+.FONT CB .FIGURE I " n"
+.TQ
+.FONT CB .FG I " n"
+leaves
+.I n
+lines blank to make room for a figure or diagram.
+.
+If fewer than
+.I n
+lines remain on the current page, text continues to
+.I fill
+this page, then the page is advanced and
+.I n
+blank lines are left at the top of the next page.
+.
+.
+.TP
+.FONT CB .INDENT I " n"
+.TQ
+.FONT CB .I I " n"
+causes a
+.CI break
+and sets the next line to begin
+.I n
+spaces to the right of the left margin.
+.
+The
+.I n
+can be negative to allow beginning a line to the left of the left
+margin.
+.
+However, a line cannot begin to the left of column 0.
+.
+If
+.I n
+is not supplied, the current paragraph indent is used.
+.
+.
+.TP
+.FONT CB .PARAGRAPH I " n, v, t"
+.FONT CB .P I " n, v, t"
+causes a
+.I break
+and formats the output paragraphs.
+.
+The
+.I n
+is optional and, if present, sets the number of spaces the paragraph
+is to be indented.
+.
+The default value for
+.I n
+is
+.FONT CB 5
+.RI ( n
+can also have a negative value).
+.
+.I v
+is the vertical spacing between paragraphs.
+.
+.I v
+can range from
+.FONT CB 0
+to
+.FONT CB 5 R .
+.
+.FONT R ( CB 1
+is
+.IR "single spacing" ,
+.FONT CB 2
+is
+.IR "double spacing" ,
+etc.)
+.
+.I t
+causes an automatic
+.FONT CI ".TEST PAGE"
+(see the
+.FONT CB ".TEST PAGE"
+.IR command ).
+.
+.
+.TP
+.FONT CB .CENTER I " n" CB ; I text
+.TQ
+.FONT CB .CENTRE I " n" CB ; I text
+.TQ
+.FONT CB .C I " n" CB ; I text
+causes a
+.I break
+and centers the following text in the source file.
+.
+The centering is over column
+.FONT CB ( I n CB " + " I "left margin" CB )/2 R .
+If
+.I n
+is not given, it is assumed to be the
+.
+.IR "right margin" .
+.
+.
+.RS
+.P
+.ce
+NOTE
+.
+.P
+.FONT CB CENTER R ,
+.FONT CB "RIGHT MARGIN" R ,
+.FONT CB "LEFT MARGIN" R ,
+.FONT CB "PAGE SIZE" R ,
+and
+.FONT CB STANDARD
+take both relative and absolute values.
+.
+Relative values are expressed as
+.FONT CB + I n
+or
+.FONT CB \- I n R ,
+while absolute values of
+.I n
+are unsigned.
+.RE
+.
+.
+.TP
+.FONT CB .FOOTNOTE I " n"
+.TQ
+.FONT CB .FN I " n"
+saves
+.I n
+lines at the bottom of the current page for a
+.IR footnote .
+.
+The
+.I n
+is multiplied by the number of spaces set with the
+.FONT CB .SPACING
+command.
+.
+If insufficient room remains on the current page, space is allocated
+at the bottom of the following page.
+.
+The text of the
+.I footnote
+should begin on the line following the
+.FONT CB .FOOTNOTE
+command.
+.
+.IR Indentation ,
+.IR "case lock" ,
+.IR justify ,
+.IR margins ,
+.IR spacing ,
+and
+.I fill
+are preserved around footnotes.
+.
+However,
+.I commands
+that affect page formatting are illegal in a
+.IR footnote .
+.
+.I Tab stops
+are illegal because they are not preserved.
+.
+A footnote within a footnote is also illegal.
+.
+.
+.P
+The actual space taken by a footnote can be more or less than
+specified by
+.IR n .
+If necessary
+.FONT CR adjust
+.I n
+after examining a draft printout.
+.
+.
+.P
+The
+.I footnote
+is terminated with a line beginning with an exclamation point (the
+remainder of which is ignored).
+.
+.
+.TP
+.FONT CB .NOTE I " text"
+.TQ
+.FONT CB .NT I " text"
+starts an
+.IR "indented note" .
+.
+This command
+.I blanks
+.FONT CB 2 R ,
+reduces both
+.IR margins ,
+.I centers
+the text (if no text is given, it centers the word
+.FONT CB NOTE R ),
+and then
+.I blanks
+.FONT CB 1 R .
+.
+At this point you enter the text of the
+.IR note .
+.
+If the left margin is at
+.FONT CB 0 R ,
+the
+.I margin reduction
+is
+.FONT CB 15 R ,
+otherwise it is
+.FONT CB 5 R .
+.
+.
+.TP
+.FONT CB ".END NOTE"
+.TQ
+.FONT CB .EN
+terminates the
+.FONT CB .NOTE
+command,
+.I blanks
+.CONT CB 2 R ,
+and reverts the margins and spacing modes to their settings before the
+last
+.FONT CB .NOTE
+command.
+.
+.
+.TP
+.FONT CB .LIST I " n"
+.FONT CB .LS I " n"
+starts an indented list with
+.I n
+spacing, moves the left margin
+.FONT CB 9
+spaces to the right for the first
+.FONT CB .LIST
+command, and
+.FONT CB 4
+more spaces for each subsequent nested
+.FONT CB .LIST R .
+.
+The normal
+.I fill
+and
+.I justify modes
+remain in effect.
+.
+Therefore, you must disengage them just after the
+.FONT CB .LS
+command if you want a ragged right.
+.
+.
+.TP
+.FONT CB ".LIST ELEMENT;" I " text"
+.TQ
+.FONT CB .LE; I " text"
+starts an item in the list, used in conjunction with the
+.FONT CB LIST
+comand.
+.
+The elements are numbered sequentially and the number is given a
+negative indent so that the list lines up.
+.
+The number is followed by a
+.I period
+and two
+.I spaces
+so that the indent will be by 
+.FONT CB \-4 R .
+.
+The
+.I list elements
+are separated by the standard paragraph spacing and
+.FONT CI "TEST PAGE" R .
+.
+If you want to type the text on the same line as the command, you must
+separate the text from the command with any number of intervening
+.I spaces
+or
+.IR tabs ,
+or (optionally) one
+.IR semicolon .
+.
+.
+.TP
+.FONT CB ".END LIST"
+.TQ
+.FONT CB .ELS
+terminates the
+.FONT CB .LIST
+command and returns to settings before the last
+.FONT CB .LIST
+command.
+.
+.
+.TP
+.FONT CB .COMMENT I " text"
+.TQ
+.FONT CB .; I " text"
+causes the line to be ignored.
+.
+The text is not printed in the output file, but rather is used as a
+.I comment
+line in the source text.
+.
+.
+.\" --------------------------------------------------------------------
+.SS Page Formatting Commands
+.\" --------------------------------------------------------------------
+.
+.TP
+.FONT CB .PAGE
+.FONT CB .PG
+causes a
+.I break
+and an
+.I advance
+to a new page.
+.
+If the current page is empty, this
+.I command
+does not
+.I advance
+the page.
+.
+Just like an
+.IR "automatic page advance" ,
+this
+.I command
+prints the
+.I title
+(if given) and
+.I page numbers
+on every page.
+.
+.
+.TP
+.FONT CB ".TEST PAGE" I " n"
+.TQ
+.FONT CB .TP I " n"
+causes a
+.I break
+followed by a
+.IR "conditional page advance" .
+.
+It skips to the next page if fewer than
+.I n
+lines are left on the page.
+.
+This capability is to ensure that the following
+.I n
+lines are all output on the same page.
+.
+This
+.I command
+has the form
+.I t
+as an optional argument to the
+.FONT CB .PARAGRAPH
+command.
+.
+.
+.TP
+.FONT CB .NUMBER I " n"
+.TQ
+.FONT CB .NM I " n"
+starts page numbering.
+.
+This is the default so there is no reason to issue this command unless
+page numbering is disengaged.
+.
+If
+.I resumption
+of page numbering is desired at a certain page, specify
+.IR n .
+.
+.
+.TP
+.FONT CB .NONUMBER
+.FONT CB .NNM
+disengages page numbering.
+.
+However, pages continue to be counted, so that the normal page number
+can appear if page numbering is re\-entered with the
+.FONT CB .NUMBER
+command.
+.
+.
+.TP
+.FONT CB .CHAPTER I " text"
+.TQ
+.FONT CB .CH I " text"
+starts a new chapter using the text as the title of the chapter.
+.
+This
+.I command
+acts as if the following
+.I command string
+were entered:
+.
+.
+.P
+.EX
+.nop ".BREAK;.PAGE;.BLANK 12;.CENTER;CHAPTER n"
+.EE
+.P
+The
+.I n
+is incremented by
+.FONT CB 1
+automatically.
+.
+After the CHAPTER
+.I n
+is typed on the page,
+.
+.
+.P
+.EX
+.nop .BLANK 2;.CENTER;text;.BLANK 3
+.EE
+.P
+occurs.
+.
+This
+.I command
+then resets the
+.IR case ,
+.IR margins ,
+.IR spacing ,
+and
+.IR "justify/fill modes" .
+.
+It also clears any
+.I subtitles
+and sets the
+.I chapter name
+as the
+.IR title .
+.
+.
+.TP
+.FONT CB ".NUMBER CHAPTER " I " n"
+supplies a number
+.I n
+to be used in a subsequent
+.FONT CB .CHAPTER
+command.
+.
+.FONT CB ".NUMBER CHAPTER"
+would be used when a
+.I chapter
+of a document occupies a source file of its own.
+.
+In such a case,
+.FONT CB ".NUMBER CHAPTER"
+would be the first command of the source file.
+.
+.
+.TP
+.FONT  CB ".HEADER LEVEL" I " n text"
+.TQ
+.FONT CB .HL I " n text"
+starts a section at the level specified and takes the following text
+as the header.
+.
+.I n
+can range from
+.FONT CB 1
+to
+.FONT CB 5 R .
+.
+The sections are incremented by
+.FONT CB 1
+automatically, and the number is output in the form
+.FONT I i CB . I j CB . I k CB . I l CB . I m R .
+If this is a chapter oriented document, the
+.I i
+is the chapter number.
+.
+Otherwise, it is the number of the
+.FONT CB ".HL 1"
+level.
+.
+This command acts as a
+.
+.P
+.EX
+.FONT CB ".BREAK;.TEST PAGE 9;.BLANK 3"
+.EE
+.
+.P
+followed by the
+.IR "section number" ,
+two
+.IR spaces ,
+and the
+.IR "section name" .
+.
+.FONT CI "HEADER LEVELS " CB 1
+and
+.FONT CB 2
+end with a
+.IR break .
+.FONT CI "HEADER LEVELS"
+.FONT CB 3 R ", " CB 4 R ,
+and
+.FONT CB 5
+end with a space\-dash\-space combination (#\-#).
+.
+.
+.TP
+.FONT CB .TITLE I " text"
+.TQ
+.FONT CB .T I " text"
+takes the remaining text as the title and outputs it on every page at
+line
+.FONT CB 0 R .
+.
+The default is no title.
+.
+If a
+.I title
+is desired, this
+.I command
+must be entered in the source file.
+.
+.
+.TP
+.FONT CB ".FIRST TITLE" I " text"
+.TQ
+.FONT CB ".FT" I " text"
+Same as
+.FONT CB .TITLE R ,
+but used to specify the title to be printed on the first page of the
+document.
+.
+This command must precede all text in the source file.
+.
+Use of the
+.FONT CB ".FIRST TITLE"
+command is the only way to print a title line on the first page of the
+document.
+.
+.
+.TP
+.FONT CB .SUBTITLE I " text"
+.TQ
+.FONT CB .SUBTTL I " text"
+.TQ
+.FONT CB .ST I " text"
+takes the remaining text as the
+.I subtitle
+and outputs it on every page.
+.
+It appears directly under the title.
+.
+The
+.I subtitle
+is not
+.IR indented ,
+but
+.I indentation
+can be achieved by typing leading spaces.
+.
+.
+.TP
+.FONT CB .INDEX I " text"
+.TQ
+.FONT CB .X I " text"
+takes the remaining text on the line as a keyword and adds it, along
+with the current
+.IR "page number" ,
+to the internal index buffer.
+.
+The command does not cause a
+.IR break .
+.
+It should appear immediately before the item to be
+.IR indexed .
+.
+A keyword may be
+.I indexed
+more than once.
+.
+.
+.TP
+.FONT CB ".DO INDEX" I " text"
+.TQ
+.FONT CB ".DX" I " text"
+forces a new page, centers the text, if given, otherwise it centers
+the word
+.FONT CI "INDEX" R .
+.
+This command prints the entire contents of the index buffer.
+.
+Entries are printed in alphabetic order and are set against the left
+margin.
+.
+Regular line spacing is used, except that a blank line is left between
+entries of different first letters.
+.
+The page number of each entry is placed on the same line as the entry
+and in the middle of the page.
+.
+Additional page numbers for multiple entries follow, separated by
+commas.
+.
+The index buffer is left empty.
+.
+.
+.TP
+.FONT CB ".PRINT INDEX"
+.TQ
+.FONT CB ".PX"
+forces a new page after which it prints the entire contents of the
+index buffer.
+.
+Entries are printed in alphabetical order and are set against the left
+margin.
+.
+Regular line spacing is used, except that a blank line is left between
+entries of different first letters.
+.
+The number of the first page on which each entry appeared is put on
+the same line as the entry, beginning at the middle of the line
+(midway betweeen the left and right margins).
+.
+Additional page numbers for multiple entries follow, separated by
+commas.
+.
+The index buffer is left empty.
+.
+.
+.P
+.FONT CB ".PRINT INDEX"
+and
+.FONT CB ".DO INDEX"
+perform the same task.
+.
+The only difference is that
+.FONT CB ".PRINT INDEX"
+does not interrupt the normal chapter and page sequencing.
+.
+.
+.TP
+.FONT CB .SUBPAGE
+executes a
+.FONT CB .PAGE
+with page numbering suspended.
+.
+The page number is unchanged, but letters are appended to the page
+number.
+.
+This permits insertion of additional pages within an existing document
+without changing the existing page numbering.
+.
+.
+.TP
+.FONT CB ".END SUBPAGE"
+disengages the
+.FONT CB .SUBPAGE
+command by executing a
+.FONT CB .PAGE
+command with page numbering resumed.
+.
+.
+.TP
+.FONT CB .APPENDIX I " text"
+.TP
+.FONT CB .AX I " text"
+starts a new appendix using the text as the title of the appendix.
+.
+This command acts as if the following command string were entered:
+.
+.RS
+.P
+.EX
+.nop ".BREAK;.PAGE;.BLANK 12;.CENTER;APPENDIX a"
+.EE
+.RE
+.P
+The a is a letter that is incremented alphabetically automatically.
+.
+After the
+.FONT CB "APPENDIX A"
+is typed on the page,
+.
+.RS
+.P
+.EX
+.nop .BLANK 2;.CENTER;text;.BLANK 3
+.EE
+.RE
+.
+.P
+occurs.
+.
+This command then resets the
+.IR case ,
+.IR margins ,
+.IR spacing ,
+and
+.IR justify/fill
+modes.
+.
+It also clears any subtitles and sets the appendix name as the title.
+.
+.
+.TP
+.FONT CB ".NUMBER APPENDIX" I " a"
+supplies a letter
+.I a
+to be used as the letter for a subsequent
+.FONT CB .APPENDIX
+command.
+.
+.
+.TP
+.FONT CB .HEADER I " arg"
+.TQ
+.FONT CB .HD I " arg"
+causes the page header
+.RI ( title ,
+.IR subtitle ,
+and
+.IR "page number" )
+to be printed.
+.
+.I arg should be
+.FONT CB UPPER
+to specify
+.I upper case characters
+for the title text,
+.FONT CB LOWER
+to specify
+.IR "lower case" ,
+or
+.FONT CB MIXED R .
+.
+The initial setting is
+.FONT CB ".HEADER UPPER" R .
+.
+.
+.TP
+.FONT CB .NOHEADER
+.TP
+.FONT CB .NHD
+causes the page header
+.RI ( title ,
+.IR subtitle ,
+and
+.IR "page number" )
+to be omitted.
+.
+The header lines are completely omitted, so that text begins at the
+top of the page with no
+.IR "top margin" .
+.
+.
+.\" --------------------------------------------------------------------
+.SS Mode Setting Commands
+.\" --------------------------------------------------------------------
+.
+.TP
+.FONT CB .JUSTIFY
+.TQ
+.FONT CB .J
+causes a break and sets subsequent output lines to be justified
+(initial setting).
+.
+The
+.I command
+increases the spaces between words until the last word exactly meets
+the right margin.
+.
+.
+.TP
+.FONT CB .NOJUSTIFY
+.TQ
+.FONT CB .NJ
+causes a
+.I break
+and prevents
+.I justification
+of subsequent output lines to make a ragged right margin.
+.
+.
+.TP
+.FONT CB .FILL
+.TQ
+.FONT CB .F
+causes a break and specifies that subsequent output lines be filled
+(inital setting).
+.
+Sets the justification mode to be that specified by the last
+appearance of
+.FONT CB  .JUSTIFY
+or
+.FONT CB NOJUSTIFY R .
+.
+.FONT CB .FILL
+adds successive words from the source text until the adding of one
+more word will exceed the right margin.
+.
+It stops before putting the last word in.
+.
+(If
+.I hyphenation
+has not been disabled,
+.FONT CB RNO
+will attempt to
+.I break
+words which cause line overflow into syllables.)
+.
+.
+.TP
+.FONT CB .NOFILL
+.TP
+.FONT CB .NF
+disengages the
+.I fill
+and
+.IR "justify modes" .
+.
+This
+.I command
+is used to permit typing a table.
+.
+.
+.RS
+.
+.
+.P
+.ce
+NOTE
+.
+.P
+1. The
+.I nofill\-nojustify mode
+need be used only where there are several lines of material to be
+copied exactly.
+.
+A single line example will not require using these commands if there
+are breaks before and after.
+.
+.
+.P
+2. Normally
+.FONT CB .FILL
+and
+.FONT CB NOFILL
+are used to turn both
+.I filling
+and
+.I justification
+on and off.
+.
+It is usually desirable to do both.
+.
+A subsequent appearance of a
+.I justification command
+will override the
+.I fill command
+however.
+.
+.
+.P
+3. Because of the action of
+.FONT CB .FILL R ,
+a single occurrance of
+.FONT CB NOJUSTIFY
+will cause the remainder of the file to be
+.IR unjustified ,
+with
+.I filling
+as specified.
+.
+In order to
+.I justify
+but
+.I not fill
+(not recommended), a
+.FONT CB .JUSTIFY
+command must follow every
+.FONT CB .NOFILL
+command.
+.
+.
+.RE
+.
+.
+.TP
+.FONT CB ".UPPER CASE"
+.TQ
+.FONT CB .UC
+sets the output mode to
+.IR "upper case" .
+.
+This comand acts the same as typing two
+.CI circumflexes
+.FONT CB ^^ R .
+.
+This is the default mode.
+.
+There is no need to type this command unless the mode was previously
+altered to
+.IR "lower case" .
+.
+.
+.TP
+.FONT CB ".LOWER CASE"
+.TQ
+.FONT CB .LC
+sets the typeout mode to
+.IR "lower case" .
+This command acts the same as typing two
+.I back\-slashes
+.FONT CB \[rs]\[rs] R .
+.
+.
+.TP
+.FONT CB ".FLAGS CAPITALIZE"
+.TQ
+.FONT CB ".FL CAPITALIZE"
+enables the
+.CI less\-than
+.FONT CB <
+character to
+.I capitalize
+the entire word it precedes.
+.
+It then returns the file to the current case mode.
+.
+This
+.I special character
+is usually
+.FONT CR off
+and must be typed at the very beginning of the source text to enable
+this character.
+.
+Typing a space or another
+.FONT CI "less\-than " CB <
+returns the file to the current
+.IR "case lock" .
+.
+.
+.TP
+.FONT CB ".NO FLAGS CAPITALIZE"
+.TQ
+.FONT CB .NFC
+disengages the
+.FONT CB "FLAG CAPITALIZE"
+command (inital setting).
+.
+.
+.TP
+.FONT CB .HYPHENATION
+.TQ
+.FONT CB .HY
+engages
+.I hyphenization
+(initial setting).
+.
+.
+.TP
+.FONT CB ".NO HYPHENATION"
+.TQ
+.FONT CB .NHY
+disengages
+IR hyphenization .
+.
+.
+.TP
+.FONT CB ".FLAGS HYPHENATE"
+.TQ
+.FONT CB ".FL HYPHENATE"
+enables the
+.I equals character
+.FONT CB =
+to disengage
+.I hyphenization
+for the word it precedes.
+.
+This
+.I special character
+is initially
+.FONT CR off
+and must be typed at the beginning of the source file to enable this
+character.
+.
+The
+.FONT CI "FLAGS HYPHENATE"
+.I character
+is used to disengage
+.I hyphenization
+for words improperly
+.I hyphenated
+by the
+.IR "hyphenization algorithm" .
+.
+.
+.TP
+.FONT CB ".NO FLAGS HYPHENATE"
+.TQ
+.FONT CB .NFH
+disengages the
+.FONT CB ".FLAGS HYPHENATE"
+command (initial setting).
+.
+.
+.TP
+.FONT CB .NFL
+disengages the
+.FONT CB ".FLAGS CAPITALIZE"
+and the
+.FONT CB ".FLAGS HYPHENATE"
+commands (initial setting).
+.
+.
+.TP
+.FONT CB .PERIOD
+.TQ
+.FONT CB .PR
+enables printing of two
+.I spaces
+after every
+.I period
+.FONT CB .
+that is followed by at least one
+.I separator character
+(initial setting).
+.
+.
+.TP
+.FONT CB .NOPERIOD
+.TQ
+.FONT CB .NPR
+disengages conversion of
+.I period/separator
+to
+.IR "period/two spaces" .
+.
+.
+.TP
+.FONT CB .LITERAL
+.TQ
+,FONT CB .LIT
+disengages
+.I fill/justify
+to permit printing of text exactly as entered in source file.
+.
+.
+.TP
+.FONT CB ".END LITERAL"
+.TQ
+.FONT CB .ELI
+used after
+.FONT CB .LITERAL
+command to re\-engage
+.IR fill/justify .
+.
+.
+.\" --------------------------------------------------------------------
+.SS Parameter Setting Commands
+.\" --------------------------------------------------------------------
+.
+.TP
+.FONT CB ".LEFT MARGIN" I " n"
+.TQ
+.FONT CB .LM I " n"
+sets the left margin to
+.IR n .
+.
+The
+.I n
+must be less than the right margin but not less than
+.FONT CB 0 R .
+The initial setting is
+.FONT CB 0 R .
+If
+.I n
+is not supplied,
+.FONT CB 0
+is used.
+.
+.
+.TP
+.FONT CB ".RIGHT MARGIN" I " n"
+.TQ
+.FONT CB .RM I " n"
+sets the right margin
+.IR n .
+The
+.I n
+must be greater than the left margin.
+.
+The initial setting is
+.FONT CB 60 R .
+.
+If
+.I n
+is not supplied, the current page width (set with the
+.FONT CB ".PAGE SIZE"
+command) is used.
+.
+.
+.TP
+.FONT CB ".PAPER SIZE" I " n" CB , I m
+.TP
+.FONT CB ".PAGE SIZE" I " n" CB , I m
+.TP
+.FONT CB ".PS" I " n" CB , I m
+sets the size of the page
+.I n
+lines by
+.I m
+columns and sets the right margin to
+.IR m .
+The default setting is
+.FONT CB 58,60 R .
+.
+.
+.TP
+.FONT CB .PITCH I " n" CB , I m
+.TQ
+.FONT CB .PIT I " n" CB , I m
+sets the horizontal and vertical pitch on a supporting output device.
+.
+The horizontal pitch is
+.I n
+and is specified as characters per inch.
+.
+The value must divide evenly into
+.FONT CB 60
+for
+.FONT CI "Anderson\-Jacobson devices"
+and into
+.FONT CB 120
+for
+.FONT CI "Diablo devices" R .
+.
+The default is
+.FONT CB 12 R .
+.
+.
+.P
+The vertical pitch is
+.I m
+and is specified as lines per inch.
+.
+.I m
+must divide evenly into
+.FONT CB 48 R .
+.
+The default is the hardware setting.
+.
+.I n
+and
+.I m
+may be set independently.
+.
+.
+.TP
+.FONT CB .SPACING I " n"
+.TQ
+.FONT CB .SP I " n"
+sets the number of spaces between lines.
+.
+The
+.I n
+can range from
+.FONT CB 1
+to
+.FONT CB 5 R .
+.
+The default setting is
+.FONT CB 1 R .
+.
+.FONT CB ".SPACING 1"
+is like
+.I single spacing
+on a typewriter and
+.FONT CB ".SPACING 2"
+is like
+.IR "double spacing" .
+.FONT CB ".SPACING 2"
+puts one
+.I blank line
+between lines of text.
+.
+.
+.TP
+.FONT CB .STANDARD I " n"
+.TQ
+.FONT CB .SD I " n"
+returns all parameters, except the pitch settings, to their initial
+settings and sets
+.I n
+as the page width.
+.
+If
+.FONT CB ".STANDARD 60"
+is specified, margins are reset
+.FONT CB ".LM 0" R ,
+.FONT CB ".RM 60" R ,
+.FONT CB ".PAGE SIZE 58,60" R ,
+.FONT CB ".SPACING 1" R ,
+.FONT CB "PARAGRAPH INDENT 5" R ,
+and
+.I fill
+and
+.I justify
+are enabled.
+.
+.FONT CB ".STANDARD 70"
+sets right margin to
+.FONT CB 70
+and
+.I page size
+to
+.FONT CB 58,70 R .
+.
+.
+.TP
+.FONT CB ".TAB STOPS" I " n" CB , I n CB , I \*[Ellipsis]
+.TQ
+.FONT CB ".TS" I " n" CB , I n CB , I \*[Ellipsis]
+sets tabs.
+.
+The
+.I  n
+must be greater than
+.FONT CB 0
+and listed in ascending order.
+.
+If tabs already exist, the issuing of another
+.FONT CB ".TAB STOPS"
+command clears all previous
+.I tabs
+before setting new ones.
+.
+The
+.I default tabs
+are set at eight\-column intervals to match the
+.FONT CR Digital
+hardware standard.
+.
+These
+.I tabs
+are at columns
+.FONT CB 8 R ,
+.FONT CB 16 R ,
+.FONT CB 24 R ,
+.FONT CB 32 R ,
+.FONT CB 40 R ,
+.FONT CB 48 R ,
+.FONT CB 56 R ,
+.FONT CB 64 R ,
+.FONT CB 72 R ,
+and
+.FONT CB 80 R .
+.
+The tabs are converted to the appropriate number of non\-expandable
+spaces.
+.
+If there are no regular spaces to the left of the
+.IR tabs ,
+they will print out at the appropriate position, even if
+.I fill
+is on.
+.
+If
+.I literal
+is on, the
+.I tabs
+are not converted to
+.IR spaces ,
+but are output as
+.IR tabs .
+.
+.
+.TP
+.FONT CB .AUTOPARAGRAPH
+.TQ
+.FONT CB .AP
+causes any
+.I blank line
+or any line starting with a
+.I space
+or
+.I tab
+to be considered as the start of a new paragraph.
+.
+This command allows normally typed text to be
+.I justified
+without special commands.
+.
+It does not cause a paragraph if
+.I blank lines
+are followed by a command.
+.
+.
+.TP
+.FONT CB .NOAUTOPARAGRAPH
+.TQ
+.FONT CB .NAP
+disengages the
+.FONT CI AUTOPARAGRAPH
+mode.
+.
+.
+.\" --------------------------------------------------------------------
+.SS List of Commands (Alphabetical)
+.\" --------------------------------------------------------------------
+.
+.if t \{
+.ig endTBL
+.\}
+.
+.\" --------------------------------------------------------------------
+.\" Table using tbl for running in tty
+.\" --------------------------------------------------------------------
+.
+.nf
+.nh
+.
+.TS
+center,allbox,tab(@);
+cIw(1.5i) sw(1.5i) cIw(1.5i).
+Command or Abbreviation@Related Commands
+=
+.
+.T&
+l l l.
+\f[CB].AP\f[R]@(=\f[CB].AUTOPARAGRAPH\f[R])@
+\f[CB].APPENDIX\f[I] text \f[R]@(=\f[CB].AX\f[R])@\f[CB].NUMBER APPENDIX\f[I] a
+\f[CB].AX\f[R]@(=\f[CB].APPENDIX\f[R])@
+\f[CB].AUTOPARAGRAPH \f[R]@(=\f[CB].AP\f[R])@T{
+\f[CB].NOAUTOPARAGRAPH
+.br
+\f[R](\f[CB].NAP\f[R])
+T}
+_
+\f[CB].B\f[R]@(=\f[CB].BLANK\f[R])@
+\f[CB].BLANK \f[I]n \f[R]@(=\f[CB].B\f[R])@T{
+\f[CB].SKIP \f[I]n
+.br
+\f[R](\f[CB].S\f[R])
+T}
+\f[CB].BR\f[R]@(=\f[CB].BREAK\f[R])@
+\f[CB].BREAK@\f[R](=\f[CB].BR\f[R])
+_
+\f[CB].C\f[R]@(=\f[CB].CENTRE\f[R])@
+\f[CB].CENTER\f[R]@(=\f[CB].CENTRE\f[R])@
+\f[CB].CENTRE \f[I]n\f[CB];\f[I]text \f[R]@(=\f[CB].C\f[R])@
+\f[CB].CH\f[R]@(=\f[CB].CHAPTER\f[R])@
+\f[CB].CHAPTER \f[I]text \f[R]@(=\f[CB].CH\f[R])@\f[CB].NUMBER CHAPTER \f[I]n
+\f[CB].COMMENT \f[I]text\f[R]@@
+_
+\f[CB].DO INDEX \f[I]text \f[R]@(=\f[CB].DX\f[R])@T{
+.
+\f[CB].PRINT INDEX
+.br
+\f[R](\f[CB].PX\f[R])
+T}
+.
+\f[CB].DX\f[R]@(=\f[CB].DO INDEX\f[R])@
+_
+\f[CB].ELS\f[R]@(=\f[CB].END LIST\f[R])@
+\f[CB].EN\f[R]@(=\f[CB].END NOTE\f[R])@
+.
+\f[CB].END LIST\f[R]@(=\f[CB].ELS\f[R])@T{
+\f[CB].LIST \f[I]n
+.br
+\f[R](\f[CB].LS\f[R])
+T}
+.
+\f[CB].END LITERAL \f[R]@(=\f[CB].ELI\f[R])@T{
+\f[CB].LITERAL
+.br
+\f[R](\f[CB].LIT\f[R])
+T}
+.
+\f[CB].END NOTE\f[R]@(=\f[CB].EN\f[R])@T{
+\f[CB].NOTE \f[I]text
+.br
+\f[R](\f[CB].NT\f[R])
+T}
+.
+\f[CB].END SUBPAGE\f[R]@@\f[CB].SUBPAGE
+_
+\f[CB].F\f[R]@(=\f[CB].FILL\f[R])@
+\f[CB].FG\f[R]@(=\f[CB].FIGURE\f[R])@
+\f[CB].FIGURE n \f[R]@(=\f[CB].FG\f[R])@
+.
+\f[CB].FILL \f[R]@(=\f[CB].F\f[R])@T{
+\f[CB].NOFILL
+.br
+\f[R](\f[CB].NF\f[R])
+T}
+.
+\f[CB].FIRST TITLE \f[I]text\f[R]@(=\f[CB].FT\f[R])@\f[CB].TITLE \f[I]text
+.
+\f[CB].FLAGS CAPITALIZE\f[R]@(=\f[CB].FL CAPITALIZE\f[R])@T{
+\f[CB].NO FLAGS CAPITALIZE
+.br
+\f[R](\f[CB].NFL\f[R])
+T}
+.
+\f[CB].FLAGS HYPHENATE \f[R]@(=\f[CB].FL HYPHENATE\f[R])@T{
+\f[CB].NO FLAGS HYPHENATE
+.br
+\f[R](\f[CB].NFH\f[R])
+T}
+.
+\f[CB].FN\f[R]@(=\f[CB].FOOTNOTE\f[R])@
+\f[CB].FOOTNOTE \f[I]n\f[R]@(=\f[CB].FN\f[R])@
+\f[CB].FT\f[R]@(=\f[CB].FIRST TITLE\f[R])@
+_
+\f[CB].HD\f[R]@(=\f[CB].HEADER\f[R])@
+.
+T{
+\f[CB].HEADER \f[I]arg\f[R]
+.br
+\f[R]  [\f[I]arg\f[R]=\f[CB]UPPER\f[R], \f[CB]LOWER\f[R], or \f[CB]MIXED]\f[R]
+T}@(=\f[CB].HD\f[R])@T{
+\f[CB].NOHEADER
+.br
+\f[R](\f[CB].NHD\f[R])
+T}
+.
+\f[CB].HEADER LEVEL \f[I]n text\f[R]@(=\f[CB].HL\f[R])@
+\f[CB].HL\f[R]@(=\f[CB].HEADER LEVEL\f[R])@
+\f[CB].HY\f[R]@(=\f[CB].HYPHENATION\f[R])@
+.
+\f[CB].HYPHENATION \f[R]@(=\f[CB].HY\f[R])@T{
+\f[CB].NO HYPHENATION
+.br
+\f[R](\f[CB].NHY\f[R])
+T}
+.
+_
+\f[CB].I\f[R]@(=\f[CB].INDENT\f[R])@
+\f[CB].INDENT \f[I]n\f[R]@(=\f[CB].I\f[R])@
+\f[CB].INDEX \f[I]text \f[R]@(=\f[CB].X\f[R])@
+_
+\f[CB].J\f[R]@(=\f[CB].JUSTIFY\f[R])@
+.
+\f[CB].JUSTIFY \f[R](\f[CB].J\f[R])@@T{
+\f[CB].NOJUSTIFY
+.br
+\f[R](\f[CB].NJ\f[R])
+T}
+.
+_
+\f[CB].LC\f[R]@(=\f[CB].LOWER CASE\f[R])@
+\f[CB].LE\f[R]@(=\f[CB].LIST ELEMENT\f[R])@
+.
+\f[CB].LEFT MARGIN \f[I]n\f[R]@(=\f[CB].LM\f[R])@T{
+\f[CB].RIGHT MARGIN \f[I]n
+.br
+\f[R](\f[CB].RM\f[R])
+T}
+.
+\f[CB].LIST \f[I]n\f[R]@(=\f[CB].LS\f[R])@T{
+\f[CB].END LIST
+.br
+\f[R](\f[CB].ELS\f[R])
+T}
+.
+\f[CB].LIST ELEMENT;\f[I]text\f[R]@(=\f[CB].LE\f[R])@T{
+\f[CB].END LIST
+.br
+\f[R](\f[CB].ELS\f[R])
+T}
+.
+\f[CB].LIT\f[R]@(=\f[CB].LITERAL\f[R])@
+.
+\f[CB].LITERAL\f[R]@(=\f[CB].LIT\f[R])@T{
+\f[CB].END LITERAL
+.br
+\f[R](\f[CB].ELI\f[R])
+T}
+.
+\f[CB].LM\f[R]@(=\f[CB].LEFT MARGIN\f[R])@
+.
+\f[CB].LOWER CASE\f[R]@(=\f[CB].LC\f[R])@T{
+\f[CB].UPPER CASE
+.br
+\f[R](\f[CB].UC\f[R])
+T}
+.
+\f[CB].LS\f[R]@(=\f[CB].LIST\f[R])@
+_
+\f[CB].NAP\f[R]@(=\f[CB].NOAUTOPARAGRAPH\f[R])@
+\f[CB].NF\f[R]@(=\f[CB].NOFILL\f[R])@
+\f[CB].NFC\f[R]@(=\f[CB].NO FLAGS CAPITALIZE\f[R])@
+\f[CB].NFH\f[R]@(=\f[CB].NO FLAGS HYPHENATE\f[R])@
+.
+\f[CB].NFL\f[R]@T{
+(=\f[CB].NO FLAGS CAPITALIZE
+.br
+.ce
+\f[R] and
+.br
+\f[CB].NO FLAGS HYPHENATE\f[R])
+T}@
+.
+\f[CB].NHD\f[R]@(=\f[CB].NO HEADER\f[R])@
+\f[CB].NHY\f[R]@(=\f[CB].NO HYPHENATION\f[R])@
+\f[CB].NJ\f[R]@(=\f[CB].NO JUSTIFY\f[R])@
+\f[CB].NM\f[R]@(=\f[CB].NUMBER\f[R])@
+\f[CB].NNM\f[R]@(=\f[CB].NO NUMBER\f[R])@
+.
+\f[CB].NOAUTOPARAGRAPH\f[R]@(=\f[CB].NAP\f[R])@T{
+\f[CB].AUTOPARAGRAPH \f[R](\f[CB].AP\f[R])
+.br
+\f[CB]\ .PARAGRAPH \f[I]n,v,t \f[R](\f[CB].P\f[R])
+T}
+.
+\f[CB].NOFILL\f[R]@=(\f[CB].NF\f[R])@T{
+\f[CB].FILL
+.br
+\f[R](\f[CB].F\f[R])
+T}
+.
+\f[CB].NO FLAGS CAPITALIZE\f[R]@(=\f[CB].NFL\f[R])@T{
+\f[CB].FLAGS CAPITALIZE
+.br
+\f[R](\f[CB].FL CAPITALIZE\f[R])
+T}
+.
+\f[CB].NO FLAGS HYPHENATE\f[R]@(=\f[CB].NFH\f[R])@T{
+\f[CB].FLAGS HYPHENATE
+.br
+\f[R](\f[CB].FL HYPHENATE\f[R])
+T}
+.
+\f[CB].NOHEADER\f[R]@(=\f[CB].NHD\f[R])@T{
+\f[CB].HEADER \f[I]arg
+.br
+\f[R](\f[CB].HD\f[R])
+T}
+.
+\f[CB].NO HYPHENATION \f[R]@(=\f[CB].NHY\f[R])@T{
+\f[CB].HYPHENATION
+.br
+\f[R](\f[CB].HY\f[R])
+T}
+.
+\f[CB].NOJUSTIFY \f[R]@(=\f[CB].NJ\f[R])@T{
+\f[CB].JUSTIFY
+.br
+\f[R](\f[CB].J\f[R])
+T}
+.
+\f[CB].NONUMBER \f[R]@(=\f[CB].NNM\f[R])@T{
+\f[CB].NUMBER \f[I]n
+.br
+\f[R](\f[CB].NM\f[R])
+T}
+.
+\f[CB].NOPERIOD \f[R]@(=\f[CB].NPR\f[R])@T{
+\f[CB].PERIOD
+.br
+\f[R](\f[CB].PR\f[R])
+T}
+.
+\f[CB].NOTE text \f[R]@(=\f[CB].NT\f[R])@T{
+\f[CB].END NOTE
+.br
+\f[R](\f[CB].EN\f[R])
+T}
+.
+\f[CB].NPR\f[R]@(=\f[CB].NO PERIOD\f[R])@
+\f[CB].NT\f[R]@(=\f[CB].NOTE\f[R])@
+\f[CB].NUMBER APPENDIX \f[I]a\f[R]@@\f[CB].APPENDIX text
+\f[CB].NUMBER CHAPTER \f[I]n\f[R]@@\f[CB].CHAPTER text
+_
+\f[CB].P\f[R]@(=\f[CB].PARAGRAPH\f[R])@
+\f[CB].PAGE\f[R]@(=\f[CB].PG\f[R])@
+\f[CB].PAGE SIZE\f[R]@(=\f[CB].PAPER SIZE\f[R])@
+.
+\f[CB].PAPER SIZE \f[I]v\f[CB],\f[I]h\f[R]@T{
+(=\f[CB].PS\f[R]
+.br
+\f[CB].PAGE SIZE\f[R])
+T}@
+.
+\f[CB].PARAGRAPH \f[I]h\f[CB],\f[I]v\f[CB],\f[I]t \f[R]@(=\f[CB].P\f[R])@
+\f[CB].SKIP \f[I]n\f[R]@(=\f[CB].S\f[R])@\f[CB].BLANK \f[I]n \f[R](\f[CB].B\f[R])
+\f[CB].SP\f[R]@(=\f[CB].SPACING\f[R])@
+\f[CB].SPACING \f[I]n \f[R]@(=\f[CB].SP\f[R])@
+.
+\f[CB].PERIOD\f[R]@(=\f[CB].PR\f[R])@T{
+\f[CB].NOPERIOD
+.br
+\f[R](\f[CB].NPR\f[R])
+T}
+.
+\f[CB].PG\f[R]@(=\f[CB].PAGE\f[R])@
+\f[CB].PITCH\f[R]@(=\f[CB].PIT\f[R])@
+
+.\f[CB].PRINT INDEX \f[R]@(=\f[CB].PX\f[R])@T{
+\f[CB].DO INDEX text
+.br
+\f[R](\f[CB].DX\f[R])
+T}
+.
+\f[CB].PS\f[R]@(=\f[CB].PAPER SIZE\f[R])@
+\f[CB].PX\f[R]@(=\f[CB].PRINT INDEX\f[R])@
+_
+\f[CB].RIGHT MARGIN \f[I]n \f[R]@(=\f[CB].RM\f[R])@
+\f[CB].RM\f[R]@(=\f[CB].RIGHT MARGIN\f[R])@
+_
+\f[CB].S\f[R]@(=\f[CB].SKIP\f[R])@
+\f[CB].SD\f[R]@(=\f[CB].STANDARD\f[R])@
+\f[CB].ST\f[R]@(=\f[CB].SUBTITLE\f[R])@
+\f[CB].SUBPAGE\f[R]@@\f[CB].END SUBPAGE
+\f[CB].SUBTITLE \f[I]text \f[R]@(=\f[CB].ST\f[R])@
+_
+\f[CB].T\f[R]@(=\f[CB].TITLE\f[R])@
+\f[CB].TAB STOPS \f[I]n,n, \*[Ellipsis] ,n \f[R]@(=\f[CB].TS\f[R])@
+\f[CB].TEST PAGE \f[I]n \f[R]@(=\f[CB].TP\f[R])@
+\f[CB].TITLE text\f[R]@(=\f[CB].T\f[R])@
+\f[CB].TP\f[R]@(=\f[CB].TEST PAGE\f[R])@
+\f[CB].TS\f[R]@(=\f[CB].TAB STOPS\f[R])@
+_
+\f[CB].UC\f[R]@(=\f[CB].UPPER CASE\f[R])@
+.
+\f[CB].UPPER CASE\f[R]@(=\f[CB].UC\f[R])@T{
+\f[CB].LOWER CASE
+.br
+\f[R](\f[CB].LC\f[R])
+T}
+.
+_
+\f[CB].X\f[R]@(=\f[CB].INDEX\f[R])@
+.
+.TE
+.
+.hy
+.fi
+.
+.
+.\" End of tbl ----------------------------------------------------------------
+.
+.
+.if t \{
+.  endTBL
+.\}
+.
+.
+.\" use groff_hdtbl
+.if t \{
+.  mso hdtbl.tmac
+.  TableHDTBL
+.\}
+.
+.
+.\" --------------------------------------------------------------------
+.SH EXPERIMENTAL ADDITIONS 1965
+.\" --------------------------------------------------------------------
+.
+.
+These
+.I "control words"
+are documented in
+.FONT CI Saltzer R 's
+documentation of 1965.
+.
+It is unsure whether they were really implemented.
+.
+.
+.P
+In this documentation, all
+.I control words
+are written in
+.IR "lower case" .
+.
+The writing in
+.I upper case
+is not mentioned, the same is true for
+.IR abbreviations .
+.
+So this documentation uses only
+.IR "lower case" . 
+.
+.
+.TP
+.FONT CB .FIGURE
+This
+.I control word
+turns control over to a 
+.I figure
+.IR processor ,
+which creates in
+.I core memory
+a representation of a
+.I flow diagram
+under the control of a few special
+.IR "control words" .
+When the
+.I control word
+.FONT CB ".END FIGURE"
+is encountered, the completed picture is printed immediately on the
+page being generated if there is room on that page; otherwise the
+.I figure
+will appear at the top of the next page.
+.
+.
+.RS
+.
+.
+.P
+Text following the
+.FONT CB ".END FIGURE"
+.I control word
+will be smoothly attached to text before the
+.FONT CB .FIGURE R .
+.
+No break is generated.
+.
+(Restriction: If a
+.I figure
+is being held for placement at the top of the next page, another
+.I figure
+may not be encountered before the first one is printed.)
+.
+.
+.P
+The only
+.I control words
+which are recognized when in the
+.I \%figure processor
+are the following three:
+.FONT CB .FRAME R ,
+.FONT CB .BOX R ,
+and
+.FONT CB ".END FIGURE" R .
+.
+.
+.RE
+.
+.
+.TP
+.FONT CB .FRAME I " m n"
+This
+.I control word
+intitalizes the
+.I figure  processor
+by giving the height and width of the figure to be produced.
+.
+.I m
+is
+the height, in lines; and
+.I n
+is the width, in characters.
+.
+(Note that a 1050 types 6 lines per inch, and 10 characters per inch.)
+.
+.
+.RS
+.
+.
+.P
+Any attempt to place items in the picture which extend beyond the
+boundaries will cause an error comment to be generated.
+.
+.I \%m
+and
+.I \%n
+must both be less than 100 and their product must be smaller than
+5400.
+.
+We may now think of the
+.I figure
+to be produced as an array of
+.I m
+times
+.I n
+elements.
+.
+.
+.RE
+.
+.
+.TP
+.FONT CB .BOX I " i j"
+The text on the lines following this
+.I control word
+will be placed in the
+.I figure
+such that the first character on the first line following the
+.FONT CB .BOX
+will appear in row
+.IR i ,
+character position
+-IR j .
+.
+The end of the text is indicated by a
+.FONT CB .BOX
+.I control word
+for another piece of text or the
+.FONT CB ".END FIGURE"
+.I control
+.IR word .
+.
+Temporarily, the text should not include underlined or overtyped
+characters.
+.
+.
+.TP
+.FONT CB ".END FIGURE"
+This
+.I control word
+causes control to return to the regular
+.I control processor
+of the
+.FONT CB RUNOFF
+command, for the decision to print the picture.
+.
+Note that another
+.FONT CB .FIGURE
+.I control word
+may not appear until after this
+.I figure
+has been printed.
+.
+.
+.RS
+.P
+One further
+.I control word
+has been added which is intended to facilitate bringing out revised
+editions of a memorandum.
+.
+.
+.RE
+.
+.
+.TP
+.FONT CB .FLAG
+The next line to be printed after this
+.I control word
+is encountered will have an asterisk placed two spaces to the right of
+the right margin, as illustrated.
+.
+.
+.TP
+.FONT CB .DEFINE I " symbol"
+.
+This
+.I control word
+defines  the  value  of  the  symbol
+.I symbol
+to be the number of the page currently being printed.
+.
+The symbol may be used later with the
+.FONT CB .USE
+.I control word
+to cause printing of the page number in text.
+.
+The characters in the symbol must be mappable into the six\-bit
+character set, and all symbols must be six of fewer characters.
+.
+.
+.TP
+.FONT CB .USE I " symbol"
+The value of the symbol
+.I symbol
+is inserted into the text with a single blank preceding and no blank
+following.
+.
+If the symbol has not been previously defined, its value is
+.FONT CB 0 R .
+Text may continue following a blank typed after the symbol.
+.
+.
+.RS
+.
+.
+.P
+Here is an example of the use of these
+.I control
+.IR words .
+.
+.
+.RS
+.
+.
+.P
+In one area of text:
+.
+.
+.RS
+.
+.
+.P
+We now discuss the operation of the typewriter
+.FONT CB ".DEFINE REF1"
+coordinator module, which \*[Ellipsis]
+.
+.
+.RE
+.
+.
+.P
+In a later area of text:
+.
+.
+.RS
+.
+.
+.P
+As we saw in the discussion of the typewriter coordinator on page
+.FONT CB ".USE REF1" R ,
+the rest of \*[Ellipsis]
+.
+.
+.RE
+.
+.
+.P
+if the first area of text were on page 14, the later line would read:
+.
+.
+.RS
+.
+.
+.P
+As we saw in the discussion of the typewriter coordinator on page 14,
+the rest of \*[Ellipsis]
+.
+.
+.RE
+.RE
+.RE
+-
+.
+.\" --------------------------------------------------------------------
+.SS Further Study of Experimental Additions
+.\" --------------------------------------------------------------------
+.
+A number of suggestions have been made for extending the
+.I control word
+language of
+.FONT CI RUNOFF R ,
+and its capabilities.
+.
+These are listed here, primarily to elicit comment and discussion,
+both on the language which describes these operations and the less
+important problem of their implementation.
+-
+.
+.TP
+1.
+.
+Word division.
+.
+This is a whole are of study in itself.
+.
+.
+.TP
+2.
+.
+Automatic  footnote  insertion.
+.
+This was handled somewhat awkwardly in the
+.FONT CB DITTO
+.IR command ,
+although the basic approach was probably reasonable.
+.
+.
+.TP
+3.
+.
+Automatic page references, perhaps via some symbolic reference scheme.
+.
+This would enable the page number in "as was described on page 32" to
+be inserted by the program.
+.
+The analogy with an assembly program should be hotly pursued for
+ideas.
+.
+.
+.TP
+4.
+.
+Special provision for printing facing pages.
+.
+This would require alternate running heads, placing page numbers
+alternately at right and left, and matching line counts on facing
+pages.
+.
+.
+.TP
+5.
+.
+Improved page\-division rules, to prevent the last line of a paragraph
+appearing alone at the top of a page, for example.
+.
+At present, copy must be run off to check by hand that awkward page
+divisions have not been made.
+.
+.
+.TP
+6.
+.
+Automatic generation of page numbers for a table of contents.
+.
+Again, the analogy of an assembly program symbol table appears
+fruitful.
+.
+.
+.TP
+7.
+.
+Automatic generations of an index.
+.
+The problem here is obtaining too many references to a given word,
+many irrelevant.
+.
+.
+.TP
+8.
+.
+Arrangement of tabulated data.
+.
+This problem may have already been partly approached with the
+above\-described figure generator, or the facilities already available
+in
+.IR RUNOFF ,
+but automatic setup of column widths and positions would be desirable.
+.
+One could include in this category the ability to call on other
+programs to computer numbers to place in tables, although this is
+going pretty far afield.
+.
+.
+.TP
+9.
+.
+Placing figures in a
+.I "cut"
+or
+.IR inset .
+.
+The control language is the most difficult problem here.
+.
+.
+.TP
+10.
+.
+Equation typing and  numbering.
+.
+Again, the control language appears formidable.
+.
+.
+.\" --------------------------------------------------------------------
+.SH MANUSCRIPT CONVENTIONS
+.\" --------------------------------------------------------------------
+.
+Initially,
+.FONT CI RUNOFF
+is set to
+.I FILL
+mode, such as by using
+.FONT CB .FILL R .
+.
+The filling is identical to
+.FONT CI groff R 's
+filling mode:
+.
+Text lines will normally be adjuted by inserting extra spaces in
+mid\-line so that the end of the line is on the right margin.
+.
+.
+.\" --------------------------------------------------------------------
+.SH AVAILABLE RUNOFF FILES
+.\" --------------------------------------------------------------------
+.
+You can still find text files in the
+.FONT CI RUNOFF
+language.
+.
+.
+.P
+In the
+.nh
+.UR http://\:www.columbia.edu/\:kermit/\:pdp10.html
+Kermit website
+.UE
+you find 3 files in
+.FONT CI RUNOFF
+language maybe of the
+.FONT CR Multics
+era or later:
+.
+.Topic
+.UR ftp://\:kermit.columbia.edu/\:kermit/\:d/\:k10133.rno
+.FONT CR k10133.rno
+.UE
+.
+.Topic
+.UR ftp://\:kermit.columbia.edu/\:kermit/\:d/\:k10mit.rnh
+.FONT CR k10mit.rnh
+.UE
+.
+.Topic
+.UR ftp://\:kermit.columbia.edu/\:kermit/\:d/\:k10v3.rno
+.FONT CR k10v3.rno
+.UE
+.hy
+.
+.
+.P
+At
+.nh
+.UR http://\:web.mit.edu/\:Saltzer/\:www/\:publications/\:pubs.html
+.FONT CR Saltzer R 's
+publication website
+.UE
+you find files in
+.FONT CI RUNOFF
+of the
+.FONT CR Multics
+era.
+.hy
+.
+Search there for
+.nh
+.FONT CR runoff
+and you will find the following 5 files:
+.
+.Topic
+.UR http://\:web.mit.edu/\:Saltzer/\:www/\:publications/\:whyring/\:whyring.run
+.FONT CR whyring.run
+.UE
+.
+.Topic
+.UR http://\:web.mit.edu/\:Saltzer/\:www/\:publications/\:starring/\:starring.run
+.FONT CR starring.run
+.UE
+.
+.Topic
+.UR http://\:web.mit.edu/\:Saltzer/\:www/\:publications/\:tmring.run
+.FONT CR tmring.run
+.UE
+.
+.Topic
+.UR http://\:web.mit.edu/\:Saltzer/\:www/\:publications/\:florence.run
+.FONT CR "RFC1498 florence.run"
+.UE
+.
+.Topic
+.UR http://\:web.mit.edu/\:Saltzer/\:www/\:publications/\:sourcerouting/\:zurich.run
+.FONT CR zurich.run
+.UE
+.hy
+.
+.
+.P
+Most
+.nh
+.FONT CI RUNOFF
+files are found in the
+.UR http://\:pdp-10.trailing-edge.com/\:cgi-bin/
+.FONT CR "DEC PDP\-10 archive"
+.UE .
+.
+Many files are very old as they are written in
+.I upper case
+only:
+.
+.Topic
+.UR http://\:pdp-10.trailing-edge.com/\:cgi-bin/\:searchbyname?name=*.rno
+normal documents
+.FONT CB *.rno
+in
+.FONT CI RUNOFF
+.UE
+.
+.Topic
+.UR http://\:pdp-10.trailing-edge.com/\:cgi-bin/\:searchbyname?name=*.rnh
+.FONT CB *.rnh
+help files in
+.FONT CI RUNOFF
+.UE
+.
+.Topic
+.UR http://\:pdp-10.trailing-edge.com/\:cgi-bin/\:searchbyname?name=runoff.*
+.FONT CB runoff.*
+documents about
+.FONT CI RUNOFF
+.UE
+.hy
+.
+.
+.\" --------------------------------------------------------------------
+.SH "SEE ALSO"
+.\" --------------------------------------------------------------------
+.
+.
+.PP
+.\" BR RUNOFF (@MAN1EXT@),
+.BR groff (@MAN1EXT@),
+.BR groff (@MAN7EXT@),
+.BR roff (@MAN7EXT@),
+.BR groff_filenames (@MAN7EXT@)
+.
+.
+.TP
+.FONT R "1964 " CR "Jerome H. Saltzer" R :
+.nh
+.FONT CI "Jerome H. Saltzer \[em] TYPSET and RUNOFF, Memorandum editor and \
+type\-out commands"
+.hy
+available at
+.UR \%http://\:mit.edu/\:Saltzer/\:www/\:publications/\:CC\-244.html
+.UE
+.
+.
+.TP
+.FONT R "1965 " CR "Jerome H. Saltzer" R :
+.nh
+.FONT CI "Jerome H. Saltzer \(em Experimental Additions to the RUNOFF Command"
+available at
+.UR http://\:web.mit.edu/\:afs/\:athena.mit.edu/\:user/\:other/\
+\:a/\:Saltzer/\:www/\:publications/\:PSN\-40.html
+.UE
+.hy
+.
+.
+.TP
+.FONT R "1966 " CR "Jerome H. Saltzer" R :
+.nh
+.FONT CI "Jerome H. Saltzer \[em] Manuscript Typing and Editing"
+.hy
+which is available in the internet at
+.UR http://\:mit.edu/\:Saltzer/\:www/\:publications/\:AH.9.01.html
+.I MIT html
+.UE
+or
+.UR \%http://\:web.mit.edu/\:Saltzer/\:www/\:publications/\:ctss\/\:AH.9.01.html
+.I CTSS html
+.UE
+or
+.UR \%http://\:web.mit.edu/\:Saltzer/\:www/\:publications/\:ctss/\:AH.9.01.pdf
+.I CTSS pdf
+.UE .
+.
+.
+.TP
+.FONT R "1973 " CR "Larry Barnes" R :
+.FONT CI "Larry Barnes \[em] RUNOFF: A Program for the Preparation of Documents"
+available as
+.UR http://\:www.textfiles.com/\:bitsavers/\:pdf/\:sds/\:9xx/\:940/\
+\:ucbProjectGenie/\:mcjones/\:R\-37_RUNOFF.pdf
+.I pdf
+.UE .
+.
+.
+.TP
+.FONT R "1974 " CR "DEC RSTS" R :
+.FONT CI "RUNOFF User's Guide" R : CR " v8.0-v4-d-rsts_e_runoff_users_guide.pdf"
+at
+.UR http://elvira.stacken.kth.se/rstsdoc/rsts-doc-v80/v8.0-v4-d-rsts_e_runoff_users_guide.pdf
+.I DEC RSTS
+.UE .
+.
+.
+.TP
+.FONT R "1981 " CR PDP\-11 R :
+This is the latest documentation on
+.FONT CI RUNOFF
+available as
+.UR http://\:malarky.udel.edu/\:~dmills/\:data/\:du0/\:RUNOFF.DOC
+text file.
+.UE .
+.
+More exactly, this
+.FONT CB .DOC
+file is an output file produced by the
+.FONT CB RUNOFF
+program a long time ago.
+.
+This extension doesn't work on actual systems who expect a Microsoft
+office file.
+.
+You have to rename this file by appending the
+.FONT CB .txt
+extension.
+.
+Then the file can be viewed by
+.FONT CB more
+or
+.FONT CB less R .
+.
+.
+.P
+.nh
+.UR http://\:www.cozx.com/\:~dpitts/\:ibm7090.html 
+Emulator for
+.FONT CR "IBM 7090 CTSS"
+.UE .
+.hy
+.
+.
+.P
+The home page of
+.FONT CI "Jerome H. Saltzer"
+is
+.UR http://\:web.mit.edu/\:Saltzer/
+.UE .
+.
+.
+.SH "AUTHORS"
+.\" --------------------------------------------------------------------
+.
+.authors
+.
+.
+.\" --------------------------------------------------------------------
+.SH "COPYING"
+.\" --------------------------------------------------------------------
+.
+.copying
+.
+.
+.\" --------------------------------------------------------------------
+.\" Emacs settings
+.\" --------------------------------------------------------------------
+.
+.\" Local Variables:
+.\" mode: nroff
+.\" End:
+


From MAILER-DAEMON Mon Aug 12 00:40:34 2013
Received: from list by lists.gnu.org with archive (Exim 4.71)
	id 1V8jvm-0001vn-3f
	for mharc-groff-commit@gnu.org; Mon, 12 Aug 2013 00:40:34 -0400
Received: from eggs.gnu.org ([2001:4830:134:3::10]:44208)
	by lists.gnu.org with esmtp (Exim 4.71)
	(envelope-from <peter@schaffter.ca>) id 1V8jvc-0001sY-5K
	for groff-commit@gnu.org; Mon, 12 Aug 2013 00:40:32 -0400
Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71)
	(envelope-from <peter@schaffter.ca>) id 1V8jvQ-0008V8-Pc
	for groff-commit@gnu.org; Mon, 12 Aug 2013 00:40:24 -0400
Received: from vcs.savannah.gnu.org ([140.186.70.72]:41001)
	by eggs.gnu.org with esmtp (Exim 4.71)
	(envelope-from <peter@schaffter.ca>) id 1V8jvQ-0008Un-Cr
	for groff-commit@gnu.org; Mon, 12 Aug 2013 00:40:12 -0400
Received: from PTPi by vcs.savannah.gnu.org with local (Exim 4.72)
	(envelope-from <peter@schaffter.ca>) id 1V8jvP-0000qu-R4
	for groff-commit@gnu.org; Mon, 12 Aug 2013 04:40:12 +0000
Date: Mon, 12 Aug 2013 04:40:11 +0000
Message-Id: <E1V8jvP-0000qu-R4@vcs.savannah.gnu.org>
To: groff-commit@gnu.org
From: Peter Schaffter <peter@schaffter.ca>
X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6.x
X-Received-From: 140.186.70.72
Subject: [Groff-commit] groff/contrib/mom ChangeLog om.tmac momdoc/refe...
X-BeenThere: groff-commit@gnu.org
X-Mailman-Version: 2.1.14
Precedence: list
List-Id: <groff-commit.gnu.org>
List-Unsubscribe: <https://lists.gnu.org/mailman/options/groff-commit>,
	<mailto:groff-commit-request@gnu.org?subject=unsubscribe>
List-Archive: <http://lists.gnu.org/archive/html/groff-commit>
List-Post: <mailto:groff-commit@gnu.org>
List-Help: <mailto:groff-commit-request@gnu.org?subject=help>
List-Subscribe: <https://lists.gnu.org/mailman/listinfo/groff-commit>,
	<mailto:groff-commit-request@gnu.org?subject=subscribe>
X-List-Received-Date: Mon, 12 Aug 2013 04:40:32 -0000

CVSROOT:	/sources/groff
Module name:	groff
Changes by:	Peter Schaffter <PTPi>	13/08/12 04:40:11

Modified files:
	contrib/mom    : ChangeLog om.tmac 
	contrib/mom/momdoc: refer.html toc.html 

Log message:
	Updated documentation concerning refer usage.

CVSWeb URLs:
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/mom/ChangeLog?cvsroot=groff&r1=1.78&r2=1.79
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/mom/om.tmac?cvsroot=groff&r1=1.72&r2=1.73
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/mom/momdoc/refer.html?cvsroot=groff&r1=1.16&r2=1.17
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/mom/momdoc/toc.html?cvsroot=groff&r1=1.42&r2=1.43

Patches:
Index: ChangeLog
===================================================================
RCS file: /sources/groff/groff/contrib/mom/ChangeLog,v
retrieving revision 1.78
retrieving revision 1.79
diff -u -b -r1.78 -r1.79
--- ChangeLog	10 Jun 2013 13:39:30 -0000	1.78
+++ ChangeLog	12 Aug 2013 04:40:10 -0000	1.79
@@ -1,3 +1,9 @@
+* Sun Aug 11 2013
+
+o Updated documentation concerning refer usage
+
+o Replaced REF_STYLE and REF<bracket-style> macros with warnings.
+
 * Wed Jun 19 2013
 
 o groff_mom.man: Fix inappropriate use of .UR/.UE.

Index: om.tmac
===================================================================
RCS file: /sources/groff/groff/contrib/mom/om.tmac,v
retrieving revision 1.72
retrieving revision 1.73
diff -u -b -r1.72 -r1.73
--- om.tmac	7 Jun 2013 15:19:58 -0000	1.72
+++ om.tmac	12 Aug 2013 04:40:11 -0000	1.73
@@ -3,7 +3,7 @@
 Mom -- a typesetting/document-processing macro set for groff.
 
 Copyright (C) 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010,
-2011, 2012
+2011, 2012, 2013
 Free Software Foundation, Inc.
  Written by Peter Schaffter <peter@schaffter.ca>
  PDF integration contributed by Deri James <deri.james@chuzzlewit.co.uk>
@@ -23,8 +23,8 @@
 You should have received a copy of the GNU General Public License
 along with this program. If not, see <http://www.gnu.org/licenses/>.
 
-Version 2.0-a
--------------
+Version 2.0-a_1
+---------------
 Antoine de St-Exupéry asserted that elegance in engineering is
 achieved not when there is nothing left to add, but when there is
 nothing left to take away.
@@ -14125,7 +14125,6 @@
 .    ie '\\$1'' \{\
 .       rr #FN_REF
 .       rr #EN_REF
-.       REF_STYLE BIBLIO
 .       nr #BIBLIOGRAPHY 1
 .       nr #BIB_FIRST_PAGE 1
 .       nr #HEADER_STATE \\n[#HEADERS_ON]
@@ -16818,27 +16817,19 @@
 \# Embedded references in text (with brackets)
 \# -------------------------------------------
 \#
+.MAC REF_BRACKETS_NOTICE END
+.    tm1 "[mom]: \\$1 has been removed from mom.  See the mom documentation 'refer.html'
+.    tm1 "       for instructions on parenthetical insertions of references into text.
+.    ie '\\$1'REF_STYLE' .tm1 "       Continuing to process '\\n[.F]' from line \\n[.c].
+.    el .ab Aborting '\\n[.F]' at \\$1, line \\n[.c].
+.END
+\#
 .MAC REF_BRACKETS_START END
-.    if \\n[#FN_REF]=1 .nr #FN_REF 2
-.    if \\n[#EN_REF]=1 .nr #EN_REF 2
-.    ds $CURRENT_EV \\n[.ev]
-.    ev REFERENCE
-.    evc \\*[$CURRENT_EV]
-.    di REFERENCE
+.    REF_BRACKETS_NOTICE \\$0
 .END
 \#
 .MAC REF_BRACKETS_END END
-.    br
-.    di
-.    ev
-.    chop REFERENCE
-.    unformat REFERENCE
-.    if '\\$0'REF)' .nop (\\*[REFERENCE])
-.    if '\\$0'REF]' .nop [\\*[REFERENCE]]
-.    if '\\$0'REF}' .nop {\\*[REFERENCE]}
-.    if '\\$0'REF>' .nop <\\*[REFERENCE]>
-.    if \\n[#FN_REF]=2 .nr #FN_REF 1
-.    if \\n[#EN_REF]=2 .nr #EN_REF 1
+.    REF_BRACKETS_NOTICE \\$0
 .END
 \#
 \# These four pairs of aliases allow users to embed references in
@@ -16857,8 +16848,7 @@
 .ALIAS REF> REF_BRACKETS_END
 \#
 .MAC REF_STYLE END
-.    if '\\$1'NOTE'   .ds $REF_STYLE NOTE
-.    if '\\$1'BIBLIO' .ds $REF_STYLE BIBLIO
+.    REF_BRACKETS_NOTICE \\$0
 .END
 \#
 \# Refer indenting
@@ -17396,7 +17386,7 @@
 .   if \\n([T .nr ref*suppress-period \\n([T
 .\}
 .el \{\
-.   ie \\n([T .ref*field C "" " " " "
+.   ie \\n([T .ref*field C "" " "
 .   el \{\
 .      ie r [e .ref*field C "" " "
 .      el .ref*field C . " "

Index: momdoc/refer.html
===================================================================
RCS file: /sources/groff/groff/contrib/mom/momdoc/refer.html,v
retrieving revision 1.16
retrieving revision 1.17
diff -u -b -r1.16 -r1.17
--- momdoc/refer.html	29 Jan 2013 05:02:46 -0000	1.16
+++ momdoc/refer.html	12 Aug 2013 04:40:11 -0000	1.17
@@ -48,15 +48,17 @@
   <ul style="margin-left: -.5em; list-style-type: disc;">
     <li><a href="#db-ref">Create a <kbd>refer</kbd> database</a></li>
     <li><a href="#rcommands-ref">Insert a <kbd>refer</kbd> block</a></li>
-    <li><a href="#placement-ref">Tell mom where you want your references (footnotes/endnotes or a bibliography)</a></li>
+    <li><a href="#placement-ref">Tell mom where you want your references (if footnotes or endnotes)</a></li>
     <li><a href="#accessing-ref">Accessing references in the database</a></li>
     <li><a href="#fn-en-recipe">Entering footnote/endnote references</a></li>
-    <li><a href="#bibliography-recipe">Creating a bibliography</a></li>
+    <li><a href="#parenthetical">Parenthetical insertions</a></li>
+    <li><a href="#bibliography-from-embedded">Generating a bibliography from parenthetical insertions</h4></a></li>
+    <li><a href="#bibliography-recipe">Generating a comprehensive bibliography</a></li>
     <li><a href="#invoking-ref">Invoking groff with mom and <kbd>refer</kbd></a></li>
   </ul></li>
   <li><a href="#mla">MLA (Modern Language Association) style</a>
   <ul style="margin-left: -.5em; list-style-type: disc;">
-    <li><a href="#ref-styles">Types of references (endnote/footnote or bibliographic)</a></li>
+    <li><a href="#ref-styles">Types of references (endnote, footnote, or embedded in text)</a></li>
     <li><a href="#parenthetical">Inserting parenthetical references into the text</a></li>
   </ul></li>
   <li><a href="#database">The <kbd>refer</kbd> database</a>
@@ -143,12 +145,15 @@
   <li><a href="#rcommands-ref">Insert a <kbd>refer</kbd> block</a>
   <ul style="margin-left: -.5em; list-style-type: disc;">
     <li><a href="#fn-en-block">refer block for footnotes/endnotes</a></li>
-    <li><a href="#bibliography-block">refer block for bibliographies</a></li>
+    <li><a href="#in-text-block">refer block for parenthetical insertions into running text</a></li>
+    <li><a href="#bibliography-block">refer block for comprehensive bibliographies (reading lists)</a></li>
   </ul></li>
-  <li><a href="#placement-ref">Tell mom where you want your references (footnotes/endnotes or a bibliography)</a></li>
+  <li><a href="#placement-ref">Tell mom where you want your references (if footnotes or endnotes)</a></li>
   <li><a href="#accessing-ref">Accessing references in the database</a></li>
   <li><a href="#fn-en-recipe">Entering footnote/endnote references</a></li>
-  <li><a href="#bibliography-recipe">Creating a bibliography</a></li>
+  <li><a href="#parenthetical-insertions">Parenthetical insertions</a></li>
+  <li><a href="#bibliography-from-embedded">Generating a bibliography from parenthetical insertions</a></li>
+  <li><a href="#bibliography-recipe">Generating a comprehensive bibliography</a></li>
   <li><a href="#invoking-ref">Invoking groff with mom and <kbd>refer</kbd></a></li>
 </ol>
 
@@ -219,10 +224,14 @@
 and <kbd>.R2</kbd> lines is called a &#8220;refer block&#8221;.
 <kbd>Refer</kbd> commands in a refer block should be entered one per
 line, in lowercase letters, <i>with no initial period</i> (dot).
-The specific commands, and the placement of the block, depend on
-whether you want your references in footnotes/endnotes or in a
-bibliography.
+The actual commands depend on whether you want your references
 </p>
+<ul>
+<li>in footnotes/endnotes</li>
+<li>parenthetically inserted (in abbreviated form) into running text,
+referring to a works-cited list (bibliography)</li>
+<li>to generate a comprehensive bibliography (a reading list)</li>
+</ul>
 
 <h5 id="fn-en-block" class="docs" style="font-size: 90%; margin-top: .25em;">Refer block for footnotes/endnotes</h5>
 
@@ -249,11 +258,42 @@
 <kbd>/home/user/refer/my-database-file</kbd>.
 </p>
 
-<h5 id="bibliography-block" class="docs" style="font-size: 90%; margin-top: .25em;">Refer block for bibliographies</h5>
+<h5 id="in-text-block" class="docs" style="font-size: 90%; margin-top: .25em;">Refer block for parenthetical insertions into running text</h5>
 
 <p style="margin-top: .5em;">
-If you want a bibliography, place this block at the <i>bottom</i> of
-your mom file, either prior to or immediately after invoking
+If you want short, parenthetical insertions into running text,
+referring to works cited in a bibliography, place this block at
+the <i>top</i> of your mom file.
+</p>
+
+<div id="refer-block2" class="examples" style="margin-top: -.5em;">
+<div class="examples-container" style="padding-bottom: 1em;">
+<span class="pre">
+.R1
+label "(A.n|Q)"
+bracket-label " (" ")" ", "
+join-authors ", and " ", " ", and "
+move-punctuation
+reverse A1
+sort A1Q1T1B1E1
+database &lt;full path to database&gt;
+.R2
+</span>
+</div>
+</div>
+<p style="margin-top: .5em; font-size: 95%; line-height: 120%;">
+<kbd>&lt;full&nbsp;path&nbsp;to&nbsp;the&nbsp;database&gt;</kbd>
+means the full path including the filename, eg
+<kbd>/home/user/refer/my-database-file</kbd>.
+</p>
+
+<h5 id="bibliography-block" class="docs" style="font-size: 90%; margin-top: .25em;">Refer block for comprehensive bibliographies</h5>
+
+<p style="margin-top: .5em;">
+If you want to output an entire <kbd>refer</kbd> database, or
+generate a comprehensive bibliography (a reading list) from a
+database, place this block at the <i>bottom</i> of your mom file,
+either prior to or immediately after invoking
 <a href="#bibliography">BIBLIOGRAPHY</a>.
 </p>
 
@@ -278,12 +318,7 @@
 <kbd>/home/user/refer/my-database</kbd>.
 </p>
 
-<!-- Some sort of header saying "these blocks for these kinds of refs", followed
-     by en/fn block and bib block.  Make embedded refs, and a discussion of why they're
-     not really a good idea, another section.
--->
-
-<h4 id="placement-ref" class="docs">3. Tell mom where you want your references (footnotes/endnotes or a bibliography)</h4>
+<h4 id="placement-ref" class="docs">3. Tell mom where you want your references</h4>
 
 <p>
 If you want references in footnotes, issue the instruction
@@ -291,7 +326,9 @@
 <span class="pre-in-pp">
   .FOOTNOTE_REFS
 </span>
-anywhere before the first citation in your file.
+anywhere before the first citation in your file.  Footnote markers
+will be inserted into the text, and the bibliographic information
+for the citation will appear as a footnote.
 </p>
 
 <p>
@@ -300,18 +337,25 @@
 <span class="pre-in-pp">
   .ENDNOTE_REFS
 </span>
-anywhere before the first citation in your file.
+anywhere before the first citation in your file.  Endnote markers
+will be inserted into the text, and the bibliographic information
+for the citation will appear as an endnote entry.
 </p>
 
 <p>
-If you want your references in a bibliography, issue the instruction
-<br/>
-<span class="pre-in-pp">
-  .BIBLIOGRAPHY
-</span>
-at the end of your file, before
-<a href="tables-of-contents.html#TOC">TOC</a>
-(Table of Contents).
+Note that if you want references parenthetically inserted
+into running text, referring to entries in a works-cited list
+(bibliography) that <kbd>mom</kbd> and <kbd>refer</kbd> assemble
+automatically, no special instructions are required.  See
+<a href="#bibliography-from-embedded">Generating a bibliography from parenthetical insertions</a>
+for how to output the collected references.
+</p>
+
+<p>
+For outputting an entire <kbd>refer</kbd> database, or
+generating a comprehensive reading list from a database, see the
+macro,
+<a href="#bibliography">BIBLIOGRAPHY</a>.
 </p>
 
 <h4 id="accessing-ref" class="docs">4. Accessing references in the database</h4>
@@ -373,7 +417,7 @@
 If FOOTNOTE_REFS is in effect, the reference between the first
 and second <kbd>.REF</kbd> will be treated as a footnote.  If
 ENDNOTE_REFS, it will be treated as an endnote.  Endnote references
-must be explictly output with
+must be explicitly output with
 <a href="docelement.html#ENDNOTES">ENDNOTES</a>
 at the end of your file, before
 <a href="tables-of-contents.html#TOC">TOC</a>.
@@ -394,26 +438,48 @@
 </p>
 </div>
 
-<h4 id="bibliography-recipe" class="docs">6. Creating a bibliography</h4>
+<h4 id="parenthetical-insertions" class="docs">6. Parenthetical insertions</h4>
+
+<p>
+See
+<a href="#parenthetical">Inserting parenthetical references into
+text</a>.
+</p>
+
+<h4 id="bibliography-from-embedded" class="docs">7. Generating a bibliography from parenthetical insertions</h4>
+
+<p>
+To generate a bibliography from works cited by parenthetical
+insertions in the text, put this at the end of your document, before
+<kbd><a href="tables-of-contest.html#TOC">.TOC</a></kbd>.
+<br/>
+<span class="pre-in-pp">
+  .BIBLIOGRAPHY
+  .[
+  $LIST$
+  .]
+  .BIBLIOGRAPHY OFF
+</span>
+</p>
+
+<h4 id="bibliography-recipe" class="docs">8. Generating a comprehensive bibliography</h4>
 
 <p>
-Bibliographic references come between
+You can also generate a comprehensive bibliography, which is to say a
+bibliography containing more works than are actually cited (a
+&#8220;reading list&#8221;), by placing references between
 <kbd><a href="#bibliography">.BIBLIOGRAPHY</a></kbd>
 and
 <kbd><a href="#bibliography">.BIBLIOGRAPHY&nbsp;OFF</a></kbd>.
-They require no <kbd>.REF</kbd>&#8217;s surrounding the
-&nbsp;&nbsp;<kbd>.[</kbd>&nbsp;&nbsp;and&nbsp;&nbsp;<kbd>.]</kbd>&nbsp;&nbsp;commands.
-Once you have input the desired references, issue the
-following, exactly as shown:
+Once you have input the desired references, insert
 <br/>
 <span class="pre-in-pp">
   .[
   $LIST$
   .]
 </span>
-and follow it with <kbd>.BIBLIOGRAPHY&nbsp;OFF</kbd>.
-Study the example provided below if you&#8217;re having trouble
-visualizing this.
+and follow it with <kbd>.BIBLIOGRAPHY&nbsp;OFF</kbd>.  Study the
+example below if you&#8217;re having trouble visualizing this.
 </p>
 
 <div id="example-bibliography" class="examples" style="margin-top: -.5em;">Example bibliography</div>
@@ -442,9 +508,9 @@
 </div>
 
 <p>
-Alternatively, if you wish to output your entire database as a
-bibliography, do the following at the end of your document, before
-<kbd><a href="tables-of-contest.html#TOC">.TOC</a></kbd>:
+Alternatively, you can output an entire database as a
+bibliography.  Do the following at the end of your document, before
+<kbd><a href="tables-of-contest.html#TOC">.TOC</a></kbd>.
 <br/>
 <span class="pre-in-pp">
   .BIBLIOGRAPHY
@@ -460,7 +526,7 @@
 </span>
 </p>
 
-<h4 id="invoking-ref" class="docs">7. Invoking groff with mom and refer</h4>
+<h4 id="invoking-ref" class="docs">9. Invoking groff with mom and refer</h4>
 
 <p>
 So, now you&#8217;ve got a document formatted properly to use
@@ -484,14 +550,14 @@
 
 <h2 id="mla" class="docs">MLA (Modern Language Association) style</h2>
 
-<h3 id="ref-styles" class="docs">Types of references (endnote/footnote or bibliographic)</h3>
+<h3 id="ref-styles" class="docs">Types of references (endnote, footnote, or embedded in text)</h3>
 
 <p>
 MLA allows for three types of references, or referencing styles:
 </p>
 <ul style="margin-top: -.5em;">
-  <li>short, parenthetical references in the text, linked to a list
-      of works cited (a bibliography) at the end of the document</li>
+  <li>short, parenthetical references in the text, linked to a
+      works-cited list (bibliography) at the end of the document</li>
   <li>footnote references</li>
   <li>endnote references</li>
 </ul>
@@ -513,61 +579,138 @@
 <a href="docelement.html#footnote-into">footnote</a>
 or
 <a href="docelement.html#endnote-into">endnote</a>.
-Parenthetical references linked to a bibliography, however, need to
-be handled differently.
+Parenthetical references, however, need to be handled differently.
+See the next section.
 </p>
 
 <h3 id="parenthetical" class="docs">Inserting parenthetical references into the text</h3>
 
 <p>
 MLA style prefers restricting the information in parenthetical
-references to the barest minimum needed to find the cited work in
-the bibliography.  Human judgment is usually required, therefore
-it is generally best to enter the parenthetical references by hand
-rather than asking mom and <kbd>refer</kbd> to generate them.  While
-the latter is possible with the macro pair,
-<kbd><a href="#bracket-refs-parens">.REF(</a> /<a href="#bracket-refs-parens">.REF)</a></kbd>,
-it requires more work to set up your
-<a href="#db-ref">database</a>
-and interrupts the flow of your input file.  Consider these two
-examples, which accomplish exactly the same thing:
-</p>
-<div class="examples-container" style="padding-bottom: .25em;">
-<span class="pre-in-pp">
-  Ancient writers attributed the invention of the monochord
-  to Pythagoras, who lived in the sixth century BC (Marcuse,
-  \*[IT]Survey\*[ROM] 197).  Marcone, however, discovered
-  precursors of the instrument dating at least two centuries
-  earlier (\*[IT]Plectrum\*[ROM] 98).
-</span>
-</div>
-<span style="display: inline-block; padding-top: .5em; padding-bottom: .5em;">versus</span>
-<div class="examples-container" style="padding-bottom: .25em;">
-<span class="pre-in-pp">
-  Ancient writers attributed the invention of the monochord
-  to Pythagoras, who lived in the sixth century BC
-  .REF(
+references to the barest minimum needed to identify works
+in the works-cited list (the bibliography).  Typically, a
+parenthetical insertion is just the author&#8217;s last name
+followed by the page number of the cited work (if only one work by
+that author is cited), or by the author, a shortened title of the
+work, and the page number (if more than one work is cited).
+</p>
+
+<p>
+This necessitates a slightly fiddly way of entering parenthetical
+references, though not by any means difficult or hard to make sense
+of.
+</p>
+
+<p>
+The <kbd>refer</kbd> block suggested
+<a href="#refer-block2">here</a>
+for parenthetical references prints only the author&#8217;s
+last name from the database record identified by your keywords
+(the <kbd>label</kbd> command), surrounded by parentheses (the
+<kbd>bracket-label</kbd> command).  Therefore, assuming you are
+citing Ray Bradbury&#8217;s <i>The Martian Chronicles</i>, and it is
+the only work by Bradbury mentioned in the text,
+<br/>
+<span class="pre-in-pp">
+  ...end of sentence.
   .[
-  survey
-  %P 197
+  martian chronicles
   .]
-  .REF)
-  .  Marcone, however, discovered precursors of the instrument
-  dating at least two centuries earlier
-  .REF(
+  A new sentence...
+</span>
+will insert &#8220;<span style="font-family: times; font-size: 105%; font-weight: bold">...end of sentence (Bradbury). A new sentence...</span>&#8221; into the text.
+<i>The Martian Chronicles</i> will be added
+to the works-cited list generated at the end of the document if it
+is not already present as the result of an earlier reference.
+</p>
+
+<p>
+If you need a page number to identify where in <i>The Martian
+Chronicles</i> to find a specific quote
+<br/>
+<span class="pre-in-pp">
+  "...aluminum roaches and iron crickets."
   .[
-  plectrum
-  %P 98
-  .]
-  .REF)
-  .
+  [ martian chronicles
+  .] 168)
+  A new sentence...
 </span>
-</div>
+results in &#8220;<span style="font-family: times; font-size: 105%; font-weight: bold">&#8220;...aluminum roaches and iron crickets.&#8221; (Bradbury 168)  A new sentence...</span>&#8221;
+(which is excruciatingly correct MLA style).  The
+&#8220;<kbd>[</kbd>&#8221; before <kbd>martian&nbsp;chronicles</kbd> tells
+refer to print the opening parenthesis; any text immediately
+following the &#8220;<kbd>.]</kbd>&#8221;, including spaces,
+<i>replaces</i> the closing parenthesis.  (Notice that you have to
+add the closing parenthesis yourself after the page number.)
+</p>
 
 <p>
-Clearly, the first example takes less work, and is much easier to read.
+If your document cites more than one work by Bradbury and you need
+a title and page number in addition to the author's name in the
+inline reference,
+<br/>
+<span class="pre-in-pp">
+  "...aluminum roaches and iron crickets."
+  .[
+  [ bradbury martian
+  .], \fIChronicles\fP 168)
+  A new sentence...
+</span>
+will produce &#8220;<span style="font-family: times; font-size: 105%; font-weight: bold">&#8220;...aluminum roaches and iron crickets.&#8221; (Bradbury, <i>Chronicles</i> 168) A new sentence...&#8221;</span>&#8221;.
 </p>
 
+<div class="examples-container" style="margin-top: 1.5em; margin-bottom: 1.5em;">
+<h3 id="tutorial-ref" class="docs">The <span style="text-transform: none">&#8216;label&#8217;<span style="text-transform: uppercase"> and <span style="text-transform: none">&#8216;bracket-label&#8217;<span style="text-transform: uppercase"> commands</h3>
+
+<p>
+The <kbd>label</kbd> and <kbd>bracket-label</kbd> commands in
+the refer block allow you to customize what information goes
+into parenthetical references, and how they should be formatted.
+<kbd>label</kbd> dictates which fields from the database record
+to print and how to punctuate them. <kbd>bracket-label</kbd>
+controls the bracketing style.  Users are encouraged to consult
+<kbd>man&nbsp;refer</kbd> for usage.
+</p>
+
+<p>
+Here&#8217;s an example of how to set up APA-style references, which
+require the author and date of publication, optionally with a page
+number or range of pages.
+<br/>
+<span class="pre-in-pp">
+  .R1
+  label "(A.n|Q) ', ' D.y"
+  bracket-label " (" ")" ", "
+  join-authors ", and " ", " ", and "
+  move-punctuation
+  reverse A1
+  sort A1Q1T1B1E1
+  database /home/peter/Groff-mom/Testing/Refer/refer-database
+  .R2
+</span>
+Assuming a reference to a work by Ursula Leguin published in 1980
+<br/>
+<span class="pre-in-pp">
+  .[
+  leguin
+  .]
+</span>
+produces
+<span style="font-family: times; font-size: 105%; font-weight: bold">
+(Leguin, 1980)
+</span>.
+If a page number is also required
+<br/>
+<span class="pre-in-pp">
+  .[
+  [ leguin
+  .], p. 73)
+</span>
+produces
+<span style="font-family: times; font-size: 105%; font-weight: bold">(Leguin, 1980, p. 73)</span>.
+</p>
+</div>
+
 <div class="rule-medium" style="margin-top: 1em;"><hr/></div>
 
 <h2 id="database" class="docs">The refer database</h2>
@@ -935,17 +1078,9 @@
 <div class="macro-list-container">
 <h3 id="index-ref" class="macro-list">The bibliography and reference macros</h3>
 <ul class="macro-list">
-  <li><a href="#ref">REF</a> &ndash; begin/end a <kbd>refer</kbd> reference</li>
+  <li><a href="#ref">REF</a> &ndash; begin/end a <kbd>refer</kbd> reference that will go in a footnote or endnote</li>
   <li><a href="#footnote-refs">FOOTNOTE_REFS</a> &ndash; instruct mom to put REFs in footnotes</li>
   <li><a href="#endnote-refs">ENDNOTE_REFS</a> &ndash; instruct mom to put REFs in endnotes</li>
-  <li><a href="#bracket-refs">Embed references in the text</a>
-  <ul style="margin-left: -.5em;">
-    <li><a href="#bracket-refs-parens">REF(</a> &ndash; embed a reference in the text between parentheses</li>
-    <li><a href="#bracket-refs-brackets">REF[</a> &ndash; embed a reference in the text between square brackets</li>
-    <li><a href="#bracket-refs-braces">REF{</a> &ndash; embed a reference in the text between braces</li>
-    <li><a href="#bracket-refs-angle">REF&lt;</a> &ndash; embed a reference in the text between angle brackets</li>
-    <li><a href="#refs-style">REF_STYLE</a> &ndash; bibliography or footnote/endnote</li>
-  </ul></li>
   <li><a href="#indent-refs">INDENT_REFS</a> &ndash; manage indenting of references, per MLA standards</li>
   <li><a href="#hyphenate-refs">HYPHENATE_REFS</a> &ndash; enable/disable hyphenation of references</li>
   <li><a href="#bibliography">BIBLIOGRAPHY</a> &ndash; begin a bibliography</li>
@@ -957,7 +1092,7 @@
 <!-- -REF- -->
 
 <div class="macro-id-overline">
-<h3 id="ref" class="macro-id">Begin/end a <kbd style="text-transform: none;">refer</kbd> reference</h3>
+<h3 id="ref" class="macro-id">Begin/end a reference that goes in a footnote or endnote</h3>
 </div>
 
 <div class="box-macro-args">
@@ -966,18 +1101,17 @@
 
 <p>
 The macro, REF, tells mom that what follows is
-<kbd>refer</kbd>-specific, a keyword-identified reference from a
-<kbd>refer</kbd> database.  Depending on whether you&#8217;ve issued
+<kbd>refer</kbd>-specific, a keyword-identified reference to a
+<kbd>refer</kbd> database record.  Depending on whether you&#8217;ve issued
 a
 <kbd><a href="#footnote-refs">.FOOTNOTE_REFS</a></kbd>
 or
 <kbd><a href="#endnote-refs">.ENDNOTE_REFS</a></kbd>
-instruction, REF also tells mom where to place the reference.  If
-FOOTNOTE_REFS, the reference will be formatted and placed in a
-footnote.  If ENDNOTE_REFS, the reference will be collected for
-output as an endnote.  If you have issued neither instruction, the
-reference will be collected for later output, most likely in a
-<a href="#bibliography">bibliography</a>.
+instruction, the reference will be formatted and placed in a
+footnote, or collected for output in the endnotes.  Parenthetical
+insertion of references into the text do not require
+<kbd>.REF</kbd> (see
+<a href="#parenthetical">Inserting parenthetical references into the text</a>.)
 </p>
 
 <p>
@@ -1031,11 +1165,7 @@
 
 <p class="tip-bottom">
 <span class="additional-note">Additional note:</span>
-When REF is used with
-<a href="#footnote-refs">FOOTNOTE_REFS</a>
-or
-<a href="#endnote-refs">ENDNOTE_REFS</a>,
-it behaves identically to
+REF behaves identically to
 <a href="docelement.html#footnote">FOOTNOTE</a>
 or
 <a href="docelement.html#footnote">ENDNOTE</a>,
@@ -1043,7 +1173,8 @@
 for
 <a href="docelement.html#footnote-note">FOOTNOTE</a>
 and/or
-<a href="docelement.html#endnote-note">ENDNOTE</a>.
+<a href="docelement.html#endnote-note">ENDNOTE</a>
+for instructions on correct entry of text preceding and following REF.
 </p>
 </div>
 
@@ -1123,82 +1254,6 @@
 at any time.
 </p>
 
-<!-- -BRACKET_REFS- -->
-
-<div class="macro-id-overline">
-<h3 id="bracket-refs" class="macro-id">Embed references in the text</h3>
-</div>
-
-<div id="bracket-refs-parens" class="box-macro-args">
-Macro pair: <b>REF(</b>&nbsp;&nbsp;...&nbsp;&nbsp;<b>REF)</b>
-</div>
-
-<div id="bracket-refs-brackets" class="box-macro-args" style="margin-top: 1em;">
-Macro pair: <b>REF[</b>&nbsp;&nbsp;...&nbsp;&nbsp;<b>REF]</b>
-</div>
-
-<div id="bracket-refs-braces" class="box-macro-args" style="margin-top: 1em;">
-Macro pair: <b>REF{</b>&nbsp;&nbsp;...&nbsp;&nbsp;<b>REF}</b>
-</div>
-
-<div id="bracket-refs-angle" class="box-macro-args" style="margin-top: 1em;">
-Macro pair: <b>REF&lt;</b>&nbsp;&nbsp;...&nbsp;&nbsp;<b>REF&gt;</b>
-</div>
-
-<p>
-You may sometimes want to embed fairly complete references directly
-into the body of your document, typically, but not always, inside
-parentheses.  An instance where this might be desirable would be
-when there are one or two citations in a document where footnotes or
-endnotes are inappropriate, and a bibliography just plain silly (as
-it would be for just one or two citations).
-</p>
-
-<p>
-Mom allows you to embed references from your database directly into
-documents through the use of the REF&lt;bracket&nbsp;type&gt;
-macros.
-</p>
-
-<p>
-All four macro pairs, above, are invoked the same way, namely
-by introducing the reference with the first (&#8220;open&#8221;)
-macro of the REF&lt;bracket&nbsp;type&gt;
-pair, and terminating it with the second (&#8220;close&#8221;)
-REF&lt;bracket&nbsp;type&gt; of the pair.  For
-example
-<br/>
-<span class="pre-in-pp">
-  .REF(
-  .[
-  keyword(s)
-  .]
-  .REF)
-</span>
-will embed a reference in the body of your document, surrounded
-by parentheses. <kbd>.REF[</kbd>&nbsp;/&nbsp;<kbd>.REF]</kbd>
-will surround the reference with square brackets, etc.
-</p>
-
-<h3 id="ref-style" class="docs">REF_STYLE</h3>
-
-<p>
-When embedding references in the body of text, you&#8217;ll need to
-tell mom which formatting style to use: footnote/endnote or
-bibliography.  Footnote/endnote referencing style uses no periods
-between fields, only proper nouns and titles are capitalized, and
-publication data is enclosed in parentheses.  Bibliography
-referencing style separates each field with a period, every
-field begins with a capital letter, and publication data is not in
-parentheses.
-</p>
-
-<p>
-If you want footnote/endnote style, invoke
-<kbd>.REF_STYLE&nbsp;NOTE</kbd>.  If you want bibliographic style,
-invoke <kbd>.REF_STYLE&nbsp;BIBLIO</kbd>.
-</p>
-
 <!-- -INDENT_REFS- -->
 
 <div class="macro-id-overline">
@@ -1228,11 +1283,11 @@
 <p>
 By default, the indent for all three types of references is 1/2-inch
 for
-<a href="docprocessing.html#printstyle">PRINSTYLE <kbd>TYPEWRITE</kbd></a>
+<a href="docprocessing.html#printstyle">PRINTSTYLE <kbd>TYPEWRITE</kbd></a>
 and 2
 <a href="definitions.html#em">ems</a>
 for
-<a href="docprocessing.html#printstyle">PRINSTYLE <kbd>TYPESET</kbd></a>.
+<a href="docprocessing.html#printstyle">PRINTSTYLE <kbd>TYPESET</kbd></a>.
 </p>
 
 <p>
@@ -1327,9 +1382,7 @@
 <div class="box-tip">
 <p class="tip">
 <span class="note">Note:</span>
-References embedded in the body of a document with
-<kbd><a href="#bracket-refs">.REF &lt;bracket&nbsp;type&gt;</a></kbd>
-are considered part of
+References embedded in the body of a document are considered part of
 <a href="definitions.html#running">running text</a>,
 and are hyphenated (or not) according to whether hyphenation is
 turned on or off for running text.  Therefore, if you want to
@@ -1340,11 +1393,9 @@
 <br/>
 <span class="pre-in-pp">
   .HY OFF
-  .REF(
   .[
   keyword(s)
   .]
-  .REF)
   .HY
 </span>
 Alternatively, sprinkle your database fields liberally with
@@ -1363,12 +1414,16 @@
 </div>
 
 <p>
-If you want to append a bibliography to your document, all you need
+To append a bibliography to your document, whether of references
+inserted parenthetically into text or a comprehensive reading list
+derived from a large <kbd>refer</kbd> database, all you need
 do is invoke <kbd>.BIBLIOGRAPHY</kbd>. <kbd>.BIBLIOGRAPHY</kbd>
 breaks to a new page, prints the title (BIBLIOGRAPHY by default, but
 that can be changed), and awaits <kbd>refer</kbd> instructions.  How
 to create bibliographies is covered in the tutorial section,
-<a href="#bibliography-recipe">Creating bibliography pages</a>.
+<a href="#bibliography-from-embedded">Generating a bibliography from parenthetical insertions</a>
+and
+<a href="#bibliography-recipe">Generating a comprehensive bibliography</a>.
 When all the required data has been entered, type
 <br/>
 <span class="pre-in-pp">
@@ -1410,11 +1465,11 @@
 
 <p>
 You may enter the BIBLIOGRAPHY_TYPE either before or after
-<kbd>.BIBLIOGRAPHY</kbd>.  It must, however, always come before
-the <kbd>refer</kbd> command to output bibliographies.  (See the
-tutorial section,
-<a href="#biblio-ref">Creating bibliography pages</a>,
-for instructions on how to output bibliographies.)
+<kbd>.BIBLIOGRAPHY</kbd>.  It must, however, always come before the
+any <kbd>refer</kbd> commands.  See
+<a href="#bibliography-from-embedded">Generating a bibliography from parenthetical insertions</a>
+and
+<a href="#bibliography-recipe">Generating a comprehensive bibliography</a>.
 </p>
 
 <p>
@@ -1918,7 +1973,7 @@
 </div>
 
 <p class="requires">
-&bull;&nbsp;Argument requires a <a href="definitions.html#unitofmeasure">unit of measusure</a>
+&bull;&nbsp;Argument requires a <a href="definitions.html#unitofmeasure">unit of measure</a>
 </p>
 
 <p>
@@ -1969,7 +2024,7 @@
 <kbd>.BIBLIOGRAPHY_STRING_UNDERSCORE</kbd> will place a single rule
 underneath the bibliography&#8217;s first-page title.  Invoked with the
 argument, <kbd>DOUBLE</kbd>, BIBLIOGRAPHY_STRING_UNDERSCORE will
-double-underscore the thtile.  Invoked with any other non-numeric
+double-underscore the title.  Invoked with any other non-numeric
 argument, (eg <kbd>OFF, NO, X</kbd>, etc.) the macro disables
 underlining of the title.
 </p>

Index: momdoc/toc.html
===================================================================
RCS file: /sources/groff/groff/contrib/mom/momdoc/toc.html,v
retrieving revision 1.42
retrieving revision 1.43
diff -u -b -r1.42 -r1.43
--- momdoc/toc.html	29 Jan 2013 05:02:46 -0000	1.42
+++ momdoc/toc.html	12 Aug 2013 04:40:11 -0000	1.43
@@ -21,7 +21,7 @@
 
 <head>
   <meta http-equiv="content-type" content="text/html;charset=utf-8"/>
-  <title>Mom, version 2.0-a -- Table of Contents</title>
+  <title>Mom, version 2.0-a_1 -- Table of Contents</title>
   <link rel="stylesheet" type="text/css" href="stylesheet.css" />
 </head>
 


From MAILER-DAEMON Mon Aug 12 00:55:48 2013
Received: from list by lists.gnu.org with archive (Exim 4.71)
	id 1V8kAW-0004Rz-EC
	for mharc-groff-commit@gnu.org; Mon, 12 Aug 2013 00:55:48 -0400
Received: from eggs.gnu.org ([2001:4830:134:3::10]:46636)
	by lists.gnu.org with esmtp (Exim 4.71)
	(envelope-from <peter@schaffter.ca>) id 1V8kAS-0004Rn-IK
	for groff-commit@gnu.org; Mon, 12 Aug 2013 00:55:46 -0400
Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71)
	(envelope-from <peter@schaffter.ca>) id 1V8kAR-0005SH-Fz
	for groff-commit@gnu.org; Mon, 12 Aug 2013 00:55:44 -0400
Received: from vcs.savannah.gnu.org ([140.186.70.72]:38909)
	by eggs.gnu.org with esmtp (Exim 4.71)
	(envelope-from <peter@schaffter.ca>) id 1V8kAR-0005S5-Bf
	for groff-commit@gnu.org; Mon, 12 Aug 2013 00:55:43 -0400
Received: from PTPi by vcs.savannah.gnu.org with local (Exim 4.72)
	(envelope-from <peter@schaffter.ca>) id 1V8kAQ-0001Sc-L2
	for groff-commit@gnu.org; Mon, 12 Aug 2013 04:55:42 +0000
Date: Mon, 12 Aug 2013 04:55:42 +0000
Message-Id: <E1V8kAQ-0001Sc-L2@vcs.savannah.gnu.org>
To: groff-commit@gnu.org
From: Peter Schaffter <peter@schaffter.ca>
X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6.x
X-Received-From: 140.186.70.72
Subject: [Groff-commit] groff/contrib/mom/momdoc toc.html
X-BeenThere: groff-commit@gnu.org
X-Mailman-Version: 2.1.14
Precedence: list
List-Id: <groff-commit.gnu.org>
List-Unsubscribe: <https://lists.gnu.org/mailman/options/groff-commit>,
	<mailto:groff-commit-request@gnu.org?subject=unsubscribe>
List-Archive: <http://lists.gnu.org/archive/html/groff-commit>
List-Post: <mailto:groff-commit@gnu.org>
List-Help: <mailto:groff-commit-request@gnu.org?subject=help>
List-Subscribe: <https://lists.gnu.org/mailman/listinfo/groff-commit>,
	<mailto:groff-commit-request@gnu.org?subject=subscribe>
X-List-Received-Date: Mon, 12 Aug 2013 04:55:46 -0000

CVSROOT:	/sources/groff
Module name:	groff
Changes by:	Peter Schaffter <PTPi>	13/08/12 04:55:42

Modified files:
	contrib/mom/momdoc: toc.html 

Log message:
	Change version number in toc.html.

CVSWeb URLs:
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/mom/momdoc/toc.html?cvsroot=groff&r1=1.43&r2=1.44

Patches:
Index: toc.html
===================================================================
RCS file: /sources/groff/groff/contrib/mom/momdoc/toc.html,v
retrieving revision 1.43
retrieving revision 1.44
diff -u -b -r1.43 -r1.44
--- toc.html	12 Aug 2013 04:40:11 -0000	1.43
+++ toc.html	12 Aug 2013 04:55:42 -0000	1.44
@@ -32,7 +32,7 @@
 <div class="page">
 
   <div class="version">
-    mom, version 2.0-a
+    mom, version 2.0-a_1
   </div>
 
 <h1 class="toc" style="margin-top: 9px;">Table of Contents</h1>


From MAILER-DAEMON Tue Aug 20 01:59:23 2013
Received: from list by lists.gnu.org with archive (Exim 4.71)
	id 1VBeyR-00038a-3G
	for mharc-groff-commit@gnu.org; Tue, 20 Aug 2013 01:59:23 -0400
Received: from eggs.gnu.org ([2001:4830:134:3::10]:54164)
	by lists.gnu.org with esmtp (Exim 4.71)
	(envelope-from <groff-bernd.warken-72@web.de>) id 1VBeyJ-00031u-Rc
	for groff-commit@gnu.org; Tue, 20 Aug 2013 01:59:22 -0400
Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71)
	(envelope-from <groff-bernd.warken-72@web.de>) id 1VBeyB-0003xz-OZ
	for groff-commit@gnu.org; Tue, 20 Aug 2013 01:59:15 -0400
Received: from vcs.savannah.gnu.org ([140.186.70.72]:55166)
	by eggs.gnu.org with esmtp (Exim 4.71)
	(envelope-from <groff-bernd.warken-72@web.de>) id 1VBeyB-0003xu-Ig
	for groff-commit@gnu.org; Tue, 20 Aug 2013 01:59:07 -0400
Received: from bwarken by vcs.savannah.gnu.org with local (Exim 4.72)
	(envelope-from <groff-bernd.warken-72@web.de>) id 1VBeyA-00061I-If
	for groff-commit@gnu.org; Tue, 20 Aug 2013 05:59:06 +0000
Date: Tue, 20 Aug 2013 05:59:06 +0000
Message-Id: <E1VBeyA-00061I-If@vcs.savannah.gnu.org>
To: groff-commit@gnu.org
From: Bernd Warken <groff-bernd.warken-72@web.de>
X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6.x
X-Received-From: 140.186.70.72
Subject: [Groff-commit] groff/contrib/mom ChangeLog Makefile.sub mom.man
X-BeenThere: groff-commit@gnu.org
X-Mailman-Version: 2.1.14
Precedence: list
List-Id: <groff-commit.gnu.org>
List-Unsubscribe: <https://lists.gnu.org/mailman/options/groff-commit>,
	<mailto:groff-commit-request@gnu.org?subject=unsubscribe>
List-Archive: <http://lists.gnu.org/archive/html/groff-commit>
List-Post: <mailto:groff-commit@gnu.org>
List-Help: <mailto:groff-commit-request@gnu.org?subject=help>
List-Subscribe: <https://lists.gnu.org/mailman/listinfo/groff-commit>,
	<mailto:groff-commit-request@gnu.org?subject=subscribe>
X-List-Received-Date: Tue, 20 Aug 2013 05:59:22 -0000

CVSROOT:	/cvsroot/groff
Module name:	groff
Changes by:	Bernd Warken <bwarken>	13/08/20 05:59:06

Modified files:
	contrib/mom    : ChangeLog Makefile.sub 
Added files:
	contrib/mom    : mom.man 

Log message:
	New man-page mom.7

CVSWeb URLs:
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/mom/ChangeLog?cvsroot=groff&r1=1.79&r2=1.80
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/mom/Makefile.sub?cvsroot=groff&r1=1.33&r2=1.34
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/mom/mom.man?cvsroot=groff&rev=1.1

Patches:
Index: ChangeLog
===================================================================
RCS file: /cvsroot/groff/groff/contrib/mom/ChangeLog,v
retrieving revision 1.79
retrieving revision 1.80
diff -u -b -r1.79 -r1.80
--- ChangeLog	12 Aug 2013 04:40:10 -0000	1.79
+++ ChangeLog	20 Aug 2013 05:59:05 -0000	1.80
@@ -1,3 +1,7 @@
+* Tue Aug 20 2013
+
+o New man page mom.7
+
 * Sun Aug 11 2013
 
 o Updated documentation concerning refer usage

Index: Makefile.sub
===================================================================
RCS file: /cvsroot/groff/groff/contrib/mom/Makefile.sub,v
retrieving revision 1.33
retrieving revision 1.34
diff -u -b -r1.33 -r1.34
--- Makefile.sub	4 Jan 2013 07:19:51 -0000	1.33
+++ Makefile.sub	20 Aug 2013 05:59:06 -0000	1.34
@@ -43,7 +43,8 @@
   $(PDFMOMBIN) $(FFLAG) $(TFLAG)
 
 MAN7=\
-  groff_mom.n
+  groff_mom.n \
+  mom.man
 
 NORMALFILES=\
   mom.tmac

Index: mom.man
===================================================================
RCS file: mom.man
diff -N mom.man
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ mom.man	20 Aug 2013 05:59:06 -0000	1.1
@@ -0,0 +1,3231 @@
+.TH RUNOFF @MAN7EXT@ "@MDATE@" "Groff Version @VERSION@"
+.SH NAME
+mom \- the best \f[CI]roff\fP langugage, part of \f[CI]groff\fP
+.
+.SH "DESCRIPTION"
+.\" The .SH was moved to this place in order to appease `apropos'.
+.
+.\" --------------------------------------------------------------------
+.\" Legalese
+.\" --------------------------------------------------------------------
+.
+.de authors
+This file was written by Bernd Warken <groff-bernd.warken-72@web.de>.
+..
+.de copyleft
+.nh
+Copyright (C) 2013
+  Free Software Foundation, Inc.
+
+Last update: 14 August 2013
+
+This file is part of groff, a free software project.
+
+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.
+
+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 Text source package.
+
+Or read the man-page gpl (1).  You can also visit
+<http://www.gnu.org/licenses/>.
+.hy
+..
+.
+.\" --------------------------------------------------------------------
+.\" Setup
+.\" --------------------------------------------------------------------
+.
+.ds Ellipsis \&.\|.\|.\&\
+.
+.
+.\" --------------------------------------------------------------------
+.\" .FONT (<font name> <text> [<font name> <text> ...])
+.\"
+.\" Print in different fonts: R, I, B, CR, CI, CB
+.\"
+.de FONT
+.  if (\\n[.$] = 0) \{\
+.	nop \&\f[P]\&
+.	return
+.  \}
+.  ds result \&
+.  while (\\n[.$] >= 2) \{\
+.	as result \,\f[\\$1]\\$2
+.	if !"\\$1"P .as result \f[P]
+.	shift 2
+.  \}
+.  if (\\n[.$] = 1) .as result \,\f[\\$1]
+.  nh
+.  nop \\*[result]\&
+.  hy
+..
+.
+.\" --------------------------------------------------------------------
+.\" SH DESCRIPTION
+.\" The .SH was moved to the beginning in order to appease `apropos'.
+.\" --------------------------------------------------------------------
+.
+.
+This man-page contains information just as in groff(7),
+.I mom macros
+and
+.I mom escape sequences
+in alphabetical order.
+.
+.
+.P
+The logical order of
+.I mom macros
+and
+.I mom escape sequences
+is very well documented in
+.
+.TP
+.B \%@HTMLDOCDIR@/\:mom/\:toc.html
+\[en] entry point to the HTML documentation
+.
+.
+.P
+That is quite good for beginners, but power users need more
+documentation in reference style.
+.
+.
+.P
+So we restrict this man-page to the alphabetical order of macros and
+escape sequences.
+.
+But, so far, we take all documentation parts from the
+.I toc.html
+file, just in a more useful order.
+.
+Moreover, this is a man-page, so you can read it with
+.BR groffer ,
+instead of some strange webbrowser for
+.BR toc.html .
+.
+So this man-page is nothing new, but only a logical arrangement.
+.
+.
+.\" --------------------------------------------------------------------
+.SH "QUICK REFERENCE"
+.\" --------------------------------------------------------------------
+.
+.\" --------------------------------------------------------------------
+.SS "Quick Reference of Inline Escape Sequences in alphabetical Order"
+.\" --------------------------------------------------------------------
+.
+.TP
+.FONT B \[rs]*[ I <colorname> B ]
+begin using an initialized colour inline
+.
+.
+.TP
+.FONT B \[rs]*[BCK I " n" B ]
+move wards in a line
+.
+.
+.TP
+.BI \[rs]*[BOLDER]
+invoke pseudo bold inline (related to macro
+.BR .SETBOLDER )
+.
+.
+.TP
+.BI \[rs]*[BOLDERX]
+off pseudo bold inline (related to macro
+.BR .SETBOLDER )
+.
+.
+.TP
+.FONT B \[rs]*[BU I " n" B ]
+move characters pairs closer together inline (related to macro
+.BR \%.KERN )
+.
+.
+.TP
+.BI \[rs]*[COND]
+invoke pseudo condensing inline (related to macro
+.BR \%.CONDENSE )
+.
+.
+.TP
+.BI \[rs]*[CONDX]
+off pseudo condensing inline (related to macro
+.BR \%.CONDENSE )
+.
+.
+.TP
+.FONT B \[rs]*[CONDSUP] R \*[Ellipsis] B \[rs]*[CONDSUPX]
+pseudo-condensed superscript
+.
+.
+.TP
+.FONT B \[rs]*[DOWN I " n" B ]
+temporarily move downwards in a line
+.
+.
+.TP
+.BI \[rs]*[EN-MARK]
+mark initial line of a range of line numbers (for use with line
+numbered endnotes)
+.
+.
+.TP
+.BI \[rs]*[EXT]
+invoke pseudo extending inline (related to macro
+.BR \%.EXTEND )
+.
+.
+.TP
+.BI \[rs]*[EXTX]
+off pseudo condensing inline (related to macro
+.BR \%.EXTEND )
+.
+.
+.TP
+.FONT B \[rs]*[EXTSUP] R \*[Ellipsis] B \[rs]*[EXTSUPX]
+pseudo extrended superscript
+.
+.
+.TP
+.FONT B \[rs]*[FU I " n" B ]
+move characters pairs further apart inline (related to macro
+.BR \%.KERN )
+.
+.
+.TP
+.FONT B \[rs]*[FWD I " n" B ]
+move forward in a line
+.
+.
+.TP
+.BI \[rs]*[LEADER]
+insert leaders at the end of a line
+.
+.
+.TP
+.BI \[rs]*[RULE]
+draw a full measure rule
+.
+.
+.TP
+.FONT B \[rs]*[SIZE I " n" B ]
+change the point size inline (related to macro
+.BR \%.PT_SIZE )
+.
+.
+.TP
+.BI \[rs]*[SLANT]
+invoke pseudo italic inline (related to macro
+.BR \%.SETSLANT )
+.
+.
+.TP
+.BI \[rs]*[SLANTX]
+off pseudo italic inline (related to macro
+.BR \%.SETSLANT )
+.
+.
+.TP
+.FONT B \[rs]*[ST I <n> B ] R \*[Ellipsis] B \[rs]*[ST I <n> B X]
+string tabs (mark tab positions inline)
+.
+.
+.TP
+.FONT B \[rs]*[SUP] R \*[Ellipsis] B \[rs]*[SUPX]
+superscript
+.
+.
+.TP
+.B \[rs]*[TB+]
+Inline escape for
+.B .TN
+.RI ( "Tab Next" )
+.
+.
+.TP
+.FONT B \[rs]*[UL] R \*[Ellipsis] B \[rs]*[ULX]
+invoke underlining inline (fixed width fonts only)
+.
+.
+.TP
+.FONT B \[rs]*[UP I " n" B ]
+temporarily move upwards in a line
+.
+.
+.\" --------------------------------------------------------------------
+.SS "Quick Reference of Macros in alphabetical Order"
+.\" --------------------------------------------------------------------
+.
+.TP
+.BI .AUTOLEAD
+set the linespacing relative to the point size
+.
+.
+.TP
+.BI .B_MARGIN
+set a bottom margin
+.
+.
+.TP
+.BI .BR
+break a justified line
+.
+.
+.TP
+.BI .CENTER
+set line-by-line quad centre
+.
+.
+.TP
+.BI .CONDENSE
+set the amount to pseudo condense
+.
+.
+.TP
+.BI .EL
+break a line without advancing on the page
+.
+.
+.TP
+.BI .EXTEND
+set the amount to pseudo extend
+.
+.
+.TP
+.BI .FALLBACK_FONT
+establish a fallback font (for missing fonts)
+.
+.
+.TP
+.BI .FAM
+alias to
+.B .FAMILY
+.
+.
+.TP
+.BI .FAMILY <family>
+set the
+.I family type
+.
+.
+.TP
+.BI .FT
+set the font style (roman, italic, etc.)
+.
+.
+.TP
+.BI ".HI [" " <measure> " ]
+hanging indent
+.
+.
+.TP
+.BI .HY
+automatic hyphenation on/off
+.
+.
+.TP
+.BI .HY_SET
+set automatic hyphenation parameters
+.
+.
+.TP
+.BI ".IB [" " <left measure> <right measure> " ]
+indent both
+.
+.
+.TP
+.B .IBX [ CLEAR ]
+exit indent both
+.
+.
+.TP
+.BI ".IL [" " <measure> " ]
+indent left
+.
+.
+.TP
+.B .ILX [ CLEAR ]
+exit indent left
+.
+.
+.TP
+.B .IQ [ CLEAR ]
+quit any/all indents
+.
+.
+.TP
+.BI ".IR [" " <measure> " ]
+indent right
+.
+.
+.TP
+.B .IRX [ CLEAR ]
+exit indent right
+.
+.
+.TP
+.BI JUSTIFY
+justify text to both margins
+.
+.
+.TP
+.BI .KERN
+automatic character pair kerning on/off
+.
+.
+.TP
+.BI .L_MARGIN
+set a left margin (page offset)
+.
+.
+.TP
+.BI .LEFT
+set line-by-line quad left
+.
+.
+.TP
+.BI .LL
+set a line length
+.
+.
+.TP
+.BI .LS
+set a linespacing (leading)
+.
+.
+.TP
+.BI .PAGE
+set explicit page dimensions and margins
+.
+.
+.TP
+.BI .PAGEWIDTH
+set a custom page width
+.
+.
+.TP
+.BI .PAGELENGTH
+set a custom page length
+.
+.
+.TP
+.BI .PAPER " <paper_type>"
+set common paper sizes (letter, A4, etc)
+.
+.
+.TP
+.BI .PT_SIZE
+set the point size
+.
+.
+.TP
+.BI .QUAD
+"justify" text left, centre, or right
+.
+.
+.TP
+.BI .R_MARGIN
+set a right margin
+.
+.
+.TP
+.BI .RIGHT
+set line-by-line quad right
+.
+.
+.TP
+.BI .SETBOLDER
+set the amount of emboldening
+.
+.
+.TP
+.BI .SETSLANT
+set the degree of slant
+.
+.
+.TP
+.BI .SPREAD
+force justify a line
+.
+.
+.TP
+.BI .SS
+set the sentence space size
+.
+.
+.TP
+.BI .T_MARGIN
+set a top margin
+.
+.
+.TP
+.BI ".TI [" " <measure> " ]
+temporary left indent
+.
+.
+.TP
+.BI .WS
+set the minimum word space size
+.
+.
+.\" --------------------------------------------------------------------
+.SH "DOCUMENTATION OF DETAILS"
+.\" --------------------------------------------------------------------
+.
+.\" --------------------------------------------------------------------
+.SS "Details of Inline Escape Sequences in alphabetical Order"
+.\" --------------------------------------------------------------------
+.
+.TP
+.FONT B \[rs]*[ I <colorname> B ]
+begin using an initialized colour inline
+.
+.
+.TP
+.FONT B \[rs]*[BCK I " n" B ]
+move wards in a line
+.
+.
+.\" ======================================================================
+.\" BOLDER
+.\" ======================================================================
+.TP
+.B \[rs]*[BOLDER]
+.TQ
+.B \[rs]*[BOLDERX]
+Emboldening on/off
+.
+.RS
+.
+.P
+.B \[rs]*[BOLDER]
+begins emboldening type.
+.
+.B \[rs]*[BOLDERX]
+turns the feature off.
+.
+Both are inline escapes, therefore they should not appear as separate
+lines, but rather be embedded in text lines, like this:
+.RS
+.EX
+.FONT R "Not " B \[rs]*[BOLDER] R everything B \[rs]*[BOLDERX] R " is as it seems."
+.EE
+.RE
+.
+.P
+Alternatively, if you wanted the whole line emboldened, you should do 
+.RS
+.EX
+.FONT B \[rs]*[BOLDER] R "Not everything is as it seems." B \[rs]*[BOLDERX]
+.EE
+.RE
+.
+Once
+.B \[rs]*[BOLDER]
+is invoked, it remains in effect until turned off.
+.
+.P
+Note: If you’re using the document processing macros with
+.B PRINTSTYLE
+.BR TYPEWRITE ,
+.B mom
+ignores
+.B \[rs]*[BOLDER]
+requests.
+.
+.RE
+.
+.
+.\" ======================================================================
+.\" BU
+.\" ======================================================================
+.TP
+.FONT B \[rs]*[BU I " n" B ]
+move characters pairs closer together inline (related to macro
+.BR \%.KERN )
+.
+.
+.\" ======================================================================
+.\" COND
+.\" ======================================================================
+.TP
+.B \[rs]*[COND]
+.TQ
+.BI \[rs]*[CONDX]
+Pseudo-condensing on/off
+.
+.RS
+.
+.P
+.B \[rs]*[COND]
+begins pseudo-condensing type.
+.
+.B \[rs]*[CONDX]
+turns the feature off.
+.
+Both are inline escapes, therefore they should not appear as separate
+lines, but rather be embedded in text lines, like this:
+.RS
+.EX
+.FONT B \[rs]*[COND] I "Not everything is as it seems." B \[rs]*[CONDX]
+.EE
+.RE
+.B \%\[rs]*[COND]
+remains in effect until you turn it off with
+.BR \%\[rs]*[CONDX] .
+.
+.P
+IMPORTANT: You must turn
+.B \%\[rs]*[COND]
+off before making any changes to the point size of your type, either
+via the
+.B \%.PT_SIZE
+macro or with the
+.B \[rs]s
+inline escape.
+.
+If you wish the new point size to be pseudo-condensed, simply reinvoke
+.B \%\[rs]*[COND]
+afterwards.
+.
+Equally,
+.B \%\[rs]*[COND]
+must be turned off before changing the condense percentage with
+.BR \%.CONDENSE .
+.
+.P
+Note: If you’re using the document processing macros with
+.B \%PRINTSTYLE
+.BR \%TYPEWRITE ,
+.B mom
+ignores
+.B \%\[rs]*[COND]
+requests.
+.
+.RE
+.
+.
+.\" ======================================================================
+.\" CONDSUP
+.\" ======================================================================
+.TP
+.FONT B \[rs]*[CONDSUP] R \*[Ellipsis] B \[rs]*[CONDSUPX]
+pseudo-condensed superscript
+.
+.
+.\" ======================================================================
+.\" DOWN
+.\" ======================================================================
+.TP
+.FONT B \[rs]*[DOWN I " n" B ]
+temporarily move downwards in a line
+.
+.
+.\" ======================================================================
+.\" EN-MARK
+.\" ======================================================================
+.TP
+.BI \[rs]*[EN-MARK]
+mark initial line of a range of line numbers (for use with line
+numbered endnotes)
+.
+.
+.\" ======================================================================
+.\" EXT
+.\" ======================================================================
+.TP
+.B \[rs]*[EXT]
+.TQ
+.B \[rs]*[EXTX]
+Pseudo-extending on/off
+.
+.RS
+.
+.P
+.B \[rs]*[EXT]
+begins pseudo-extending type.
+.
+.B \[rs]*[EXTX]
+turns the feature off.
+.
+Both are inline escapes, therefore they should not appear as separate
+lines, but rather be embedded in text lines, like this:
+.RS
+.EX
+.FONT B \[rs]*[EXT] I "Not everything is as it seems." B \[rs]*[EXTX]
+.EE
+.RE
+.B \[rs]*[EXT]
+remains in effect until you turn it off with
+.BR \[rs]*[EXTX] .
+.
+.P
+IMPORTANT: You must turn
+.B \%\[rs]*[EXT]
+off before making any changes to the point size of your type, either
+via the
+.B \%.PT_SIZE
+macro or with the
+.B \[rs]s
+inline escape.
+.
+If you wish the new point size to be
+.IR \%pseudo-extended ,
+simply reinvoke
+.B \%\[rs]*[EXT]
+afterwards.
+.
+Equally,
+.B \%\[rs]*[EXT]
+must be turned off before changing the extend percentage with
+.BR \%.EXTEND .
+.
+.P
+Note: If you are using the document processing macros with
+.B \%.PRINTSTYLE
+.BR \%TYPEWRITE ,
+.B mom
+ignores
+.B \%\[rs]*[EXT]
+requests.
+.
+.RE
+.
+.
+.\" ======================================================================
+.\" EXTSUP
+.\" ======================================================================
+.TP
+.FONT B \[rs]*[EXTSUP] R \*[Ellipsis] B \[rs]*[EXTSUPX]
+pseudo extrended superscript
+.
+.
+.\" ======================================================================
+.\" FU
+.\" ======================================================================
+.TP
+.FONT B \[rs]*[FU I " n" B ]
+move characters pairs further apart inline (related to macro
+.BR .KERN )
+.
+.
+.\" ======================================================================
+.\" FWD
+.\" ======================================================================
+.TP
+.FONT B \[rs]*[FWD I " n" B ]
+move forward in a line
+.
+.
+.\" ======================================================================
+.\" LEADER
+.\" ======================================================================
+.TP
+.BI \[rs]*[LEADER]
+insert leaders at the end of a line
+.
+.
+.\" ======================================================================
+.\" RULE
+.\" ======================================================================
+.TP
+.BI \[rs]*[RULE]
+draw a full measure rule
+.
+.
+.\" ======================================================================
+.\" PT_SIZE
+.\" ======================================================================
+.TP
+.FONT B \[rs]*[SIZE I " n" B ]
+change the point size inline (related to macro
+.BR \%.PT_SIZE )
+.
+.
+.\" ======================================================================
+.\" SLANT
+.\" ======================================================================
+.TP
+.B \[rs]*[SLANT]
+.TQ
+.B \[rs]*[SLANTX]
+Pseudo italic on/off
+.
+.RS
+.
+.P
+.B \%\[rs]*[SLANT]
+begins
+.I pseudo-italicizing
+.IR type .
+.
+.B \%\[rs]*[SLANTX]
+turns the feature off.
+.
+Both are
+.I inline
+.IR escapes ,
+therefore they should not appear as separate lines, but rather be
+embedded in text lines, like this:
+.RS
+.EX
+.FONT R "Not " B \[rs]*[SLANT] R everything B \[rs]*[SLANTX] R " is as it seems."
+.EE
+.RE
+.
+.P
+Alternatively, if you wanted the whole line
+.IR pseudo-italicized ,
+you\[aa]d do
+.RS
+.EX
+.FONT B \[rs]*[SLANT] R "Not everything is as it seems." B \[rs]*[SLANTX]
+.EE
+.RE
+.
+.P
+Once
+.B \[rs]*[SLANT]
+is invoked, it remains in effect until turned off.
+.
+.P
+Note: If you’re using the document processing macros with
+.B .PRINTSTYLE
+.BR TYPEWRITE ,
+.B mom
+underlines pseudo-italics by default.
+.
+To change this behaviour, use the special macro
+.BR .SLANT_MEANS_SLANT .
+.
+.RE
+.
+.
+.\" ======================================================================
+.\" ST
+.\" ======================================================================
+.TP
+.FONT B \[rs]*[ST I <number> B ] R \*[Ellipsis] B \[rs]*[ST I <number> B X]
+Mark positions of string tabs
+.
+.RS
+.P
+The
+.I quad
+direction must be
+.B LEFT
+or
+.B \%JUSTIFY
+(see
+.B \%.QUAD
+and
+.BR \%.JUSTIFY )
+or the
+.I no-fill mode
+set to
+.B LEFT
+in order for these inlines to function properly.
+.
+Please see
+.IR \%IMPORTANT ,
+below.
+.
+.P
+String tabs need to be marked off with inline escapes before being set
+up with the
+.B .ST
+macro.
+.
+Any input line may contain string tab markers.
+.
+.IR <number> ,
+above, means the numeric identifier of the tab.
+.
+.P
+The following shows a sample input line with string tab markers. 
+.RS
+.EX
+.FONT B \[rs]*[ST1] R "Now is the time" B \[rs]*[ST1X] R " for all " B \[rs]*[ST2] R "good men" B \[rs]*ST2X] R " to come to the aid of the party."
+.EE
+.RE
+.
+.P
+String
+.I tab 1
+begins at the start of the line and ends after the word
+.IR \%time .
+.
+String
+.I tab 2
+starts at
+.I good
+and ends after
+.IR men .
+.
+.I Inline escapes
+(e.g.
+.I font
+or
+.I point size
+.IR changes ,
+or horizontal movements, including padding) are taken into account
+when
+.B mom
+determines the
+.I position
+and
+.I length
+of
+.I string
+.IR tabs .
+.
+.P
+Up to nineteen string tabs may be marked (not necessarily all on the
+same line, of course), and they must be numbered between 1 and 19.
+.
+.P
+Once string tabs have been marked in input lines, they have to be
+.I set
+with
+.BR .ST ,
+after which they may be called, by number, with
+.BR .TAB .
+.
+.P
+Note: Lines with string tabs marked off in them are normal input
+lines, i.e. they get printed, just like any input line.
+.
+If you want to set up string tabs without the line printing, use the
+.B \%.SILENT
+macro.
+.
+.P
+.I IMPORTANT:
+Owing to the way
+.B groff
+processes input lines and turns them into output lines, it is not
+possible for
+.B mom
+to
+.I guess
+the correct starting position of string tabs marked off in lines that
+are centered or set flush right.
+.
+.P
+Equally, she cannot guess the starting position if a line is fully
+justified and broken with
+.BR \%.SPREAD .
+.
+.P
+In other words, in order to use string tabs,
+.B LEFT
+must be active, or, if
+.B .QUAD LEFT
+or
+.B \%JUSTIFY
+are active, the line on which the
+.I string tabs
+are marked must be broken
+.I manually
+with
+.B .BR
+(but not
+.BR \%.SPREAD ).
+.
+.P
+To circumvent this behaviour, I recommend using the
+.B PAD
+to set up string tabs in centered or flush right lines.
+.
+Say, for example, you want to use a
+.I string tab
+to
+.I underscore
+the text of a centered line with a rule.
+.
+Rather than this,
+.RS
+.EX
+.B .CENTER
+.B \[rs]*[ST1]A line of text\[rs]*[ST1X]\[rs]c
+.B .EL
+.B .ST 1
+.B .TAB 1
+.B .PT_SIZE 24
+.B .ALD 3p
+.B \[rs]*[RULE]
+.B .RLD 3p
+.B .TQ
+.EE
+.RE
+you should do: 
+.RS
+.EX
+.B .QUAD CENTER
+.B .PAD \[rq]#\[rs]*[ST1]A line of text\[rs]*[ST1X]#\[rq]
+.B .EL
+.B .ST 1
+.B .TAB 1
+.B .PT_SIZE 24
+.B .ALD 3p
+.B \[rs]*[RULE] \[rs]\[rq] Note that you can\[aa]t use \[rs]*[UP] or \[rs]*[DOWN] with \[rs]*[RULE]
+.B .RLD 3p
+.B .TQ
+.EE
+.RE
+.
+.RE
+.
+.
+.\" ======================================================================
+.\" SUP
+.\" ======================================================================
+.TP
+.FONT B \[rs]*[SUP] R \*[Ellipsis] B \[rs]*[SUPX]
+superscript
+.
+.
+.\" ======================================================================
+.\" TB+
+.\" ======================================================================
+.TP
+.B \[rs]*[TB+]
+Inline escape for
+.B .TN
+.RI ( "Tab Next" )
+.
+.
+.\" ======================================================================
+.\" UL
+.\" ======================================================================
+.TP
+.FONT B \[rs]*[UL] R \*[Ellipsis] B \[rs]*[ULX]
+invoke underlining inline (fixed width fonts only)
+.
+.
+.\" ======================================================================
+.\" UP
+.\" ======================================================================
+.TP
+.FONT B \[rs]*[UP I " n" B ]
+temporarily move upwards in a line
+.
+.
+.\" --------------------------------------------------------------------
+.SS "Details of Macros in alphabetical Order"
+.\" --------------------------------------------------------------------
+.
+.\" ======================================================================
+.\" AUTOLEAD
+.\" ======================================================================
+.TP
+.BI .AUTOLEAD
+set the linespacing relative to the point size
+.
+.
+.\" ======================================================================
+.\" Bottom Margin
+.\" ======================================================================
+.TP
+.BI .B_MARGIN " <bottom margin>"
+Bottom Margin
+.
+.RS
+.
+.P
+Requires a unit of measure
+.
+.P
+.B .B_MARGIN
+sets a nominal position at the bottom of the page beyond which you
+don’t want your type to go.
+.
+When the bottom margin is reached,
+.B mom
+starts a new page.
+.
+.B .B_MARGIN requires a unit of measure.
+.
+Decimal fractions are allowed.
+.
+To set a nominal bottom margin of 3/4 inch, enter 
+.RS
+.EX
+.B .B_MARGIN .75i
+.EE
+.RE
+.
+.P
+Obviously, if you haven’t spaced the type on your pages so that the
+last lines fall perfectly at the bottom margin, the margin will vary
+from page to page.
+.
+Usually, but not always, the last line of type that fits on a page
+before the bottom margin causes mom to start a new page.
+.
+.P
+Occasionally, owing to a peculiarity in
+.IR groff ,
+an extra line will fall below the nominal bottom margin.
+.
+If you’re using the document processing macros, this is unlikely to
+happen; the document processing macros are very hard-nosed about
+aligning bottom margins.
+.
+.P
+Note: The meaning of
+.B .B_MARGIN
+is slightly different when you’re using the document processing
+macros.
+.
+.RE
+.
+.
+.\" ======================================================================
+.\" Fallback Font
+.\" ======================================================================
+.TP
+.BI \%.FALLBACK_FONT " <fallback font> " "[ ABORT | WARN ]"
+Fallback Font
+.
+.RS
+.
+.P
+In the event that you pass an invalid argument to
+.B \%.FAMILY
+(i.e. a non-existent
+.IR family ),
+.BR mom ,
+by default, uses the
+.IR "fallback font" ,
+.B Courier Medium Roman
+.RB ( CR ),
+in order to continue processing your file.
+.
+.P
+If you\[aa]d prefer another
+.IR "fallback font" ,
+pass
+.B \%.FALLBACK_FONT
+the full
+.I family+font name
+of the
+.I font
+you\[aa]d like.
+.
+For example, if you\[aa]d rather the
+.I fallback font
+were
+.BR "Times Roman Medium Roman" , 
+.RS
+.EX
+.B .FALLBACK_FONT TR
+.EE
+.RE
+would do the trick.
+.
+.P
+.B Mom
+issues a warning whenever a
+.I font style set
+with
+.B .FT
+does not exist, either because you haven\[aa]t registered the style
+or because the
+.I font style
+does not exist in the current
+.I family set
+with
+.BR .FAMILY .
+.
+By default,
+.B \%mom
+then aborts, which allows you to correct the problem.
+.
+.P
+If you\[aa]d prefer that
+.B \%mom
+not abort on non-existent
+.IR fonts ,
+but rather continue processing using a
+.IR "fallback font" ,
+you can pass
+.B \%.FALLBACK_FONT
+the argument
+.BR WARN ,
+either by itself, or in conjunction with your chosen
+.IB "fallback font" .
+.
+.P
+Some examples of invoking
+.BR \%.FALLBACK_FONT :
+.
+.TP
+.B .FALLBACK_FONT WARN
+.B mom
+will issue a warning whenever you try to access a non-existent
+.I font
+but will continue processing your file with the default
+.IR "fallback font" ,
+.BR "Courier Medium Roman" .
+.
+.
+.TP
+.B .FALLBACK_FONT TR WARN
+.B \%mom
+will issue a warning whenever you try to access a non-existent
+.I font
+but will continue processing your file with a
+.I fallback font
+of
+.BR "Times Roman Medium Roman" ;
+additionally,
+.B TR
+will be the
+.I fallback font
+whenever you try to access a
+.I family
+that does not exist.
+.
+.TP
+.B .FALLBACK_FONT TR ABORT 
+.B \%mom
+will abort whenever you try to access a non-existent
+.BR font ,
+and will use the
+.I fallback font
+.B TR
+whenever you try to access a
+.I family
+that does not exist.
+.
+If, for some reason, you want to revert to
+.BR ABORT ,
+just enter
+.B \%".FALLBACK_FONT ABORT"
+and
+.B mom
+will once again abort on
+.IR "font errors" .
+.
+.RE
+.
+.
+.\" ======================================================================
+.\" FAM
+.\" ======================================================================
+.TP
+.BI .FAM " <family>"
+Type Family, alias of \fB.FAMILY\fR
+.
+.
+.\" ======================================================================
+.\" FAMILY
+.\" ======================================================================
+.TP
+.BI .FAMILY " <family>"
+Type Family, alias \fB.FAM\fR
+.
+.RS
+.
+.P
+.B .FAMILY
+takes one argument: the name of the
+.I family
+you want.
+.
+.I Groff
+comes with a small set of basic families, each identified by a 1-,
+2-or 3-letter mnemonic.
+.
+The standard families are:
+.RS
+.EX
+.B A   = Avant Garde
+.B BM  = Bookman
+.B H   = Helvetica
+.B HN  = Helvetica Narrow
+.B N   = New Century Schoolbook
+.B P   = Palatino
+.B T   = Times Roman
+.B ZCM = Zapf Chancery
+.EE
+.RE
+.
+.P
+The argument you pass to
+.B .FAMILY
+is the identifier at left, above.
+.
+For example, if you want
+.BR Helvetica ,
+enter 
+.RS
+.EX
+.B .FAMILY H
+.EE
+.RE
+.
+.P
+Note: The font macro
+.RB ( .FT )
+lets you specify both the type
+.I family
+and the desired font with a single macro.
+.
+While this saves a few
+keystrokes, I recommend using
+.B .FAMILY for
+.IR family ,
+and
+.B .FT for
+.IR font ,
+except where doing so is genuinely inconvenient.
+.
+.BR ZCM ,
+for example,
+only exists in one style:
+.B Italic
+.RB ( I ).
+.
+.P
+Therefore,
+.RS
+.EX
+.B .FT ZCMI
+.EE
+.RE
+makes more sense than setting the
+.I family
+to
+.BR ZCM ,
+then setting the
+.I font
+to
+.IR I .
+.
+.P
+Additional note: If you are running a version of groff lower than
+1.19.2, you must follow all
+.B .FAMILY
+requests with a
+.B FT
+request, otherwise
+.B mom
+will set all type up to the next
+.B .FT
+request in the fallback font.
+.
+.P
+If you are running a version of groff greater than or equal to 1.19.2,
+when you invoke the
+.B .FAMILY
+macro,
+.B mom
+.I remembers
+the font style
+.BR ( Roman ,
+.BR Italic ,
+etc) currently in use (if the font style exists in the new
+.IR family ) and will continue to use the same font style in the new
+.IR family .
+For example:
+.RS
+.EX
+.BI ".FAMILY BM " "\[rs]\[rq] Bookman family"
+.BI ".FT I " "\[rs]\[rq] Medium Italic"
+.I <some text> \[rs]\[rq] Bookman Medium Italic
+.BI ".FAMILY H " "\[rs]\[rq] Helvetica family"
+.I <more text> \[rs]\[rq] Helvetica Medium Italic
+.EE
+.RE
+.
+.P
+However, if the font style does not exist in the new family,
+.B mom
+will set all subsequent type in the fallback font (by default,
+.B Courier Medium
+.BR Roman )
+until she encounters a
+.B .FT
+request that\[aa]s valid for the
+.IR family .
+.
+.P
+For example, assuming you don\[aa]t have the font
+.B Medium Condensed Roman
+.RB  ( mom
+extension
+.IR CD )
+in the
+.I Helvetica
+.IR family :
+.RS
+.EX
+.BI ".FAMILY UN " "\[rs]\[rq]Univers family"
+.BI ".FT CD " "\[rs]\[rq] Medium Condensed"
+.I <some text> \[rs]\[rq] Univers Medium Condensed
+.BI ".FAMILY H " "\[rs]\[rq] Helvetica family"
+.I <more text> \[rs]\[rq] Courier Medium Roman!
+.EE
+.RE
+.
+.P
+In the above example, you must follow
+.B .FAMILY H
+with a
+.B .FT
+request that’s valid for
+.BR Helvetica .
+.
+.P
+Please see the Appendices,
+.I Adding fonts to
+.IR groff ,
+for information on adding fonts and families to groff, as well as to
+see a list of the extensions
+.B mom
+provides to
+.IR groff \[aa]s
+basic
+.BR R ,
+.BR I ,
+.BR B ,
+.B BI
+styles.
+.
+.P
+Suggestion: When adding
+.I families to
+.IR groff ,
+I recommend following the established standard for the naming families
+and fonts.
+.
+For example, if you add the
+.B Garamond
+family, name the font files
+.RS
+.EX
+.B GARAMONDR
+.B GARAMONDI
+.B GARAMONDB
+.B GARAMONDBI
+.EE
+.RE
+.
+.B GARAMOND then becomes a valid
+.I family name
+you can pass to
+.BR .FAMILY .
+.
+(You could, of course, shorten
+.B GARAMOND
+to just
+.BR G ,
+or
+.BR GD .)
+.BR R ,
+.BR I ,
+.BR B ,
+and
+.B BI
+after
+.B GARAMOND
+are the
+.IR roman ,
+.IR italic ,
+.I bold
+and
+.I bold-italic
+fonts respectively.
+.
+.RE
+.
+.
+.\" ======================================================================
+.\" FONT
+.\" ======================================================================
+.TP
+.BI .FONT R " | " B " | " BI " | " <any other valid font style>"
+Alias to
+.B .FT
+.
+.
+.\" ======================================================================
+.\" FT
+.\" ======================================================================
+.TP
+.BI .FT R " | " B " | " BI " | " <any other valid font style>"
+Set font
+.
+.RS
+.
+.P
+By default,
+.I groff
+permits
+.B .FT
+to take one of four possible arguments specifying the desired font: 
+.RS
+.EX
+.B R = (Medium) Roman
+.B I = (Medium) Italic
+.B B = Bold (Roman)
+.B BI = Bold Italic
+.EE
+.RE
+.
+.P
+For example, if your
+.I family
+is
+.BR Helvetica ,
+entering 
+.RS
+.EX
+.B .FT B
+.EE
+.RE
+will give you the
+.I Helvetica bold
+.IR font .
+.
+If your
+.I family
+were
+.BR \%Palatino ,
+you\[aa]d get the
+.I \%Palatino bold
+.IR font .
+.
+.P
+.B Mom
+considerably extends the range of arguments you can pass to
+.BR .FT ,
+making it more convenient to add and access fonts of differing weights
+and shapes within the same family.
+.
+.P
+Have a look here for a list of the weight/style arguments
+.B mom
+allows.
+.
+Be aware, though, that you must have the fonts, correctly installed
+and named, in order to use the arguments.
+.
+(See
+.I Adding fonts to groff
+for instructions and information.)
+.
+Please also read the
+.I ADDITIONAL NOTE
+found in the description of the
+.B \%.FAMILY
+macro.
+.
+.P
+How
+.B mom
+reacts to an invalid argument to
+.B .FT
+depends on which version of groff you\[aa]re using.
+.
+If your
+.I groff version
+is greater than or equal to 1.19.2,
+.B mom
+will issue a warning and, depending on how you’ve set up the fallback
+font, either continue processing using the fallback font, or abort
+(allowing you to correct the problem). If your
+.I groff version
+is less than 1.19.2,
+.B mom
+will silently continue processing, using either the fallback font or
+the font that was in effect prior to the invalid
+.B .FT
+call.
+.
+.P
+.B .FT
+will also accept, as an argument, a full
+.I family
+and
+.I font
+.IR name .
+.
+.P
+For example, 
+.RS
+.EX
+.B .FT HB
+.EE
+.RE
+will set subsequent type in
+.I Helvetica
+.IR Bold .
+.
+.P
+However, I strongly recommend keeping
+.I family
+and
+.I font
+separate except where doing so is genuinely inconvenient.
+.
+.P
+For inline control of
+.IR fonts ,
+see
+.I Inline
+.IR Escapes ,
+font control.
+.
+.RE
+.
+.
+.\" ======================================================================
+.\" Hanging Indent
+.\" ======================================================================
+.TP
+.BI "\%.HI [" " <measure> " ]
+Hanging indent \[em] the optional argument requires a unit of measure.
+.
+.RS
+.
+.P
+A hanging indent looks like this: 
+.RS
+.EX
+\fB  The thousand injuries of Fortunato I had borne as best I
+    could, but when he ventured upon insult, I vowed
+    revenge.  You who so well know the nature of my soul
+    will not suppose, however, that I gave utterance to a
+    threat, at length I would be avenged...
+.EE
+.RE
+.
+The first line of text
+.I hangs
+outside the
+.IR "left margin" .
+.
+.P
+In order to use
+.IR "hanging indents" ,
+you must first have a
+.I left indent
+active (set with either
+.B .IL
+or
+.BR .IB ).
+.
+.B Mom
+will not hang text outside the
+.I left margin set
+with
+.B \%.L_MARGIN
+or outside the
+.I left margin
+of a
+.IR \%tab .
+.
+.P
+The first time you invoke
+.BR .HI ,
+you must give it a
+.BR measure .
+.
+If you want the first line of a paragraph to
+.IR "hang by" ,
+say,
+.IR "1 pica" ,
+do 
+.RS
+.EX
+.B .IL 1P
+.B .HI 1P
+.EE
+.RE
+.
+Subsequent invocations of
+.B \%.HI
+do not require you to supply a
+.IR measure ;
+.B mom
+keeps track of the last measure you gave it.
+.
+.P
+Generally speaking, you should invoke
+.B .HI
+immediately prior to the line you want hung (i.e. without any
+intervening control lines).
+.
+And because
+.I hanging indents
+affect only one line, there\[aa]s no need to turn them off.
+.
+.P
+.I IMPORTANT:
+Unlike
+.BR IL ,
+.B IR
+and
+.BR IB ,
+measures given to
+.B .HI
+are NOT additive.
+.
+Each time you pass a measure to
+.B .HI ,
+the measure is treated literally.
+.
+.B
+.I Recipe:
+A numbered list using
+.I hanging indents
+.
+.P
+.I Note:
+.B mom
+has macros for setting lists.
+.
+This recipe exists to demonstrate the use of
+.I hanging indents
+only.
+.RS
+.EX
+.B .PAGE 8.5i 11i 1i 1i 1i 1i
+.B .FAMILY  T
+.B .FT      R
+.B .PT_SIZE 12
+.B .LS      14
+.B .JUSTIFY
+.B .KERN
+.B .SS 0
+.B .IL \[rs]w'\[rs]0\[rs]0.'
+.B .HI \[rs]w'\[rs]0\[rs]0.'
+\fB1.\[rs]0The most important point to be considered is whether the
+answer to the meaning of Life, the Universe, and Everything
+really is 42.  We have no-one’s word on the subject except
+Mr. Adams’.
+.B .HI
+2.\[rs]0If the answer to the meaning of Life, the Universe,
+and Everything is indeed 42, what impact does this have on
+the politics of representation?  42 is, after all not a
+prime number.  Are we to infer that prime numbers don’t
+deserve equal rights and equal access in the universe?
+.B .HI
+3.\[rs]0If 42 is deemed non-exclusionary, how do we present it
+as the answer and, at the same time, forestall debate on its
+exclusionary implications?
+.EE
+.RE
+.
+.P
+First, we invoke a left indent with a measure equal to the width of 2
+figures spaces plus a period (using the \[rs]w inline escape).
+.
+At this point, the left indent is active; text afterwards would
+normally be indented.
+.
+However, we invoke a hanging indent of exactly the same width, which
+hangs the first line (and first line only!) to the left of the indent
+by the same distance (in this case, that means “out to the left
+margin”).
+.
+Because we begin the first line with a number, a period, and a figure
+space, the actual text
+.RI ( "The most important point..." )
+starts at exactly the same spot as the indented lines that follow.
+.
+.P
+Notice that subsequent invocations of
+.B .HI
+don’t require a
+.I measure
+to be given.
+.
+.P
+Paste the example above into a file and preview it with 
+.RS
+.EX
+.B pdfmom filename.mom | ps2pdf - filename.pdf
+.EE
+.RE
+to see hanging indents in action.
+.
+.RE
+.
+.
+.\" ======================================================================
+.\" IB - INDENT BOTH
+.\" ======================================================================
+.TP
+.BI "\%.IB [" " <left measure> <right measure> " ]
+Indent both \[em] the optional argument requires a unit of measure
+.
+.RS
+.
+.P
+.B .IB
+allows you to set or invoke a left and a right indent at the same time.
+.
+.P
+At its first invocation, you must supply a measure for both indents;
+at subsequent invocations when you wish to supply a measure, both must
+be given again.
+.
+As with
+.B .IL
+and
+.BR .IR ,
+the measures are added to the values previously passed to the
+macro.
+.
+Hence, if you wish to change just one of the values, you must give an
+argument of zero to the other.
+.
+.P
+.I A word of advice:
+If you need to manipulate left and right indents separately, use a
+combination of
+.B .IL
+and
+.B .IR
+instead of
+.BR .IB .
+.
+You’ll save yourself a lot of grief.
+.
+.P
+A
+.I minus sign
+may be prepended to the arguments to subtract from their current
+values.
+.
+The \[rs]w inline escape may be used to specify text-dependent
+measures, in which case no unit of measure is required.
+.
+For example,
+.RS
+.EX
+.B .IB \[rs]w\[aa]margarine\[aa] \[rs]w\[aa]jello\[aa]
+.EE
+.RE
+left indents text by the width of the word
+.I margarine
+and right indents by the width of
+.IR jello .
+.
+.P
+Like
+.B .IL
+and
+.BR .IR ,
+.B .IB
+with no argument indents by its last active values.
+.
+See the brief explanation of how mom handles indents for more details.
+.
+.P
+.I Note:
+Calling a
+.I tab
+(with
+.BR ".TAB <n>" )
+automatically cancels any active indents.
+.
+.P
+.I Additional note:
+Invoking
+.B .IB
+automatically turns off
+.B .IL
+and
+.BR .IR .
+.
+.RE
+.
+.
+.\" ======================================================================
+.\" IL - INDENT LEFT
+.\" ======================================================================
+.TP
+.BI "\%.IL [" " <measure> " ]
+Indent left \[em] the optional argument requires a unit of measure
+.
+.RS
+.
+.P
+.B .IL
+indents text from the left margin of the page, or if you’re in a
+.IR tab ,
+from the left edge of the
+.IR tab
+.
+Once
+.I IL
+is on, the
+.I left indent
+is applied uniformly to every subsequent line of text, even if you
+change the line length.
+.
+.P
+The first time you invoke
+.BR .IL ,
+you must give it a measure.
+.
+Subsequent invocations with a measure add to the previous measure.
+.
+A minus sign may be prepended to the argument to subtract from the
+current measure.
+.
+The
+.B \[rs]w
+inline escape may be used to specify a text-dependent measure, in
+which case no unit of measure is required.
+.
+For example,
+.RS
+.EX
+.B .IL \[rs]w'margarine'
+.EE
+.RE
+indents text by the width of the word
+.IR margarine .
+.
+.P
+With no argument,
+.B .IL
+indents by its last active value.
+.
+See the brief explanation of how
+.B mom
+handles indents for more details.
+.
+.P
+.I Note:
+Calling a
+.I tab
+(with
+.BR ".TAB <n>" )
+automatically cancels any active indents.
+.
+.P
+.I Additional note:
+Invoking
+.B .IL
+automatically turns off
+.BR IB .
+.
+.RE
+.
+.
+.\" ======================================================================
+.\" IQ - quit any/all indents
+.\" ======================================================================
+.TP
+.BI "\%.IQ [" " <measure> " ]
+IQ \[em] quit any/all indents
+.
+.RS
+.
+.P
+.I IMPORTANT NOTE:
+The original macro for quitting all indents was
+.BR .IX .
+.
+This usage has been deprecated in favour of
+.BR IQ .
+.
+.B .IX
+will continue to behave as before, but
+.B mom
+will issue a warning to
+.I stderr
+indicating that you should update your documents.
+.
+.P
+As a consequence of this change,
+.BR .ILX ,
+.B .IRX
+and
+.B .IBX
+may now also be invoked as
+.BR .ILQ ,
+.B .IRQ
+and
+.BR .IBQ .
+.
+Both forms are acceptable.
+.
+.P
+Without an argument, the macros to quit indents merely restore your
+original margins and line length.
+.
+The measures stored in the indent macros themselves are saved so you
+can call them again without having to supply a measure.
+.
+.P
+If you pass these macros the optional argument
+.BR CLEAR ,
+they not only restore your original left margin and line length, but
+also clear any values associated with a particular indent style.
+.
+The next time you need an indent of the same style, you have to supply
+a measure again.
+.
+.P
+.BR ".IQ CLEAR" ,
+as you\[aa]d suspect, quits and clears the values for all indent
+styles at once.
+.
+.RE
+.
+.
+.\" ======================================================================
+.\" IR - INDENT RIGHT
+.\" ======================================================================
+.TP
+.BI "\%.IR [" " <measure> " ]
+Indent right \[em] the optional argument requires a unit of measure
+.
+.RS
+.
+.P
+.B .IR
+indents text from the
+.I right margin
+of the page, or if you’re in a
+.IR tab ,
+from the end of the
+.IR tab .
+.
+.P
+The first time you invoke
+.BR .IR ,
+you must give it a measure.
+.
+Subsequent invocations with a measure add to the previous indent
+measure.
+.
+A
+.I minus sign
+may be prepended to the argument to subtract from the current indent
+measure.
+.
+The \[rs]w inline escape may be used to specify a text-dependent
+measure, in which case no
+.I unit of measure
+is required.
+.
+For example,
+.RS
+.EX
+.B .IR \[rs]w'jello'
+.EE
+.RE
+indents text by the width of the word
+.IR jello .
+.
+.P
+With no argument,
+.B .IR
+indents by its last active value.
+.
+See the brief explanation of how
+.B mom
+handles indents for more details.
+.
+.P
+.I Note:
+Calling a
+.I tab
+(with
+.BR "\%.TAB <n>" )
+automatically cancels any active indents.
+.
+.P
+.I Additional note:
+Invoking
+.B .IR
+automatically turns off
+.BR IB .
+.
+.RE
+.
+.
+.\" ======================================================================
+.\" Left Margin
+.\" ======================================================================
+.TP
+.BI .L_MARGIN " <left margin>"
+Left Margin
+.
+.RS
+.
+.P
+L_MARGIN establishes the distance from the left edge of the printer
+sheet at which you want your type to start.
+.
+It may be used any time, and remains in effect until you enter a new value.
+.
+.P
+Left indents and tabs are calculated from the value you pass to
+.BR .L_MARGIN ,
+hence it’s always a good idea to invoke it before starting any serious
+typesetting.
+.
+A unit of measure is required.
+.
+Decimal fractions are allowed.
+.
+Therefore, to set the left margin at 3 picas (1/2 inch), you’d enter either 
+.RS
+.EX
+.B .L_MARGIN 3P
+.EE
+.RE
+or
+.RS
+.EX
+.B .L_MARGIN .5i
+.EE
+.RE
+.
+.P
+If you use the macros
+.BR .PAGE ,
+.B .PAGEWIDTH
+or
+.B .PAPER
+without invoking
+.B .L_MARGIN
+(either before or afterwards),
+.B mom
+automatically sets
+.B .L_MARGIN
+to
+.IR "1 inch" .
+.
+.P
+Note:
+.B .L_MARGIN
+behaves in a special way when you’re using the document processing
+macros.
+.
+.RE
+.
+.
+.\" ======================================================================
+.\" MCO - BEGIN MULTI-COLUMN SETTING
+.\" ======================================================================
+.TP
+.B .MCO
+Begin multi-column setting.
+.
+.RS
+.P
+.B .MCO
+.RI ( "Multi-Column On" )
+is the
+.I macro
+you use to begin
+.IR "multi-column setting" .
+.
+It marks the current baseline as the top of your columns, for use
+later with
+.BR .MCR .
+.
+See the introduction to columns for an explanation of
+.I multi-columns
+and some sample input.
+.
+.P
+.I Note:
+Do not confuse
+.B .MCO
+with the
+.B .COLUMNS
+macro in the document processing macros.
+.
+.RE
+.
+.
+.\" ======================================================================
+.\" MCR - RETURN TO TOP OF COLUMN
+.\" ======================================================================
+.TP
+.B \%.MCR
+Once you\[aa]ve turned
+.I multi-columns
+on (with
+.BR \%.MCO ),
+.BR .MCR ,
+at any time, returns you to the
+.IR "top of your columns".
+.
+.
+.\" ======================================================================
+.\" MCX - EXIT MULTI-COLUMNS
+.\" ======================================================================
+.TP
+.BI "\%.MCX [ " "<distance to advance below longest column>" " ]"
+Optional argument requires a unit of measure.
+.
+.RS
+.
+.P
+.B .MCX
+takes you out of any
+.I tab
+you were in (by silently invoking
+.BR .TQ )
+and advances to the bottom of the longest column.
+.
+.P
+Without an argument,
+.B .MCX
+advances
+.I 1 linespace
+below the longest column.
+.
+.P
+Linespace, in this instance, is the leading in effect at the moment
+.B .MCX
+is invoked.
+.
+.P
+If you pass the
+.I <distance>
+argument to
+.BR .MCX ,
+it advances
+.I 1 linespace
+below the longest column (see above)
+.I PLUS
+the distance specified by the argument.
+.
+The argument requires a unit of measure; therefore, to advance an
+extra 6 points below where
+.B \%.MCX
+would normally place you, you’d enter
+.RS
+.EX
+.B .MCX 6p
+.EE
+.RE
+.
+.P
+.I Note:
+If you wish to advance a precise distance below the baseline of the
+longest column, use
+.B .MCX
+with an argument of
+.B 0
+(zero; no
+.I unit of measure
+required) in conjunction with the
+.B \%.ALD
+macro, like this:
+.RS
+.EX
+.B .MCX 0
+.B .ALD 24p
+.EE
+.RE
+.
+The above advances to precisely
+.I 24 points
+below the baseline of the longest column.
+.
+.RE
+.
+.
+.\" ======================================================================
+.\" Start a new Page
+.\" ======================================================================
+.TP
+.B .NEWPAGE
+.
+.RS
+.
+.P
+Whenever you want to start a new page, use
+.BR .NEWPAGE ,
+by itself with no argument.
+.
+.B Mom
+will finish up processing the current page and move you to the top of
+a new one (subject to the top margin set with
+.BR .T_MARGIN ).
+.
+.RE
+.
+.
+.\" ======================================================================
+.\" Page
+.\" ======================================================================
+.TP
+.B .PAGE " <width> [ <length> [ <lm> [ <rm> [ <tm> [ <bm> ] ] ] ] ]"
+.
+.RS
+.
+.P
+All arguments require a unit of measure
+.
+.P
+.I IMPORTANT:
+If you\[aa]re using the document processing macros,
+.B .PAGE
+must come after
+.BR .START .
+.
+Otherwise, it should go at the top of a document, prior to any text.
+.
+And remember, when you\[aa]re using the document processing macros, top
+margin and bottom margin mean something slightly different than when
+you\[aa]re using just the typesetting macros (see Top and bottom margins
+in document processing).
+.
+.P
+.B .PAGE
+lets you establish paper dimensions and page margins with a single
+macro.
+.
+The only required argument is page width.
+.
+The rest are
+optional, but they must appear in order and you can’t skip over
+any.
+.
+.IR <lm> ,
+.IR <rm> ,
+.I <tm>
+and
+.I <bm>
+refer to the left, right, top and bottom margins respectively.
+.
+.P
+Assuming your page dimensions are 11 inches by 17 inches, and that’s
+all you want to set, enter
+.RS
+.EX
+.B .PAGE 11i 17i
+.EE
+.RE
+.
+If you want to set the left margin as well, say, at 1 inch,
+.B PAGE
+would look like this: 
+.RS
+.EX
+.B .PAGE 11i 17i 1i
+.EE
+.RE
+.
+.P
+Now suppose you also want to set the top margin, say, at 1-1/2 inches.
+.
+.I <tm>
+comes after
+.I <rm>
+in the optional arguments, but you can’t skip over any arguments,
+therefore to set the top margin, you must also give a right margin.
+.
+The
+.B .PAGE
+macro would look like this: 
+.RS
+.EX
+\f[B].PAGE 11i 17i 1i 1i 1.5i
+                 |   |
+required right---+   +---top margin
+        margin\f[R]
+.EE
+.RE
+.
+.P
+Clearly,
+.B .PAGE
+is best used when you want a convenient way to tell
+.B mom
+just the dimensions of your printer sheet (width and length), or when
+you want to tell her everything about the page (dimensions and all the
+margins), for example
+.RS
+.EX
+.B .PAGE 8.5i 11i 45p 45p 45p 45p
+.EE
+.RE
+.
+This sets up an 8-1/2 by 11 inch page with margins of 45 points
+(5/8-inch) all around.
+.
+.P
+Additionally, if you invoke
+.B .PAGE
+with a top margin argument, any macros you invoke after
+.B .PAGE
+will almost certainly move the baseline of the first line of text down
+by one linespace.
+.
+To compensate, do 
+.RS
+.EX
+.B .RLD 1v
+.EE
+.RE
+immediately before entering any text, or, if it’s feasible, make
+.B .PAGE
+the last macro you invoke prior to entering text.
+.
+.P
+Please read the
+.I Important note
+on page dimensions and papersize for information on ensuring groff
+respects your
+.B .PAGE
+dimensions and margins.
+.
+.RE
+.
+.
+.\" ======================================================================
+.\" Page Length
+.\" ======================================================================
+.TP
+.BI .PAGELENGTH " <length_of_printer_sheet>"
+tells
+.B mom
+how long your printer sheet is.
+.
+It works just like
+.BR .PAGEWIDTH .
+.
+.RS
+.
+.P
+Therefore, to tell
+.B mom
+your printer sheet is 11 inches long, you enter 
+.RS
+.EX
+.B .PAGELENGTH 11i
+.EE
+.RE
+.
+Please read the important note on page dimensions and papersize for
+information on ensuring groff respects your
+.IR PAGELENGTH .
+.
+.RE
+.
+.
+.\" ======================================================================
+.\" Page Width
+.\" ======================================================================
+.TP
+.BI .PAGEWIDTH " <width_of_printer_sheet>"
+.
+.RS
+.
+.P
+The argument to
+.B .PAGEWIDTH
+is the width of your printer sheet.
+.
+.P
+.B .PAGEWIDTH
+requires a unit of measure.
+.
+Decimal fractions are allowed.
+.
+Hence, to tell
+.B mom
+that the width of your printer sheet is 8-1/2 inches, you enter
+.RS
+.EX
+.PAGEWIDTH 8.5i
+.EE
+.RE
+.
+.P
+Please read the Important note on page dimensions and papersize for
+information on ensuring groff respects your
+.IR PAGEWIDTH .
+.
+.RE
+.
+.
+.\" ======================================================================
+.\" Paper
+.\" ======================================================================
+.TP
+.BI .PAPER " <paper_type>"
+provides a convenient way to set the page dimensions for some common
+printer sheet sizes.
+.
+The argument
+.I <paper type>
+can be one of:
+.BR LETTER ,
+.BR LEGAL ,
+.BR STATEMENT ,
+.BR TABLOID ,
+.BR LEDGER ,
+.BR FOLIO ,
+.BR QUARTO ,
+.BR EXECUTIVE ,
+.BR 10x14 ,
+.BR A3 ,
+.BR A4 ,
+.BR A5 ,
+.BR B4 ,
+.BR B5 .
+.
+.
+.TP
+.B .PRINTSTYLE
+.
+.
+.\" ======================================================================
+.\" PT_SIZE - POINT SIZE OF TYPE
+.\" ======================================================================
+.TP
+.BR .PT_SIZE " <size of type in points>"
+Point size of type, does not require a
+.IR "unit of measure" .
+.
+.RS
+.
+.P
+.B \%.PT_SIZE
+.RI ( "Point Size" )
+takes one argument: the
+.I size of type
+in
+.IR points .
+.
+Unlike most other macros that establish the
+.I size
+or
+.I measure
+of something,
+.B \%.PT_SIZE
+does not require that you supply a
+.I unit of measure
+since it\[aa]s a near universal convention that
+.I type size
+is measured in
+.IR points .
+.
+Therefore, to change the
+.I type size
+to, say,
+.IR "11 points" ,
+enter
+.RS
+.EX
+.B .PT_SIZE 11
+.EE
+.RE
+.
+.I Point sizes
+may be
+.I fractional
+(eg
+.I 10.25
+or
+.IR 12.5 ).
+.
+.P
+You can prepend a
+.I plus
+or a
+.I minus sign
+to the argument to
+.BR \%.PT_SIZE ,
+in which case the
+.I point size
+will be changed by
+.I +
+or
+.I -
+the original value.
+.
+For example, if the
+.I point size
+is
+.I 12 ,
+and you want
+.I 14 ,
+you can do
+.RS
+.EX
+.B .PT_SIZE +2
+.EE
+.RE
+then later reset it to
+.I 12
+with
+.RS
+.EX
+.B .PT_SIZE -2
+.EE
+.RE
+.
+The
+.I size of type
+can also be changed inline.
+.
+.P
+.I Note:
+It is unfortunate that the
+.B \%pic
+preprocessor has already taken the name, PS, and thus
+.IR mom \[aa]s
+macro for setting
+.I point sizes
+can’t use it.
+.
+However, if you aren\[aa]t using
+.BR pic ,
+you might want to alias
+.B \%.PT_SIZE
+as
+.BR .PS ,
+since there\[aa]d be no conflict.
+.
+For example
+.RS
+.EX
+.B .ALIAS PS PT_SIZE
+.EE
+.RE
+would allow you to set
+.I point sizes
+with
+.BR .PS .
+.
+.RE
+.
+.
+.\" ======================================================================
+.\" Right Margin
+.\" ======================================================================
+.TP
+.BR .R_MARGIN " <right margin>"
+Right Margin
+.
+.RS
+.
+.P
+Requires a unit of measure.
+.
+.P
+IMPORTANT:
+.BR .R_MARGIN ,
+if used, must come after
+.BR .PAPER ,
+.BR .PAGEWIDTH ,
+.BR .L_MARGIN ,
+and/or
+.B .PAGE
+(if a right margin isn’t given to PAGE).
+.
+The reason is that
+.B .R_MARGIN
+calculates line length from the overall page dimensions and the left margin.
+.
+.P
+Obviously, it can’t make the calculation if it doesn’t know the page
+width and the left margin.
+.
+.P
+.B .R_MARGIN
+establishes the amount of space you want between the end of typeset
+lines and the right hand edge of the printer sheet.
+.
+In other words, it sets the line length.
+.B .R_MARGIN
+requires a unit of measure.
+.
+Decimal fractions are allowed.
+.
+.P
+The line length macro (LL) can be used in place of
+.BR .R_MARGIN .
+.
+In either case, the last one invoked sets the line length.
+.
+The choice of which to use is up to you.
+.
+In some instances, you may find it easier to think of a section of
+type as having a right margin.
+.
+In others, giving a line length may make more sense.
+.
+.P
+For example, if you’re setting a page of type you know should have
+6-pica margins left and right, it makes sense to enter a left and
+right margin, like this:
+.RS
+.EX
+.B .L_MARGIN 6P
+.B .R_MARGIN 6P
+.EE
+.RE
+.
+.P
+That way, you don’t have to worry about calculating the line
+length.
+.
+On the other hand, if you know the line length for a patch of type
+should be 17 picas and 3 points, entering the line length with LL is
+much easier than calculating the right margin, eg
+.RS
+.EX
+.B .LL 17P+3p
+.EE
+.RE
+.
+.P
+If you use the macros
+.BR .PAGE ,
+.B .PAGEWIDTH
+or
+.B PAPER
+without invoking
+.B .R_MARGIN
+afterwards,
+.B mom
+automatically sets
+.B .R_MARGIN
+to
+.IR "1 inch" .
+.
+If you set a line length after these macros (with
+.BR .LL ),
+the line length calculated by
+.B .R_MARGIN
+is, of course, overridden.
+.
+.P
+Note:
+.B .R_MARGIN
+behaves in a special way when you’re using the document processing
+macros.
+.
+.RE
+.
+.
+.\" ======================================================================
+.\" ST - Set String Tabs
+.\" ======================================================================
+.TP
+.FONT B .ST I " <tab number> " B "L | R | C | J [ QUAD ]"
+.
+.RS
+.P
+After
+.I string tabs
+have been marked off on an input line (see
+.BR \[rs]*[ST]\*[Ellipsis]\[rs]*[STX] ),
+you need to
+.I set
+them by giving them a direction and, optionally, the
+.B \%QUAD
+argument.
+.
+.P
+In this respect,
+.B .ST
+is like
+.B \%.TAB_SET
+except that you don\[aa]t have to give
+.B .ST
+an indent or a line length (that\[aa]s already taken care of, inline,
+by
+.BR \[rs]*[ST]...\[rs]*[STX] ).
+.
+.P
+If you want string
+.I tab 1
+to be
+.BR \%left ,
+enter
+.RS
+.EX
+.B .ST 1 L
+.EE
+.RE
+.
+If you want it to be
+.I \%left
+and
+.IR \%filled ,
+enter 
+.RS
+.EX
+.B .ST 1 L \%QUAD
+.EE
+.RE
+.
+If you want it to be justified, enter 
+.RS
+.EX
+.B .ST 1 J
+.EE
+.RE
+.
+.RE
+.
+.
+.\" ======================================================================
+.\" TAB - Call Tabs
+.\" ======================================================================
+.TP
+.BI \%.TAB " <tab number>"
+After
+.I tabs
+have been defined (either with
+.B \%.TAB_SET
+or
+.BR .ST ),
+.B \%TAB
+moves to whatever
+.I tab number
+you pass it as an argument.
+.
+.RS
+.
+.P
+For example,
+.RS
+.EX
+.B \%.TAB 3
+.EE
+.RE
+moves you to
+.I "\%tab 3" .
+.
+.P
+Note:
+.B \%.TAB
+breaks the line preceding it and advances 1 linespace.
+.
+Hence, 
+.RS
+.EX
+.B .TAB 1
+.B  A line of text in tab 1.
+.B .TAB 2
+.B  A line of text in tab 2.
+.EE
+.RE
+produces, on output 
+.RS
+.EX
+.B "A line of text in tab 1."
+.B "                             A line of text in tab 2."
+.EE
+.RE
+.
+.P
+If you want the tabs to line up, use
+.B .TN
+.RI ( "Tab Next" )
+or, more conveniently, the inline escape \[rs]*[TB+]: 
+.RS
+.EX
+\fB.TAB 1
+A line of text in tab 1.\[rs]*[TB+]
+A line of text in tab 2.
+.EE
+.RE
+which produces 
+.RS
+.EX
+.B "A line of text in tab 1.   A line of text in tab 2."
+.EE
+.RE
+.
+.P
+If the text in your tabs runs to several lines, and you want the first
+lines of each tab to align, you must use the multi-column macros.
+.
+.P
+.I Additional note:
+Any indents in effect prior to calling a tab are automatically turned
+off by
+.BR TAB .
+.
+If you were happily zipping down the page with a left indent of
+.I 2 picas
+turned on, and you call a
+.I tab
+whose indent from the left margin is
+.IR "6 picas" ,
+your new distance from the
+.I left margin
+will be
+.IR "6 picas" ,
+not
+I 6 picas plus the 2 pica
+indent.
+.
+.P
+.I \%Tabs
+are not by nature columnar, which is to say that if the text inside a
+.I tab
+runs to several lines, calling another
+.I tab
+does not automatically move to the baseline of the first line in the
+.IR "previous tab" .
+.
+To demonstrate:
+.RS
+.EX
+\f[BTAB 1
+Carrots
+Potatoes
+Broccoli
+.TAB 2
+$1.99/5 lbs
+$0.25/lb
+$0.99/bunch
+.EE
+.RE
+produces, on output 
+.RS
+.EX
+\fBCarrots
+Potatoes
+Broccoli
+            $1.99/5 lbs
+            $0.25/lb
+            $0.99/bunch
+.EE
+.RE
+.
+.RE
+.
+.\" ======================================================================
+.\" TB - Call Tabs Alias
+.\" ======================================================================
+.TP
+.BI TB " <tab number>"
+Alias to
+.B .TAB
+.
+.
+.\" ======================================================================
+.\" TI - TEMPORARY (LEFT) INDENT
+.\" ======================================================================
+.TP
+.BI "\%.TI [" " <measure> " ]
+Temporary left indent \[em] the optional argument requires a
+.I unit of measure
+.
+.RS
+.
+.P
+A temporary indent is one that applies only to the first line of text
+that comes after it.
+.
+Its chief use is indenting the first line of paragraphs.
+.RB ( Mom\[aa]s
+.B .PP
+macro, for example, uses a
+.IR "temporary indent" .)
+.
+.P
+The first time you invoke
+.BR .TI ,
+you must give it a measure.
+.
+If you want to
+.I indent
+the first line of a paragraph by, say, 2 ems, do 
+.RS
+.EX
+.B .TI 2m
+.EE
+.RE
+.
+.P
+Subsequent invocations of
+.B .TI
+do not require you to supply a measure;
+.B mom
+keeps track of the last measure you gave it.
+.
+.P
+Because
+.I temporary indents
+are temporary, there’s no need to turn them off.
+.
+.P
+.I IMPORTANT:
+Unlike
+.BR .IL ,
+.B .IR
+and
+.BR IB ,
+measures given to
+.B .TI
+are NOT additive.
+.
+In the following example, the second
+.B \%".TI 2P"
+is exactly
+.IR "2 picas" . 
+.RS
+.EX
+.B .TI 1P
+.B The beginning of a paragraph...
+.B .TI 2P
+.B The beginning of another paragraph...
+.EE
+.RE
+.
+.RE
+.
+.
+.
+.\" ======================================================================
+.\" TN - Tab Next
+.\" ======================================================================
+.TP
+.B TN
+Tab Next
+.
+.RS
+.P
+Inline escape
+.B \[rs]*[TB+]
+.
+.P
+.B TN
+moves over to the
+.I next tab
+in numeric sequence
+.RI ( "tab n+1" )
+without advancing on the page.
+.
+See the
+.I NOTE
+in the description of the
+.B \%.TAB
+macro for an example of how
+.B TN
+works.
+.
+.P
+In
+.I \%tabs
+that aren\[aa]t given the
+.B QUAD
+argument when they\[aa]re set up with
+.B \%.TAB_SET
+or
+.BR ST ,
+you must terminate the line preceding
+.B .TN
+with the
+.B \[rs]c
+inline escape.
+.
+Conversely, if you did give a
+.B QUAD
+argument to
+.B \%.TAB_SET
+or
+.BR ST ,
+the
+.B \[rs]c must not be used.
+.
+.P
+If you find remembering whether to put in the
+.B \[rs]c
+bothersome, you may prefer to use the inline escape alternative
+to
+.BR .TN ,
+.BR \[rs]*[TB+] ,
+which works consistently regardless of the fill mode.
+.
+.P
+.I Note:
+You must put text in the input line immediately after
+.BR .TN .
+.
+Stacking of
+.BR .TN \[aa]s
+is not allowed.
+.
+In other words, you cannot do 
+.RS
+.EX
+\fB.TAB 1
+Some text\[rs]c
+.TN
+Some more text\[rs]c
+.TN
+.TN
+Yet more text\fR
+.EE
+.RE
+.
+The above example, assuming
+.I tabs
+numbered from
+.I 1
+to
+.IR 4 ,
+should be entered 
+.RS
+.EX
+\fB.TAB 1
+Some text\[rs]c
+.TN
+Some more text\[rs]c
+.TN
+\[rs]&\[rs]c
+.TN
+Yet more text
+.EE
+.RE
+.
+\[rs]& is a zero-width, non-printing character that
+.I groff
+recognizes as valid input, hence meets the requirement for input text
+following
+.BR .TN .
+.
+.RE
+.
+.
+.\" ======================================================================
+.\" Tab Quit
+.\" ======================================================================
+.TP
+.B .TQ
+.B TQ
+takes you out of whatever
+.I tab
+you were in, advances
+.IR "1 linespace" ,
+and restores the
+.IR "left margin" ,
+.IR "line length" ,
+.I quad direction
+and
+.I fill mode
+that were in effect prior to invoking any
+.IR tabs .
+.
+.
+.\" ======================================================================
+.\" Top Margin
+.\" ======================================================================
+.TP
+.B .T_MARGIN " <top margin>"
+Top margin
+.
+.RS
+.
+.P
+Requires a unit of measure
+.
+.P
+.B .T_MARGIN
+establishes the distance from the top of the printer sheet at which
+you want your type to start.
+.
+It requires a unit of measure, and decimal fractions are allowed.
+.
+To set a top margin of 2-1/2 centimetres, you’d enter 
+.RS
+.EX
+.B .T_MARGIN 2.5c
+.EE
+.RE
+.
+.B .T_MARGIN
+calculates the vertical position of the first line of type on a page
+by treating the top edge of the printer sheet as a baseline.
+Therefore, 
+.RS
+.EX
+.B .T_MARGIN 1.5i
+.EE
+.RE
+puts the baseline of the first line of type 1-1/2 inches beneath the
+top of the page.
+.
+.P
+Note:
+.B .T_MARGIN
+means something slightly different when you’re using the document
+processing macros.
+.
+See Top and bottom margins in document processing for an explanation.
+.
+.P
+IMPORTANT:
+.B .T_MARGIN
+does two things: it establishes the top margin for pages that come
+after it and it moves to that position on the current page.
+.
+Therefore,
+.B .T_MARGIN
+should only be used at the top of a file (prior to entering text) or
+after NEWPAGE, like this:
+.RS
+.EX
+.B .NEWPAGE
+.B .T_MARGIN 6P
+.I <text>
+.EE
+.RE
+.
+.RE
+.
+.
+.\" --------------------------------------------------------------------
+.SH "SEE ALSO"
+.\" --------------------------------------------------------------------
+.
+.BR groff (@MAN1EXT@),
+.BR groff_mom (@MAN7EXT@),
+.
+.TP
+.B \%@HTMLDOCDIR@/\:mom/\:toc.html
+\[en] entry point to the HTML documentation
+.
+.
+.\" --------------------------------------------------------------------
+.SH "AUTHORS"
+.\" --------------------------------------------------------------------
+.
+.authors
+.
+.\" --------------------------------------------------------------------
+.SH "COPYING"
+.\" --------------------------------------------------------------------
+.
+.copyleft
+.
+.
+.\" --------------------------------------------------------------------
+.\" Emacs settings
+.\" --------------------------------------------------------------------
+.
+.\" Local Variables:
+.\" mode: nroff
+.\" End:


From MAILER-DAEMON Tue Aug 20 04:22:29 2013
Received: from list by lists.gnu.org with archive (Exim 4.71)
	id 1VBhCv-0005N1-7e
	for mharc-groff-commit@gnu.org; Tue, 20 Aug 2013 04:22:29 -0400
Received: from eggs.gnu.org ([2001:4830:134:3::10]:58241)
	by lists.gnu.org with esmtp (Exim 4.71)
	(envelope-from <groff-bernd.warken-72@web.de>) id 1VBhCn-0005Et-Kj
	for groff-commit@gnu.org; Tue, 20 Aug 2013 04:22:28 -0400
Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71)
	(envelope-from <groff-bernd.warken-72@web.de>) id 1VBhCf-0005P0-51
	for groff-commit@gnu.org; Tue, 20 Aug 2013 04:22:21 -0400
Received: from vcs.savannah.gnu.org ([140.186.70.72]:47516)
	by eggs.gnu.org with esmtp (Exim 4.71)
	(envelope-from <groff-bernd.warken-72@web.de>) id 1VBhCf-0005Ol-18
	for groff-commit@gnu.org; Tue, 20 Aug 2013 04:22:13 -0400
Received: from bwarken by vcs.savannah.gnu.org with local (Exim 4.72)
	(envelope-from <groff-bernd.warken-72@web.de>) id 1VBhCd-0005kw-G2
	for groff-commit@gnu.org; Tue, 20 Aug 2013 08:22:11 +0000
Date: Tue, 20 Aug 2013 08:22:11 +0000
Message-Id: <E1VBhCd-0005kw-G2@vcs.savannah.gnu.org>
To: groff-commit@gnu.org
From: Bernd Warken <groff-bernd.warken-72@web.de>
X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6.x
X-Received-From: 140.186.70.72
Subject: [Groff-commit] groff/contrib/mom ChangeLog groff_mom.man mom.man
X-BeenThere: groff-commit@gnu.org
X-Mailman-Version: 2.1.14
Precedence: list
List-Id: <groff-commit.gnu.org>
List-Unsubscribe: <https://lists.gnu.org/mailman/options/groff-commit>,
	<mailto:groff-commit-request@gnu.org?subject=unsubscribe>
List-Archive: <http://lists.gnu.org/archive/html/groff-commit>
List-Post: <mailto:groff-commit@gnu.org>
List-Help: <mailto:groff-commit-request@gnu.org?subject=help>
List-Subscribe: <https://lists.gnu.org/mailman/listinfo/groff-commit>,
	<mailto:groff-commit-request@gnu.org?subject=subscribe>
X-List-Received-Date: Tue, 20 Aug 2013 08:22:28 -0000

CVSROOT:	/cvsroot/groff
Module name:	groff
Changes by:	Bernd Warken <bwarken>	13/08/20 08:22:11

Modified files:
	contrib/mom    : ChangeLog 
Removed files:
	contrib/mom    : groff_mom.man mom.man 

Log message:
	Removing for test only

CVSWeb URLs:
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/mom/ChangeLog?cvsroot=groff&r1=1.80&r2=1.81
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/mom/groff_mom.man?cvsroot=groff&r1=1.19&r2=0
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/mom/mom.man?cvsroot=groff&r1=1.1&r2=0

Patches:
Index: ChangeLog
===================================================================
RCS file: /cvsroot/groff/groff/contrib/mom/ChangeLog,v
retrieving revision 1.80
retrieving revision 1.81
diff -u -b -r1.80 -r1.81
--- ChangeLog	20 Aug 2013 05:59:05 -0000	1.80
+++ ChangeLog	20 Aug 2013 08:22:09 -0000	1.81
@@ -1,5 +1,9 @@
 * Tue Aug 20 2013
 
+o Integrate mom.7 into the man-page groff_mom.7
+
+* Tue Aug 20 2013
+
 o New man page mom.7
 
 * Sun Aug 11 2013

Index: groff_mom.man
===================================================================
RCS file: groff_mom.man
diff -N groff_mom.man
--- groff_mom.man	10 Jun 2013 04:27:24 -0000	1.19
+++ /dev/null	1 Jan 1970 00:00:00 -0000
@@ -1,156 +0,0 @@
-.ig
-This file is part of groff, the GNU roff type-setting system.
-
-Copyright (C) 2002, 2003, 2005, 2008, 2009, 2011, 2012, 2013
-  Free Software Foundation, Inc.
-written by Werner Lemberg <wl@gnu.org>
-revised 2012 by Peter Schaffter <peter@schaffter.ca>
-
-Permission is granted to copy, distribute and/or modify this document
-under the terms of the GNU Free Documentation License, Version 1.3 or
-any later version published by the Free Software Foundation; with the
-Invariant Sections being this .ig-section and AUTHORS, with no
-Front-Cover Texts, and with no Back-Cover Texts.
-
-A copy of the Free Documentation License is included as a file called
-FDL in the main directory of the groff source package.
-..
-.
-.do nr groff_mom_C \n[.C]
-.cp 0
-.
-.de TQ
-.br
-.ns
-.TP \\$1
-..
-.
-.TH GROFF_MOM @MAN7EXT@ "@MDATE@" "Groff Version @VERSION@"
-.
-.
-.SH NAME
-.
-groff_mom \- groff `mom' macros
-.
-.
-.SH SYNOPSIS
-.
-.SY pdfmom
-.OP \-Tps "\fR[pdfroff options]"
-[groff options]
-.I files .\|.\|.
-.YS
-.
-.SY groff
-.OP \-mom
-.I files .\|.\|.
-.YS
-.
-.SY groff
-.OP "\-m mom"
-.I files .\|.\|.
-.YS
-.
-.SH DESCRIPTION
-.
-.B mom
-is a macro set for groff, designed primarily to format documents for
-PDF and PostScript output.
-.P
-.B mom
-provides two categories of macros: macros for typesetting, and
-macros for document processing.
-The typesetting macros provide access to groff's typesetting
-capabilities in ways that are simpler to master than groff's
-primitives.
-The document processing macros provide highly customizable markup
-tags that allow the user to design and output professional-looking
-documents with a minimum of typesetting intervention.
-.P
-Files processed with
-.B pdfmom
-(man(@MAN1EXT@)
-.BR pdfmom\c
-), with or without the
-.RI -T ps
-option, produce PDF documents.
-The documents include a PDF outline that appears in the
-\[oq]Contents\[cq] panel of document viewers, and may contain
-clickable internal and external links.
-.P
-When
-.RI -T ps
-is absent,
-.B groff's
-native PDF driver,
-.B gropdf\c
-, is used to generate the output.
-When given, the output is still PDF, but processing is passed over to
-.B pdfroff\c
-, which uses
-.B groff's
-PostScript driver,
-.B grops\c
-\&.
-Not all PDF features are available when
-.RI -T ps
-is given; its primary use is to allow processing of files with
-embedded PostScript images.
-.P
-Files processed with
-.B groff -mom
-(or
-.BI "-m " mom
-) produce PostScript output by default.
-.P
-mom comes with her own very complete documentation in HTML format.
-A separate PDF manual,
-.I Producing PDFs with groff and mom\c
-, covers full mom/PDF usage.
-.
-.SH FILES
-.TP
-.B om.tmac
-\[en] the main macro file
-.TQ
-.B mom.tmac
-\[en] a wrapper file that calls om.tmac directly.
-.
-.TP
-.B \%@HTMLDOCDIR@/\:mom/\:toc.html
-\[en] entry point to the HTML documentation
-.
-.TP
-.B \%@PDFDOCDIR@/\:mom-pdf.pdf
-\[en] the PDF manual,
-.I Producing PDFs with groff and mom
-.
-.TP
-.B @EXAMPLEDIR@/mom/*.mom
-\[en] example files using mom
-.
-.
-.SH AUTHOR
-.
-.B mom
-was written by
-.MT peter@schaffter.ca
-Peter Schaffter
-.ME .
-.br
-PDF support was provided by
-.MT deri@chuzzlewit.demon.co.uk
-Deri James
-.ME .
-.sp
-Please send bug reports to the
-.MT bug-groff@gnu.org
-groff-bug mailing list
-.ME
-or directly to the authors.
-.
-.cp \n[groff_mom_C]
-.
-.\" Local Variables:
-.\" mode: nroff
-.\" End:

Index: mom.man
===================================================================
RCS file: mom.man
diff -N mom.man
--- mom.man	20 Aug 2013 05:59:06 -0000	1.1
+++ /dev/null	1 Jan 1970 00:00:00 -0000
@@ -1,3231 +0,0 @@
-.TH RUNOFF @MAN7EXT@ "@MDATE@" "Groff Version @VERSION@"
-.SH NAME
-mom \- the best \f[CI]roff\fP langugage, part of \f[CI]groff\fP
-.
-.SH "DESCRIPTION"
-.\" The .SH was moved to this place in order to appease `apropos'.
-.
-.\" --------------------------------------------------------------------
-.\" Legalese
-.\" --------------------------------------------------------------------
-.
-.de authors
-This file was written by Bernd Warken <groff-bernd.warken-72@web.de>.
-..
-.de copyleft
-.nh
-Copyright (C) 2013
-  Free Software Foundation, Inc.
-
-Last update: 14 August 2013
-
-This file is part of groff, a free software project.
-
-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.
-
-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 Text source package.
-
-Or read the man-page gpl (1).  You can also visit
-<http://www.gnu.org/licenses/>.
-.hy
-..
-.
-.\" --------------------------------------------------------------------
-.\" Setup
-.\" --------------------------------------------------------------------
-.
-.ds Ellipsis \&.\|.\|.\&\
-.
-.
-.\" --------------------------------------------------------------------
-.\" .FONT (<font name> <text> [<font name> <text> ...])
-.\"
-.\" Print in different fonts: R, I, B, CR, CI, CB
-.\"
-.de FONT
-.  if (\\n[.$] = 0) \{\
-.	nop \&\f[P]\&
-.	return
-.  \}
-.  ds result \&
-.  while (\\n[.$] >= 2) \{\
-.	as result \,\f[\\$1]\\$2
-.	if !"\\$1"P .as result \f[P]
-.	shift 2
-.  \}
-.  if (\\n[.$] = 1) .as result \,\f[\\$1]
-.  nh
-.  nop \\*[result]\&
-.  hy
-..
-.
-.\" --------------------------------------------------------------------
-.\" SH DESCRIPTION
-.\" The .SH was moved to the beginning in order to appease `apropos'.
-.\" --------------------------------------------------------------------
-.
-.
-This man-page contains information just as in groff(7),
-.I mom macros
-and
-.I mom escape sequences
-in alphabetical order.
-.
-.
-.P
-The logical order of
-.I mom macros
-and
-.I mom escape sequences
-is very well documented in
-.
-.TP
-.B \%@HTMLDOCDIR@/\:mom/\:toc.html
-\[en] entry point to the HTML documentation
-.
-.
-.P
-That is quite good for beginners, but power users need more
-documentation in reference style.
-.
-.
-.P
-So we restrict this man-page to the alphabetical order of macros and
-escape sequences.
-.
-But, so far, we take all documentation parts from the
-.I toc.html
-file, just in a more useful order.
-.
-Moreover, this is a man-page, so you can read it with
-.BR groffer ,
-instead of some strange webbrowser for
-.BR toc.html .
-.
-So this man-page is nothing new, but only a logical arrangement.
-.
-.
-.\" --------------------------------------------------------------------
-.SH "QUICK REFERENCE"
-.\" --------------------------------------------------------------------
-.
-.\" --------------------------------------------------------------------
-.SS "Quick Reference of Inline Escape Sequences in alphabetical Order"
-.\" --------------------------------------------------------------------
-.
-.TP
-.FONT B \[rs]*[ I <colorname> B ]
-begin using an initialized colour inline
-.
-.
-.TP
-.FONT B \[rs]*[BCK I " n" B ]
-move wards in a line
-.
-.
-.TP
-.BI \[rs]*[BOLDER]
-invoke pseudo bold inline (related to macro
-.BR .SETBOLDER )
-.
-.
-.TP
-.BI \[rs]*[BOLDERX]
-off pseudo bold inline (related to macro
-.BR .SETBOLDER )
-.
-.
-.TP
-.FONT B \[rs]*[BU I " n" B ]
-move characters pairs closer together inline (related to macro
-.BR \%.KERN )
-.
-.
-.TP
-.BI \[rs]*[COND]
-invoke pseudo condensing inline (related to macro
-.BR \%.CONDENSE )
-.
-.
-.TP
-.BI \[rs]*[CONDX]
-off pseudo condensing inline (related to macro
-.BR \%.CONDENSE )
-.
-.
-.TP
-.FONT B \[rs]*[CONDSUP] R \*[Ellipsis] B \[rs]*[CONDSUPX]
-pseudo-condensed superscript
-.
-.
-.TP
-.FONT B \[rs]*[DOWN I " n" B ]
-temporarily move downwards in a line
-.
-.
-.TP
-.BI \[rs]*[EN-MARK]
-mark initial line of a range of line numbers (for use with line
-numbered endnotes)
-.
-.
-.TP
-.BI \[rs]*[EXT]
-invoke pseudo extending inline (related to macro
-.BR \%.EXTEND )
-.
-.
-.TP
-.BI \[rs]*[EXTX]
-off pseudo condensing inline (related to macro
-.BR \%.EXTEND )
-.
-.
-.TP
-.FONT B \[rs]*[EXTSUP] R \*[Ellipsis] B \[rs]*[EXTSUPX]
-pseudo extrended superscript
-.
-.
-.TP
-.FONT B \[rs]*[FU I " n" B ]
-move characters pairs further apart inline (related to macro
-.BR \%.KERN )
-.
-.
-.TP
-.FONT B \[rs]*[FWD I " n" B ]
-move forward in a line
-.
-.
-.TP
-.BI \[rs]*[LEADER]
-insert leaders at the end of a line
-.
-.
-.TP
-.BI \[rs]*[RULE]
-draw a full measure rule
-.
-.
-.TP
-.FONT B \[rs]*[SIZE I " n" B ]
-change the point size inline (related to macro
-.BR \%.PT_SIZE )
-.
-.
-.TP
-.BI \[rs]*[SLANT]
-invoke pseudo italic inline (related to macro
-.BR \%.SETSLANT )
-.
-.
-.TP
-.BI \[rs]*[SLANTX]
-off pseudo italic inline (related to macro
-.BR \%.SETSLANT )
-.
-.
-.TP
-.FONT B \[rs]*[ST I <n> B ] R \*[Ellipsis] B \[rs]*[ST I <n> B X]
-string tabs (mark tab positions inline)
-.
-.
-.TP
-.FONT B \[rs]*[SUP] R \*[Ellipsis] B \[rs]*[SUPX]
-superscript
-.
-.
-.TP
-.B \[rs]*[TB+]
-Inline escape for
-.B .TN
-.RI ( "Tab Next" )
-.
-.
-.TP
-.FONT B \[rs]*[UL] R \*[Ellipsis] B \[rs]*[ULX]
-invoke underlining inline (fixed width fonts only)
-.
-.
-.TP
-.FONT B \[rs]*[UP I " n" B ]
-temporarily move upwards in a line
-.
-.
-.\" --------------------------------------------------------------------
-.SS "Quick Reference of Macros in alphabetical Order"
-.\" --------------------------------------------------------------------
-.
-.TP
-.BI .AUTOLEAD
-set the linespacing relative to the point size
-.
-.
-.TP
-.BI .B_MARGIN
-set a bottom margin
-.
-.
-.TP
-.BI .BR
-break a justified line
-.
-.
-.TP
-.BI .CENTER
-set line-by-line quad centre
-.
-.
-.TP
-.BI .CONDENSE
-set the amount to pseudo condense
-.
-.
-.TP
-.BI .EL
-break a line without advancing on the page
-.
-.
-.TP
-.BI .EXTEND
-set the amount to pseudo extend
-.
-.
-.TP
-.BI .FALLBACK_FONT
-establish a fallback font (for missing fonts)
-.
-.
-.TP
-.BI .FAM
-alias to
-.B .FAMILY
-.
-.
-.TP
-.BI .FAMILY <family>
-set the
-.I family type
-.
-.
-.TP
-.BI .FT
-set the font style (roman, italic, etc.)
-.
-.
-.TP
-.BI ".HI [" " <measure> " ]
-hanging indent
-.
-.
-.TP
-.BI .HY
-automatic hyphenation on/off
-.
-.
-.TP
-.BI .HY_SET
-set automatic hyphenation parameters
-.
-.
-.TP
-.BI ".IB [" " <left measure> <right measure> " ]
-indent both
-.
-.
-.TP
-.B .IBX [ CLEAR ]
-exit indent both
-.
-.
-.TP
-.BI ".IL [" " <measure> " ]
-indent left
-.
-.
-.TP
-.B .ILX [ CLEAR ]
-exit indent left
-.
-.
-.TP
-.B .IQ [ CLEAR ]
-quit any/all indents
-.
-.
-.TP
-.BI ".IR [" " <measure> " ]
-indent right
-.
-.
-.TP
-.B .IRX [ CLEAR ]
-exit indent right
-.
-.
-.TP
-.BI JUSTIFY
-justify text to both margins
-.
-.
-.TP
-.BI .KERN
-automatic character pair kerning on/off
-.
-.
-.TP
-.BI .L_MARGIN
-set a left margin (page offset)
-.
-.
-.TP
-.BI .LEFT
-set line-by-line quad left
-.
-.
-.TP
-.BI .LL
-set a line length
-.
-.
-.TP
-.BI .LS
-set a linespacing (leading)
-.
-.
-.TP
-.BI .PAGE
-set explicit page dimensions and margins
-.
-.
-.TP
-.BI .PAGEWIDTH
-set a custom page width
-.
-.
-.TP
-.BI .PAGELENGTH
-set a custom page length
-.
-.
-.TP
-.BI .PAPER " <paper_type>"
-set common paper sizes (letter, A4, etc)
-.
-.
-.TP
-.BI .PT_SIZE
-set the point size
-.
-.
-.TP
-.BI .QUAD
-"justify" text left, centre, or right
-.
-.
-.TP
-.BI .R_MARGIN
-set a right margin
-.
-.
-.TP
-.BI .RIGHT
-set line-by-line quad right
-.
-.
-.TP
-.BI .SETBOLDER
-set the amount of emboldening
-.
-.
-.TP
-.BI .SETSLANT
-set the degree of slant
-.
-.
-.TP
-.BI .SPREAD
-force justify a line
-.
-.
-.TP
-.BI .SS
-set the sentence space size
-.
-.
-.TP
-.BI .T_MARGIN
-set a top margin
-.
-.
-.TP
-.BI ".TI [" " <measure> " ]
-temporary left indent
-.
-.
-.TP
-.BI .WS
-set the minimum word space size
-.
-.
-.\" --------------------------------------------------------------------
-.SH "DOCUMENTATION OF DETAILS"
-.\" --------------------------------------------------------------------
-.
-.\" --------------------------------------------------------------------
-.SS "Details of Inline Escape Sequences in alphabetical Order"
-.\" --------------------------------------------------------------------
-.
-.TP
-.FONT B \[rs]*[ I <colorname> B ]
-begin using an initialized colour inline
-.
-.
-.TP
-.FONT B \[rs]*[BCK I " n" B ]
-move wards in a line
-.
-.
-.\" ======================================================================
-.\" BOLDER
-.\" ======================================================================
-.TP
-.B \[rs]*[BOLDER]
-.TQ
-.B \[rs]*[BOLDERX]
-Emboldening on/off
-.
-.RS
-.
-.P
-.B \[rs]*[BOLDER]
-begins emboldening type.
-.
-.B \[rs]*[BOLDERX]
-turns the feature off.
-.
-Both are inline escapes, therefore they should not appear as separate
-lines, but rather be embedded in text lines, like this:
-.RS
-.EX
-.FONT R "Not " B \[rs]*[BOLDER] R everything B \[rs]*[BOLDERX] R " is as it seems."
-.EE
-.RE
-.
-.P
-Alternatively, if you wanted the whole line emboldened, you should do 
-.RS
-.EX
-.FONT B \[rs]*[BOLDER] R "Not everything is as it seems." B \[rs]*[BOLDERX]
-.EE
-.RE
-.
-Once
-.B \[rs]*[BOLDER]
-is invoked, it remains in effect until turned off.
-.
-.P
-Note: If you’re using the document processing macros with
-.B PRINTSTYLE
-.BR TYPEWRITE ,
-.B mom
-ignores
-.B \[rs]*[BOLDER]
-requests.
-.
-.RE
-.
-.
-.\" ======================================================================
-.\" BU
-.\" ======================================================================
-.TP
-.FONT B \[rs]*[BU I " n" B ]
-move characters pairs closer together inline (related to macro
-.BR \%.KERN )
-.
-.
-.\" ======================================================================
-.\" COND
-.\" ======================================================================
-.TP
-.B \[rs]*[COND]
-.TQ
-.BI \[rs]*[CONDX]
-Pseudo-condensing on/off
-.
-.RS
-.
-.P
-.B \[rs]*[COND]
-begins pseudo-condensing type.
-.
-.B \[rs]*[CONDX]
-turns the feature off.
-.
-Both are inline escapes, therefore they should not appear as separate
-lines, but rather be embedded in text lines, like this:
-.RS
-.EX
-.FONT B \[rs]*[COND] I "Not everything is as it seems." B \[rs]*[CONDX]
-.EE
-.RE
-.B \%\[rs]*[COND]
-remains in effect until you turn it off with
-.BR \%\[rs]*[CONDX] .
-.
-.P
-IMPORTANT: You must turn
-.B \%\[rs]*[COND]
-off before making any changes to the point size of your type, either
-via the
-.B \%.PT_SIZE
-macro or with the
-.B \[rs]s
-inline escape.
-.
-If you wish the new point size to be pseudo-condensed, simply reinvoke
-.B \%\[rs]*[COND]
-afterwards.
-.
-Equally,
-.B \%\[rs]*[COND]
-must be turned off before changing the condense percentage with
-.BR \%.CONDENSE .
-.
-.P
-Note: If you’re using the document processing macros with
-.B \%PRINTSTYLE
-.BR \%TYPEWRITE ,
-.B mom
-ignores
-.B \%\[rs]*[COND]
-requests.
-.
-.RE
-.
-.
-.\" ======================================================================
-.\" CONDSUP
-.\" ======================================================================
-.TP
-.FONT B \[rs]*[CONDSUP] R \*[Ellipsis] B \[rs]*[CONDSUPX]
-pseudo-condensed superscript
-.
-.
-.\" ======================================================================
-.\" DOWN
-.\" ======================================================================
-.TP
-.FONT B \[rs]*[DOWN I " n" B ]
-temporarily move downwards in a line
-.
-.
-.\" ======================================================================
-.\" EN-MARK
-.\" ======================================================================
-.TP
-.BI \[rs]*[EN-MARK]
-mark initial line of a range of line numbers (for use with line
-numbered endnotes)
-.
-.
-.\" ======================================================================
-.\" EXT
-.\" ======================================================================
-.TP
-.B \[rs]*[EXT]
-.TQ
-.B \[rs]*[EXTX]
-Pseudo-extending on/off
-.
-.RS
-.
-.P
-.B \[rs]*[EXT]
-begins pseudo-extending type.
-.
-.B \[rs]*[EXTX]
-turns the feature off.
-.
-Both are inline escapes, therefore they should not appear as separate
-lines, but rather be embedded in text lines, like this:
-.RS
-.EX
-.FONT B \[rs]*[EXT] I "Not everything is as it seems." B \[rs]*[EXTX]
-.EE
-.RE
-.B \[rs]*[EXT]
-remains in effect until you turn it off with
-.BR \[rs]*[EXTX] .
-.
-.P
-IMPORTANT: You must turn
-.B \%\[rs]*[EXT]
-off before making any changes to the point size of your type, either
-via the
-.B \%.PT_SIZE
-macro or with the
-.B \[rs]s
-inline escape.
-.
-If you wish the new point size to be
-.IR \%pseudo-extended ,
-simply reinvoke
-.B \%\[rs]*[EXT]
-afterwards.
-.
-Equally,
-.B \%\[rs]*[EXT]
-must be turned off before changing the extend percentage with
-.BR \%.EXTEND .
-.
-.P
-Note: If you are using the document processing macros with
-.B \%.PRINTSTYLE
-.BR \%TYPEWRITE ,
-.B mom
-ignores
-.B \%\[rs]*[EXT]
-requests.
-.
-.RE
-.
-.
-.\" ======================================================================
-.\" EXTSUP
-.\" ======================================================================
-.TP
-.FONT B \[rs]*[EXTSUP] R \*[Ellipsis] B \[rs]*[EXTSUPX]
-pseudo extrended superscript
-.
-.
-.\" ======================================================================
-.\" FU
-.\" ======================================================================
-.TP
-.FONT B \[rs]*[FU I " n" B ]
-move characters pairs further apart inline (related to macro
-.BR .KERN )
-.
-.
-.\" ======================================================================
-.\" FWD
-.\" ======================================================================
-.TP
-.FONT B \[rs]*[FWD I " n" B ]
-move forward in a line
-.
-.
-.\" ======================================================================
-.\" LEADER
-.\" ======================================================================
-.TP
-.BI \[rs]*[LEADER]
-insert leaders at the end of a line
-.
-.
-.\" ======================================================================
-.\" RULE
-.\" ======================================================================
-.TP
-.BI \[rs]*[RULE]
-draw a full measure rule
-.
-.
-.\" ======================================================================
-.\" PT_SIZE
-.\" ======================================================================
-.TP
-.FONT B \[rs]*[SIZE I " n" B ]
-change the point size inline (related to macro
-.BR \%.PT_SIZE )
-.
-.
-.\" ======================================================================
-.\" SLANT
-.\" ======================================================================
-.TP
-.B \[rs]*[SLANT]
-.TQ
-.B \[rs]*[SLANTX]
-Pseudo italic on/off
-.
-.RS
-.
-.P
-.B \%\[rs]*[SLANT]
-begins
-.I pseudo-italicizing
-.IR type .
-.
-.B \%\[rs]*[SLANTX]
-turns the feature off.
-.
-Both are
-.I inline
-.IR escapes ,
-therefore they should not appear as separate lines, but rather be
-embedded in text lines, like this:
-.RS
-.EX
-.FONT R "Not " B \[rs]*[SLANT] R everything B \[rs]*[SLANTX] R " is as it seems."
-.EE
-.RE
-.
-.P
-Alternatively, if you wanted the whole line
-.IR pseudo-italicized ,
-you\[aa]d do
-.RS
-.EX
-.FONT B \[rs]*[SLANT] R "Not everything is as it seems." B \[rs]*[SLANTX]
-.EE
-.RE
-.
-.P
-Once
-.B \[rs]*[SLANT]
-is invoked, it remains in effect until turned off.
-.
-.P
-Note: If you’re using the document processing macros with
-.B .PRINTSTYLE
-.BR TYPEWRITE ,
-.B mom
-underlines pseudo-italics by default.
-.
-To change this behaviour, use the special macro
-.BR .SLANT_MEANS_SLANT .
-.
-.RE
-.
-.
-.\" ======================================================================
-.\" ST
-.\" ======================================================================
-.TP
-.FONT B \[rs]*[ST I <number> B ] R \*[Ellipsis] B \[rs]*[ST I <number> B X]
-Mark positions of string tabs
-.
-.RS
-.P
-The
-.I quad
-direction must be
-.B LEFT
-or
-.B \%JUSTIFY
-(see
-.B \%.QUAD
-and
-.BR \%.JUSTIFY )
-or the
-.I no-fill mode
-set to
-.B LEFT
-in order for these inlines to function properly.
-.
-Please see
-.IR \%IMPORTANT ,
-below.
-.
-.P
-String tabs need to be marked off with inline escapes before being set
-up with the
-.B .ST
-macro.
-.
-Any input line may contain string tab markers.
-.
-.IR <number> ,
-above, means the numeric identifier of the tab.
-.
-.P
-The following shows a sample input line with string tab markers. 
-.RS
-.EX
-.FONT B \[rs]*[ST1] R "Now is the time" B \[rs]*[ST1X] R " for all " B \[rs]*[ST2] R "good men" B \[rs]*ST2X] R " to come to the aid of the party."
-.EE
-.RE
-.
-.P
-String
-.I tab 1
-begins at the start of the line and ends after the word
-.IR \%time .
-.
-String
-.I tab 2
-starts at
-.I good
-and ends after
-.IR men .
-.
-.I Inline escapes
-(e.g.
-.I font
-or
-.I point size
-.IR changes ,
-or horizontal movements, including padding) are taken into account
-when
-.B mom
-determines the
-.I position
-and
-.I length
-of
-.I string
-.IR tabs .
-.
-.P
-Up to nineteen string tabs may be marked (not necessarily all on the
-same line, of course), and they must be numbered between 1 and 19.
-.
-.P
-Once string tabs have been marked in input lines, they have to be
-.I set
-with
-.BR .ST ,
-after which they may be called, by number, with
-.BR .TAB .
-.
-.P
-Note: Lines with string tabs marked off in them are normal input
-lines, i.e. they get printed, just like any input line.
-.
-If you want to set up string tabs without the line printing, use the
-.B \%.SILENT
-macro.
-.
-.P
-.I IMPORTANT:
-Owing to the way
-.B groff
-processes input lines and turns them into output lines, it is not
-possible for
-.B mom
-to
-.I guess
-the correct starting position of string tabs marked off in lines that
-are centered or set flush right.
-.
-.P
-Equally, she cannot guess the starting position if a line is fully
-justified and broken with
-.BR \%.SPREAD .
-.
-.P
-In other words, in order to use string tabs,
-.B LEFT
-must be active, or, if
-.B .QUAD LEFT
-or
-.B \%JUSTIFY
-are active, the line on which the
-.I string tabs
-are marked must be broken
-.I manually
-with
-.B .BR
-(but not
-.BR \%.SPREAD ).
-.
-.P
-To circumvent this behaviour, I recommend using the
-.B PAD
-to set up string tabs in centered or flush right lines.
-.
-Say, for example, you want to use a
-.I string tab
-to
-.I underscore
-the text of a centered line with a rule.
-.
-Rather than this,
-.RS
-.EX
-.B .CENTER
-.B \[rs]*[ST1]A line of text\[rs]*[ST1X]\[rs]c
-.B .EL
-.B .ST 1
-.B .TAB 1
-.B .PT_SIZE 24
-.B .ALD 3p
-.B \[rs]*[RULE]
-.B .RLD 3p
-.B .TQ
-.EE
-.RE
-you should do: 
-.RS
-.EX
-.B .QUAD CENTER
-.B .PAD \[rq]#\[rs]*[ST1]A line of text\[rs]*[ST1X]#\[rq]
-.B .EL
-.B .ST 1
-.B .TAB 1
-.B .PT_SIZE 24
-.B .ALD 3p
-.B \[rs]*[RULE] \[rs]\[rq] Note that you can\[aa]t use \[rs]*[UP] or \[rs]*[DOWN] with \[rs]*[RULE]
-.B .RLD 3p
-.B .TQ
-.EE
-.RE
-.
-.RE
-.
-.
-.\" ======================================================================
-.\" SUP
-.\" ======================================================================
-.TP
-.FONT B \[rs]*[SUP] R \*[Ellipsis] B \[rs]*[SUPX]
-superscript
-.
-.
-.\" ======================================================================
-.\" TB+
-.\" ======================================================================
-.TP
-.B \[rs]*[TB+]
-Inline escape for
-.B .TN
-.RI ( "Tab Next" )
-.
-.
-.\" ======================================================================
-.\" UL
-.\" ======================================================================
-.TP
-.FONT B \[rs]*[UL] R \*[Ellipsis] B \[rs]*[ULX]
-invoke underlining inline (fixed width fonts only)
-.
-.
-.\" ======================================================================
-.\" UP
-.\" ======================================================================
-.TP
-.FONT B \[rs]*[UP I " n" B ]
-temporarily move upwards in a line
-.
-.
-.\" --------------------------------------------------------------------
-.SS "Details of Macros in alphabetical Order"
-.\" --------------------------------------------------------------------
-.
-.\" ======================================================================
-.\" AUTOLEAD
-.\" ======================================================================
-.TP
-.BI .AUTOLEAD
-set the linespacing relative to the point size
-.
-.
-.\" ======================================================================
-.\" Bottom Margin
-.\" ======================================================================
-.TP
-.BI .B_MARGIN " <bottom margin>"
-Bottom Margin
-.
-.RS
-.
-.P
-Requires a unit of measure
-.
-.P
-.B .B_MARGIN
-sets a nominal position at the bottom of the page beyond which you
-don’t want your type to go.
-.
-When the bottom margin is reached,
-.B mom
-starts a new page.
-.
-.B .B_MARGIN requires a unit of measure.
-.
-Decimal fractions are allowed.
-.
-To set a nominal bottom margin of 3/4 inch, enter 
-.RS
-.EX
-.B .B_MARGIN .75i
-.EE
-.RE
-.
-.P
-Obviously, if you haven’t spaced the type on your pages so that the
-last lines fall perfectly at the bottom margin, the margin will vary
-from page to page.
-.
-Usually, but not always, the last line of type that fits on a page
-before the bottom margin causes mom to start a new page.
-.
-.P
-Occasionally, owing to a peculiarity in
-.IR groff ,
-an extra line will fall below the nominal bottom margin.
-.
-If you’re using the document processing macros, this is unlikely to
-happen; the document processing macros are very hard-nosed about
-aligning bottom margins.
-.
-.P
-Note: The meaning of
-.B .B_MARGIN
-is slightly different when you’re using the document processing
-macros.
-.
-.RE
-.
-.
-.\" ======================================================================
-.\" Fallback Font
-.\" ======================================================================
-.TP
-.BI \%.FALLBACK_FONT " <fallback font> " "[ ABORT | WARN ]"
-Fallback Font
-.
-.RS
-.
-.P
-In the event that you pass an invalid argument to
-.B \%.FAMILY
-(i.e. a non-existent
-.IR family ),
-.BR mom ,
-by default, uses the
-.IR "fallback font" ,
-.B Courier Medium Roman
-.RB ( CR ),
-in order to continue processing your file.
-.
-.P
-If you\[aa]d prefer another
-.IR "fallback font" ,
-pass
-.B \%.FALLBACK_FONT
-the full
-.I family+font name
-of the
-.I font
-you\[aa]d like.
-.
-For example, if you\[aa]d rather the
-.I fallback font
-were
-.BR "Times Roman Medium Roman" , 
-.RS
-.EX
-.B .FALLBACK_FONT TR
-.EE
-.RE
-would do the trick.
-.
-.P
-.B Mom
-issues a warning whenever a
-.I font style set
-with
-.B .FT
-does not exist, either because you haven\[aa]t registered the style
-or because the
-.I font style
-does not exist in the current
-.I family set
-with
-.BR .FAMILY .
-.
-By default,
-.B \%mom
-then aborts, which allows you to correct the problem.
-.
-.P
-If you\[aa]d prefer that
-.B \%mom
-not abort on non-existent
-.IR fonts ,
-but rather continue processing using a
-.IR "fallback font" ,
-you can pass
-.B \%.FALLBACK_FONT
-the argument
-.BR WARN ,
-either by itself, or in conjunction with your chosen
-.IB "fallback font" .
-.
-.P
-Some examples of invoking
-.BR \%.FALLBACK_FONT :
-.
-.TP
-.B .FALLBACK_FONT WARN
-.B mom
-will issue a warning whenever you try to access a non-existent
-.I font
-but will continue processing your file with the default
-.IR "fallback font" ,
-.BR "Courier Medium Roman" .
-.
-.
-.TP
-.B .FALLBACK_FONT TR WARN
-.B \%mom
-will issue a warning whenever you try to access a non-existent
-.I font
-but will continue processing your file with a
-.I fallback font
-of
-.BR "Times Roman Medium Roman" ;
-additionally,
-.B TR
-will be the
-.I fallback font
-whenever you try to access a
-.I family
-that does not exist.
-.
-.TP
-.B .FALLBACK_FONT TR ABORT 
-.B \%mom
-will abort whenever you try to access a non-existent
-.BR font ,
-and will use the
-.I fallback font
-.B TR
-whenever you try to access a
-.I family
-that does not exist.
-.
-If, for some reason, you want to revert to
-.BR ABORT ,
-just enter
-.B \%".FALLBACK_FONT ABORT"
-and
-.B mom
-will once again abort on
-.IR "font errors" .
-.
-.RE
-.
-.
-.\" ======================================================================
-.\" FAM
-.\" ======================================================================
-.TP
-.BI .FAM " <family>"
-Type Family, alias of \fB.FAMILY\fR
-.
-.
-.\" ======================================================================
-.\" FAMILY
-.\" ======================================================================
-.TP
-.BI .FAMILY " <family>"
-Type Family, alias \fB.FAM\fR
-.
-.RS
-.
-.P
-.B .FAMILY
-takes one argument: the name of the
-.I family
-you want.
-.
-.I Groff
-comes with a small set of basic families, each identified by a 1-,
-2-or 3-letter mnemonic.
-.
-The standard families are:
-.RS
-.EX
-.B A   = Avant Garde
-.B BM  = Bookman
-.B H   = Helvetica
-.B HN  = Helvetica Narrow
-.B N   = New Century Schoolbook
-.B P   = Palatino
-.B T   = Times Roman
-.B ZCM = Zapf Chancery
-.EE
-.RE
-.
-.P
-The argument you pass to
-.B .FAMILY
-is the identifier at left, above.
-.
-For example, if you want
-.BR Helvetica ,
-enter 
-.RS
-.EX
-.B .FAMILY H
-.EE
-.RE
-.
-.P
-Note: The font macro
-.RB ( .FT )
-lets you specify both the type
-.I family
-and the desired font with a single macro.
-.
-While this saves a few
-keystrokes, I recommend using
-.B .FAMILY for
-.IR family ,
-and
-.B .FT for
-.IR font ,
-except where doing so is genuinely inconvenient.
-.
-.BR ZCM ,
-for example,
-only exists in one style:
-.B Italic
-.RB ( I ).
-.
-.P
-Therefore,
-.RS
-.EX
-.B .FT ZCMI
-.EE
-.RE
-makes more sense than setting the
-.I family
-to
-.BR ZCM ,
-then setting the
-.I font
-to
-.IR I .
-.
-.P
-Additional note: If you are running a version of groff lower than
-1.19.2, you must follow all
-.B .FAMILY
-requests with a
-.B FT
-request, otherwise
-.B mom
-will set all type up to the next
-.B .FT
-request in the fallback font.
-.
-.P
-If you are running a version of groff greater than or equal to 1.19.2,
-when you invoke the
-.B .FAMILY
-macro,
-.B mom
-.I remembers
-the font style
-.BR ( Roman ,
-.BR Italic ,
-etc) currently in use (if the font style exists in the new
-.IR family ) and will continue to use the same font style in the new
-.IR family .
-For example:
-.RS
-.EX
-.BI ".FAMILY BM " "\[rs]\[rq] Bookman family"
-.BI ".FT I " "\[rs]\[rq] Medium Italic"
-.I <some text> \[rs]\[rq] Bookman Medium Italic
-.BI ".FAMILY H " "\[rs]\[rq] Helvetica family"
-.I <more text> \[rs]\[rq] Helvetica Medium Italic
-.EE
-.RE
-.
-.P
-However, if the font style does not exist in the new family,
-.B mom
-will set all subsequent type in the fallback font (by default,
-.B Courier Medium
-.BR Roman )
-until she encounters a
-.B .FT
-request that\[aa]s valid for the
-.IR family .
-.
-.P
-For example, assuming you don\[aa]t have the font
-.B Medium Condensed Roman
-.RB  ( mom
-extension
-.IR CD )
-in the
-.I Helvetica
-.IR family :
-.RS
-.EX
-.BI ".FAMILY UN " "\[rs]\[rq]Univers family"
-.BI ".FT CD " "\[rs]\[rq] Medium Condensed"
-.I <some text> \[rs]\[rq] Univers Medium Condensed
-.BI ".FAMILY H " "\[rs]\[rq] Helvetica family"
-.I <more text> \[rs]\[rq] Courier Medium Roman!
-.EE
-.RE
-.
-.P
-In the above example, you must follow
-.B .FAMILY H
-with a
-.B .FT
-request that’s valid for
-.BR Helvetica .
-.
-.P
-Please see the Appendices,
-.I Adding fonts to
-.IR groff ,
-for information on adding fonts and families to groff, as well as to
-see a list of the extensions
-.B mom
-provides to
-.IR groff \[aa]s
-basic
-.BR R ,
-.BR I ,
-.BR B ,
-.B BI
-styles.
-.
-.P
-Suggestion: When adding
-.I families to
-.IR groff ,
-I recommend following the established standard for the naming families
-and fonts.
-.
-For example, if you add the
-.B Garamond
-family, name the font files
-.RS
-.EX
-.B GARAMONDR
-.B GARAMONDI
-.B GARAMONDB
-.B GARAMONDBI
-.EE
-.RE
-.
-.B GARAMOND then becomes a valid
-.I family name
-you can pass to
-.BR .FAMILY .
-.
-(You could, of course, shorten
-.B GARAMOND
-to just
-.BR G ,
-or
-.BR GD .)
-.BR R ,
-.BR I ,
-.BR B ,
-and
-.B BI
-after
-.B GARAMOND
-are the
-.IR roman ,
-.IR italic ,
-.I bold
-and
-.I bold-italic
-fonts respectively.
-.
-.RE
-.
-.
-.\" ======================================================================
-.\" FONT
-.\" ======================================================================
-.TP
-.BI .FONT R " | " B " | " BI " | " <any other valid font style>"
-Alias to
-.B .FT
-.
-.
-.\" ======================================================================
-.\" FT
-.\" ======================================================================
-.TP
-.BI .FT R " | " B " | " BI " | " <any other valid font style>"
-Set font
-.
-.RS
-.
-.P
-By default,
-.I groff
-permits
-.B .FT
-to take one of four possible arguments specifying the desired font: 
-.RS
-.EX
-.B R = (Medium) Roman
-.B I = (Medium) Italic
-.B B = Bold (Roman)
-.B BI = Bold Italic
-.EE
-.RE
-.
-.P
-For example, if your
-.I family
-is
-.BR Helvetica ,
-entering 
-.RS
-.EX
-.B .FT B
-.EE
-.RE
-will give you the
-.I Helvetica bold
-.IR font .
-.
-If your
-.I family
-were
-.BR \%Palatino ,
-you\[aa]d get the
-.I \%Palatino bold
-.IR font .
-.
-.P
-.B Mom
-considerably extends the range of arguments you can pass to
-.BR .FT ,
-making it more convenient to add and access fonts of differing weights
-and shapes within the same family.
-.
-.P
-Have a look here for a list of the weight/style arguments
-.B mom
-allows.
-.
-Be aware, though, that you must have the fonts, correctly installed
-and named, in order to use the arguments.
-.
-(See
-.I Adding fonts to groff
-for instructions and information.)
-.
-Please also read the
-.I ADDITIONAL NOTE
-found in the description of the
-.B \%.FAMILY
-macro.
-.
-.P
-How
-.B mom
-reacts to an invalid argument to
-.B .FT
-depends on which version of groff you\[aa]re using.
-.
-If your
-.I groff version
-is greater than or equal to 1.19.2,
-.B mom
-will issue a warning and, depending on how you’ve set up the fallback
-font, either continue processing using the fallback font, or abort
-(allowing you to correct the problem). If your
-.I groff version
-is less than 1.19.2,
-.B mom
-will silently continue processing, using either the fallback font or
-the font that was in effect prior to the invalid
-.B .FT
-call.
-.
-.P
-.B .FT
-will also accept, as an argument, a full
-.I family
-and
-.I font
-.IR name .
-.
-.P
-For example, 
-.RS
-.EX
-.B .FT HB
-.EE
-.RE
-will set subsequent type in
-.I Helvetica
-.IR Bold .
-.
-.P
-However, I strongly recommend keeping
-.I family
-and
-.I font
-separate except where doing so is genuinely inconvenient.
-.
-.P
-For inline control of
-.IR fonts ,
-see
-.I Inline
-.IR Escapes ,
-font control.
-.
-.RE
-.
-.
-.\" ======================================================================
-.\" Hanging Indent
-.\" ======================================================================
-.TP
-.BI "\%.HI [" " <measure> " ]
-Hanging indent \[em] the optional argument requires a unit of measure.
-.
-.RS
-.
-.P
-A hanging indent looks like this: 
-.RS
-.EX
-\fB  The thousand injuries of Fortunato I had borne as best I
-    could, but when he ventured upon insult, I vowed
-    revenge.  You who so well know the nature of my soul
-    will not suppose, however, that I gave utterance to a
-    threat, at length I would be avenged...
-.EE
-.RE
-.
-The first line of text
-.I hangs
-outside the
-.IR "left margin" .
-.
-.P
-In order to use
-.IR "hanging indents" ,
-you must first have a
-.I left indent
-active (set with either
-.B .IL
-or
-.BR .IB ).
-.
-.B Mom
-will not hang text outside the
-.I left margin set
-with
-.B \%.L_MARGIN
-or outside the
-.I left margin
-of a
-.IR \%tab .
-.
-.P
-The first time you invoke
-.BR .HI ,
-you must give it a
-.BR measure .
-.
-If you want the first line of a paragraph to
-.IR "hang by" ,
-say,
-.IR "1 pica" ,
-do 
-.RS
-.EX
-.B .IL 1P
-.B .HI 1P
-.EE
-.RE
-.
-Subsequent invocations of
-.B \%.HI
-do not require you to supply a
-.IR measure ;
-.B mom
-keeps track of the last measure you gave it.
-.
-.P
-Generally speaking, you should invoke
-.B .HI
-immediately prior to the line you want hung (i.e. without any
-intervening control lines).
-.
-And because
-.I hanging indents
-affect only one line, there\[aa]s no need to turn them off.
-.
-.P
-.I IMPORTANT:
-Unlike
-.BR IL ,
-.B IR
-and
-.BR IB ,
-measures given to
-.B .HI
-are NOT additive.
-.
-Each time you pass a measure to
-.B .HI ,
-the measure is treated literally.
-.
-.B
-.I Recipe:
-A numbered list using
-.I hanging indents
-.
-.P
-.I Note:
-.B mom
-has macros for setting lists.
-.
-This recipe exists to demonstrate the use of
-.I hanging indents
-only.
-.RS
-.EX
-.B .PAGE 8.5i 11i 1i 1i 1i 1i
-.B .FAMILY  T
-.B .FT      R
-.B .PT_SIZE 12
-.B .LS      14
-.B .JUSTIFY
-.B .KERN
-.B .SS 0
-.B .IL \[rs]w'\[rs]0\[rs]0.'
-.B .HI \[rs]w'\[rs]0\[rs]0.'
-\fB1.\[rs]0The most important point to be considered is whether the
-answer to the meaning of Life, the Universe, and Everything
-really is 42.  We have no-one’s word on the subject except
-Mr. Adams’.
-.B .HI
-2.\[rs]0If the answer to the meaning of Life, the Universe,
-and Everything is indeed 42, what impact does this have on
-the politics of representation?  42 is, after all not a
-prime number.  Are we to infer that prime numbers don’t
-deserve equal rights and equal access in the universe?
-.B .HI
-3.\[rs]0If 42 is deemed non-exclusionary, how do we present it
-as the answer and, at the same time, forestall debate on its
-exclusionary implications?
-.EE
-.RE
-.
-.P
-First, we invoke a left indent with a measure equal to the width of 2
-figures spaces plus a period (using the \[rs]w inline escape).
-.
-At this point, the left indent is active; text afterwards would
-normally be indented.
-.
-However, we invoke a hanging indent of exactly the same width, which
-hangs the first line (and first line only!) to the left of the indent
-by the same distance (in this case, that means “out to the left
-margin”).
-.
-Because we begin the first line with a number, a period, and a figure
-space, the actual text
-.RI ( "The most important point..." )
-starts at exactly the same spot as the indented lines that follow.
-.
-.P
-Notice that subsequent invocations of
-.B .HI
-don’t require a
-.I measure
-to be given.
-.
-.P
-Paste the example above into a file and preview it with 
-.RS
-.EX
-.B pdfmom filename.mom | ps2pdf - filename.pdf
-.EE
-.RE
-to see hanging indents in action.
-.
-.RE
-.
-.
-.\" ======================================================================
-.\" IB - INDENT BOTH
-.\" ======================================================================
-.TP
-.BI "\%.IB [" " <left measure> <right measure> " ]
-Indent both \[em] the optional argument requires a unit of measure
-.
-.RS
-.
-.P
-.B .IB
-allows you to set or invoke a left and a right indent at the same time.
-.
-.P
-At its first invocation, you must supply a measure for both indents;
-at subsequent invocations when you wish to supply a measure, both must
-be given again.
-.
-As with
-.B .IL
-and
-.BR .IR ,
-the measures are added to the values previously passed to the
-macro.
-.
-Hence, if you wish to change just one of the values, you must give an
-argument of zero to the other.
-.
-.P
-.I A word of advice:
-If you need to manipulate left and right indents separately, use a
-combination of
-.B .IL
-and
-.B .IR
-instead of
-.BR .IB .
-.
-You’ll save yourself a lot of grief.
-.
-.P
-A
-.I minus sign
-may be prepended to the arguments to subtract from their current
-values.
-.
-The \[rs]w inline escape may be used to specify text-dependent
-measures, in which case no unit of measure is required.
-.
-For example,
-.RS
-.EX
-.B .IB \[rs]w\[aa]margarine\[aa] \[rs]w\[aa]jello\[aa]
-.EE
-.RE
-left indents text by the width of the word
-.I margarine
-and right indents by the width of
-.IR jello .
-.
-.P
-Like
-.B .IL
-and
-.BR .IR ,
-.B .IB
-with no argument indents by its last active values.
-.
-See the brief explanation of how mom handles indents for more details.
-.
-.P
-.I Note:
-Calling a
-.I tab
-(with
-.BR ".TAB <n>" )
-automatically cancels any active indents.
-.
-.P
-.I Additional note:
-Invoking
-.B .IB
-automatically turns off
-.B .IL
-and
-.BR .IR .
-.
-.RE
-.
-.
-.\" ======================================================================
-.\" IL - INDENT LEFT
-.\" ======================================================================
-.TP
-.BI "\%.IL [" " <measure> " ]
-Indent left \[em] the optional argument requires a unit of measure
-.
-.RS
-.
-.P
-.B .IL
-indents text from the left margin of the page, or if you’re in a
-.IR tab ,
-from the left edge of the
-.IR tab
-.
-Once
-.I IL
-is on, the
-.I left indent
-is applied uniformly to every subsequent line of text, even if you
-change the line length.
-.
-.P
-The first time you invoke
-.BR .IL ,
-you must give it a measure.
-.
-Subsequent invocations with a measure add to the previous measure.
-.
-A minus sign may be prepended to the argument to subtract from the
-current measure.
-.
-The
-.B \[rs]w
-inline escape may be used to specify a text-dependent measure, in
-which case no unit of measure is required.
-.
-For example,
-.RS
-.EX
-.B .IL \[rs]w'margarine'
-.EE
-.RE
-indents text by the width of the word
-.IR margarine .
-.
-.P
-With no argument,
-.B .IL
-indents by its last active value.
-.
-See the brief explanation of how
-.B mom
-handles indents for more details.
-.
-.P
-.I Note:
-Calling a
-.I tab
-(with
-.BR ".TAB <n>" )
-automatically cancels any active indents.
-.
-.P
-.I Additional note:
-Invoking
-.B .IL
-automatically turns off
-.BR IB .
-.
-.RE
-.
-.
-.\" ======================================================================
-.\" IQ - quit any/all indents
-.\" ======================================================================
-.TP
-.BI "\%.IQ [" " <measure> " ]
-IQ \[em] quit any/all indents
-.
-.RS
-.
-.P
-.I IMPORTANT NOTE:
-The original macro for quitting all indents was
-.BR .IX .
-.
-This usage has been deprecated in favour of
-.BR IQ .
-.
-.B .IX
-will continue to behave as before, but
-.B mom
-will issue a warning to
-.I stderr
-indicating that you should update your documents.
-.
-.P
-As a consequence of this change,
-.BR .ILX ,
-.B .IRX
-and
-.B .IBX
-may now also be invoked as
-.BR .ILQ ,
-.B .IRQ
-and
-.BR .IBQ .
-.
-Both forms are acceptable.
-.
-.P
-Without an argument, the macros to quit indents merely restore your
-original margins and line length.
-.
-The measures stored in the indent macros themselves are saved so you
-can call them again without having to supply a measure.
-.
-.P
-If you pass these macros the optional argument
-.BR CLEAR ,
-they not only restore your original left margin and line length, but
-also clear any values associated with a particular indent style.
-.
-The next time you need an indent of the same style, you have to supply
-a measure again.
-.
-.P
-.BR ".IQ CLEAR" ,
-as you\[aa]d suspect, quits and clears the values for all indent
-styles at once.
-.
-.RE
-.
-.
-.\" ======================================================================
-.\" IR - INDENT RIGHT
-.\" ======================================================================
-.TP
-.BI "\%.IR [" " <measure> " ]
-Indent right \[em] the optional argument requires a unit of measure
-.
-.RS
-.
-.P
-.B .IR
-indents text from the
-.I right margin
-of the page, or if you’re in a
-.IR tab ,
-from the end of the
-.IR tab .
-.
-.P
-The first time you invoke
-.BR .IR ,
-you must give it a measure.
-.
-Subsequent invocations with a measure add to the previous indent
-measure.
-.
-A
-.I minus sign
-may be prepended to the argument to subtract from the current indent
-measure.
-.
-The \[rs]w inline escape may be used to specify a text-dependent
-measure, in which case no
-.I unit of measure
-is required.
-.
-For example,
-.RS
-.EX
-.B .IR \[rs]w'jello'
-.EE
-.RE
-indents text by the width of the word
-.IR jello .
-.
-.P
-With no argument,
-.B .IR
-indents by its last active value.
-.
-See the brief explanation of how
-.B mom
-handles indents for more details.
-.
-.P
-.I Note:
-Calling a
-.I tab
-(with
-.BR "\%.TAB <n>" )
-automatically cancels any active indents.
-.
-.P
-.I Additional note:
-Invoking
-.B .IR
-automatically turns off
-.BR IB .
-.
-.RE
-.
-.
-.\" ======================================================================
-.\" Left Margin
-.\" ======================================================================
-.TP
-.BI .L_MARGIN " <left margin>"
-Left Margin
-.
-.RS
-.
-.P
-L_MARGIN establishes the distance from the left edge of the printer
-sheet at which you want your type to start.
-.
-It may be used any time, and remains in effect until you enter a new value.
-.
-.P
-Left indents and tabs are calculated from the value you pass to
-.BR .L_MARGIN ,
-hence it’s always a good idea to invoke it before starting any serious
-typesetting.
-.
-A unit of measure is required.
-.
-Decimal fractions are allowed.
-.
-Therefore, to set the left margin at 3 picas (1/2 inch), you’d enter either 
-.RS
-.EX
-.B .L_MARGIN 3P
-.EE
-.RE
-or
-.RS
-.EX
-.B .L_MARGIN .5i
-.EE
-.RE
-.
-.P
-If you use the macros
-.BR .PAGE ,
-.B .PAGEWIDTH
-or
-.B .PAPER
-without invoking
-.B .L_MARGIN
-(either before or afterwards),
-.B mom
-automatically sets
-.B .L_MARGIN
-to
-.IR "1 inch" .
-.
-.P
-Note:
-.B .L_MARGIN
-behaves in a special way when you’re using the document processing
-macros.
-.
-.RE
-.
-.
-.\" ======================================================================
-.\" MCO - BEGIN MULTI-COLUMN SETTING
-.\" ======================================================================
-.TP
-.B .MCO
-Begin multi-column setting.
-.
-.RS
-.P
-.B .MCO
-.RI ( "Multi-Column On" )
-is the
-.I macro
-you use to begin
-.IR "multi-column setting" .
-.
-It marks the current baseline as the top of your columns, for use
-later with
-.BR .MCR .
-.
-See the introduction to columns for an explanation of
-.I multi-columns
-and some sample input.
-.
-.P
-.I Note:
-Do not confuse
-.B .MCO
-with the
-.B .COLUMNS
-macro in the document processing macros.
-.
-.RE
-.
-.
-.\" ======================================================================
-.\" MCR - RETURN TO TOP OF COLUMN
-.\" ======================================================================
-.TP
-.B \%.MCR
-Once you\[aa]ve turned
-.I multi-columns
-on (with
-.BR \%.MCO ),
-.BR .MCR ,
-at any time, returns you to the
-.IR "top of your columns".
-.
-.
-.\" ======================================================================
-.\" MCX - EXIT MULTI-COLUMNS
-.\" ======================================================================
-.TP
-.BI "\%.MCX [ " "<distance to advance below longest column>" " ]"
-Optional argument requires a unit of measure.
-.
-.RS
-.
-.P
-.B .MCX
-takes you out of any
-.I tab
-you were in (by silently invoking
-.BR .TQ )
-and advances to the bottom of the longest column.
-.
-.P
-Without an argument,
-.B .MCX
-advances
-.I 1 linespace
-below the longest column.
-.
-.P
-Linespace, in this instance, is the leading in effect at the moment
-.B .MCX
-is invoked.
-.
-.P
-If you pass the
-.I <distance>
-argument to
-.BR .MCX ,
-it advances
-.I 1 linespace
-below the longest column (see above)
-.I PLUS
-the distance specified by the argument.
-.
-The argument requires a unit of measure; therefore, to advance an
-extra 6 points below where
-.B \%.MCX
-would normally place you, you’d enter
-.RS
-.EX
-.B .MCX 6p
-.EE
-.RE
-.
-.P
-.I Note:
-If you wish to advance a precise distance below the baseline of the
-longest column, use
-.B .MCX
-with an argument of
-.B 0
-(zero; no
-.I unit of measure
-required) in conjunction with the
-.B \%.ALD
-macro, like this:
-.RS
-.EX
-.B .MCX 0
-.B .ALD 24p
-.EE
-.RE
-.
-The above advances to precisely
-.I 24 points
-below the baseline of the longest column.
-.
-.RE
-.
-.
-.\" ======================================================================
-.\" Start a new Page
-.\" ======================================================================
-.TP
-.B .NEWPAGE
-.
-.RS
-.
-.P
-Whenever you want to start a new page, use
-.BR .NEWPAGE ,
-by itself with no argument.
-.
-.B Mom
-will finish up processing the current page and move you to the top of
-a new one (subject to the top margin set with
-.BR .T_MARGIN ).
-.
-.RE
-.
-.
-.\" ======================================================================
-.\" Page
-.\" ======================================================================
-.TP
-.B .PAGE " <width> [ <length> [ <lm> [ <rm> [ <tm> [ <bm> ] ] ] ] ]"
-.
-.RS
-.
-.P
-All arguments require a unit of measure
-.
-.P
-.I IMPORTANT:
-If you\[aa]re using the document processing macros,
-.B .PAGE
-must come after
-.BR .START .
-.
-Otherwise, it should go at the top of a document, prior to any text.
-.
-And remember, when you\[aa]re using the document processing macros, top
-margin and bottom margin mean something slightly different than when
-you\[aa]re using just the typesetting macros (see Top and bottom margins
-in document processing).
-.
-.P
-.B .PAGE
-lets you establish paper dimensions and page margins with a single
-macro.
-.
-The only required argument is page width.
-.
-The rest are
-optional, but they must appear in order and you can’t skip over
-any.
-.
-.IR <lm> ,
-.IR <rm> ,
-.I <tm>
-and
-.I <bm>
-refer to the left, right, top and bottom margins respectively.
-.
-.P
-Assuming your page dimensions are 11 inches by 17 inches, and that’s
-all you want to set, enter
-.RS
-.EX
-.B .PAGE 11i 17i
-.EE
-.RE
-.
-If you want to set the left margin as well, say, at 1 inch,
-.B PAGE
-would look like this: 
-.RS
-.EX
-.B .PAGE 11i 17i 1i
-.EE
-.RE
-.
-.P
-Now suppose you also want to set the top margin, say, at 1-1/2 inches.
-.
-.I <tm>
-comes after
-.I <rm>
-in the optional arguments, but you can’t skip over any arguments,
-therefore to set the top margin, you must also give a right margin.
-.
-The
-.B .PAGE
-macro would look like this: 
-.RS
-.EX
-\f[B].PAGE 11i 17i 1i 1i 1.5i
-                 |   |
-required right---+   +---top margin
-        margin\f[R]
-.EE
-.RE
-.
-.P
-Clearly,
-.B .PAGE
-is best used when you want a convenient way to tell
-.B mom
-just the dimensions of your printer sheet (width and length), or when
-you want to tell her everything about the page (dimensions and all the
-margins), for example
-.RS
-.EX
-.B .PAGE 8.5i 11i 45p 45p 45p 45p
-.EE
-.RE
-.
-This sets up an 8-1/2 by 11 inch page with margins of 45 points
-(5/8-inch) all around.
-.
-.P
-Additionally, if you invoke
-.B .PAGE
-with a top margin argument, any macros you invoke after
-.B .PAGE
-will almost certainly move the baseline of the first line of text down
-by one linespace.
-.
-To compensate, do 
-.RS
-.EX
-.B .RLD 1v
-.EE
-.RE
-immediately before entering any text, or, if it’s feasible, make
-.B .PAGE
-the last macro you invoke prior to entering text.
-.
-.P
-Please read the
-.I Important note
-on page dimensions and papersize for information on ensuring groff
-respects your
-.B .PAGE
-dimensions and margins.
-.
-.RE
-.
-.
-.\" ======================================================================
-.\" Page Length
-.\" ======================================================================
-.TP
-.BI .PAGELENGTH " <length_of_printer_sheet>"
-tells
-.B mom
-how long your printer sheet is.
-.
-It works just like
-.BR .PAGEWIDTH .
-.
-.RS
-.
-.P
-Therefore, to tell
-.B mom
-your printer sheet is 11 inches long, you enter 
-.RS
-.EX
-.B .PAGELENGTH 11i
-.EE
-.RE
-.
-Please read the important note on page dimensions and papersize for
-information on ensuring groff respects your
-.IR PAGELENGTH .
-.
-.RE
-.
-.
-.\" ======================================================================
-.\" Page Width
-.\" ======================================================================
-.TP
-.BI .PAGEWIDTH " <width_of_printer_sheet>"
-.
-.RS
-.
-.P
-The argument to
-.B .PAGEWIDTH
-is the width of your printer sheet.
-.
-.P
-.B .PAGEWIDTH
-requires a unit of measure.
-.
-Decimal fractions are allowed.
-.
-Hence, to tell
-.B mom
-that the width of your printer sheet is 8-1/2 inches, you enter
-.RS
-.EX
-.PAGEWIDTH 8.5i
-.EE
-.RE
-.
-.P
-Please read the Important note on page dimensions and papersize for
-information on ensuring groff respects your
-.IR PAGEWIDTH .
-.
-.RE
-.
-.
-.\" ======================================================================
-.\" Paper
-.\" ======================================================================
-.TP
-.BI .PAPER " <paper_type>"
-provides a convenient way to set the page dimensions for some common
-printer sheet sizes.
-.
-The argument
-.I <paper type>
-can be one of:
-.BR LETTER ,
-.BR LEGAL ,
-.BR STATEMENT ,
-.BR TABLOID ,
-.BR LEDGER ,
-.BR FOLIO ,
-.BR QUARTO ,
-.BR EXECUTIVE ,
-.BR 10x14 ,
-.BR A3 ,
-.BR A4 ,
-.BR A5 ,
-.BR B4 ,
-.BR B5 .
-.
-.
-.TP
-.B .PRINTSTYLE
-.
-.
-.\" ======================================================================
-.\" PT_SIZE - POINT SIZE OF TYPE
-.\" ======================================================================
-.TP
-.BR .PT_SIZE " <size of type in points>"
-Point size of type, does not require a
-.IR "unit of measure" .
-.
-.RS
-.
-.P
-.B \%.PT_SIZE
-.RI ( "Point Size" )
-takes one argument: the
-.I size of type
-in
-.IR points .
-.
-Unlike most other macros that establish the
-.I size
-or
-.I measure
-of something,
-.B \%.PT_SIZE
-does not require that you supply a
-.I unit of measure
-since it\[aa]s a near universal convention that
-.I type size
-is measured in
-.IR points .
-.
-Therefore, to change the
-.I type size
-to, say,
-.IR "11 points" ,
-enter
-.RS
-.EX
-.B .PT_SIZE 11
-.EE
-.RE
-.
-.I Point sizes
-may be
-.I fractional
-(eg
-.I 10.25
-or
-.IR 12.5 ).
-.
-.P
-You can prepend a
-.I plus
-or a
-.I minus sign
-to the argument to
-.BR \%.PT_SIZE ,
-in which case the
-.I point size
-will be changed by
-.I +
-or
-.I -
-the original value.
-.
-For example, if the
-.I point size
-is
-.I 12 ,
-and you want
-.I 14 ,
-you can do
-.RS
-.EX
-.B .PT_SIZE +2
-.EE
-.RE
-then later reset it to
-.I 12
-with
-.RS
-.EX
-.B .PT_SIZE -2
-.EE
-.RE
-.
-The
-.I size of type
-can also be changed inline.
-.
-.P
-.I Note:
-It is unfortunate that the
-.B \%pic
-preprocessor has already taken the name, PS, and thus
-.IR mom \[aa]s
-macro for setting
-.I point sizes
-can’t use it.
-.
-However, if you aren\[aa]t using
-.BR pic ,
-you might want to alias
-.B \%.PT_SIZE
-as
-.BR .PS ,
-since there\[aa]d be no conflict.
-.
-For example
-.RS
-.EX
-.B .ALIAS PS PT_SIZE
-.EE
-.RE
-would allow you to set
-.I point sizes
-with
-.BR .PS .
-.
-.RE
-.
-.
-.\" ======================================================================
-.\" Right Margin
-.\" ======================================================================
-.TP
-.BR .R_MARGIN " <right margin>"
-Right Margin
-.
-.RS
-.
-.P
-Requires a unit of measure.
-.
-.P
-IMPORTANT:
-.BR .R_MARGIN ,
-if used, must come after
-.BR .PAPER ,
-.BR .PAGEWIDTH ,
-.BR .L_MARGIN ,
-and/or
-.B .PAGE
-(if a right margin isn’t given to PAGE).
-.
-The reason is that
-.B .R_MARGIN
-calculates line length from the overall page dimensions and the left margin.
-.
-.P
-Obviously, it can’t make the calculation if it doesn’t know the page
-width and the left margin.
-.
-.P
-.B .R_MARGIN
-establishes the amount of space you want between the end of typeset
-lines and the right hand edge of the printer sheet.
-.
-In other words, it sets the line length.
-.B .R_MARGIN
-requires a unit of measure.
-.
-Decimal fractions are allowed.
-.
-.P
-The line length macro (LL) can be used in place of
-.BR .R_MARGIN .
-.
-In either case, the last one invoked sets the line length.
-.
-The choice of which to use is up to you.
-.
-In some instances, you may find it easier to think of a section of
-type as having a right margin.
-.
-In others, giving a line length may make more sense.
-.
-.P
-For example, if you’re setting a page of type you know should have
-6-pica margins left and right, it makes sense to enter a left and
-right margin, like this:
-.RS
-.EX
-.B .L_MARGIN 6P
-.B .R_MARGIN 6P
-.EE
-.RE
-.
-.P
-That way, you don’t have to worry about calculating the line
-length.
-.
-On the other hand, if you know the line length for a patch of type
-should be 17 picas and 3 points, entering the line length with LL is
-much easier than calculating the right margin, eg
-.RS
-.EX
-.B .LL 17P+3p
-.EE
-.RE
-.
-.P
-If you use the macros
-.BR .PAGE ,
-.B .PAGEWIDTH
-or
-.B PAPER
-without invoking
-.B .R_MARGIN
-afterwards,
-.B mom
-automatically sets
-.B .R_MARGIN
-to
-.IR "1 inch" .
-.
-If you set a line length after these macros (with
-.BR .LL ),
-the line length calculated by
-.B .R_MARGIN
-is, of course, overridden.
-.
-.P
-Note:
-.B .R_MARGIN
-behaves in a special way when you’re using the document processing
-macros.
-.
-.RE
-.
-.
-.\" ======================================================================
-.\" ST - Set String Tabs
-.\" ======================================================================
-.TP
-.FONT B .ST I " <tab number> " B "L | R | C | J [ QUAD ]"
-.
-.RS
-.P
-After
-.I string tabs
-have been marked off on an input line (see
-.BR \[rs]*[ST]\*[Ellipsis]\[rs]*[STX] ),
-you need to
-.I set
-them by giving them a direction and, optionally, the
-.B \%QUAD
-argument.
-.
-.P
-In this respect,
-.B .ST
-is like
-.B \%.TAB_SET
-except that you don\[aa]t have to give
-.B .ST
-an indent or a line length (that\[aa]s already taken care of, inline,
-by
-.BR \[rs]*[ST]...\[rs]*[STX] ).
-.
-.P
-If you want string
-.I tab 1
-to be
-.BR \%left ,
-enter
-.RS
-.EX
-.B .ST 1 L
-.EE
-.RE
-.
-If you want it to be
-.I \%left
-and
-.IR \%filled ,
-enter 
-.RS
-.EX
-.B .ST 1 L \%QUAD
-.EE
-.RE
-.
-If you want it to be justified, enter 
-.RS
-.EX
-.B .ST 1 J
-.EE
-.RE
-.
-.RE
-.
-.
-.\" ======================================================================
-.\" TAB - Call Tabs
-.\" ======================================================================
-.TP
-.BI \%.TAB " <tab number>"
-After
-.I tabs
-have been defined (either with
-.B \%.TAB_SET
-or
-.BR .ST ),
-.B \%TAB
-moves to whatever
-.I tab number
-you pass it as an argument.
-.
-.RS
-.
-.P
-For example,
-.RS
-.EX
-.B \%.TAB 3
-.EE
-.RE
-moves you to
-.I "\%tab 3" .
-.
-.P
-Note:
-.B \%.TAB
-breaks the line preceding it and advances 1 linespace.
-.
-Hence, 
-.RS
-.EX
-.B .TAB 1
-.B  A line of text in tab 1.
-.B .TAB 2
-.B  A line of text in tab 2.
-.EE
-.RE
-produces, on output 
-.RS
-.EX
-.B "A line of text in tab 1."
-.B "                             A line of text in tab 2."
-.EE
-.RE
-.
-.P
-If you want the tabs to line up, use
-.B .TN
-.RI ( "Tab Next" )
-or, more conveniently, the inline escape \[rs]*[TB+]: 
-.RS
-.EX
-\fB.TAB 1
-A line of text in tab 1.\[rs]*[TB+]
-A line of text in tab 2.
-.EE
-.RE
-which produces 
-.RS
-.EX
-.B "A line of text in tab 1.   A line of text in tab 2."
-.EE
-.RE
-.
-.P
-If the text in your tabs runs to several lines, and you want the first
-lines of each tab to align, you must use the multi-column macros.
-.
-.P
-.I Additional note:
-Any indents in effect prior to calling a tab are automatically turned
-off by
-.BR TAB .
-.
-If you were happily zipping down the page with a left indent of
-.I 2 picas
-turned on, and you call a
-.I tab
-whose indent from the left margin is
-.IR "6 picas" ,
-your new distance from the
-.I left margin
-will be
-.IR "6 picas" ,
-not
-I 6 picas plus the 2 pica
-indent.
-.
-.P
-.I \%Tabs
-are not by nature columnar, which is to say that if the text inside a
-.I tab
-runs to several lines, calling another
-.I tab
-does not automatically move to the baseline of the first line in the
-.IR "previous tab" .
-.
-To demonstrate:
-.RS
-.EX
-\f[BTAB 1
-Carrots
-Potatoes
-Broccoli
-.TAB 2
-$1.99/5 lbs
-$0.25/lb
-$0.99/bunch
-.EE
-.RE
-produces, on output 
-.RS
-.EX
-\fBCarrots
-Potatoes
-Broccoli
-            $1.99/5 lbs
-            $0.25/lb
-            $0.99/bunch
-.EE
-.RE
-.
-.RE
-.
-.\" ======================================================================
-.\" TB - Call Tabs Alias
-.\" ======================================================================
-.TP
-.BI TB " <tab number>"
-Alias to
-.B .TAB
-.
-.
-.\" ======================================================================
-.\" TI - TEMPORARY (LEFT) INDENT
-.\" ======================================================================
-.TP
-.BI "\%.TI [" " <measure> " ]
-Temporary left indent \[em] the optional argument requires a
-.I unit of measure
-.
-.RS
-.
-.P
-A temporary indent is one that applies only to the first line of text
-that comes after it.
-.
-Its chief use is indenting the first line of paragraphs.
-.RB ( Mom\[aa]s
-.B .PP
-macro, for example, uses a
-.IR "temporary indent" .)
-.
-.P
-The first time you invoke
-.BR .TI ,
-you must give it a measure.
-.
-If you want to
-.I indent
-the first line of a paragraph by, say, 2 ems, do 
-.RS
-.EX
-.B .TI 2m
-.EE
-.RE
-.
-.P
-Subsequent invocations of
-.B .TI
-do not require you to supply a measure;
-.B mom
-keeps track of the last measure you gave it.
-.
-.P
-Because
-.I temporary indents
-are temporary, there’s no need to turn them off.
-.
-.P
-.I IMPORTANT:
-Unlike
-.BR .IL ,
-.B .IR
-and
-.BR IB ,
-measures given to
-.B .TI
-are NOT additive.
-.
-In the following example, the second
-.B \%".TI 2P"
-is exactly
-.IR "2 picas" . 
-.RS
-.EX
-.B .TI 1P
-.B The beginning of a paragraph...
-.B .TI 2P
-.B The beginning of another paragraph...
-.EE
-.RE
-.
-.RE
-.
-.
-.
-.\" ======================================================================
-.\" TN - Tab Next
-.\" ======================================================================
-.TP
-.B TN
-Tab Next
-.
-.RS
-.P
-Inline escape
-.B \[rs]*[TB+]
-.
-.P
-.B TN
-moves over to the
-.I next tab
-in numeric sequence
-.RI ( "tab n+1" )
-without advancing on the page.
-.
-See the
-.I NOTE
-in the description of the
-.B \%.TAB
-macro for an example of how
-.B TN
-works.
-.
-.P
-In
-.I \%tabs
-that aren\[aa]t given the
-.B QUAD
-argument when they\[aa]re set up with
-.B \%.TAB_SET
-or
-.BR ST ,
-you must terminate the line preceding
-.B .TN
-with the
-.B \[rs]c
-inline escape.
-.
-Conversely, if you did give a
-.B QUAD
-argument to
-.B \%.TAB_SET
-or
-.BR ST ,
-the
-.B \[rs]c must not be used.
-.
-.P
-If you find remembering whether to put in the
-.B \[rs]c
-bothersome, you may prefer to use the inline escape alternative
-to
-.BR .TN ,
-.BR \[rs]*[TB+] ,
-which works consistently regardless of the fill mode.
-.
-.P
-.I Note:
-You must put text in the input line immediately after
-.BR .TN .
-.
-Stacking of
-.BR .TN \[aa]s
-is not allowed.
-.
-In other words, you cannot do 
-.RS
-.EX
-\fB.TAB 1
-Some text\[rs]c
-.TN
-Some more text\[rs]c
-.TN
-.TN
-Yet more text\fR
-.EE
-.RE
-.
-The above example, assuming
-.I tabs
-numbered from
-.I 1
-to
-.IR 4 ,
-should be entered 
-.RS
-.EX
-\fB.TAB 1
-Some text\[rs]c
-.TN
-Some more text\[rs]c
-.TN
-\[rs]&\[rs]c
-.TN
-Yet more text
-.EE
-.RE
-.
-\[rs]& is a zero-width, non-printing character that
-.I groff
-recognizes as valid input, hence meets the requirement for input text
-following
-.BR .TN .
-.
-.RE
-.
-.
-.\" ======================================================================
-.\" Tab Quit
-.\" ======================================================================
-.TP
-.B .TQ
-.B TQ
-takes you out of whatever
-.I tab
-you were in, advances
-.IR "1 linespace" ,
-and restores the
-.IR "left margin" ,
-.IR "line length" ,
-.I quad direction
-and
-.I fill mode
-that were in effect prior to invoking any
-.IR tabs .
-.
-.
-.\" ======================================================================
-.\" Top Margin
-.\" ======================================================================
-.TP
-.B .T_MARGIN " <top margin>"
-Top margin
-.
-.RS
-.
-.P
-Requires a unit of measure
-.
-.P
-.B .T_MARGIN
-establishes the distance from the top of the printer sheet at which
-you want your type to start.
-.
-It requires a unit of measure, and decimal fractions are allowed.
-.
-To set a top margin of 2-1/2 centimetres, you’d enter 
-.RS
-.EX
-.B .T_MARGIN 2.5c
-.EE
-.RE
-.
-.B .T_MARGIN
-calculates the vertical position of the first line of type on a page
-by treating the top edge of the printer sheet as a baseline.
-Therefore, 
-.RS
-.EX
-.B .T_MARGIN 1.5i
-.EE
-.RE
-puts the baseline of the first line of type 1-1/2 inches beneath the
-top of the page.
-.
-.P
-Note:
-.B .T_MARGIN
-means something slightly different when you’re using the document
-processing macros.
-.
-See Top and bottom margins in document processing for an explanation.
-.
-.P
-IMPORTANT:
-.B .T_MARGIN
-does two things: it establishes the top margin for pages that come
-after it and it moves to that position on the current page.
-.
-Therefore,
-.B .T_MARGIN
-should only be used at the top of a file (prior to entering text) or
-after NEWPAGE, like this:
-.RS
-.EX
-.B .NEWPAGE
-.B .T_MARGIN 6P
-.I <text>
-.EE
-.RE
-.
-.RE
-.
-.
-.\" --------------------------------------------------------------------
-.SH "SEE ALSO"
-.\" --------------------------------------------------------------------
-.
-.BR groff (@MAN1EXT@),
-.BR groff_mom (@MAN7EXT@),
-.
-.TP
-.B \%@HTMLDOCDIR@/\:mom/\:toc.html
-\[en] entry point to the HTML documentation
-.
-.
-.\" --------------------------------------------------------------------
-.SH "AUTHORS"
-.\" --------------------------------------------------------------------
-.
-.authors
-.
-.\" --------------------------------------------------------------------
-.SH "COPYING"
-.\" --------------------------------------------------------------------
-.
-.copyleft
-.
-.
-.\" --------------------------------------------------------------------
-.\" Emacs settings
-.\" --------------------------------------------------------------------
-.
-.\" Local Variables:
-.\" mode: nroff
-.\" End:


From MAILER-DAEMON Tue Aug 20 08:22:36 2013
Received: from list by lists.gnu.org with archive (Exim 4.71)
	id 1VBkxI-0006hX-1E
	for mharc-groff-commit@gnu.org; Tue, 20 Aug 2013 08:22:36 -0400
Received: from eggs.gnu.org ([2001:4830:134:3::10]:35057)
	by lists.gnu.org with esmtp (Exim 4.71) (envelope-from <wl@gnu.org>)
	id 1VBkx9-0006XN-CT
	for groff-commit@gnu.org; Tue, 20 Aug 2013 08:22:34 -0400
Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71)
	(envelope-from <wl@gnu.org>) id 1VBkx1-000493-C7
	for groff-commit@gnu.org; Tue, 20 Aug 2013 08:22:27 -0400
Received: from vcs.savannah.gnu.org ([140.186.70.72]:39763)
	by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from <wl@gnu.org>)
	id 1VBkx1-00048z-53
	for groff-commit@gnu.org; Tue, 20 Aug 2013 08:22:19 -0400
Received: from wl by vcs.savannah.gnu.org with local (Exim 4.72)
	(envelope-from <wl@gnu.org>) id 1VBkx0-00012i-Mo
	for groff-commit@gnu.org; Tue, 20 Aug 2013 12:22:18 +0000
Date: Tue, 20 Aug 2013 12:22:18 +0000
Message-Id: <E1VBkx0-00012i-Mo@vcs.savannah.gnu.org>
To: groff-commit@gnu.org
From: Werner LEMBERG <wl@gnu.org>
X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6.x
X-Received-From: 140.186.70.72
Subject: [Groff-commit] groff/contrib/mom groff_mom.man
X-BeenThere: groff-commit@gnu.org
X-Mailman-Version: 2.1.14
Precedence: list
List-Id: <groff-commit.gnu.org>
List-Unsubscribe: <https://lists.gnu.org/mailman/options/groff-commit>,
	<mailto:groff-commit-request@gnu.org?subject=unsubscribe>
List-Archive: <http://lists.gnu.org/archive/html/groff-commit>
List-Post: <mailto:groff-commit@gnu.org>
List-Help: <mailto:groff-commit-request@gnu.org?subject=help>
List-Subscribe: <https://lists.gnu.org/mailman/listinfo/groff-commit>,
	<mailto:groff-commit-request@gnu.org?subject=subscribe>
X-List-Received-Date: Tue, 20 Aug 2013 12:22:34 -0000

CVSROOT:	/sources/groff
Module name:	groff
Changes by:	Werner LEMBERG <wl>	13/08/20 12:22:18

Added files:
	contrib/mom    : groff_mom.man 

Log message:
	Integrate mom.7 into the man-page groff_mom.7

CVSWeb URLs:
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/mom/groff_mom.man?cvsroot=groff&rev=1.21

Patches:
Index: groff_mom.man
===================================================================
RCS file: groff_mom.man
diff -N groff_mom.man
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ groff_mom.man	20 Aug 2013 12:22:18 -0000	1.21
@@ -0,0 +1,3413 @@
+.TH GROFF_MOM @MAN7EXT@ "@MDATE@" "Groff Version @VERSION@"
+.SH NAME
+groff_mom \- groff `mom' macros , `mom' is a `roff' language, part of `groff'
+.
+.SH "SYNOPSIS"
+.\" The .SH was moved to this place in order to appease `apropos'.
+.
+.\" --------------------------------------------------------------------
+.\" Legalese
+.\" --------------------------------------------------------------------
+.
+.de authors
+.P
+.B mom
+was written by
+.MT peter@schaffter.ca
+Peter Schaffter
+.ME .
+.
+.P
+.I PDF
+support was provided by
+.MT deri@chuzzlewit.demon.co.uk
+Deri James
+.ME .
+.
+.P
+The alphabetical documentation of macros and escape seqauences in this
+man-page were written by the
+.I mom
+team.
+.
+.P
+Please send bug reports to the
+.MT bug-groff@gnu.org
+groff-bug mailing list
+.ME
+or directly to the authors.
+..
+.de copyleft
+.nh
+Copyright (C) 2002, 2003, 2005, 2008, 2009, 2011, 2012, 2013
+  Free Software Foundation, Inc.
+written by Werner Lemberg <wl@gnu.org>
+revised 2012 by Peter Schaffter <peter@schaffter.ca>
+
+Last update: 20 August 2013
+
+This file is part of groff, a free software project.
+
+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.
+
+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 Text source package.
+
+Or read the man-page gpl (1).  You can also visit
+<http://www.gnu.org/licenses/>.
+.hy
+..
+.
+.\" --------------------------------------------------------------------
+.\" Setup
+.\" --------------------------------------------------------------------
+.
+.ds Ellipsis \&.\|.\|.\&\
+.
+.
+.\" --------------------------------------------------------------------
+.\" .FONT (<font name> <text> [<font name> <text> ...])
+.\"
+.\" Print in different fonts: R, I, B, CR, CI, CB
+.\"
+.de FONT
+.  if (\\n[.$] = 0) \{\
+.	nop \&\f[P]\&
+.	return
+.  \}
+.  ds result \&
+.  while (\\n[.$] >= 2) \{\
+.	as result \,\f[\\$1]\\$2
+.	if !"\\$1"P .as result \f[P]
+.	shift 2
+.  \}
+.  if (\\n[.$] = 1) .as result \,\f[\\$1]
+.  nh
+.  nop \\*[result]\&
+.  hy
+..
+.
+.
+.do nr groff_mom_C \n[.C]
+.cp 0
+.
+.de TQ
+.br
+.ns
+.TP \\$1
+..
+.
+.
+.\" --------------------------------------------------------------------
+.\" SH SYNOPSIS
+.\" --------------------------------------------------------------------
+.
+.SY pdfmom
+.OP \-Tps "\fR[pdfroff options]"
+[groff options]
+.I files .\|.\|.
+.YS
+.
+.SY groff
+.OP \-mom
+.I files .\|.\|.
+.YS
+.
+.SY groff
+.OP "\-m mom"
+.I files .\|.\|.
+.YS
+.
+.
+.\" --------------------------------------------------------------------
+.SH CALLING MOM
+.\" --------------------------------------------------------------------
+.
+.B mom
+is a macro set for
+.BR groff ,
+designed primarily to format documents for
+.I PDF
+and
+.I PostScript
+output.
+.
+.
+.P
+.B mom
+provides two categories of macros: macros for typesetting, and
+macros for document processing.
+.
+The typesetting macros provide access to groff\[aa]s typesetting
+capabilities in ways that are simpler to master than groff\[aa]s
+primitives.
+.
+The document processing macros provide highly customizable markup
+tags that allow the user to design and output professional-looking
+documents with a minimum of typesetting intervention.
+.
+.
+.P
+Files processed with
+.BR pdfmom (@MAN1EXT@)
+with or without the
+.RI -T ps
+option, produce
+.I PDF
+documents.
+.
+The documents include a
+.I PDF
+outline that appears in the \[oq]Contents\[cq] panel of document
+viewers, and may contain clickable internal and external links.
+.
+.
+.P
+When
+.RI -T ps
+is absent,
+.B groff\[aa]s
+native
+.I PDF
+driver,
+.BR gropdf ,
+is used to generate the output.
+.
+When given, the output is still
+.IR PDF ,
+but processing is passed over to
+.BR pdfroff ,
+which uses
+.B groff\[aa]s
+PostScript driver,
+.BR grops \&.
+Not all
+.I PDF
+features are available when
+.RI -T ps
+is given; its primary use is to allow processing of files with
+embedded
+.I PostScript
+images.
+.
+.
+.P
+Files processed with
+.B groff -mom
+(or
+.BI "-m " mom
+) produce
+.I PostScript
+output by default.
+.
+.
+.P
+.B mom
+comes with her own very complete documentation in
+.I HTML
+format.
+.
+A separate
+.IR "PDF manual" ,
+.I Producing PDFs
+with groff and
+.BR mom ,
+covers full
+.B mom
+or
+.I PDF
+usage.
+.
+.
+.\" --------------------------------------------------------------------
+.SH FILES
+.\" --------------------------------------------------------------------
+.
+.TP
+.B om.tmac
+\[en] the main macro file
+.TQ
+.B mom.tmac
+\[en] a wrapper file that calls om.tmac directly.
+.
+.TP
+.B \%@HTMLDOCDIR@/\:mom/\:toc.html
+\[en] entry point to the HTML documentation
+.
+.TP
+.B \%@PDFDOCDIR@/\:mom-pdf.pdf
+\[en] the PDF manual,
+.I Producing PDFs with groff and mom
+.
+.TP
+.B @EXAMPLEDIR@/mom/*.mom
+\[en] example files using mom
+.
+.
+.\" --------------------------------------------------------------------
+.SH DOCUMENTATION IN ALPHABETICAL ORDER
+.\" --------------------------------------------------------------------
+.
+.
+This part of the man-page contains information just as in groff(7),
+.I mom macros
+and
+.I mom escape sequences
+in alphabetical order.
+.
+.
+.P
+The logical order of
+.I mom macros
+and
+.I mom escape sequences
+is very well documented in
+.
+.TP
+.B \%@HTMLDOCDIR@/\:mom/\:toc.html
+\[en] entry point to the HTML documentation
+.
+.
+.P
+That document is quite good for beginners, but other users should be
+happy to have some documentation in reference style.
+.
+.
+.P
+So we restrict this part to the alphabetical order of macros and
+escape sequences.
+.
+But, so far, we took all documentation details from the
+.I toc.html
+file, just in a more useful alphabetical order.
+.
+.
+So this part of the man-page is nothing new, but only a logical
+arrangement.
+.
+.
+.\" --------------------------------------------------------------------
+.SH "QUICK REFERENCE"
+.\" --------------------------------------------------------------------
+.
+.\" --------------------------------------------------------------------
+.SS "Quick Reference of Inline Escape Sequences in alphabetical Order"
+.\" --------------------------------------------------------------------
+.
+.TP
+.FONT B \[rs]*[ I <colorname> B ]
+begin using an initialized colour inline
+.
+.
+.TP
+.FONT B \[rs]*[BCK I " n" B ]
+move wards in a line
+.
+.
+.TP
+.BI \[rs]*[BOLDER]
+invoke pseudo bold inline (related to macro
+.BR .SETBOLDER )
+.
+.
+.TP
+.BI \[rs]*[BOLDERX]
+off pseudo bold inline (related to macro
+.BR .SETBOLDER )
+.
+.
+.TP
+.FONT B \[rs]*[BU I " n" B ]
+move characters pairs closer together inline (related to macro
+.BR \%.KERN )
+.
+.
+.TP
+.BI \[rs]*[COND]
+invoke pseudo condensing inline (related to macro
+.BR \%.CONDENSE )
+.
+.
+.TP
+.BI \[rs]*[CONDX]
+off pseudo condensing inline (related to macro
+.BR \%.CONDENSE )
+.
+.
+.TP
+.FONT B \[rs]*[CONDSUP] R \*[Ellipsis] B \[rs]*[CONDSUPX]
+pseudo-condensed superscript
+.
+.
+.TP
+.FONT B \[rs]*[DOWN I " n" B ]
+temporarily move downwards in a line
+.
+.
+.TP
+.BI \[rs]*[EN-MARK]
+mark initial line of a range of line numbers (for use with line
+numbered endnotes)
+.
+.
+.TP
+.BI \[rs]*[EXT]
+invoke pseudo extending inline (related to macro
+.BR \%.EXTEND )
+.
+.
+.TP
+.BI \[rs]*[EXTX]
+off pseudo condensing inline (related to macro
+.BR \%.EXTEND )
+.
+.
+.TP
+.FONT B \[rs]*[EXTSUP] R \*[Ellipsis] B \[rs]*[EXTSUPX]
+pseudo extrended superscript
+.
+.
+.TP
+.FONT B \[rs]*[FU I " n" B ]
+move characters pairs further apart inline (related to macro
+.BR \%.KERN )
+.
+.
+.TP
+.FONT B \[rs]*[FWD I " n" B ]
+move forward in a line
+.
+.
+.TP
+.BI \[rs]*[LEADER]
+insert leaders at the end of a line
+.
+.
+.TP
+.BI \[rs]*[RULE]
+draw a full measure rule
+.
+.
+.TP
+.FONT B \[rs]*[SIZE I " n" B ]
+change the point size inline (related to macro
+.BR \%.PT_SIZE )
+.
+.
+.TP
+.BI \[rs]*[SLANT]
+invoke pseudo italic inline (related to macro
+.BR \%.SETSLANT )
+.
+.
+.TP
+.BI \[rs]*[SLANTX]
+off pseudo italic inline (related to macro
+.BR \%.SETSLANT )
+.
+.
+.TP
+.FONT B \[rs]*[ST I <n> B ] R \*[Ellipsis] B \[rs]*[ST I <n> B X]
+string tabs (mark tab positions inline)
+.
+.
+.TP
+.FONT B \[rs]*[SUP] R \*[Ellipsis] B \[rs]*[SUPX]
+superscript
+.
+.
+.TP
+.B \[rs]*[TB+]
+Inline escape for
+.B .TN
+.RI ( "Tab Next" )
+.
+.
+.TP
+.FONT B \[rs]*[UL] R \*[Ellipsis] B \[rs]*[ULX]
+invoke underlining inline (fixed width fonts only)
+.
+.
+.TP
+.FONT B \[rs]*[UP I " n" B ]
+temporarily move upwards in a line
+.
+.
+.\" --------------------------------------------------------------------
+.SS "Quick Reference of Macros in alphabetical Order"
+.\" --------------------------------------------------------------------
+.
+.TP
+.BI .AUTOLEAD
+set the linespacing relative to the point size
+.
+.
+.TP
+.BI .B_MARGIN
+set a bottom margin
+.
+.
+.TP
+.BI .BR
+break a justified line
+.
+.
+.TP
+.BI .CENTER
+set line-by-line quad centre
+.
+.
+.TP
+.BI .CONDENSE
+set the amount to pseudo condense
+.
+.
+.TP
+.BI .EL
+break a line without advancing on the page
+.
+.
+.TP
+.BI .EXTEND
+set the amount to pseudo extend
+.
+.
+.TP
+.BI .FALLBACK_FONT
+establish a fallback font (for missing fonts)
+.
+.
+.TP
+.BI .FAM
+alias to
+.B .FAMILY
+.
+.
+.TP
+.BI .FAMILY <family>
+set the
+.I family type
+.
+.
+.TP
+.BI .FT
+set the font style (roman, italic, etc.)
+.
+.
+.TP
+.BI ".HI [" " <measure> " ]
+hanging indent
+.
+.
+.TP
+.BI .HY
+automatic hyphenation on/off
+.
+.
+.TP
+.BI .HY_SET
+set automatic hyphenation parameters
+.
+.
+.TP
+.BI ".IB [" " <left measure> <right measure> " ]
+indent both
+.
+.
+.TP
+.B .IBX [ CLEAR ]
+exit indent both
+.
+.
+.TP
+.BI ".IL [" " <measure> " ]
+indent left
+.
+.
+.TP
+.B .ILX [ CLEAR ]
+exit indent left
+.
+.
+.TP
+.B .IQ [ CLEAR ]
+quit any/all indents
+.
+.
+.TP
+.BI ".IR [" " <measure> " ]
+indent right
+.
+.
+.TP
+.B .IRX [ CLEAR ]
+exit indent right
+.
+.
+.TP
+.BI JUSTIFY
+justify text to both margins
+.
+.
+.TP
+.BI .KERN
+automatic character pair kerning on/off
+.
+.
+.TP
+.BI .L_MARGIN
+set a left margin (page offset)
+.
+.
+.TP
+.BI .LEFT
+set line-by-line quad left
+.
+.
+.TP
+.BI .LL
+set a line length
+.
+.
+.TP
+.BI .LS
+set a linespacing (leading)
+.
+.
+.TP
+.BI .PAGE
+set explicit page dimensions and margins
+.
+.
+.TP
+.BI .PAGEWIDTH
+set a custom page width
+.
+.
+.TP
+.BI .PAGELENGTH
+set a custom page length
+.
+.
+.TP
+.BI .PAPER " <paper_type>"
+set common paper sizes (letter, A4, etc)
+.
+.
+.TP
+.BI .PT_SIZE
+set the point size
+.
+.
+.TP
+.BI .QUAD
+"justify" text left, centre, or right
+.
+.
+.TP
+.BI .R_MARGIN
+set a right margin
+.
+.
+.TP
+.BI .RIGHT
+set line-by-line quad right
+.
+.
+.TP
+.BI .SETBOLDER
+set the amount of emboldening
+.
+.
+.TP
+.BI .SETSLANT
+set the degree of slant
+.
+.
+.TP
+.BI .SPREAD
+force justify a line
+.
+.
+.TP
+.BI .SS
+set the sentence space size
+.
+.
+.TP
+.BI .T_MARGIN
+set a top margin
+.
+.
+.TP
+.BI ".TI [" " <measure> " ]
+temporary left indent
+.
+.
+.TP
+.BI .WS
+set the minimum word space size
+.
+.
+.\" --------------------------------------------------------------------
+.SH "DOCUMENTATION OF DETAILS"
+.\" --------------------------------------------------------------------
+.
+.\" --------------------------------------------------------------------
+.SS "Details of Inline Escape Sequences in alphabetical Order"
+.\" --------------------------------------------------------------------
+.
+.TP
+.FONT B \[rs]*[ I <colorname> B ]
+begin using an initialized colour inline
+.
+.
+.TP
+.FONT B \[rs]*[BCK I " n" B ]
+move wards in a line
+.
+.
+.\" ======================================================================
+.\" BOLDER
+.\" ======================================================================
+.TP
+.B \[rs]*[BOLDER]
+.TQ
+.B \[rs]*[BOLDERX]
+Emboldening on/off
+.
+.RS
+.
+.P
+.B \[rs]*[BOLDER]
+begins emboldening type.
+.
+.B \[rs]*[BOLDERX]
+turns the feature off.
+.
+Both are inline escapes, therefore they should not appear as separate
+lines, but rather be embedded in text lines, like this:
+.RS
+.EX
+.FONT R "Not " B \[rs]*[BOLDER] R everything B \[rs]*[BOLDERX] R " is as it seems."
+.EE
+.RE
+.
+.P
+Alternatively, if you wanted the whole line emboldened, you should do 
+.RS
+.EX
+.FONT B \[rs]*[BOLDER] R "Not everything is as it seems." B \[rs]*[BOLDERX]
+.EE
+.RE
+.
+Once
+.B \[rs]*[BOLDER]
+is invoked, it remains in effect until turned off.
+.
+.P
+Note: If you’re using the document processing macros with
+.B PRINTSTYLE
+.BR TYPEWRITE ,
+.B mom
+ignores
+.B \[rs]*[BOLDER]
+requests.
+.
+.RE
+.
+.
+.\" ======================================================================
+.\" BU
+.\" ======================================================================
+.TP
+.FONT B \[rs]*[BU I " n" B ]
+move characters pairs closer together inline (related to macro
+.BR \%.KERN )
+.
+.
+.\" ======================================================================
+.\" COND
+.\" ======================================================================
+.TP
+.B \[rs]*[COND]
+.TQ
+.BI \[rs]*[CONDX]
+Pseudo-condensing on/off
+.
+.RS
+.
+.P
+.B \[rs]*[COND]
+begins pseudo-condensing type.
+.
+.B \[rs]*[CONDX]
+turns the feature off.
+.
+Both are inline escapes, therefore they should not appear as separate
+lines, but rather be embedded in text lines, like this:
+.RS
+.EX
+.FONT B \[rs]*[COND] I "Not everything is as it seems." B \[rs]*[CONDX]
+.EE
+.RE
+.B \%\[rs]*[COND]
+remains in effect until you turn it off with
+.BR \%\[rs]*[CONDX] .
+.
+.P
+IMPORTANT: You must turn
+.B \%\[rs]*[COND]
+off before making any changes to the point size of your type, either
+via the
+.B \%.PT_SIZE
+macro or with the
+.B \[rs]s
+inline escape.
+.
+If you wish the new point size to be pseudo-condensed, simply reinvoke
+.B \%\[rs]*[COND]
+afterwards.
+.
+Equally,
+.B \%\[rs]*[COND]
+must be turned off before changing the condense percentage with
+.BR \%.CONDENSE .
+.
+.P
+Note: If you’re using the document processing macros with
+.B \%PRINTSTYLE
+.BR \%TYPEWRITE ,
+.B mom
+ignores
+.B \%\[rs]*[COND]
+requests.
+.
+.RE
+.
+.
+.\" ======================================================================
+.\" CONDSUP
+.\" ======================================================================
+.TP
+.FONT B \[rs]*[CONDSUP] R \*[Ellipsis] B \[rs]*[CONDSUPX]
+pseudo-condensed superscript
+.
+.
+.\" ======================================================================
+.\" DOWN
+.\" ======================================================================
+.TP
+.FONT B \[rs]*[DOWN I " n" B ]
+temporarily move downwards in a line
+.
+.
+.\" ======================================================================
+.\" EN-MARK
+.\" ======================================================================
+.TP
+.BI \[rs]*[EN-MARK]
+mark initial line of a range of line numbers (for use with line
+numbered endnotes)
+.
+.
+.\" ======================================================================
+.\" EXT
+.\" ======================================================================
+.TP
+.B \[rs]*[EXT]
+.TQ
+.B \[rs]*[EXTX]
+Pseudo-extending on/off
+.
+.RS
+.
+.P
+.B \[rs]*[EXT]
+begins pseudo-extending type.
+.
+.B \[rs]*[EXTX]
+turns the feature off.
+.
+Both are inline escapes, therefore they should not appear as separate
+lines, but rather be embedded in text lines, like this:
+.RS
+.EX
+.FONT B \[rs]*[EXT] I "Not everything is as it seems." B \[rs]*[EXTX]
+.EE
+.RE
+.B \[rs]*[EXT]
+remains in effect until you turn it off with
+.BR \[rs]*[EXTX] .
+.
+.P
+IMPORTANT: You must turn
+.B \%\[rs]*[EXT]
+off before making any changes to the point size of your type, either
+via the
+.B \%.PT_SIZE
+macro or with the
+.B \[rs]s
+inline escape.
+.
+If you wish the new point size to be
+.IR \%pseudo-extended ,
+simply reinvoke
+.B \%\[rs]*[EXT]
+afterwards.
+.
+Equally,
+.B \%\[rs]*[EXT]
+must be turned off before changing the extend percentage with
+.BR \%.EXTEND .
+.
+.P
+Note: If you are using the document processing macros with
+.B \%.PRINTSTYLE
+.BR \%TYPEWRITE ,
+.B mom
+ignores
+.B \%\[rs]*[EXT]
+requests.
+.
+.RE
+.
+.
+.\" ======================================================================
+.\" EXTSUP
+.\" ======================================================================
+.TP
+.FONT B \[rs]*[EXTSUP] R \*[Ellipsis] B \[rs]*[EXTSUPX]
+pseudo extrended superscript
+.
+.
+.\" ======================================================================
+.\" FU
+.\" ======================================================================
+.TP
+.FONT B \[rs]*[FU I " n" B ]
+move characters pairs further apart inline (related to macro
+.BR .KERN )
+.
+.
+.\" ======================================================================
+.\" FWD
+.\" ======================================================================
+.TP
+.FONT B \[rs]*[FWD I " n" B ]
+move forward in a line
+.
+.
+.\" ======================================================================
+.\" LEADER
+.\" ======================================================================
+.TP
+.BI \[rs]*[LEADER]
+insert leaders at the end of a line
+.
+.
+.\" ======================================================================
+.\" RULE
+.\" ======================================================================
+.TP
+.BI \[rs]*[RULE]
+draw a full measure rule
+.
+.
+.\" ======================================================================
+.\" PT_SIZE
+.\" ======================================================================
+.TP
+.FONT B \[rs]*[SIZE I " n" B ]
+change the point size inline (related to macro
+.BR \%.PT_SIZE )
+.
+.
+.\" ======================================================================
+.\" SLANT
+.\" ======================================================================
+.TP
+.B \[rs]*[SLANT]
+.TQ
+.B \[rs]*[SLANTX]
+Pseudo italic on/off
+.
+.RS
+.
+.P
+.B \%\[rs]*[SLANT]
+begins
+.I pseudo-italicizing
+.IR type .
+.
+.B \%\[rs]*[SLANTX]
+turns the feature off.
+.
+Both are
+.I inline
+.IR escapes ,
+therefore they should not appear as separate lines, but rather be
+embedded in text lines, like this:
+.RS
+.EX
+.FONT R "Not " B \[rs]*[SLANT] R everything B \[rs]*[SLANTX] R " is as it seems."
+.EE
+.RE
+.
+.P
+Alternatively, if you wanted the whole line
+.IR pseudo-italicized ,
+you\[aa]d do
+.RS
+.EX
+.FONT B \[rs]*[SLANT] R "Not everything is as it seems." B \[rs]*[SLANTX]
+.EE
+.RE
+.
+.P
+Once
+.B \[rs]*[SLANT]
+is invoked, it remains in effect until turned off.
+.
+.P
+Note: If you’re using the document processing macros with
+.B .PRINTSTYLE
+.BR TYPEWRITE ,
+.B mom
+underlines pseudo-italics by default.
+.
+To change this behaviour, use the special macro
+.BR .SLANT_MEANS_SLANT .
+.
+.RE
+.
+.
+.\" ======================================================================
+.\" ST
+.\" ======================================================================
+.TP
+.FONT B \[rs]*[ST I <number> B ] R \*[Ellipsis] B \[rs]*[ST I <number> B X]
+Mark positions of string tabs
+.
+.RS
+.P
+The
+.I quad
+direction must be
+.B LEFT
+or
+.B \%JUSTIFY
+(see
+.B \%.QUAD
+and
+.BR \%.JUSTIFY )
+or the
+.I no-fill mode
+set to
+.B LEFT
+in order for these inlines to function properly.
+.
+Please see
+.IR \%IMPORTANT ,
+below.
+.
+.P
+String tabs need to be marked off with inline escapes before being set
+up with the
+.B .ST
+macro.
+.
+Any input line may contain string tab markers.
+.
+.IR <number> ,
+above, means the numeric identifier of the tab.
+.
+.P
+The following shows a sample input line with string tab markers. 
+.RS
+.EX
+.FONT B \[rs]*[ST1] R "Now is the time" B \[rs]*[ST1X] R " for all " B \[rs]*[ST2] R "good men" B \[rs]*ST2X] R " to come to the aid of the party."
+.EE
+.RE
+.
+.P
+String
+.I tab 1
+begins at the start of the line and ends after the word
+.IR \%time .
+.
+String
+.I tab 2
+starts at
+.I good
+and ends after
+.IR men .
+.
+.I Inline escapes
+(e.g.
+.I font
+or
+.I point size
+.IR changes ,
+or horizontal movements, including padding) are taken into account
+when
+.B mom
+determines the
+.I position
+and
+.I length
+of
+.I string
+.IR tabs .
+.
+.P
+Up to nineteen string tabs may be marked (not necessarily all on the
+same line, of course), and they must be numbered between 1 and 19.
+.
+.P
+Once string tabs have been marked in input lines, they have to be
+.I set
+with
+.BR .ST ,
+after which they may be called, by number, with
+.BR .TAB .
+.
+.P
+Note: Lines with string tabs marked off in them are normal input
+lines, i.e. they get printed, just like any input line.
+.
+If you want to set up string tabs without the line printing, use the
+.B \%.SILENT
+macro.
+.
+.P
+.I IMPORTANT:
+Owing to the way
+.B groff
+processes input lines and turns them into output lines, it is not
+possible for
+.B mom
+to
+.I guess
+the correct starting position of string tabs marked off in lines that
+are centered or set flush right.
+.
+.P
+Equally, she cannot guess the starting position if a line is fully
+justified and broken with
+.BR \%.SPREAD .
+.
+.P
+In other words, in order to use string tabs,
+.B LEFT
+must be active, or, if
+.B .QUAD LEFT
+or
+.B \%JUSTIFY
+are active, the line on which the
+.I string tabs
+are marked must be broken
+.I manually
+with
+.B .BR
+(but not
+.BR \%.SPREAD ).
+.
+.P
+To circumvent this behaviour, I recommend using the
+.B PAD
+to set up string tabs in centered or flush right lines.
+.
+Say, for example, you want to use a
+.I string tab
+to
+.I underscore
+the text of a centered line with a rule.
+.
+Rather than this,
+.RS
+.EX
+.B .CENTER
+.B \[rs]*[ST1]A line of text\[rs]*[ST1X]\[rs]c
+.B .EL
+.B .ST 1
+.B .TAB 1
+.B .PT_SIZE 24
+.B .ALD 3p
+.B \[rs]*[RULE]
+.B .RLD 3p
+.B .TQ
+.EE
+.RE
+you should do: 
+.RS
+.EX
+.B .QUAD CENTER
+.B .PAD \[rq]#\[rs]*[ST1]A line of text\[rs]*[ST1X]#\[rq]
+.B .EL
+.B .ST 1
+.B .TAB 1
+.B .PT_SIZE 24
+.B .ALD 3p
+.B \[rs]*[RULE] \[rs]\[rq] Note that you can\[aa]t use \[rs]*[UP] or \[rs]*[DOWN] with \[rs]*[RULE]
+.B .RLD 3p
+.B .TQ
+.EE
+.RE
+.
+.RE
+.
+.
+.\" ======================================================================
+.\" SUP
+.\" ======================================================================
+.TP
+.FONT B \[rs]*[SUP] R \*[Ellipsis] B \[rs]*[SUPX]
+superscript
+.
+.
+.\" ======================================================================
+.\" TB+
+.\" ======================================================================
+.TP
+.B \[rs]*[TB+]
+Inline escape for
+.B .TN
+.RI ( "Tab Next" )
+.
+.
+.\" ======================================================================
+.\" UL
+.\" ======================================================================
+.TP
+.FONT B \[rs]*[UL] R \*[Ellipsis] B \[rs]*[ULX]
+invoke underlining inline (fixed width fonts only)
+.
+.
+.\" ======================================================================
+.\" UP
+.\" ======================================================================
+.TP
+.FONT B \[rs]*[UP I " n" B ]
+temporarily move upwards in a line
+.
+.
+.\" --------------------------------------------------------------------
+.SS "Details of Macros in alphabetical Order"
+.\" --------------------------------------------------------------------
+.
+.\" ======================================================================
+.\" AUTOLEAD
+.\" ======================================================================
+.TP
+.BI .AUTOLEAD
+set the linespacing relative to the point size
+.
+.
+.\" ======================================================================
+.\" Bottom Margin
+.\" ======================================================================
+.TP
+.BI .B_MARGIN " <bottom margin>"
+Bottom Margin
+.
+.RS
+.
+.P
+Requires a unit of measure
+.
+.P
+.B .B_MARGIN
+sets a nominal position at the bottom of the page beyond which you
+don’t want your type to go.
+.
+When the bottom margin is reached,
+.B mom
+starts a new page.
+.
+.B .B_MARGIN requires a unit of measure.
+.
+Decimal fractions are allowed.
+.
+To set a nominal bottom margin of 3/4 inch, enter 
+.RS
+.EX
+.B .B_MARGIN .75i
+.EE
+.RE
+.
+.P
+Obviously, if you haven’t spaced the type on your pages so that the
+last lines fall perfectly at the bottom margin, the margin will vary
+from page to page.
+.
+Usually, but not always, the last line of type that fits on a page
+before the bottom margin causes mom to start a new page.
+.
+.P
+Occasionally, owing to a peculiarity in
+.IR groff ,
+an extra line will fall below the nominal bottom margin.
+.
+If you’re using the document processing macros, this is unlikely to
+happen; the document processing macros are very hard-nosed about
+aligning bottom margins.
+.
+.P
+Note: The meaning of
+.B .B_MARGIN
+is slightly different when you’re using the document processing
+macros.
+.
+.RE
+.
+.
+.\" ======================================================================
+.\" Fallback Font
+.\" ======================================================================
+.TP
+.BI \%.FALLBACK_FONT " <fallback font> " "[ ABORT | WARN ]"
+Fallback Font
+.
+.RS
+.
+.P
+In the event that you pass an invalid argument to
+.B \%.FAMILY
+(i.e. a non-existent
+.IR family ),
+.BR mom ,
+by default, uses the
+.IR "fallback font" ,
+.B Courier Medium Roman
+.RB ( CR ),
+in order to continue processing your file.
+.
+.P
+If you\[aa]d prefer another
+.IR "fallback font" ,
+pass
+.B \%.FALLBACK_FONT
+the full
+.I family+font name
+of the
+.I font
+you\[aa]d like.
+.
+For example, if you\[aa]d rather the
+.I fallback font
+were
+.BR "Times Roman Medium Roman" , 
+.RS
+.EX
+.B .FALLBACK_FONT TR
+.EE
+.RE
+would do the trick.
+.
+.P
+.B Mom
+issues a warning whenever a
+.I font style set
+with
+.B .FT
+does not exist, either because you haven\[aa]t registered the style
+or because the
+.I font style
+does not exist in the current
+.I family set
+with
+.BR .FAMILY .
+.
+By default,
+.B \%mom
+then aborts, which allows you to correct the problem.
+.
+.P
+If you\[aa]d prefer that
+.B \%mom
+not abort on non-existent
+.IR fonts ,
+but rather continue processing using a
+.IR "fallback font" ,
+you can pass
+.B \%.FALLBACK_FONT
+the argument
+.BR WARN ,
+either by itself, or in conjunction with your chosen
+.IB "fallback font" .
+.
+.P
+Some examples of invoking
+.BR \%.FALLBACK_FONT :
+.
+.TP
+.B .FALLBACK_FONT WARN
+.B mom
+will issue a warning whenever you try to access a non-existent
+.I font
+but will continue processing your file with the default
+.IR "fallback font" ,
+.BR "Courier Medium Roman" .
+.
+.
+.TP
+.B .FALLBACK_FONT TR WARN
+.B \%mom
+will issue a warning whenever you try to access a non-existent
+.I font
+but will continue processing your file with a
+.I fallback font
+of
+.BR "Times Roman Medium Roman" ;
+additionally,
+.B TR
+will be the
+.I fallback font
+whenever you try to access a
+.I family
+that does not exist.
+.
+.TP
+.B .FALLBACK_FONT TR ABORT 
+.B \%mom
+will abort whenever you try to access a non-existent
+.BR font ,
+and will use the
+.I fallback font
+.B TR
+whenever you try to access a
+.I family
+that does not exist.
+.
+If, for some reason, you want to revert to
+.BR ABORT ,
+just enter
+.B \%".FALLBACK_FONT ABORT"
+and
+.B mom
+will once again abort on
+.IR "font errors" .
+.
+.RE
+.
+.
+.\" ======================================================================
+.\" FAM
+.\" ======================================================================
+.TP
+.BI .FAM " <family>"
+Type Family, alias of \fB.FAMILY\fR
+.
+.
+.\" ======================================================================
+.\" FAMILY
+.\" ======================================================================
+.TP
+.BI .FAMILY " <family>"
+Type Family, alias \fB.FAM\fR
+.
+.RS
+.
+.P
+.B .FAMILY
+takes one argument: the name of the
+.I family
+you want.
+.
+.I Groff
+comes with a small set of basic families, each identified by a 1-,
+2-or 3-letter mnemonic.
+.
+The standard families are:
+.RS
+.EX
+.B A   = Avant Garde
+.B BM  = Bookman
+.B H   = Helvetica
+.B HN  = Helvetica Narrow
+.B N   = New Century Schoolbook
+.B P   = Palatino
+.B T   = Times Roman
+.B ZCM = Zapf Chancery
+.EE
+.RE
+.
+.P
+The argument you pass to
+.B .FAMILY
+is the identifier at left, above.
+.
+For example, if you want
+.BR Helvetica ,
+enter 
+.RS
+.EX
+.B .FAMILY H
+.EE
+.RE
+.
+.P
+Note: The font macro
+.RB ( .FT )
+lets you specify both the type
+.I family
+and the desired font with a single macro.
+.
+While this saves a few
+keystrokes, I recommend using
+.B .FAMILY for
+.IR family ,
+and
+.B .FT for
+.IR font ,
+except where doing so is genuinely inconvenient.
+.
+.BR ZCM ,
+for example,
+only exists in one style:
+.B Italic
+.RB ( I ).
+.
+.P
+Therefore,
+.RS
+.EX
+.B .FT ZCMI
+.EE
+.RE
+makes more sense than setting the
+.I family
+to
+.BR ZCM ,
+then setting the
+.I font
+to
+.IR I .
+.
+.P
+Additional note: If you are running a version of groff lower than
+1.19.2, you must follow all
+.B .FAMILY
+requests with a
+.B FT
+request, otherwise
+.B mom
+will set all type up to the next
+.B .FT
+request in the fallback font.
+.
+.P
+If you are running a version of groff greater than or equal to 1.19.2,
+when you invoke the
+.B .FAMILY
+macro,
+.B mom
+.I remembers
+the font style
+.BR ( Roman ,
+.BR Italic ,
+etc) currently in use (if the font style exists in the new
+.IR family ) and will continue to use the same font style in the new
+.IR family .
+For example:
+.RS
+.EX
+.BI ".FAMILY BM " "\[rs]\[rq] Bookman family"
+.BI ".FT I " "\[rs]\[rq] Medium Italic"
+.I <some text> \[rs]\[rq] Bookman Medium Italic
+.BI ".FAMILY H " "\[rs]\[rq] Helvetica family"
+.I <more text> \[rs]\[rq] Helvetica Medium Italic
+.EE
+.RE
+.
+.P
+However, if the font style does not exist in the new family,
+.B mom
+will set all subsequent type in the fallback font (by default,
+.B Courier Medium
+.BR Roman )
+until she encounters a
+.B .FT
+request that\[aa]s valid for the
+.IR family .
+.
+.P
+For example, assuming you don\[aa]t have the font
+.B Medium Condensed Roman
+.RB  ( mom
+extension
+.IR CD )
+in the
+.I Helvetica
+.IR family :
+.RS
+.EX
+.BI ".FAMILY UN " "\[rs]\[rq]Univers family"
+.BI ".FT CD " "\[rs]\[rq] Medium Condensed"
+.I <some text> \[rs]\[rq] Univers Medium Condensed
+.BI ".FAMILY H " "\[rs]\[rq] Helvetica family"
+.I <more text> \[rs]\[rq] Courier Medium Roman!
+.EE
+.RE
+.
+.P
+In the above example, you must follow
+.B .FAMILY H
+with a
+.B .FT
+request that’s valid for
+.BR Helvetica .
+.
+.P
+Please see the Appendices,
+.I Adding fonts to
+.IR groff ,
+for information on adding fonts and families to groff, as well as to
+see a list of the extensions
+.B mom
+provides to
+.IR groff \[aa]s
+basic
+.BR R ,
+.BR I ,
+.BR B ,
+.B BI
+styles.
+.
+.P
+Suggestion: When adding
+.I families to
+.IR groff ,
+I recommend following the established standard for the naming families
+and fonts.
+.
+For example, if you add the
+.B Garamond
+family, name the font files
+.RS
+.EX
+.B GARAMONDR
+.B GARAMONDI
+.B GARAMONDB
+.B GARAMONDBI
+.EE
+.RE
+.
+.B GARAMOND then becomes a valid
+.I family name
+you can pass to
+.BR .FAMILY .
+.
+(You could, of course, shorten
+.B GARAMOND
+to just
+.BR G ,
+or
+.BR GD .)
+.BR R ,
+.BR I ,
+.BR B ,
+and
+.B BI
+after
+.B GARAMOND
+are the
+.IR roman ,
+.IR italic ,
+.I bold
+and
+.I bold-italic
+fonts respectively.
+.
+.RE
+.
+.
+.\" ======================================================================
+.\" FONT
+.\" ======================================================================
+.TP
+.BI .FONT R " | " B " | " BI " | " <any other valid font style>"
+Alias to
+.B .FT
+.
+.
+.\" ======================================================================
+.\" FT
+.\" ======================================================================
+.TP
+.BI .FT R " | " B " | " BI " | " <any other valid font style>"
+Set font
+.
+.RS
+.
+.P
+By default,
+.I groff
+permits
+.B .FT
+to take one of four possible arguments specifying the desired font: 
+.RS
+.EX
+.B R = (Medium) Roman
+.B I = (Medium) Italic
+.B B = Bold (Roman)
+.B BI = Bold Italic
+.EE
+.RE
+.
+.P
+For example, if your
+.I family
+is
+.BR Helvetica ,
+entering 
+.RS
+.EX
+.B .FT B
+.EE
+.RE
+will give you the
+.I Helvetica bold
+.IR font .
+.
+If your
+.I family
+were
+.BR \%Palatino ,
+you\[aa]d get the
+.I \%Palatino bold
+.IR font .
+.
+.P
+.B Mom
+considerably extends the range of arguments you can pass to
+.BR .FT ,
+making it more convenient to add and access fonts of differing weights
+and shapes within the same family.
+.
+.P
+Have a look here for a list of the weight/style arguments
+.B mom
+allows.
+.
+Be aware, though, that you must have the fonts, correctly installed
+and named, in order to use the arguments.
+.
+(See
+.I Adding fonts to groff
+for instructions and information.)
+.
+Please also read the
+.I ADDITIONAL NOTE
+found in the description of the
+.B \%.FAMILY
+macro.
+.
+.P
+How
+.B mom
+reacts to an invalid argument to
+.B .FT
+depends on which version of groff you\[aa]re using.
+.
+If your
+.I groff version
+is greater than or equal to 1.19.2,
+.B mom
+will issue a warning and, depending on how you’ve set up the fallback
+font, either continue processing using the fallback font, or abort
+(allowing you to correct the problem). If your
+.I groff version
+is less than 1.19.2,
+.B mom
+will silently continue processing, using either the fallback font or
+the font that was in effect prior to the invalid
+.B .FT
+call.
+.
+.P
+.B .FT
+will also accept, as an argument, a full
+.I family
+and
+.I font
+.IR name .
+.
+.P
+For example, 
+.RS
+.EX
+.B .FT HB
+.EE
+.RE
+will set subsequent type in
+.I Helvetica
+.IR Bold .
+.
+.P
+However, I strongly recommend keeping
+.I family
+and
+.I font
+separate except where doing so is genuinely inconvenient.
+.
+.P
+For inline control of
+.IR fonts ,
+see
+.I Inline
+.IR Escapes ,
+font control.
+.
+.RE
+.
+.
+.\" ======================================================================
+.\" Hanging Indent
+.\" ======================================================================
+.TP
+.BI "\%.HI [" " <measure> " ]
+Hanging indent \[em] the optional argument requires a unit of measure.
+.
+.RS
+.
+.P
+A hanging indent looks like this: 
+.RS
+.EX
+\fB  The thousand injuries of Fortunato I had borne as best I
+    could, but when he ventured upon insult, I vowed
+    revenge.  You who so well know the nature of my soul
+    will not suppose, however, that I gave utterance to a
+    threat, at length I would be avenged...
+.EE
+.RE
+.
+The first line of text
+.I hangs
+outside the
+.IR "left margin" .
+.
+.P
+In order to use
+.IR "hanging indents" ,
+you must first have a
+.I left indent
+active (set with either
+.B .IL
+or
+.BR .IB ).
+.
+.B Mom
+will not hang text outside the
+.I left margin set
+with
+.B \%.L_MARGIN
+or outside the
+.I left margin
+of a
+.IR \%tab .
+.
+.P
+The first time you invoke
+.BR .HI ,
+you must give it a
+.BR measure .
+.
+If you want the first line of a paragraph to
+.IR "hang by" ,
+say,
+.IR "1 pica" ,
+do 
+.RS
+.EX
+.B .IL 1P
+.B .HI 1P
+.EE
+.RE
+.
+Subsequent invocations of
+.B \%.HI
+do not require you to supply a
+.IR measure ;
+.B mom
+keeps track of the last measure you gave it.
+.
+.P
+Generally speaking, you should invoke
+.B .HI
+immediately prior to the line you want hung (i.e. without any
+intervening control lines).
+.
+And because
+.I hanging indents
+affect only one line, there\[aa]s no need to turn them off.
+.
+.P
+.I IMPORTANT:
+Unlike
+.BR IL ,
+.B IR
+and
+.BR IB ,
+measures given to
+.B .HI
+are NOT additive.
+.
+Each time you pass a measure to
+.B .HI ,
+the measure is treated literally.
+.
+.B
+.I Recipe:
+A numbered list using
+.I hanging indents
+.
+.P
+.I Note:
+.B mom
+has macros for setting lists.
+.
+This recipe exists to demonstrate the use of
+.I hanging indents
+only.
+.RS
+.EX
+.B .PAGE 8.5i 11i 1i 1i 1i 1i
+.B .FAMILY  T
+.B .FT      R
+.B .PT_SIZE 12
+.B .LS      14
+.B .JUSTIFY
+.B .KERN
+.B .SS 0
+.B .IL \[rs]w'\[rs]0\[rs]0.'
+.B .HI \[rs]w'\[rs]0\[rs]0.'
+\fB1.\[rs]0The most important point to be considered is whether the
+answer to the meaning of Life, the Universe, and Everything
+really is 42.  We have no-one’s word on the subject except
+Mr. Adams’.
+.B .HI
+2.\[rs]0If the answer to the meaning of Life, the Universe,
+and Everything is indeed 42, what impact does this have on
+the politics of representation?  42 is, after all not a
+prime number.  Are we to infer that prime numbers don’t
+deserve equal rights and equal access in the universe?
+.B .HI
+3.\[rs]0If 42 is deemed non-exclusionary, how do we present it
+as the answer and, at the same time, forestall debate on its
+exclusionary implications?
+.EE
+.RE
+.
+.P
+First, we invoke a left indent with a measure equal to the width of 2
+figures spaces plus a period (using the \[rs]w inline escape).
+.
+At this point, the left indent is active; text afterwards would
+normally be indented.
+.
+However, we invoke a hanging indent of exactly the same width, which
+hangs the first line (and first line only!) to the left of the indent
+by the same distance (in this case, that means “out to the left
+margin”).
+.
+Because we begin the first line with a number, a period, and a figure
+space, the actual text
+.RI ( "The most important point..." )
+starts at exactly the same spot as the indented lines that follow.
+.
+.P
+Notice that subsequent invocations of
+.B .HI
+don’t require a
+.I measure
+to be given.
+.
+.P
+Paste the example above into a file and preview it with 
+.RS
+.EX
+.B pdfmom filename.mom | ps2pdf - filename.pdf
+.EE
+.RE
+to see hanging indents in action.
+.
+.RE
+.
+.
+.\" ======================================================================
+.\" IB - INDENT BOTH
+.\" ======================================================================
+.TP
+.BI "\%.IB [" " <left measure> <right measure> " ]
+Indent both \[em] the optional argument requires a unit of measure
+.
+.RS
+.
+.P
+.B .IB
+allows you to set or invoke a left and a right indent at the same time.
+.
+.P
+At its first invocation, you must supply a measure for both indents;
+at subsequent invocations when you wish to supply a measure, both must
+be given again.
+.
+As with
+.B .IL
+and
+.BR .IR ,
+the measures are added to the values previously passed to the
+macro.
+.
+Hence, if you wish to change just one of the values, you must give an
+argument of zero to the other.
+.
+.P
+.I A word of advice:
+If you need to manipulate left and right indents separately, use a
+combination of
+.B .IL
+and
+.B .IR
+instead of
+.BR .IB .
+.
+You’ll save yourself a lot of grief.
+.
+.P
+A
+.I minus sign
+may be prepended to the arguments to subtract from their current
+values.
+.
+The \[rs]w inline escape may be used to specify text-dependent
+measures, in which case no unit of measure is required.
+.
+For example,
+.RS
+.EX
+.B .IB \[rs]w\[aa]margarine\[aa] \[rs]w\[aa]jello\[aa]
+.EE
+.RE
+left indents text by the width of the word
+.I margarine
+and right indents by the width of
+.IR jello .
+.
+.P
+Like
+.B .IL
+and
+.BR .IR ,
+.B .IB
+with no argument indents by its last active values.
+.
+See the brief explanation of how mom handles indents for more details.
+.
+.P
+.I Note:
+Calling a
+.I tab
+(with
+.BR ".TAB <n>" )
+automatically cancels any active indents.
+.
+.P
+.I Additional note:
+Invoking
+.B .IB
+automatically turns off
+.B .IL
+and
+.BR .IR .
+.
+.RE
+.
+.
+.\" ======================================================================
+.\" IL - INDENT LEFT
+.\" ======================================================================
+.TP
+.BI "\%.IL [" " <measure> " ]
+Indent left \[em] the optional argument requires a unit of measure
+.
+.RS
+.
+.P
+.B .IL
+indents text from the left margin of the page, or if you’re in a
+.IR tab ,
+from the left edge of the
+.IR tab
+.
+Once
+.I IL
+is on, the
+.I left indent
+is applied uniformly to every subsequent line of text, even if you
+change the line length.
+.
+.P
+The first time you invoke
+.BR .IL ,
+you must give it a measure.
+.
+Subsequent invocations with a measure add to the previous measure.
+.
+A minus sign may be prepended to the argument to subtract from the
+current measure.
+.
+The
+.B \[rs]w
+inline escape may be used to specify a text-dependent measure, in
+which case no unit of measure is required.
+.
+For example,
+.RS
+.EX
+.B .IL \[rs]w'margarine'
+.EE
+.RE
+indents text by the width of the word
+.IR margarine .
+.
+.P
+With no argument,
+.B .IL
+indents by its last active value.
+.
+See the brief explanation of how
+.B mom
+handles indents for more details.
+.
+.P
+.I Note:
+Calling a
+.I tab
+(with
+.BR ".TAB <n>" )
+automatically cancels any active indents.
+.
+.P
+.I Additional note:
+Invoking
+.B .IL
+automatically turns off
+.BR IB .
+.
+.RE
+.
+.
+.\" ======================================================================
+.\" IQ - quit any/all indents
+.\" ======================================================================
+.TP
+.BI "\%.IQ [" " <measure> " ]
+IQ \[em] quit any/all indents
+.
+.RS
+.
+.P
+.I IMPORTANT NOTE:
+The original macro for quitting all indents was
+.BR .IX .
+.
+This usage has been deprecated in favour of
+.BR IQ .
+.
+.B .IX
+will continue to behave as before, but
+.B mom
+will issue a warning to
+.I stderr
+indicating that you should update your documents.
+.
+.P
+As a consequence of this change,
+.BR .ILX ,
+.B .IRX
+and
+.B .IBX
+may now also be invoked as
+.BR .ILQ ,
+.B .IRQ
+and
+.BR .IBQ .
+.
+Both forms are acceptable.
+.
+.P
+Without an argument, the macros to quit indents merely restore your
+original margins and line length.
+.
+The measures stored in the indent macros themselves are saved so you
+can call them again without having to supply a measure.
+.
+.P
+If you pass these macros the optional argument
+.BR CLEAR ,
+they not only restore your original left margin and line length, but
+also clear any values associated with a particular indent style.
+.
+The next time you need an indent of the same style, you have to supply
+a measure again.
+.
+.P
+.BR ".IQ CLEAR" ,
+as you\[aa]d suspect, quits and clears the values for all indent
+styles at once.
+.
+.RE
+.
+.
+.\" ======================================================================
+.\" IR - INDENT RIGHT
+.\" ======================================================================
+.TP
+.BI "\%.IR [" " <measure> " ]
+Indent right \[em] the optional argument requires a unit of measure
+.
+.RS
+.
+.P
+.B .IR
+indents text from the
+.I right margin
+of the page, or if you’re in a
+.IR tab ,
+from the end of the
+.IR tab .
+.
+.P
+The first time you invoke
+.BR .IR ,
+you must give it a measure.
+.
+Subsequent invocations with a measure add to the previous indent
+measure.
+.
+A
+.I minus sign
+may be prepended to the argument to subtract from the current indent
+measure.
+.
+The \[rs]w inline escape may be used to specify a text-dependent
+measure, in which case no
+.I unit of measure
+is required.
+.
+For example,
+.RS
+.EX
+.B .IR \[rs]w'jello'
+.EE
+.RE
+indents text by the width of the word
+.IR jello .
+.
+.P
+With no argument,
+.B .IR
+indents by its last active value.
+.
+See the brief explanation of how
+.B mom
+handles indents for more details.
+.
+.P
+.I Note:
+Calling a
+.I tab
+(with
+.BR "\%.TAB <n>" )
+automatically cancels any active indents.
+.
+.P
+.I Additional note:
+Invoking
+.B .IR
+automatically turns off
+.BR IB .
+.
+.RE
+.
+.
+.\" ======================================================================
+.\" Left Margin
+.\" ======================================================================
+.TP
+.BI .L_MARGIN " <left margin>"
+Left Margin
+.
+.RS
+.
+.P
+L_MARGIN establishes the distance from the left edge of the printer
+sheet at which you want your type to start.
+.
+It may be used any time, and remains in effect until you enter a new value.
+.
+.P
+Left indents and tabs are calculated from the value you pass to
+.BR .L_MARGIN ,
+hence it’s always a good idea to invoke it before starting any serious
+typesetting.
+.
+A unit of measure is required.
+.
+Decimal fractions are allowed.
+.
+Therefore, to set the left margin at 3 picas (1/2 inch), you’d enter either 
+.RS
+.EX
+.B .L_MARGIN 3P
+.EE
+.RE
+or
+.RS
+.EX
+.B .L_MARGIN .5i
+.EE
+.RE
+.
+.P
+If you use the macros
+.BR .PAGE ,
+.B .PAGEWIDTH
+or
+.B .PAPER
+without invoking
+.B .L_MARGIN
+(either before or afterwards),
+.B mom
+automatically sets
+.B .L_MARGIN
+to
+.IR "1 inch" .
+.
+.P
+Note:
+.B .L_MARGIN
+behaves in a special way when you’re using the document processing
+macros.
+.
+.RE
+.
+.
+.\" ======================================================================
+.\" MCO - BEGIN MULTI-COLUMN SETTING
+.\" ======================================================================
+.TP
+.B .MCO
+Begin multi-column setting.
+.
+.RS
+.P
+.B .MCO
+.RI ( "Multi-Column On" )
+is the
+.I macro
+you use to begin
+.IR "multi-column setting" .
+.
+It marks the current baseline as the top of your columns, for use
+later with
+.BR .MCR .
+.
+See the introduction to columns for an explanation of
+.I multi-columns
+and some sample input.
+.
+.P
+.I Note:
+Do not confuse
+.B .MCO
+with the
+.B .COLUMNS
+macro in the document processing macros.
+.
+.RE
+.
+.
+.\" ======================================================================
+.\" MCR - RETURN TO TOP OF COLUMN
+.\" ======================================================================
+.TP
+.B \%.MCR
+Once you\[aa]ve turned
+.I multi-columns
+on (with
+.BR \%.MCO ),
+.BR .MCR ,
+at any time, returns you to the
+.IR "top of your columns".
+.
+.
+.\" ======================================================================
+.\" MCX - EXIT MULTI-COLUMNS
+.\" ======================================================================
+.TP
+.BI "\%.MCX [ " "<distance to advance below longest column>" " ]"
+Optional argument requires a unit of measure.
+.
+.RS
+.
+.P
+.B .MCX
+takes you out of any
+.I tab
+you were in (by silently invoking
+.BR .TQ )
+and advances to the bottom of the longest column.
+.
+.P
+Without an argument,
+.B .MCX
+advances
+.I 1 linespace
+below the longest column.
+.
+.P
+Linespace, in this instance, is the leading in effect at the moment
+.B .MCX
+is invoked.
+.
+.P
+If you pass the
+.I <distance>
+argument to
+.BR .MCX ,
+it advances
+.I 1 linespace
+below the longest column (see above)
+.I PLUS
+the distance specified by the argument.
+.
+The argument requires a unit of measure; therefore, to advance an
+extra 6 points below where
+.B \%.MCX
+would normally place you, you’d enter
+.RS
+.EX
+.B .MCX 6p
+.EE
+.RE
+.
+.P
+.I Note:
+If you wish to advance a precise distance below the baseline of the
+longest column, use
+.B .MCX
+with an argument of
+.B 0
+(zero; no
+.I unit of measure
+required) in conjunction with the
+.B \%.ALD
+macro, like this:
+.RS
+.EX
+.B .MCX 0
+.B .ALD 24p
+.EE
+.RE
+.
+The above advances to precisely
+.I 24 points
+below the baseline of the longest column.
+.
+.RE
+.
+.
+.\" ======================================================================
+.\" Start a new Page
+.\" ======================================================================
+.TP
+.B .NEWPAGE
+.
+.RS
+.
+.P
+Whenever you want to start a new page, use
+.BR .NEWPAGE ,
+by itself with no argument.
+.
+.B Mom
+will finish up processing the current page and move you to the top of
+a new one (subject to the top margin set with
+.BR .T_MARGIN ).
+.
+.RE
+.
+.
+.\" ======================================================================
+.\" Page
+.\" ======================================================================
+.TP
+.B .PAGE " <width> [ <length> [ <lm> [ <rm> [ <tm> [ <bm> ] ] ] ] ]"
+.
+.RS
+.
+.P
+All arguments require a unit of measure
+.
+.P
+.I IMPORTANT:
+If you\[aa]re using the document processing macros,
+.B .PAGE
+must come after
+.BR .START .
+.
+Otherwise, it should go at the top of a document, prior to any text.
+.
+And remember, when you\[aa]re using the document processing macros, top
+margin and bottom margin mean something slightly different than when
+you\[aa]re using just the typesetting macros (see Top and bottom margins
+in document processing).
+.
+.P
+.B .PAGE
+lets you establish paper dimensions and page margins with a single
+macro.
+.
+The only required argument is page width.
+.
+The rest are
+optional, but they must appear in order and you can’t skip over
+any.
+.
+.IR <lm> ,
+.IR <rm> ,
+.I <tm>
+and
+.I <bm>
+refer to the left, right, top and bottom margins respectively.
+.
+.P
+Assuming your page dimensions are 11 inches by 17 inches, and that’s
+all you want to set, enter
+.RS
+.EX
+.B .PAGE 11i 17i
+.EE
+.RE
+.
+If you want to set the left margin as well, say, at 1 inch,
+.B PAGE
+would look like this: 
+.RS
+.EX
+.B .PAGE 11i 17i 1i
+.EE
+.RE
+.
+.P
+Now suppose you also want to set the top margin, say, at 1-1/2 inches.
+.
+.I <tm>
+comes after
+.I <rm>
+in the optional arguments, but you can’t skip over any arguments,
+therefore to set the top margin, you must also give a right margin.
+.
+The
+.B .PAGE
+macro would look like this: 
+.RS
+.EX
+\f[B].PAGE 11i 17i 1i 1i 1.5i
+                 |   |
+required right---+   +---top margin
+        margin\f[R]
+.EE
+.RE
+.
+.P
+Clearly,
+.B .PAGE
+is best used when you want a convenient way to tell
+.B mom
+just the dimensions of your printer sheet (width and length), or when
+you want to tell her everything about the page (dimensions and all the
+margins), for example
+.RS
+.EX
+.B .PAGE 8.5i 11i 45p 45p 45p 45p
+.EE
+.RE
+.
+This sets up an 8-1/2 by 11 inch page with margins of 45 points
+(5/8-inch) all around.
+.
+.P
+Additionally, if you invoke
+.B .PAGE
+with a top margin argument, any macros you invoke after
+.B .PAGE
+will almost certainly move the baseline of the first line of text down
+by one linespace.
+.
+To compensate, do 
+.RS
+.EX
+.B .RLD 1v
+.EE
+.RE
+immediately before entering any text, or, if it’s feasible, make
+.B .PAGE
+the last macro you invoke prior to entering text.
+.
+.P
+Please read the
+.I Important note
+on page dimensions and papersize for information on ensuring groff
+respects your
+.B .PAGE
+dimensions and margins.
+.
+.RE
+.
+.
+.\" ======================================================================
+.\" Page Length
+.\" ======================================================================
+.TP
+.BI .PAGELENGTH " <length_of_printer_sheet>"
+tells
+.B mom
+how long your printer sheet is.
+.
+It works just like
+.BR .PAGEWIDTH .
+.
+.RS
+.
+.P
+Therefore, to tell
+.B mom
+your printer sheet is 11 inches long, you enter 
+.RS
+.EX
+.B .PAGELENGTH 11i
+.EE
+.RE
+.
+Please read the important note on page dimensions and papersize for
+information on ensuring groff respects your
+.IR PAGELENGTH .
+.
+.RE
+.
+.
+.\" ======================================================================
+.\" Page Width
+.\" ======================================================================
+.TP
+.BI .PAGEWIDTH " <width_of_printer_sheet>"
+.
+.RS
+.
+.P
+The argument to
+.B .PAGEWIDTH
+is the width of your printer sheet.
+.
+.P
+.B .PAGEWIDTH
+requires a unit of measure.
+.
+Decimal fractions are allowed.
+.
+Hence, to tell
+.B mom
+that the width of your printer sheet is 8-1/2 inches, you enter
+.RS
+.EX
+.PAGEWIDTH 8.5i
+.EE
+.RE
+.
+.P
+Please read the Important note on page dimensions and papersize for
+information on ensuring groff respects your
+.IR PAGEWIDTH .
+.
+.RE
+.
+.
+.\" ======================================================================
+.\" Paper
+.\" ======================================================================
+.TP
+.BI .PAPER " <paper_type>"
+provides a convenient way to set the page dimensions for some common
+printer sheet sizes.
+.
+The argument
+.I <paper type>
+can be one of:
+.BR LETTER ,
+.BR LEGAL ,
+.BR STATEMENT ,
+.BR TABLOID ,
+.BR LEDGER ,
+.BR FOLIO ,
+.BR QUARTO ,
+.BR EXECUTIVE ,
+.BR 10x14 ,
+.BR A3 ,
+.BR A4 ,
+.BR A5 ,
+.BR B4 ,
+.BR B5 .
+.
+.
+.TP
+.B .PRINTSTYLE
+.
+.
+.\" ======================================================================
+.\" PT_SIZE - POINT SIZE OF TYPE
+.\" ======================================================================
+.TP
+.BR .PT_SIZE " <size of type in points>"
+Point size of type, does not require a
+.IR "unit of measure" .
+.
+.RS
+.
+.P
+.B \%.PT_SIZE
+.RI ( "Point Size" )
+takes one argument: the
+.I size of type
+in
+.IR points .
+.
+Unlike most other macros that establish the
+.I size
+or
+.I measure
+of something,
+.B \%.PT_SIZE
+does not require that you supply a
+.I unit of measure
+since it\[aa]s a near universal convention that
+.I type size
+is measured in
+.IR points .
+.
+Therefore, to change the
+.I type size
+to, say,
+.IR "11 points" ,
+enter
+.RS
+.EX
+.B .PT_SIZE 11
+.EE
+.RE
+.
+.I Point sizes
+may be
+.I fractional
+(eg
+.I 10.25
+or
+.IR 12.5 ).
+.
+.P
+You can prepend a
+.I plus
+or a
+.I minus sign
+to the argument to
+.BR \%.PT_SIZE ,
+in which case the
+.I point size
+will be changed by
+.I +
+or
+.I -
+the original value.
+.
+For example, if the
+.I point size
+is
+.I 12 ,
+and you want
+.I 14 ,
+you can do
+.RS
+.EX
+.B .PT_SIZE +2
+.EE
+.RE
+then later reset it to
+.I 12
+with
+.RS
+.EX
+.B .PT_SIZE -2
+.EE
+.RE
+.
+The
+.I size of type
+can also be changed inline.
+.
+.P
+.I Note:
+It is unfortunate that the
+.B \%pic
+preprocessor has already taken the name, PS, and thus
+.IR mom \[aa]s
+macro for setting
+.I point sizes
+can’t use it.
+.
+However, if you aren\[aa]t using
+.BR pic ,
+you might want to alias
+.B \%.PT_SIZE
+as
+.BR .PS ,
+since there\[aa]d be no conflict.
+.
+For example
+.RS
+.EX
+.B .ALIAS PS PT_SIZE
+.EE
+.RE
+would allow you to set
+.I point sizes
+with
+.BR .PS .
+.
+.RE
+.
+.
+.\" ======================================================================
+.\" Right Margin
+.\" ======================================================================
+.TP
+.BR .R_MARGIN " <right margin>"
+Right Margin
+.
+.RS
+.
+.P
+Requires a unit of measure.
+.
+.P
+IMPORTANT:
+.BR .R_MARGIN ,
+if used, must come after
+.BR .PAPER ,
+.BR .PAGEWIDTH ,
+.BR .L_MARGIN ,
+and/or
+.B .PAGE
+(if a right margin isn’t given to PAGE).
+.
+The reason is that
+.B .R_MARGIN
+calculates line length from the overall page dimensions and the left margin.
+.
+.P
+Obviously, it can’t make the calculation if it doesn’t know the page
+width and the left margin.
+.
+.P
+.B .R_MARGIN
+establishes the amount of space you want between the end of typeset
+lines and the right hand edge of the printer sheet.
+.
+In other words, it sets the line length.
+.B .R_MARGIN
+requires a unit of measure.
+.
+Decimal fractions are allowed.
+.
+.P
+The line length macro (LL) can be used in place of
+.BR .R_MARGIN .
+.
+In either case, the last one invoked sets the line length.
+.
+The choice of which to use is up to you.
+.
+In some instances, you may find it easier to think of a section of
+type as having a right margin.
+.
+In others, giving a line length may make more sense.
+.
+.P
+For example, if you’re setting a page of type you know should have
+6-pica margins left and right, it makes sense to enter a left and
+right margin, like this:
+.RS
+.EX
+.B .L_MARGIN 6P
+.B .R_MARGIN 6P
+.EE
+.RE
+.
+.P
+That way, you don’t have to worry about calculating the line
+length.
+.
+On the other hand, if you know the line length for a patch of type
+should be 17 picas and 3 points, entering the line length with LL is
+much easier than calculating the right margin, eg
+.RS
+.EX
+.B .LL 17P+3p
+.EE
+.RE
+.
+.P
+If you use the macros
+.BR .PAGE ,
+.B .PAGEWIDTH
+or
+.B PAPER
+without invoking
+.B .R_MARGIN
+afterwards,
+.B mom
+automatically sets
+.B .R_MARGIN
+to
+.IR "1 inch" .
+.
+If you set a line length after these macros (with
+.BR .LL ),
+the line length calculated by
+.B .R_MARGIN
+is, of course, overridden.
+.
+.P
+Note:
+.B .R_MARGIN
+behaves in a special way when you’re using the document processing
+macros.
+.
+.RE
+.
+.
+.\" ======================================================================
+.\" ST - Set String Tabs
+.\" ======================================================================
+.TP
+.FONT B .ST I " <tab number> " B "L | R | C | J [ QUAD ]"
+.
+.RS
+.P
+After
+.I string tabs
+have been marked off on an input line (see
+.BR \[rs]*[ST]\*[Ellipsis]\[rs]*[STX] ),
+you need to
+.I set
+them by giving them a direction and, optionally, the
+.B \%QUAD
+argument.
+.
+.P
+In this respect,
+.B .ST
+is like
+.B \%.TAB_SET
+except that you don\[aa]t have to give
+.B .ST
+an indent or a line length (that\[aa]s already taken care of, inline,
+by
+.BR \[rs]*[ST]...\[rs]*[STX] ).
+.
+.P
+If you want string
+.I tab 1
+to be
+.BR \%left ,
+enter
+.RS
+.EX
+.B .ST 1 L
+.EE
+.RE
+.
+If you want it to be
+.I \%left
+and
+.IR \%filled ,
+enter 
+.RS
+.EX
+.B .ST 1 L \%QUAD
+.EE
+.RE
+.
+If you want it to be justified, enter 
+.RS
+.EX
+.B .ST 1 J
+.EE
+.RE
+.
+.RE
+.
+.
+.\" ======================================================================
+.\" TAB - Call Tabs
+.\" ======================================================================
+.TP
+.BI \%.TAB " <tab number>"
+After
+.I tabs
+have been defined (either with
+.B \%.TAB_SET
+or
+.BR .ST ),
+.B \%TAB
+moves to whatever
+.I tab number
+you pass it as an argument.
+.
+.RS
+.
+.P
+For example,
+.RS
+.EX
+.B \%.TAB 3
+.EE
+.RE
+moves you to
+.I "\%tab 3" .
+.
+.P
+Note:
+.B \%.TAB
+breaks the line preceding it and advances 1 linespace.
+.
+Hence, 
+.RS
+.EX
+.B .TAB 1
+.B  A line of text in tab 1.
+.B .TAB 2
+.B  A line of text in tab 2.
+.EE
+.RE
+produces, on output 
+.RS
+.EX
+.B "A line of text in tab 1."
+.B "                             A line of text in tab 2."
+.EE
+.RE
+.
+.P
+If you want the tabs to line up, use
+.B .TN
+.RI ( "Tab Next" )
+or, more conveniently, the inline escape \[rs]*[TB+]: 
+.RS
+.EX
+\fB.TAB 1
+A line of text in tab 1.\[rs]*[TB+]
+A line of text in tab 2.
+.EE
+.RE
+which produces 
+.RS
+.EX
+.B "A line of text in tab 1.   A line of text in tab 2."
+.EE
+.RE
+.
+.P
+If the text in your tabs runs to several lines, and you want the first
+lines of each tab to align, you must use the multi-column macros.
+.
+.P
+.I Additional note:
+Any indents in effect prior to calling a tab are automatically turned
+off by
+.BR TAB .
+.
+If you were happily zipping down the page with a left indent of
+.I 2 picas
+turned on, and you call a
+.I tab
+whose indent from the left margin is
+.IR "6 picas" ,
+your new distance from the
+.I left margin
+will be
+.IR "6 picas" ,
+not
+I 6 picas plus the 2 pica
+indent.
+.
+.P
+.I \%Tabs
+are not by nature columnar, which is to say that if the text inside a
+.I tab
+runs to several lines, calling another
+.I tab
+does not automatically move to the baseline of the first line in the
+.IR "previous tab" .
+.
+To demonstrate:
+.RS
+.EX
+\f[BTAB 1
+Carrots
+Potatoes
+Broccoli
+.TAB 2
+$1.99/5 lbs
+$0.25/lb
+$0.99/bunch
+.EE
+.RE
+produces, on output 
+.RS
+.EX
+\fBCarrots
+Potatoes
+Broccoli
+            $1.99/5 lbs
+            $0.25/lb
+            $0.99/bunch
+.EE
+.RE
+.
+.RE
+.
+.\" ======================================================================
+.\" TB - Call Tabs Alias
+.\" ======================================================================
+.TP
+.BI .TB " <tab number>"
+Alias to
+.B .TAB
+.
+.
+.\" ======================================================================
+.\" TI - TEMPORARY (LEFT) INDENT
+.\" ======================================================================
+.TP
+.BI "\%.TI [" " <measure> " ]
+Temporary left indent \[em] the optional argument requires a
+.I unit of measure
+.
+.RS
+.
+.P
+A temporary indent is one that applies only to the first line of text
+that comes after it.
+.
+Its chief use is indenting the first line of paragraphs.
+.RB ( Mom\[aa]s
+.B .PP
+macro, for example, uses a
+.IR "temporary indent" .)
+.
+.P
+The first time you invoke
+.BR .TI ,
+you must give it a measure.
+.
+If you want to
+.I indent
+the first line of a paragraph by, say, 2 ems, do 
+.RS
+.EX
+.B .TI 2m
+.EE
+.RE
+.
+.P
+Subsequent invocations of
+.B .TI
+do not require you to supply a measure;
+.B mom
+keeps track of the last measure you gave it.
+.
+.P
+Because
+.I temporary indents
+are temporary, there’s no need to turn them off.
+.
+.P
+.I IMPORTANT:
+Unlike
+.BR .IL ,
+.B .IR
+and
+.BR IB ,
+measures given to
+.B .TI
+are NOT additive.
+.
+In the following example, the second
+.B \%".TI 2P"
+is exactly
+.IR "2 picas" . 
+.RS
+.EX
+.B .TI 1P
+.B The beginning of a paragraph...
+.B .TI 2P
+.B The beginning of another paragraph...
+.EE
+.RE
+.
+.RE
+.
+.
+.
+.\" ======================================================================
+.\" TN - Tab Next
+.\" ======================================================================
+.TP
+.B .TN
+Tab Next
+.
+.RS
+.P
+Inline escape
+.B \[rs]*[TB+]
+.
+.P
+.B TN
+moves over to the
+.I next tab
+in numeric sequence
+.RI ( "tab n+1" )
+without advancing on the page.
+.
+See the
+.I NOTE
+in the description of the
+.B \%.TAB
+macro for an example of how
+.B TN
+works.
+.
+.P
+In
+.I \%tabs
+that aren\[aa]t given the
+.B QUAD
+argument when they\[aa]re set up with
+.B \%.TAB_SET
+or
+.BR ST ,
+you must terminate the line preceding
+.B .TN
+with the
+.B \[rs]c
+inline escape.
+.
+Conversely, if you did give a
+.B QUAD
+argument to
+.B \%.TAB_SET
+or
+.BR ST ,
+the
+.B \[rs]c must not be used.
+.
+.P
+If you find remembering whether to put in the
+.B \[rs]c
+bothersome, you may prefer to use the inline escape alternative
+to
+.BR .TN ,
+.BR \[rs]*[TB+] ,
+which works consistently regardless of the fill mode.
+.
+.P
+.I Note:
+You must put text in the input line immediately after
+.BR .TN .
+.
+Stacking of
+.BR .TN \[aa]s
+is not allowed.
+.
+In other words, you cannot do 
+.RS
+.EX
+\fB.TAB 1
+Some text\[rs]c
+.TN
+Some more text\[rs]c
+.TN
+.TN
+Yet more text\fR
+.EE
+.RE
+.
+The above example, assuming
+.I tabs
+numbered from
+.I 1
+to
+.IR 4 ,
+should be entered 
+.RS
+.EX
+\fB.TAB 1
+Some text\[rs]c
+.TN
+Some more text\[rs]c
+.TN
+\[rs]&\[rs]c
+.TN
+Yet more text
+.EE
+.RE
+.
+\[rs]& is a zero-width, non-printing character that
+.I groff
+recognizes as valid input, hence meets the requirement for input text
+following
+.BR .TN .
+.
+.RE
+.
+.
+.\" ======================================================================
+.\" Tab Quit
+.\" ======================================================================
+.TP
+.B .TQ
+.B TQ
+takes you out of whatever
+.I tab
+you were in, advances
+.IR "1 linespace" ,
+and restores the
+.IR "left margin" ,
+.IR "line length" ,
+.I quad direction
+and
+.I fill mode
+that were in effect prior to invoking any
+.IR tabs .
+.
+.
+.\" ======================================================================
+.\" Top Margin
+.\" ======================================================================
+.TP
+.B .T_MARGIN " <top margin>"
+Top margin
+.
+.RS
+.
+.P
+Requires a unit of measure
+.
+.P
+.B .T_MARGIN
+establishes the distance from the top of the printer sheet at which
+you want your type to start.
+.
+It requires a unit of measure, and decimal fractions are allowed.
+.
+To set a top margin of 2-1/2 centimetres, you’d enter 
+.RS
+.EX
+.B .T_MARGIN 2.5c
+.EE
+.RE
+.
+.B .T_MARGIN
+calculates the vertical position of the first line of type on a page
+by treating the top edge of the printer sheet as a baseline.
+Therefore, 
+.RS
+.EX
+.B .T_MARGIN 1.5i
+.EE
+.RE
+puts the baseline of the first line of type 1-1/2 inches beneath the
+top of the page.
+.
+.P
+Note:
+.B .T_MARGIN
+means something slightly different when you’re using the document
+processing macros.
+.
+See Top and bottom margins in document processing for an explanation.
+.
+.P
+IMPORTANT:
+.B .T_MARGIN
+does two things: it establishes the top margin for pages that come
+after it and it moves to that position on the current page.
+.
+Therefore,
+.B .T_MARGIN
+should only be used at the top of a file (prior to entering text) or
+after NEWPAGE, like this:
+.RS
+.EX
+.B .NEWPAGE
+.B .T_MARGIN 6P
+.I <text>
+.EE
+.RE
+.
+.RE
+.
+.
+.\" --------------------------------------------------------------------
+.SH "SEE ALSO"
+.\" --------------------------------------------------------------------
+.
+.BR groff (@MAN1EXT@),
+.BR groff_mom (@MAN7EXT@),
+.
+.TP
+.B \%@HTMLDOCDIR@/\:mom/\:toc.html
+\[en] entry point to the HTML documentation
+.
+.
+.\" --------------------------------------------------------------------
+.SH "AUTHORS"
+.\" --------------------------------------------------------------------
+.
+.authors
+.
+.\" --------------------------------------------------------------------
+.SH "COPYING"
+.\" --------------------------------------------------------------------
+.
+.copyleft
+.
+.
+.cp \n[groff_mom_C]
+.
+.\" --------------------------------------------------------------------
+.\" Emacs settings
+.\" --------------------------------------------------------------------
+.
+.\" Local Variables:
+.\" mode: nroff
+.\" End:


From MAILER-DAEMON Sat Aug 24 18:28:04 2013
Received: from list by lists.gnu.org with archive (Exim 4.71)
	id 1VDMJQ-0003zY-Ql
	for mharc-groff-commit@gnu.org; Sat, 24 Aug 2013 18:28:04 -0400
Received: from eggs.gnu.org ([2001:4830:134:3::10]:48696)
	by lists.gnu.org with esmtp (Exim 4.71)
	(envelope-from <peter@schaffter.ca>) id 1VDMJO-0003zS-56
	for groff-commit@gnu.org; Sat, 24 Aug 2013 18:28:03 -0400
Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71)
	(envelope-from <peter@schaffter.ca>) id 1VDMJM-0000KB-JP
	for groff-commit@gnu.org; Sat, 24 Aug 2013 18:28:02 -0400
Received: from vcs.savannah.gnu.org ([140.186.70.72]:44607)
	by eggs.gnu.org with esmtp (Exim 4.71)
	(envelope-from <peter@schaffter.ca>) id 1VDMJM-0000J5-FX
	for groff-commit@gnu.org; Sat, 24 Aug 2013 18:28:00 -0400
Received: from PTPi by vcs.savannah.gnu.org with local (Exim 4.72)
	(envelope-from <peter@schaffter.ca>) id 1VDMJM-0005Jq-94
	for groff-commit@gnu.org; Sat, 24 Aug 2013 22:28:00 +0000
Date: Sat, 24 Aug 2013 22:28:00 +0000
Message-Id: <E1VDMJM-0005Jq-94@vcs.savannah.gnu.org>
To: groff-commit@gnu.org
From: Peter Schaffter <peter@schaffter.ca>
X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6.x
X-Received-From: 140.186.70.72
Subject: [Groff-commit] groff/contrib/mom BUGS ChangeLog om.tmac momdoc...
X-BeenThere: groff-commit@gnu.org
X-Mailman-Version: 2.1.14
Precedence: list
List-Id: <groff-commit.gnu.org>
List-Unsubscribe: <https://lists.gnu.org/mailman/options/groff-commit>,
	<mailto:groff-commit-request@gnu.org?subject=unsubscribe>
List-Archive: <http://lists.gnu.org/archive/html/groff-commit>
List-Post: <mailto:groff-commit@gnu.org>
List-Help: <mailto:groff-commit-request@gnu.org?subject=help>
List-Subscribe: <https://lists.gnu.org/mailman/listinfo/groff-commit>,
	<mailto:groff-commit-request@gnu.org?subject=subscribe>
X-List-Received-Date: Sat, 24 Aug 2013 22:28:03 -0000

CVSROOT:	/sources/groff
Module name:	groff
Changes by:	Peter Schaffter <PTPi>	13/08/24 22:28:00

Modified files:
	contrib/mom    : BUGS ChangeLog om.tmac 
	contrib/mom/momdoc: refer.html toc.html 

Log message:
	Fixed tbl bug (overprinting 1st two lines when tables span pages).
	Fixed AUTOLEAD to retain its value after START.
	Fixed PDF_IMAGE and .IL/.IR/.IB placement bug.
	Restored reserved.html to toc.html of docs.

CVSWeb URLs:
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/mom/BUGS?cvsroot=groff&r1=1.54&r2=1.55
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/mom/ChangeLog?cvsroot=groff&r1=1.81&r2=1.82
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/mom/om.tmac?cvsroot=groff&r1=1.73&r2=1.74
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/mom/momdoc/refer.html?cvsroot=groff&r1=1.17&r2=1.18
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/mom/momdoc/toc.html?cvsroot=groff&r1=1.44&r2=1.45

Patches:
Index: BUGS
===================================================================
RCS file: /sources/groff/groff/contrib/mom/BUGS,v
retrieving revision 1.54
retrieving revision 1.55
diff -u -b -r1.54 -r1.55
--- BUGS	7 Jun 2013 15:19:57 -0000	1.54
+++ BUGS	24 Aug 2013 22:27:59 -0000	1.55
@@ -22,6 +22,19 @@
 
 ====================================================================
 
+Version 2.0-a_1
+===============
+
+Tables that span pages overprinting first two lines of table on new
+pages.
+---Fixed---
+
+PDF_IMAGE not respecting .IL, .IR, or .IB.
+---Fixed---
+
+AUTOLEAD not sticking after .START.
+---Fixed---
+
 Version 2.0-a
 =============
 

Index: ChangeLog
===================================================================
RCS file: /sources/groff/groff/contrib/mom/ChangeLog,v
retrieving revision 1.81
retrieving revision 1.82
diff -u -b -r1.81 -r1.82
--- ChangeLog	20 Aug 2013 08:22:09 -0000	1.81
+++ ChangeLog	24 Aug 2013 22:27:59 -0000	1.82
@@ -1,3 +1,7 @@
+* Sat Aug 24 2013
+
+o Restored reserved.html to toc.html in docs.
+
 * Tue Aug 20 2013
 
 o Integrate mom.7 into the man-page groff_mom.7

Index: om.tmac
===================================================================
RCS file: /sources/groff/groff/contrib/mom/om.tmac,v
retrieving revision 1.73
retrieving revision 1.74
diff -u -b -r1.73 -r1.74
--- om.tmac	12 Aug 2013 04:40:11 -0000	1.73
+++ om.tmac	24 Aug 2013 22:27:59 -0000	1.74
@@ -5840,6 +5840,10 @@
 .    \}
 .\" This diversion is to get a value for #FN_AUTOLEAD
 .    di NULL
+.       if \\n[#AUTO_LEAD] \{\
+.          nr #RESTORE_AUTO_LEAD 1
+.          nr #SAVED_AUTOLEAD_VALUE \\n[#AUTOLEAD_VALUE]
+.       \}
 .       ev NULL
 .       if \\n[#PRINT_STYLE]=1 \{\
 .          ps \\*[$TYPEWRITER_PS]
@@ -5854,6 +5858,10 @@
 .       if \\n[#PRINT_STYLE]=2 .LS \\n[#DOC_LEAD]u
 .       ev
 .    di
+.    if \\n[#RESTORE_AUTO_LEAD] \{\
+.       nr #AUTO_LEAD 1
+.       nr #AUTOLEAD_VALUE  \\n[#SAVED_AUTOLEAD_VALUE]
+.    \}
 .    ie !\\n[#COLLATE] \{\
 .\" DOC_LEAD adjusted (or not) here
 .       TRAPS
@@ -7279,7 +7287,12 @@
 .       nr #PP 0
 .    \}
 .    el \{\
+.       if \\n[#AUTO_LEAD] .nr #RESTORE_AUTO_LEAD 1
 .       if \\n[#PRINT_STYLE]=2 .LS \\n[#DOC_LEAD]u\\*[$DOCHEADER_LEAD_ADJ]
+.       if \\n[#RESTORE_AUTO_LEAD] \{\
+.          nr #AUTO_LEAD 1
+.          nr #AUTOLEAD_VALUE  \\n[#SAVED_AUTOLEAD_VALUE]
+.       \}
 .       nr #DOCHEADER_LEAD \\n[#LEAD]
 .\" Default doctype
 .       if \\n[#DOC_TYPE]=1 \{\
@@ -7464,7 +7477,9 @@
 .          \}
 .       \}
 .    \}
+.    if \\n[#AUTO_LEAD] .nr #RESTORE_AUTO_LEAD 1
 .    LS \\n[#DOC_LEAD]u
+.    if \\n[#RESTORE_AUTO_LEAD] .nr #AUTO_LEAD 1
 .    if \\n[#ADJ_DOC_LEAD]=1 \{\
 .       ie !r#ADVANCE_FROM_TOP \{\
 .          if \\n[#DOC_HEADER]=1 .SHIM
@@ -9372,6 +9387,10 @@
 .       rm float-adj:top
 .       rm float-adj:bottom
 .    \}
+.    if \\n[#TABLE] \{\
+.       rs
+.       sp
+.    \}
 .END
 \#
 \# ====================================================================
@@ -15795,6 +15814,7 @@
 \# Boxed tables don't play nice with vertical spacing.
 \# Compensation is applied in FLOAT.
 .MAC TS END
+.    nr #TABLE 1
 .    if '\\n[.z]'FLOAT*DIV' \{\
 .       if '\\$1'BOXED' \{\
 .          if !\\n[.d] .nr boxed-table 1
@@ -15804,6 +15824,7 @@
 .
 .MAC TE END
 .    if '\\n[.z]'FLOAT*DIV' .nr bx-tbl-depth \\n[.d]
+.    rr #TABLE
 .END
 \#
 \# FLOAT
@@ -18386,16 +18407,12 @@
 .    substring pos:tmp 0 0
 .    ie !'\\*[pos:tmp]'-' .ds pdf-img:pos -C
 .    el \{\
-.       ie '\\$1'-I' \{\
-.          shift
-.          ds pdf-img:ind \\$1
-.          ds pdf-img:pos -L
-.          shift
-.       \}
-.       el \{\
 .          ds pdf-img:pos \\$1
 .          shift
 .       \}
+.    if '\\*[pdf-img:pos]'-I' \{\
+.       nr pdf-img:ind \\$1
+.       shift
 .    \}
 .    ds pdf-img:file \\$1
 .    ds pdf-img@file \\$1
@@ -18440,10 +18457,20 @@
 .       ds pdf-img:adj    0
 .       ds pdf-img:bottom +
 .    \}
+.    if '\\*[pdf-img:pos]'-C' \{\
+.       nr pdf-img:ind (\\n[.ll]-\\n[pdf-img:width])/2
+.       if \\n[.in] .nr pdf-img:ind -(\\n[.in]/2)
+.    \}
+.    if '\\*[pdf-img:pos]'-R' \{\
+.       nr pdf-img:ind \\n[.ll]-\\n[pdf-img:width]
+.       if \\n[.in] .nr pdf-img:ind -\\n[.in]
+.    \}
 .    di PDF*IMAGE
 .    nf
-.    if d pdf-img:ind .ti \\*[pdf-img:ind]
-.    nop \X'pdf: pdfpic \\*[pdf-img:file] \\*[pdf-img:pos] \\n[pdf-img:width]z \\n[pdf-img:depth]z \\n[.ll]z'
+.    in 0
+.    if r pdf-img:ind .ti \\n[pdf-img:ind]u
+.    nop \X'pdf: pdfpic \\*[pdf-img:file] -L \\n[pdf-img:width]z \\n[pdf-img:depth]z'
+.    in
 .    di
 .    nr dn +\\n[pdf-img:depth]-1v
 .    nr pdf-img 1

Index: momdoc/refer.html
===================================================================
RCS file: /sources/groff/groff/contrib/mom/momdoc/refer.html,v
retrieving revision 1.17
retrieving revision 1.18
diff -u -b -r1.17 -r1.18
--- momdoc/refer.html	12 Aug 2013 04:40:11 -0000	1.17
+++ momdoc/refer.html	24 Aug 2013 22:27:59 -0000	1.18
@@ -656,7 +656,7 @@
   .], \fIChronicles\fP 168)
   A new sentence...
 </span>
-will produce &#8220;<span style="font-family: times; font-size: 105%; font-weight: bold">&#8220;...aluminum roaches and iron crickets.&#8221; (Bradbury, <i>Chronicles</i> 168) A new sentence...&#8221;</span>&#8221;.
+will produce &#8220;<span style="font-family: times; font-size: 105%; font-weight: bold">&#8220;...aluminum roaches and iron crickets.&#8221; (Bradbury, <i>Chronicles</i> 168) A new sentence...</span>&#8221;.
 </p>
 
 <div class="examples-container" style="margin-top: 1.5em; margin-bottom: 1.5em;">

Index: momdoc/toc.html
===================================================================
RCS file: /sources/groff/groff/contrib/mom/momdoc/toc.html,v
retrieving revision 1.44
retrieving revision 1.45
diff -u -b -r1.44 -r1.45
--- momdoc/toc.html	12 Aug 2013 04:55:42 -0000	1.44
+++ momdoc/toc.html	24 Aug 2013 22:27:59 -0000	1.45
@@ -403,12 +403,13 @@
       <h3 id="quick" class="toc highlight"><a style="color: #6e70cc" href="macrolist.html#top">6. QUICK REFERENCE GUIDE</a></h3>
       <h3 id="appendices" class="toc" style="margin-top: .5em;"><a style="color: #6e70cc" href="appendices.html#top">7. APPENDICES</a></h3>
       <ul class="toc">
-      <li><a href="appendices.html#fonts">7.2 Adding fonts to groff</a>
+      <li><a href="appendices.html#fonts">7.1 Adding fonts to groff</a>
         <ul>
-          <li><a href="appendices.html#steps">7.2.1 Step-by-step instructions</a></li>
+          <li><a href="appendices.html#steps">7.1.1 Step-by-step instructions</a></li>
       </ul></li>
-      <li><a href="appendices.html#codenotes">7.3 Some reflections on mom</a></li>
-      <li><a href="appendices.html#contact">7.5 Contact the author</a></li>
+      <li><a href="appendices.html#codenotes">7.2 Some reflections on mom</a></li>
+      <li><a href="reserved.html">7.3 List of reserved words (macros, registers, strings)</a></li>
+      <li><a href="appendices.html#contact">7.4 Contact the author</a></li>
     </ul>
   </div>
 


From MAILER-DAEMON Mon Aug 26 12:49:39 2013
Received: from list by lists.gnu.org with archive (Exim 4.71)
	id 1VDzz1-0006OZ-FN
	for mharc-groff-commit@gnu.org; Mon, 26 Aug 2013 12:49:39 -0400
Received: from eggs.gnu.org ([2001:4830:134:3::10]:56213)
	by lists.gnu.org with esmtp (Exim 4.71)
	(envelope-from <peter@schaffter.ca>) id 1VDzyv-0006BM-EP
	for groff-commit@gnu.org; Mon, 26 Aug 2013 12:49:38 -0400
Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71)
	(envelope-from <peter@schaffter.ca>) id 1VDzyt-0006Lg-Bz
	for groff-commit@gnu.org; Mon, 26 Aug 2013 12:49:33 -0400
Received: from vcs.savannah.gnu.org ([140.186.70.72]:40852)
	by eggs.gnu.org with esmtp (Exim 4.71)
	(envelope-from <peter@schaffter.ca>) id 1VDzyt-0006Lc-9N
	for groff-commit@gnu.org; Mon, 26 Aug 2013 12:49:31 -0400
Received: from PTPi by vcs.savannah.gnu.org with local (Exim 4.72)
	(envelope-from <peter@schaffter.ca>) id 1VDzys-0004Ec-Or
	for groff-commit@gnu.org; Mon, 26 Aug 2013 16:49:30 +0000
Date: Mon, 26 Aug 2013 16:49:30 +0000
Message-Id: <E1VDzys-0004Ec-Or@vcs.savannah.gnu.org>
To: groff-commit@gnu.org
From: Peter Schaffter <peter@schaffter.ca>
X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6.x
X-Received-From: 140.186.70.72
Subject: [Groff-commit] groff/contrib/mom/momdoc typesetting.html
X-BeenThere: groff-commit@gnu.org
X-Mailman-Version: 2.1.14
Precedence: list
List-Id: <groff-commit.gnu.org>
List-Unsubscribe: <https://lists.gnu.org/mailman/options/groff-commit>,
	<mailto:groff-commit-request@gnu.org?subject=unsubscribe>
List-Archive: <http://lists.gnu.org/archive/html/groff-commit>
List-Post: <mailto:groff-commit@gnu.org>
List-Help: <mailto:groff-commit-request@gnu.org?subject=help>
List-Subscribe: <https://lists.gnu.org/mailman/listinfo/groff-commit>,
	<mailto:groff-commit-request@gnu.org?subject=subscribe>
X-List-Received-Date: Mon, 26 Aug 2013 16:49:38 -0000

CVSROOT:	/sources/groff
Module name:	groff
Changes by:	Peter Schaffter <PTPi>	13/08/26 16:49:30

Modified files:
	contrib/mom/momdoc: typesetting.html 

Log message:
	Doc fix.

CVSWeb URLs:
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/mom/momdoc/typesetting.html?cvsroot=groff&r1=1.31&r2=1.32

Patches:
Index: typesetting.html
===================================================================
RCS file: /sources/groff/groff/contrib/mom/momdoc/typesetting.html,v
retrieving revision 1.31
retrieving revision 1.32
diff -u -b -r1.31 -r1.32
--- typesetting.html	29 Jan 2013 05:02:46 -0000	1.31
+++ typesetting.html	26 Aug 2013 16:49:30 -0000	1.32
@@ -637,7 +637,7 @@
 <span class="important">IMPORTANT:</span> If you&#8217;re using the
 <a href="docprocessing.html#docprocessing">document processing macros</a>,
 PAGE must come after
-<a href="docprocessing.html#start">START</a>.
+<a href="docprocessing.html#printstyle">PRINTSTYLE</a>.
 Otherwise, it should go at the top of a document, prior to any
 text.  And remember, when you&#8217;re using the document processing
 macros, top margin and bottom margin mean something slightly


