README
1The `groffer' program is the easiest way to read documents written in
2some `roff' language, such as the `man pages', the manual pages in
3many operating systems.
4
5All input is sent to `grog' and then to `groff' such that no special
6`groff' arguments must be determined, but all `groff' options can be
7specified.
8
9`groffer' also has many built-in `man' functionalities to find and
10read the manual pages on UNIX and similar operating systems. It
11accepts the information from an installed `man' program, but tries to
12find a man path by itself.
13
14So far, `groffer' is a shell script. It should run on any POSIX or
15Bourne style shell.
16
17For reporting bugs of `groffer', groff's free mailing list
18<bug-groff@gnu.org> can be used. For a general discussion, the
19mailing list <groff@gnu.org> is more useful; see the `README' file in
20the top directory of the `groff' source package for more details on
21these mailing lists.
22
23
24####### License
25
26Copyright (C) 2003,2004 Free Software Foundation, Inc.
27Written by Bernd Warken
28
29This file is part of groffer, which is part of groff.
30
31groff is free software; you can redistribute it and/or modify it
32under the terms of the GNU General Public License as published by
33the Free Software Foundation; either version 2, or (at your option)
34any later version.
35
36groff is distributed in the hope that it will be useful, but WITHOUT
37ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
38or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public
39License for more details.
40
41You should have received a copy of the GNU General Public License
42along with groff; see the files COPYING and LICENSE in the top
43directory of the groff source. If not, write to the Free Software
44Foundation, 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
45
README_SH
1Description of groffer.sh, the shell version of groffer
2
3Display groff files and man pages on X or tty, even when compressed.
4
5
6Usage
7
8Input comes from either standard input or command line parameters that
9represent names of exisiting roff files or standardized specifications
10for searching man pages. All of these can be compressed in a format
11that is decompressible by `gzip', including `.gz', `bz2', and `.Z'.
12
13The following displaying modes are available:
14- Display formatted input with the X roff viewer `gxditview',
15- with a Prostcript viewer,
16- with a dvi viewer,
17- with a web browser.
18- Display formatted input in plain text mode.
19- Run a pager on the formatted input in a text terminal (tty).
20- Generate output for some groff device on stdout without a viewer.
21- Output only the source code without any groff processing.
22- Generate the troff intermediate output on standard output
23 without groff postprocessing.
24By default, the program tries to display with `gxditview' as graphical
25device, `tty' mode with a pager is tried as text display.
26
27
28Several File Arguments
29
30So far, `groffer' bundles all filespec parameters into a single output
31file in the same way as `groff'. The disadvantage of this is that all
32file name arguments must have the same groff language.
33
34To change this, the option parsing must be revised for large parts.
35It seems that this would create incompatibilities, so the actual
36option strategy is kept.
37
38
39Error Handling
40
41Error handling and exit behavior is complicated by the fact that
42`exit' can only escape from the current shell; trouble occurs in
43subshells. This was solved by sending kill signals, see $_PROCESS_ID
44and error().
45
46
47Shell Compatibility
48
49This shell script is compatible to the both the GNU and the POSIX
50shell and utilities. Care was taken to restrict the programming
51technics used here in order to achieve POSIX compatibility as far back
52as POSIX P1003.2 Draft 11.2 of September 1991.
53
54The only non-builtin used here is POSIX `sed'. This script was tested
55under `bash', `ash', and `ksh'. The speed under `ash' is more than
56double when compared to the larger shells. The new version of `ash'
57taken from `dash' produces strange errors, so the automatic call of
58`ash' was removed.
59
60This script provides its own option parser. It is compatible to the
61usual GNU style command line (option clusters, long options, mixing of
62options and non-option file names), except that it is not possible to
63abbreviate long option names.
64
65The flexible mixing of options and file names in GNU style is always
66possible, even if the environment variable `$POSIXLY_CORRECT' is set
67to a non-empty value. This disables the rather wicked POSIX behavior
68to terminate option parsing when the first non-option command line
69argument is found.
70
71
72Survey of Functions defined in groffer.sh
73
74The elements specified within paranthesis `(<>)' give hints to what
75the arguments are meant to be; the argument names are irrelevant.
76<>? 0 or 1
77<>* arbitrarily many such arguments, incl. none
78<>+ one or more such arguments
79<> exactly 1
80
81A function that starts with an underscore `_' is an internal function
82for some function. The internal functions are defined just after
83their corresponding function; they are not mentioned in the following.
84
85abort (text>*)
86base_name (path)
87catz (<file>)
88clean_up ()
89diag (text>*)
90dirname_append (<path> [<dir...>])
91dirname_chop (<path>)
92do_filearg (<filearg>)
93do_nothing ()
94echo2 (<text>*)
95echo2n (<text>*)
96error (<text>*)
97get_first_essential (<arg>*)
98is_dir (<name>)
99is_empty (<string>)
100is_equal (<string1> <string2>)
101is_file (<name>)
102is_non_empty_file (<name>)
103is_not_dir (<name>)
104is_not_empty (<string>)
105is_not_equal (<string1> <string2>)
106is_not_file (<name>)
107is_not_prog (<name>)
108is_not_writable (<name>)
109is_not_yes (<string>)
110is_prog (<name>)
111is_yes (<string>)
112leave ()
113landmark (<text>)
114list_append (<list> <element>...)
115list_from_cmdline (<pre_name_of_opt_lists> [<cmdline_arg>...])
116list_from_split (<string> <separator>)
117list_get (<list>)
118list_has (<list> <element>)
119list_has_not (<list> <element>)
120main_*(), see after the functions
121man_do_filespec (<filespec>)
122man_setup ()
123man_register_file (<file> [<name> [<section>]])
124man_search_section (<name> <section>)
125man_set()
126manpath_add_lang(<path> <language>)
127manpath_add_system()
128manpath_from_path ()
129normalize_args (<shortopts> <longopts> <arg>*)
130path_chop (<path>)
131path_clean (<path>)
132path_contains (<path> <dir>)
133path_not_contains (<path> <dir>)
134path_split (<path>)
135register_file (<filename>)
136register_title (<filespec>)
137res (<var_name> <function_name> <arg>...)
138reset ()
139save_stdin ()
140string_contains (<string> <part>)
141string_not_contains (<string> <part>)
142tmp_cat ()
143tmp_create (<suffix>?)
144to_tmp (<filename>)
145trap_clean ()
146trap_set (<functionname>)
147usage ()
148version ()
149warning (<string>)
150whatis (<filename>)
151where (<program>)
152
153
154External non-groffer Environment Variables
155
156If these variables are exported in the script the `ash' shell coughs
157when calling `groff' in `main_display()'.
158
159external system environment variables that are explicitly used
160$DISPLAY: Presets the X display.
161$LANG: For language specific man pages.
162$LC_ALL: For language specific man pages.
163$LC_MESSAGES: For language specific man pages.
164$PAGER: Paging program for tty mode.
165$PATH: Path for the programs called (: list).
166
167groffer native environment variables
168$GROFFER_OPT preset options for groffer.
169
170all groff environment variables are used, see groff(1)
171$GROFF_BIN_PATH: Path for all groff programs.
172$GROFF_COMMAND_PREFIX: '' (normally) or 'g' (several troffs).
173$GROFF_FONT_PATH: Path to non-default groff fonts.
174$GROFF_TMAC_PATH: Path to non-default groff macro files.
175$GROFF_TMPDIR: Directory for groff temporary files.
176$GROFF_TYPESETTER: Preset default device.
177
178all GNU man environment variables are used, see man(1).
179$MANOPT: Preset options for man pages.
180$MANPATH: Search path for man pages (: list).
181$MANROFFSEQ: Ignored because of grog guessing.
182$MANSECT: Search man pages only in sections (:).
183$SYSTEM: Man pages for different OS's (, list).
184
185
186Object-oriented Functions
187
188The groffer script provides an object-oriented construction (OOP). In
189object-oriented terminology, a type of object is called a `class'; a
190function that handles objects from a class is named `method'.
191
192In the groffer script, the object is a variable name whose content is
193the object's data. Methods are functions that have an object as first
194argument.
195
196The basic functions for object handling are obj_*().
197
198The class `list' represents an array structure, see list_*().
199
200
201####### License
202
203Copyright (C) 2003,2004 Free Software Foundation, Inc.
204Written by Bernd Warken
205
206This file is part of groffer, which is part of groff.
207
208groff is free software; you can redistribute it and/or modify it
209under the terms of the GNU General Public License as published by
210the Free Software Foundation; either version 2, or (at your option)
211any later version.
212
213groff is distributed in the hope that it will be useful, but WITHOUT
214ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
215or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public
216License for more details.
217
218You should have received a copy of the GNU General Public License
219along with groff; see the files COPYING and LICENSE in the top
220directory of the groff source. If not, write to the Free Software
221Foundation, 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
222