jimzah/freebsd-src
1
0
Fork 0
mirror of https://github.com/freebsd/freebsd-src.git synced 2024-11-28 13:22:48 +00:00
Code Issues Actions 1 Packages Projects Releases Wiki Activity

Virgin import of FSF groff v1.19.2

Browse Source
This commit is contained in:
Ruslan Ermilov 2005-10-20 10:45:19 +00:00
parent bc33253bf8
commit 22e7cbb874
Notes: svn2git 2020-12-20 02:59:44 +00:00 
svn path=/vendor/groff/dist/; revision=151497
525 changed files with 148612 additions and 67090 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

13
contrib/groff/COPYING
View File

@ -1,8 +1,8 @@
GNU GENERAL PUBLIC LICENSE
Version 2, June 1991
Copyright (C) 1989, 1990, 1991, 1992 Free Software Foundation, Inc.
59 Temple Place - Suite 330, Boston, MA 02111-1307, USA
Copyright (C) 1989, 1991 Free Software Foundation, Inc.
51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.
@ -279,7 +279,7 @@ POSSIBILITY OF SUCH DAMAGES.
END OF TERMS AND CONDITIONS
Appendix: How to Apply These Terms to Your New Programs
How to Apply These Terms to Your New Programs
If you develop a new program, and you want it to be of the greatest
possible use to the public, the best way to achieve this is to make it
@ -291,7 +291,7 @@ convey the exclusion of warranty; and each file should have at least
the "copyright" line and a pointer to where the full notice is found.
<one line to give the program's name and a brief idea of what it does.>
Copyright (C) 19yy <name of author>
Copyright (C) <year> <name of author>
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
@ -305,14 +305,15 @@ the "copyright" line and a pointer to where the full notice is found.
You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
Also add information on how to contact you by electronic and paper mail.
If the program is interactive, make it output a short notice like this
when it starts in an interactive mode:
Gnomovision version 69, Copyright (C) 19yy name of author
Gnomovision version 69, Copyright (C) year name of author
Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
This is free software, and you are welcome to redistribute it
under certain conditions; type `show c' for details.

17027
contrib/groff/ChangeLog
View File

File diff suppressed because it is too large Load Diff

6147
contrib/groff/ChangeLog.115 Normal file
View File

File diff suppressed because it is too large Load Diff

1388
contrib/groff/ChangeLog.116 Normal file
View File

File diff suppressed because it is too large Load Diff

2190
contrib/groff/ChangeLog.117 Normal file
View File

File diff suppressed because it is too large Load Diff

3794
contrib/groff/ChangeLog.118 Normal file
View File

File diff suppressed because it is too large Load Diff

211
contrib/groff/FDL
View File

@ -1,8 +1,9 @@
GNU Free Documentation License
Version 1.1, March 2000
Version 1.2, November 2002
Copyright (C) 2000 Free Software Foundation, Inc.
59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
Copyright (C) 2000,2001,2002 Free Software Foundation, Inc.
51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.
@ -10,12 +11,12 @@
0. PREAMBLE
The purpose of this License is to make a manual, textbook, or other
written document "free" in the sense of freedom: to assure everyone
the effective freedom to copy and redistribute it, with or without
modifying it, either commercially or noncommercially. Secondarily,
this License preserves for the author and publisher a way to get
credit for their work, while not being considered responsible for
modifications made by others.
functional and useful document "free" in the sense of freedom: to
assure everyone the effective freedom to copy and redistribute it,
with or without modifying it, either commercially or noncommercially.
Secondarily, this License preserves for the author and publisher a way
to get credit for their work, while not being considered responsible
for modifications made by others.
This License is a kind of "copyleft", which means that derivative
works of the document must themselves be free in the same sense. It
@ -33,11 +34,15 @@ principally for works whose purpose is instruction or reference.
1. APPLICABILITY AND DEFINITIONS
This License applies to any manual or other work that contains a
notice placed by the copyright holder saying it can be distributed
under the terms of this License. The "Document", below, refers to any
such manual or work. Any member of the public is a licensee, and is
addressed as "you".
This License applies to any manual or other work, in any medium, that
contains a notice placed by the copyright holder saying it can be
distributed under the terms of this License. Such a notice grants a
world-wide, royalty-free license, unlimited in duration, to use that
work under the conditions stated herein. The "Document", below,
refers to any such manual or work. Any member of the public is a
licensee, and is addressed as "you". You accept the license if you
copy, modify or distribute the work in a way requiring permission
under copyright law.
A "Modified Version" of the Document means any work containing the
Document or a portion of it, either copied verbatim, or with
@ -47,7 +52,7 @@ A "Secondary Section" is a named appendix or a front-matter section of
the Document that deals exclusively with the relationship of the
publishers or authors of the Document to the Document's overall subject
(or to related matters) and contains nothing that could fall directly
within that overall subject. (For example, if the Document is in part a
within that overall subject. (Thus, if the Document is in part a
textbook of mathematics, a Secondary Section may not explain any
mathematics.) The relationship could be a matter of historical
connection with the subject or with related matters, or of legal,
@ -56,33 +61,40 @@ them.
The "Invariant Sections" are certain Secondary Sections whose titles
are designated, as being those of Invariant Sections, in the notice
that says that the Document is released under this License.
that says that the Document is released under this License. If a
section does not fit the above definition of Secondary then it is not
allowed to be designated as Invariant. The Document may contain zero
Invariant Sections. If the Document does not identify any Invariant
Sections then there are none.
The "Cover Texts" are certain short passages of text that are listed,
as Front-Cover Texts or Back-Cover Texts, in the notice that says that
the Document is released under this License.
the Document is released under this License. A Front-Cover Text may
be at most 5 words, and a Back-Cover Text may be at most 25 words.
A "Transparent" copy of the Document means a machine-readable copy,
represented in a format whose specification is available to the
general public, whose contents can be viewed and edited directly and
general public, that is suitable for revising the document
straightforwardly with generic text editors or (for images composed of
pixels) generic paint programs or (for drawings) some widely available
drawing editor, and that is suitable for input to text formatters or
for automatic translation to a variety of formats suitable for input
to text formatters. A copy made in an otherwise Transparent file
format whose markup has been designed to thwart or discourage
subsequent modification by readers is not Transparent. A copy that is
not "Transparent" is called "Opaque".
format whose markup, or absence of markup, has been arranged to thwart
or discourage subsequent modification by readers is not Transparent.
An image format is not Transparent if used for any substantial amount
of text. A copy that is not "Transparent" is called "Opaque".
Examples of suitable formats for Transparent copies include plain
ASCII without markup, Texinfo input format, LaTeX input format, SGML
or XML using a publicly available DTD, and standard-conforming simple
HTML designed for human modification. Opaque formats include
PostScript, PDF, proprietary formats that can be read and edited only
by proprietary word processors, SGML or XML for which the DTD and/or
HTML, PostScript or PDF designed for human modification. Examples of
transparent image formats include PNG, XCF and JPG. Opaque formats
include proprietary formats that can be read and edited only by
proprietary word processors, SGML or XML for which the DTD and/or
processing tools are not generally available, and the
machine-generated HTML produced by some word processors for output
purposes only.
machine-generated HTML, PostScript or PDF produced by some word
processors for output purposes only.
The "Title Page" means, for a printed book, the title page itself,
plus such following pages as are needed to hold, legibly, the material
@ -91,6 +103,21 @@ formats which do not have any title page as such, "Title Page" means
the text near the most prominent appearance of the work's title,
preceding the beginning of the body of the text.
A section "Entitled XYZ" means a named subunit of the Document whose
title either is precisely XYZ or contains XYZ in parentheses following
text that translates XYZ in another language. (Here XYZ stands for a
specific section name mentioned below, such as "Acknowledgements",
"Dedications", "Endorsements", or "History".) To "Preserve the Title"
of such a section when you modify the Document means that it remains a
section "Entitled XYZ" according to this definition.
The Document may include Warranty Disclaimers next to the notice which
states that this License applies to the Document. These Warranty
Disclaimers are considered to be included by reference in this
License, but only as regards disclaiming warranties: any other
implication that these Warranty Disclaimers may have is void and has
no effect on the meaning of this License.
2. VERBATIM COPYING
@ -110,9 +137,10 @@ you may publicly display copies.
3. COPYING IN QUANTITY
If you publish printed copies of the Document numbering more than 100,
and the Document's license notice requires Cover Texts, you must enclose
the copies in covers that carry, clearly and legibly, all these Cover
If you publish printed copies (or copies in media that commonly have
printed covers) of the Document, numbering more than 100, and the
Document's license notice requires Cover Texts, you must enclose the
copies in covers that carry, clearly and legibly, all these Cover
Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
the back cover. Both covers must also clearly and legibly identify
you as the publisher of these copies. The front cover must present
@ -130,16 +158,15 @@ pages.
If you publish or distribute Opaque copies of the Document numbering
more than 100, you must either include a machine-readable Transparent
copy along with each Opaque copy, or state in or with each Opaque copy
a publicly-accessible computer-network location containing a complete
Transparent copy of the Document, free of added material, which the
general network-using public has access to download anonymously at no
charge using public-standard network protocols. If you use the latter
option, you must take reasonably prudent steps, when you begin
distribution of Opaque copies in quantity, to ensure that this
Transparent copy will remain thus accessible at the stated location
until at least one year after the last time you distribute an Opaque
copy (directly or through your agents or retailers) of that edition to
the public.
a computer-network location from which the general network-using
public has access to download using public-standard network protocols
a complete Transparent copy of the Document, free of added material.
If you use the latter option, you must take reasonably prudent steps,
when you begin distribution of Opaque copies in quantity, to ensure
that this Transparent copy will remain thus accessible at the stated
location until at least one year after the last time you distribute an
Opaque copy (directly or through your agents or retailers) of that
edition to the public.
It is requested, but not required, that you contact the authors of the
Document well before redistributing any large number of copies, to give
@ -163,7 +190,8 @@ A. Use in the Title Page (and on the covers, if any) a title distinct
B. List on the Title Page, as authors, one or more persons or entities
responsible for authorship of the modifications in the Modified
Version, together with at least five of the principal authors of the
Document (all of its principal authors, if it has less than five).
Document (all of its principal authors, if it has fewer than five),
unless they release you from this requirement.
C. State on the Title page the name of the publisher of the
Modified Version, as the publisher.
D. Preserve all the copyright notices of the Document.
@ -175,10 +203,10 @@ F. Include, immediately after the copyright notices, a license notice
G. Preserve in that license notice the full lists of Invariant Sections
and required Cover Texts given in the Document's license notice.
H. Include an unaltered copy of this License.
I. Preserve the section entitled "History", and its title, and add to
it an item stating at least the title, year, new authors, and
I. Preserve the section Entitled "History", Preserve its Title, and add
to it an item stating at least the title, year, new authors, and
publisher of the Modified Version as given on the Title Page. If
there is no section entitled "History" in the Document, create one
there is no section Entitled "History" in the Document, create one
stating the title, year, authors, and publisher of the Document as
given on its Title Page, then add an item describing the Modified
Version as stated in the previous sentence.
@ -189,17 +217,18 @@ J. Preserve the network location, if any, given in the Document for
You may omit a network location for a work that was published at
least four years before the Document itself, or if the original
publisher of the version it refers to gives permission.
K. In any section entitled "Acknowledgements" or "Dedications",
preserve the section's title, and preserve in the section all the
substance and tone of each of the contributor acknowledgements
K. For any section Entitled "Acknowledgements" or "Dedications",
Preserve the Title of the section, and preserve in the section all
the substance and tone of each of the contributor acknowledgements
and/or dedications given therein.
L. Preserve all the Invariant Sections of the Document,
unaltered in their text and in their titles. Section numbers
or the equivalent are not considered part of the section titles.
M. Delete any section entitled "Endorsements". Such a section
M. Delete any section Entitled "Endorsements". Such a section
may not be included in the Modified Version.
N. Do not retitle any existing section as "Endorsements"
N. Do not retitle any existing section to be Entitled "Endorsements"
or to conflict in title with any Invariant Section.
O. Preserve any Warranty Disclaimers.
If the Modified Version includes new front-matter sections or
appendices that qualify as Secondary Sections and contain no material
@ -208,7 +237,7 @@ of these sections as invariant. To do this, add their titles to the
list of Invariant Sections in the Modified Version's license notice.
These titles must be distinct from any other section titles.
You may add a section entitled "Endorsements", provided it contains
You may add a section Entitled "Endorsements", provided it contains
nothing but endorsements of your Modified Version by various
parties--for example, statements of peer review or that the text has
been approved by an organization as the authoritative definition of a
@ -236,7 +265,7 @@ License, under the terms defined in section 4 above for modified
versions, provided that you include in the combination all of the
Invariant Sections of all of the original documents, unmodified, and
list them all as Invariant Sections of your combined work in its
license notice.
license notice, and that you preserve all their Warranty Disclaimers.
The combined work need only contain one copy of this License, and
multiple identical Invariant Sections may be replaced with a single
@ -247,11 +276,11 @@ author or publisher of that section if known, or else a unique number.
Make the same adjustment to the section titles in the list of
Invariant Sections in the license notice of the combined work.
In the combination, you must combine any sections entitled "History"
in the various original documents, forming one section entitled
"History"; likewise combine any sections entitled "Acknowledgements",
and any sections entitled "Dedications". You must delete all sections
entitled "Endorsements."
In the combination, you must combine any sections Entitled "History"
in the various original documents, forming one section Entitled
"History"; likewise combine any sections Entitled "Acknowledgements",
and any sections Entitled "Dedications". You must delete all sections
Entitled "Endorsements".
6. COLLECTIONS OF DOCUMENTS
@ -268,23 +297,24 @@ License into the extracted document, and follow this License in all
other respects regarding verbatim copying of that document.
7. AGGREGATION WITH INDEPENDENT WORKS
A compilation of the Document or its derivatives with other separate
and independent documents or works, in or on a volume of a storage or
distribution medium, does not as a whole count as a Modified Version
of the Document, provided no compilation copyright is claimed for the
compilation. Such a compilation is called an "aggregate", and this
License does not apply to the other self-contained works thus compiled
with the Document, on account of their being thus compiled, if they
are not themselves derivative works of the Document.
distribution medium, is called an "aggregate" if the copyright
resulting from the compilation is not used to limit the legal rights
of the compilation's users beyond what the individual works permit.
When the Document is included in an aggregate, this License does not
apply to the other works in the aggregate which are not themselves
derivative works of the Document.
If the Cover Text requirement of section 3 is applicable to these
copies of the Document, then if the Document is less than one quarter
of the entire aggregate, the Document's Cover Texts may be placed on
covers that surround only the Document within the aggregate.
Otherwise they must appear on covers around the whole aggregate.
copies of the Document, then if the Document is less than one half of
the entire aggregate, the Document's Cover Texts may be placed on
covers that bracket the Document within the aggregate, or the
electronic equivalent of covers if the Document is in electronic form.
Otherwise they must appear on printed covers that bracket the whole
aggregate.
8. TRANSLATION
@ -295,10 +325,17 @@ Replacing Invariant Sections with translations requires special
permission from their copyright holders, but you may include
translations of some or all Invariant Sections in addition to the
original versions of these Invariant Sections. You may include a
translation of this License provided that you also include the
original English version of this License. In case of a disagreement
between the translation and the original English version of this
License, the original English version will prevail.
translation of this License, and all the license notices in the
Document, and any Warranty Disclaimers, provided that you also include
the original English version of this License and the original versions
of those notices and disclaimers. In case of a disagreement between
the translation and the original version of this License or a notice
or disclaimer, the original version will prevail.
If a section in the Document is Entitled "Acknowledgements",
"Dedications", or "History", the requirement (section 4) to Preserve
its Title (section 1) will typically require changing the actual
title.
9. TERMINATION
@ -317,8 +354,8 @@ parties remain in full compliance.
The Free Software Foundation may publish new, revised versions
of the GNU Free Documentation License from time to time. Such new
versions will be similar in spirit to the present version, but may
differ in detail to address new problems or concerns. See
http:///www.gnu.org/copyleft/.
differ in detail to address new problems or concerns. See
http://www.gnu.org/copyleft/.
Each version of the License is given a distinguishing version number.
If the Document specifies that a particular numbered version of this
@ -336,23 +373,25 @@ To use this License in a document you have written, include a copy of
the License in the document and put the following copyright and
license notices just after the title page:
Copyright (c) YEAR YOUR NAME.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1
or any later version published by the Free Software Foundation;
with the Invariant Sections being LIST THEIR TITLES, with the
Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.
A copy of the license is included in the section entitled "GNU
Free Documentation License".
Copyright (c) YEAR YOUR NAME.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.2
or any later version published by the Free Software Foundation;
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
A copy of the license is included in the section entitled "GNU
Free Documentation License".
If you have no Invariant Sections, write "with no Invariant Sections"
instead of saying which ones are invariant. If you have no
Front-Cover Texts, write "no Front-Cover Texts" instead of
"Front-Cover Texts being LIST"; likewise for Back-Cover Texts.
If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts,
replace the "with...Texts." line with this:
with the Invariant Sections being LIST THEIR TITLES, with the
Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.
If you have Invariant Sections without Cover Texts, or some other
combination of the three, merge those two alternatives to suit the
situation.
If your document contains nontrivial examples of program code, we
recommend releasing these examples in parallel under your choice of
free software license, such as the GNU General Public License,
to permit their use in free software.

22
contrib/groff/INSTALL
View File

@ -5,6 +5,9 @@ This file contains information that supplements those instructions.
(For instructions how to build groff with DJGPP tools for MS-DOS and
MS-Windows, see the file arch/djgpp/README.)
(For instructions how to build groff with the MinGW tools for
MS-Windows, see the file README.MinGW.)
groff is written in C++, so you will need a C++ compiler. The C++
source files use a suffix of `.cpp', so your C++ compiler must be able
to handle this. If you don't already have a C++ compiler, I suggest
@ -25,26 +28,23 @@ an incorrect guess, say
PAGE=xxx ./configure
where `xxx' should be either `A4' or `letter'. Note that this will only
affect the paper selection for grops. For compatibility with ditroff,
the default page length in gtroff is always 11 inches. The page length
can be changed with the `pl' request.
affect the paper selection of some device drivers like grops (which can
be still overridden on the command line). For compatibility with
ditroff, the default page length in gtroff is always 11 inches. The
page length can be changed with the `pl' request.
When you have built groff, you can use the test-groff script to try
groff out on one of the man pages. (Use the .n files not the .man
files.) The test-groff script sets up environment variables to allow
groff to run without being installed. The current directory must be
the build directory when the script is run. For example, you could do
groff to run without being installed. For example, you could do
./test-groff -man -Tascii src/roff/groff/groff.n | less
If you want to compile and install gxditview (an X11 previewer),
follow the instructions in the INSTALL file in the src/xditview
subdirectory.
To get a DVI, PDF, or HTML version of the groff texinfo manual, say `make
groff.dvi', `make groff.pdf', or `make groff.html', respectively, in the
`doc' subdirectory (after compiling the groff package). Note that you
need texinfo version 4.3 or newer as a prerequisite.
`doc' subdirectory (after configuring the groff package). Note that you
need texinfo version 4.6 as a prerequisite. Neither older versions nor
texinfo 4.7 (due to a bug) will work.
If you have problems, read the PROBLEMS file. If this doesn't help
send a bug report using the form in the file BUG-REPORT.

87
contrib/groff/INSTALL.gen
View File

@ -1,7 +1,16 @@
Installation Instructions
*************************
Copyright (C) 1994, 1995, 1996, 1999, 2000, 2001, 2002, 2004 Free
Software Foundation, Inc.
This file is free documentation; the Free Software Foundation gives
unlimited permission to copy, distribute and modify it.
Basic Installation
==================
These are generic installation instructions.
These are generic installation instructions.
The `configure' shell script attempts to guess correct values for
various system-dependent variables used during compilation. It uses
@ -61,21 +70,22 @@ The simplest way to compile this package is:
Compilers and Options
=====================
Some systems require unusual options for compilation or linking that
the `configure' script does not know about. Run `./configure --help'
for details on some of the pertinent environment variables.
Some systems require unusual options for compilation or linking that the
`configure' script does not know about. Run `./configure --help' for
details on some of the pertinent environment variables.
You can give `configure' initial values for variables by setting
them in the environment. You can do that on the command line like this:
You can give `configure' initial values for configuration parameters
by setting variables in the command line or in the environment. Here
is an example:
./configure CC=c89 CFLAGS=-O2 LIBS=-lposix
*Note Environment Variables::, for more details.
*Note Defining Variables::, for more details.
Compiling For Multiple Architectures
====================================
You can compile the package for more than one kind of computer at the
You can compile the package for more than one kind of computer at the
same time, by placing the object files for each architecture in their
own directory. To do this, you must use a version of `make' that
supports the `VPATH' variable, such as GNU `make'. `cd' to the
@ -84,27 +94,27 @@ the `configure' script. `configure' automatically checks for the
source code in the directory that `configure' is in and in `..'.
If you have to use a `make' that does not support the `VPATH'
variable, you have to compile the package for one architecture at a time
in the source code directory. After you have installed the package for
one architecture, use `make distclean' before reconfiguring for another
architecture.
variable, you have to compile the package for one architecture at a
time in the source code directory. After you have installed the
package for one architecture, use `make distclean' before reconfiguring
for another architecture.
Installation Names
==================
By default, `make install' will install the package's files in
By default, `make install' will install the package's files in
`/usr/local/bin', `/usr/local/man', etc. You can specify an
installation prefix other than `/usr/local' by giving `configure' the
option `--prefix=PATH'.
option `--prefix=PREFIX'.
You can specify separate installation prefixes for
architecture-specific files and architecture-independent files. If you
give `configure' the option `--exec-prefix=PATH', the package will use
PATH as the prefix for installing programs and libraries.
give `configure' the option `--exec-prefix=PREFIX', the package will
use PREFIX as the prefix for installing programs and libraries.
Documentation and other data files will still use the regular prefix.
In addition, if you use an unusual directory layout you can give
options like `--bindir=PATH' to specify different values for particular
options like `--bindir=DIR' to specify different values for particular
kinds of files. Run `configure --help' for a list of the directories
you can set and what kinds of files go in them.
@ -115,7 +125,7 @@ option `--program-prefix=PREFIX' or `--program-suffix=SUFFIX'.
Optional Features
=================
Some packages pay attention to `--enable-FEATURE' options to
Some packages pay attention to `--enable-FEATURE' options to
`configure', where FEATURE indicates an optional part of the package.
They may also pay attention to `--with-PACKAGE' options, where PACKAGE
is something like `gnu-as' or `x' (for the X Window System). The
@ -130,10 +140,11 @@ you can use the `configure' options `--x-includes=DIR' and
Specifying the System Type
==========================
There may be some features `configure' cannot figure out
automatically, but needs to determine by the type of host the package
will run on. Usually `configure' can figure that out, but if it prints
a message saying it cannot guess the host type, give it the
There may be some features `configure' cannot figure out automatically,
but needs to determine by the type of machine the package will run on.
Usually, assuming the package is built to be run on the _same_
architectures, `configure' can figure that out, but if it prints a
message saying it cannot guess the machine type, give it the
`--build=TYPE' option. TYPE can either be a short name for the system
type, such as `sun4', or a canonical name which has the form:
@ -141,42 +152,37 @@ type, such as `sun4', or a canonical name which has the form:
where SYSTEM can have one of these forms:
OS
KERNEL-OS
OS KERNEL-OS
See the file `config.sub' for the possible values of each field. If
`config.sub' isn't included in this package, then this package doesn't
need to know the host type.
need to know the machine type.
If you are _building_ compiler tools for cross-compiling, you should
use the `--target=TYPE' option to select the type of system they will
produce code for.
If you want to _use_ a cross compiler, that generates code for a
platform different from the build platform, you should specify the host
platform (i.e., that on which the generated programs will eventually be
run) with `--host=TYPE'. In this case, you should also specify the
build platform with `--build=TYPE', because, in this case, it may not
be possible to guess the build platform (it sometimes involves
compiling and running simple test programs, and this can't be done if
the compiler is a cross compiler).
platform different from the build platform, you should specify the
"host" platform (i.e., that on which the generated programs will
eventually be run) with `--host=TYPE'.
Sharing Defaults
================
If you want to set default values for `configure' scripts to share,
you can create a site shell script called `config.site' that gives
default values for variables like `CC', `cache_file', and `prefix'.
If you want to set default values for `configure' scripts to share, you
can create a site shell script called `config.site' that gives default
values for variables like `CC', `cache_file', and `prefix'.
`configure' looks for `PREFIX/share/config.site' if it exists, then
`PREFIX/etc/config.site' if it exists. Or, you can set the
`CONFIG_SITE' environment variable to the location of the site script.
A warning: not all `configure' scripts look for a site script.
Environment Variables
=====================
Defining Variables
==================
Variables not defined in a site shell script can be set in the
environment passed to configure. However, some packages may run
Variables not defined in a site shell script can be set in the
environment passed to `configure'. However, some packages may run
configure again during the build, and the customized values of these
variables may be lost. In order to avoid this problem, you should set
them in the `configure' command line, using `VAR=value'. For example:
@ -189,8 +195,7 @@ overridden in the site shell script).
`configure' Invocation
======================
`configure' recognizes the following options to control how it
operates.
`configure' recognizes the following options to control how it operates.
`--help'
`-h'

21
contrib/groff/LICENSE Normal file
View File

@ -0,0 +1,21 @@
LICENSE
The groff program is a free software project. It is licensed under
the GNU General Public License (GNU GPL), version 2 or later.
The file COPYING in the top directory of the groff source package
contains a copy of the GPL that was downloaded from the GNU web site
http://www.gnu.org/copyleft/gpl.txt at 1 dec 2003.
All files of the groff source package are licensed under this version
of the GPL (or licenses which are compatible with the GPL).
You are free to choose version 2 or any subsequent version of the GPL.
The GPL names an address where you can get the actual version by
normal post. Further information is found in the internet at
http://www.gnu.org/copyleft.
The groff program is a GNU package, and the copyright of all files of
the groff source package which are under the GPL has been assigned to
the Free Sofware Foundation (FSF). Information on GNU and FSF is
found at http://www.fsf.org/.

19
contrib/groff/MANIFEST
View File

@ -1,10 +1,10 @@
MANIFEST
Last update: 13 Apr 2003
Last update: 26 May 2005
This file is part of groff, the GNU roff type-setting system.
Copyright (C) 2001, 2003 Free Software Foundation, Inc.
Copyright (C) 2001, 2003, 2004, 2005 Free Software Foundation, Inc.
written by Bernd Warken <bwarken@mayn.de>
maintained by Werner Lemberg <wl@gnu.org>
@ -31,13 +31,14 @@ the groff source distribution.
FDL The Free Documentation License (FDL).
INSTALL Information on compiling and installing groff.
INSTALL.gen Generic information on configuration and compiling.
LICENSE Licensing information.
MANIFEST The file you are reading.
MORE.STUFF Useful stuff in other packages.
NEWS Recent user-visible changes in groff.
PROBLEMS Tips to handle known critical situations.
PROJECTS Long-term additions to groff.
README Availability and contact information for groff.
README.WIN32 Documentation of the Win32 port of groff.
README.MinGW Build information for MinGW.
TODO Things planned for future groff versions.
All other files in the top directory are related to the configuration,
@ -48,13 +49,20 @@ the groff source distribution.
./arch Data that is special for different architectures.
djgpp Data special for the 32-bit DOS compiler djgpp.
misc Data needed for various platforms.
./contrib Part of groff, but maintained by other people.
eqn2graph Convert equations created with EQN into different
graphical formats.
gdiffmk An improved implementation of the diffmk command to mark
differences between groff/nroff/troff files.
grap2graph Convert grap diagraps into different graphical formats.
groffer A wrapper to conveniently view roff files.
mm The groff mm macro package.
mom The groff mom macro package.
pdfmark A package to add PDF marks to groff documents, together
with a shell script (pdfroff) for easy creation of PDF
documents.
pic2graph Convert PIC diagrams into different graphical formats.
./doc Manuals and tutorials to groff aspects.
@ -85,6 +93,7 @@ the groff source distribution.
grolj4 HP Laserjet 4, PCL 5, and compatible printers.
grops PostScript output.
grotty Text output.
xditview A groff (pre)viewer for the X Window system.
./src/include The *.h C/C++ include files.
@ -92,6 +101,7 @@ the groff source distribution.
libbib Library of bibliographic functions.
libdriver Parser for intermediate output and postprocessor code.
libgroff Library for general support functions used everywhere.
libxutil Utility functions for xditview and xtotroff.
snprintf An implementation of snprintf() and friends.
./src/preproc Preprocessors.
@ -118,8 +128,7 @@ the groff source distribution.
lookbib Interactively search bibliographic databases.
pfbtops Translate a PostScript font in PFB format to PFA.
tfmtodit Create font description files for TeX DVI device.
./src/xditview A groff (pre)viewer for the X Window System.
xtotroff Create font description files for xditview.
./tmac Macro files.

19
contrib/groff/MORE.STUFF
View File

@ -1,8 +1,8 @@
More stuff for groff
====================
win32
-----
Windows 32
----------
Here two ports using the gcc compiler and other GNU tools:
@ -32,7 +32,7 @@ from
ftp://ftp.simtel.net/pub/simtelnet/gnu/djgpp/v2gnu/gro*b.zip
and its mirrors; for installation details please read `arch/djgpp/README'.
This port also runs on win32 systems, except Win2K.
This port also runs on Windows 32 systems, except Windows 2000.
grap
----
@ -43,14 +43,15 @@ can be found at
http://www.lunabase.org/~faber/Vault/software/grap/
A djgpp port which runs on dos and most win32 systems (Win95, Win98,
WinNT) done by Kees Zeelenberg <c.zeelenberg@hccnet.nl> is available from
A djgpp port which runs on dos and most Windows 32 systems (Windows 95,
Windows 98, Windows NT) done by Kees Zeelenberg <c.zeelenberg@hccnet.nl>
is available from
ftp://ftp.simtel.net/pub/simtelnet/gnu/djgpp/v2apps/
It is intended to be used with the djgpp port of groff.
A win32 port is included in the groff package available from
A Windows 32 port is included in the groff package available from
http://gnuwin32.sourceforge.net/
@ -110,14 +111,14 @@ cpp-style #line lines.
http://www.moria.de/deroff/
Version 1.6 compiled with DJGPP (for MS-DOS and all Win32 systems, i.e.
Win95, Win98, WinNT) is available from
Version 1.6 compiled with DJGPP (for MS-DOS and all Windows 32 systems,
i.e. Windows 95, Windows 98, Windows NT) is available from
ftp://ftp.simtel.net/pub/simtelnet/gnu/djgpp/v2apps/
and its mirrors.
A win32 port of version 1.8 is available from
A Windows 32 port of version 1.8 is available from
http://gnuwin32.sourceforge.net/

2
contrib/groff/Makefile
View File

@ -15,7 +15,7 @@
#
# You should have received a copy of the GNU General Public License along
# with groff; see the file COPYING. If not, write to the Free Software
# Foundation, 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
# Foundation, 51 Franklin St - Fifth Floor, Boston, MA 02110-1301, USA.
SHELL=/bin/sh

2
contrib/groff/Makefile.ccpg
View File

@ -9,7 +9,7 @@ MAKEFILEPARTS=\
all: $(PROG) $(MANPAGES)
$(PROG): $(OBJS) $(XLIBS)
$(LINK.cpp) -o $@ $(OBJS) $(XLIBS) $(LIBS) $(MLIB)
$(LINK.cpp) -o $@ $(OBJS) $(XLIBS) $(EXTRA_LDFLAGS) $(LIBS) $(MLIB)
install_bin: install_prog
install_prog: $(PROG)

77
contrib/groff/Makefile.comm
View File

@ -1,4 +1,4 @@
# Copyright (C) 1989-2000, 2002 Free Software Foundation, Inc.
# Copyright (C) 1989-2000, 2002, 2003, 2004 Free Software Foundation, Inc.
# Written by James Clark (jjc@jclark.com)
#
# This file is part of groff.
@ -15,11 +15,10 @@
#
# You should have received a copy of the GNU General Public License along
# with groff; see the file COPYING. If not, write to the Free Software
# Foundation, 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
# Foundation, 51 Franklin St - Fifth Floor, Boston, MA 02110-1301, USA.
#
# Makefile.comm
#
SHELL=/bin/sh
INCLUDES=-I. -I$(srcdir) \
-I$(top_builddir)/src/include -I$(top_srcdir)/src/include
ALL_CCFLAGS=$(INCLUDES) $(CCDEFINES) $(CCFLAGS) $(CPPFLAGS)
@ -31,6 +30,7 @@ LINK.c=$(CC) $(CFLAGS) $(LDFLAGS)
LIBGROFF=$(top_builddir)/src/libs/libgroff/libgroff.$(LIBEXT)
LIBBIB=$(top_builddir)/src/libs/libbib/libbib.$(LIBEXT)
LIBDRIVER=$(top_builddir)/src/libs/libdriver/libdriver.$(LIBEXT)
LIBXUTIL=$(top_builddir)/src/libs/libxutil/libxutil.$(LIBEXT)
MLIB=
XLIBS=
YTABH=
@ -93,22 +93,22 @@ realclean: distclean
-rm -f $(REALCLEANFILES)
extraclean: distclean
-rm -f \#* *~ =* core junk grot old temp tmp tem
-rm -f \#* *~ =* core junk grot old temp tmp tem *.new *.old *.orig
.SUFFIXES:
.SUFFIXES: .o .obj .cpp .c .y .man .n
.cpp.o:
$(COMPILE.cpp) $<
$(COMPILE.cpp) $(EXTRA_CCFLAGS) $<
.c.o:
$(COMPILE.c) $<
$(COMPILE.c) $(EXTRA_CFLAGS) $<
.cpp.obj:
$(COMPILE.cpp) $<
$(COMPILE.cpp) $(EXTRA_CCFLAGS) $<
.c.obj:
$(COMPILE.c) $<
$(COMPILE.c) $(EXTRA_CFLAGS) $<
.y.cpp:
if test -n "$(YTABH)"; then \
@ -119,7 +119,7 @@ extraclean: distclean
-test -f y.tab.h && mv y.tab.h y_tab.h
-test -f y.tab.c && mv y.tab.c y_tab.c
mv y_tab.c $(YTABC)
if test -n "$(YTABH)"; then mv y_tab.h $(YTABH); fi
test -z "$(YTABH)" || mv y_tab.h $(YTABH)
# The next rule is needed for make of Solaris 2.5.1 to override its
# built-in .y.o rule (which takes precedence over the .y.cpp rule above).
@ -132,8 +132,8 @@ extraclean: distclean
-test -f y.tab.h && mv y.tab.h y_tab.h
-test -f y.tab.c && mv y.tab.c y_tab.c
mv y_tab.c $(YTABC)
if test -n "$(YTABH)"; then mv y_tab.h $(YTABH); fi
$(COMPILE.cpp) $(YTABC)
test -z "$(YTABH)" || mv y_tab.h $(YTABH)
$(COMPILE.cpp) $(EXTRA_CCFLAGS) $(YTABC)
.man.n:
@echo Making $@ from $<
@ -148,6 +148,7 @@ extraclean: distclean
-e "s|@DOCDIR@|$(docdir)|g" \
-e "s|@EXAMPLEDIR@|$(exampledir)|g" \
-e "s|@HTMLDOCDIR@|$(htmldocdir)|g" \
-e "s|@PDFDOCDIR@|$(pdfdocdir)|g" \
-e "s|@DEVICE@|$(DEVICE)|g" \
-e "s|@DEFAULT_INDEX@|$(indexdir)/$(indexname)|g" \
-e "s|@DEFAULT_INDEX_NAME@|$(indexname)|g" \
@ -235,32 +236,35 @@ install_dev:
-test -d $(fontdir) || $(mkinstalldirs) $(fontdir)
-test -d $(fontsubdir) || $(mkinstalldirs) $(fontsubdir)
-if test -d $(srcdir)/generate; then \
test -d $(fontsubdir)/generate || \
$(mkinstalldirs) $(fontsubdir)/generate; \
test -d $(fontsubdir)/generate \
|| $(mkinstalldirs) $(fontsubdir)/generate; \
fi
-for f in $(DEVFILES); do \
rm -f $(fontsubdir)/$$f; \
if test -f $$f; then \
$(INSTALL_DATA) $$f $(fontsubdir)/$$f; \
else \
$(INSTALL_DATA) $(srcdir)/$$f $(fontsubdir)/$$f; \
fi; \
done
-for f in $(DEVSCRIPTS); do \
rm -f $(fontsubdir)/$$f; \
if test -f $$f; then \
$(INSTALL_SCRIPT) $$f $(fontsubdir)/$$f; \
else \
$(INSTALL_SCRIPT) $(srcdir)/$$f $(fontsubdir)/$$f; \
fi; \
done
-test -z "$(DEVFILES)" \
|| for f in ""$(DEVFILES); do \
rm -f $(fontsubdir)/$$f; \
if test -f $$f; then \
$(INSTALL_DATA) $$f $(fontsubdir)/$$f; \
else \
$(INSTALL_DATA) $(srcdir)/$$f $(fontsubdir)/$$f; \
fi; \
done
-test -z "$(DEVSCRIPTS)" \
|| for f in ""$(DEVSCRIPTS); do \
rm -f $(fontsubdir)/$$f; \
if test -f $$f; then \
$(INSTALL_SCRIPT) $$f $(fontsubdir)/$$f; \
else \
$(INSTALL_SCRIPT) $(srcdir)/$$f $(fontsubdir)/$$f; \
fi; \
done
.PHONY: uninstall_dev
uninstall_dev:
-for f in $(DEVFILES) $(DEVSCRIPTS); do rm -f $(fontsubdir)/$$f; done
-if test -d $(fontsubdir)/generate; then \
rmdir $(fontsubdir)/generate; \
fi
-test -z "$(DEVFILES)$(DEVSCRIPTS)" \
|| for f in ""$(DEVFILES) $(DEVSCRIPTS); do \
rm -f $(fontsubdir)/$$f; \
done
-test -d $(fontsubdir)/generate && rmdir $(fontsubdir)/generate
-rmdir $(fontsubdir)
.PHONY: depend_src
@ -278,10 +282,9 @@ depend.temp: FORCE
|| $(CCC) $(ALL_CCFLAGS) -MM $(CCSRCS) $$ytabc >>depend.temp
test -z "$(CSRCS)" \
|| $(CC) $(ALL_CFLAGS) -MM $(CSRCS) >>depend.temp
if test -n "$(YTABH)"; then \
sed -e 's|$(YTABH)|$(YTABC)|g' depend.temp >depend1.temp; \
mv depend1.temp depend.temp; \
fi
test -z "$(YTABH)" \
|| (sed -e 's|$(YTABH)|$(YTABC)|g' depend.temp >depend1.temp; \
mv depend1.temp depend.temp)
.PHONY: TAGS_src
TAGS_src:

2
contrib/groff/Makefile.cpg
View File

@ -9,7 +9,7 @@ MAKEFILEPARTS=\
all: $(PROG) $(MANPAGES)
$(PROG): $(OBJS) $(XLIBS)
$(LINK.c) -o $@ $(OBJS) $(XLIBS) $(LIBS) $(MLIB)
$(LINK.c) -o $@ $(OBJS) $(XLIBS) $(EXTRA_LDFLAGS) $(LIBS) $(MLIB)
install_bin: install_prog
install_prog: $(PROG)

219
contrib/groff/Makefile.in
View File

@ -1,4 +1,5 @@
# Copyright (C) 1989-2000, 2001, 2002, 2003 Free Software Foundation, Inc.
# Copyright (C) 1989-2000, 2001, 2002, 2003, 2004, 2005
# Free Software Foundation, Inc.
# Written by James Clark (jjc@jclark.com)
#
# This file is part of groff.
@ -15,13 +16,23 @@
#
# You should have received a copy of the GNU General Public License along
# with groff; see the file COPYING. If not, write to the Free Software
# Foundation, 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
# Foundation, 51 Franklin St - Fifth Floor, Boston, MA 02110-1301, USA.
SHELL=@SHELL@
srcdir=@srcdir@
top_srcdir=@top_srcdir@
top_srcdir=@abs_top_srcdir@
VPATH=@srcdir@
top_builddir=@groff_top_builddir@
SEP=@PATH_SEPARATOR@
top_builddir=@abs_top_builddir@
# `RT_SEP' is the operating system's native PATH SEPARATOR CHAR, which
# is to be used in runtime PATHs compiled into groff executables.
RT_SEP=@GROFF_PATH_SEPARATOR@
# `SH_SEP' is a alternative PATH SEPARATOR CHAR, to be used in shell
# scripts and makefile rules; it may be the same as `RT_SEP', but,
# particularly in some Microsoft environments, it may differ.
SH_SEP=@PATH_SEPARATOR@
version=`cat $(top_srcdir)/VERSION`
# No additional number if revision is zero.
@ -32,6 +43,18 @@ revision=`sed -e 's/^0$$//' -e 's/^[1-9].*$$/.&/' $(top_srcdir)/REVISION`
# world).
PAGE=@PAGE@
# The name of the ghostscript program. Normally, gs, on GNU/Linux
# but it might be different on MS-DOS/MS-WIN32 systems.
GHOSTSCRIPT=@GHOSTSCRIPT@
# `ALT_GHOSTSCRIPT_PROGS' specifies a list alternative names,
# which can be tried if `GHOSTSCRIPT' cannot be found at run time.
ALT_GHOSTSCRIPT_PROGS=@ALT_GHOSTSCRIPT_PROGS@
# Similarly, `ALT_AWK_PROGS' specifies a list of alternative names,
# which can be tried at run time, to identify the awk program.
ALT_AWK_PROGS=@ALT_AWK_PROGS@
# Normally the Postscript driver, grops, produces output that conforms
# to version 3.0 of the Adobe Document Structuring Conventions.
# Unfortunately some spoolers and previewers can't handle such output.
@ -58,6 +81,15 @@ BROKEN_SPOOLER_FLAGS=@BROKEN_SPOOLER_FLAGS@
# `DEVICE' is the default device.
DEVICE=ps
# `XDEVDIRS' is either `font/devX{75,100}{,-12}' or empty.
XDEVDIRS=@XDEVDIRS@
# `XPROGDIRS' is either `src/devices/xditview src/utils/xtotroff' or empty.
XPROGDIRS=@XPROGDIRS@
# `XLIBDIRS' is either `src/libs/libxutil' or empty.
XLIBDIRS=@XLIBDIRS@
# `TTYDEVDIRS' is either `font/devascii font/devlatin1' (for
# ASCII) or `font/devcp1047' (for EBCDIC) plus font/devutf8.
TTYDEVDIRS=@TTYDEVDIRS@ font/devutf8
@ -111,6 +143,9 @@ exampledir=$(docdir)/examples
# `htmldocdir' says where to install documentation in HTML format.
htmldocdir=$(docdir)/html
# `pdfdocdir' says where to install documentation in PDF format.
pdfdocdir=$(docdir)/pdf
# `fontdir' says where to install dev*/*.
fontdir=$(datasubdir)/font
@ -121,7 +156,7 @@ localfontdir=$(dataprogramdir)/site-font
legacyfontdir=/usr/lib/font
# `fontpath' says where to look for dev*/*.
fontpath=$(localfontdir)$(SEP)$(fontdir)$(SEP)$(legacyfontdir)
fontpath=$(localfontdir)$(RT_SEP)$(fontdir)$(RT_SEP)$(legacyfontdir)
# `tmacdir' says where to install macros.
tmacdir=$(datasubdir)/tmac
@ -132,12 +167,16 @@ systemtmacdir=$(libprogramdir)/site-tmac
# `localtmacdir' says where local files will be installed.
localtmacdir=$(dataprogramdir)/site-tmac
# `appresdir' says where to install the application resource file for
# gxditview.
appresdir=@appresdir@
# `tmacpath' says where to look for macro files.
# The current directory will be prepended in unsafe mode only; the home
# directory will be always added.
# `troffrc' and `troffrc-end' (and `eqnrc') are searched neither in the
# current nor in the home directory.
tmacpath=$(systemtmacdir)$(SEP)$(localtmacdir)$(SEP)$(tmacdir)
tmacpath=$(systemtmacdir)$(RT_SEP)$(localtmacdir)$(RT_SEP)$(tmacdir)
# `sys_tmac_prefix' is prefix (if any) for system macro packages.
sys_tmac_prefix=@sys_tmac_prefix@
@ -206,6 +245,11 @@ man7dir=$(manroot)/man$(man7ext)
make_html=@make_html@
make_install_html=@make_install_html@
# The configure script also checks whether all necessary utility programs
# for pdfroff are available -- only then we can build PDF documentation.
make_pdfdoc=@make_pdfdoc@
make_install_pdfdoc=@make_install_pdfdoc@
# DEFINES should include the following:
# -DHAVE_MMAP if you have mmap() and <sys/mman.h>
# -DARRAY_DELETE_NEEDS_SIZE if your C++ doesn't understand `delete []'
@ -220,7 +264,7 @@ make_install_html=@make_install_html@
# -DHAVE_CC_LIMITS_H if you have a C++ <limits.h>
# -DHAVE_MATH_H if you have <math.h>
# -DHAVE_CC_OSFCN_H if you have a C++ <osfcn.h>
# -DHAVE_CC_STDINT_H if you have a C++ <stdint.h>
# -DHAVE_CC_INTTYPES_H if you have a C++ <inttypes.h>
# -DHAVE_STDLIB_H if you have <stdlib.h>
# -DHAVE_STRING_H if you have <string.h>
# -DHAVE_STRINGS_H if you have <strings.h>
@ -232,6 +276,7 @@ make_install_html=@make_install_html@
# -DHAVE_GETCWD if you have getcwd()
# -DHAVE_GETTIMEOFDAY if you have gettimeofday()
# -DHAVE_ISATTY if you have isatty()
# -DHAVE_KILL if you have kill()
# -DHAVE_MKSTEMP if you have mkstemp()
# -DHAVE_MMAP if you have mmap()
# -DHAVE_PUTENV if you have putenv()
@ -243,6 +288,7 @@ make_install_html=@make_install_html@
# -DHAVE_STRERROR if you have strerror()
# -DHAVE_STRSEP if you have strsep()
# -DHAVE_STRTOL if you have strtol()
# -DHAVE_VSNPRINTF if you have vsnprintf()
#
# -DNEED_DECLARATION_GETTIMEOFTODAY
# if your C++ <sys/time.h> doesn't declare
@ -250,15 +296,21 @@ make_install_html=@make_install_html@
# -DNEED_DECLARATION_HYPOT if your C++ <math.h> doesn't declare hypot()
# -DNEED_DECLARATION_PCLOSE if your C++ <stdio.h> doesn't declare pclose()
# -DNEED_DECLARATION_POPEN if your C++ <stdio.h> doesn't declare popen()
# -DNEED_DECLARATION_PUTENV if your C++ <stdlib.h> doesn't declare putenv()
# -DNEED_DECLARATION_PUTENV if your C++ <stdlib.h> doesn't declare
# putenv()
# -DNEED_DECLARATION_RAND if your C++ <stdlib.h> doesn't declare rand()
# -DNEED_DECLARATION_SNPRINTF if your C++ <stdio.h> doesn't declare snprintf()
# -DNEED_DECLARATION_SNPRINTF if your C++ <stdio.h> doesn't declare
# snprintf()
# -DNEED_DECLARATION_SRAND if your C++ <stdlib.h> doesn't declare srand()
# -DNEED_DECLARATION_STRCASECMP if your C++ <string.h> doesn't declare
# strcasecmp()
# -DNEED_DECLARATION_STRNCASECMP
# if your C++ <string.h> doesn't declare
# strncasecmp()
# -DNEED_DECLARATION_VFPRINTF if your C++ <stdio.h> doesn't declare
# vfprintf()
# -DNEED_DECLARATION_VSNPRINTF if your C++ <stdio.h> doesn't declare
# vsnprintf()
#
# -DRET_TYPE_SRAND_IS_VOID if srand() returns void not int
# -DHAVE_SYS_NERR if you have sysnerr in <errno.h> or <stdio.h>
@ -270,7 +322,9 @@ make_install_html=@make_install_html@
# -DHAVE_STRUCT_EXCEPTION if <math.h> defines struct exception
# -DRETSIGTYPE=int if signal handlers return int not void
# -DIS_EBCDIC_HOST if the host's encoding is EBCDIC
# -DPAGEA4 if the the printer's page size is A4
# -DPAGE=A4 if the the printer's page size is A4
# -DGHOSTSCRIPT=gs the name (and directory if required) of the
# ghostscript program
DEFINES=@DEFS@
# Include
@ -279,6 +333,7 @@ DEFINES=@DEFS@
# strerror,strncasecmp,strtol}.$(OBJEXT)
#
# in LIBOBJS if your C library is missing the corresponding function.
# vsnprintf is defined in the snprintf.$(OBJEXT) module.
LIBOBJS=@LIBOBJS@
# `CCC' is the compiler for C++ (.cpp) files.
@ -291,7 +346,14 @@ CDEFINES=$(DEFINES)
CCFLAGS=@CXXFLAGS@
CFLAGS=@CFLAGS@
CPPFLAGS=@CPPFLAGS@
LDFLAGS=@LDFLAGS@
X_CFLAGS=@X_CFLAGS@
X_LIBS=@X_LIBS@
X_EXTRA_LIBS=@X_EXTRA_LIBS@
X_PRE_LIBS=@X_PRE_LIBS@
YACC=@YACC@
YACCFLAGS=-v
@ -317,9 +379,11 @@ ETAGSCCFLAG=-C
PERLPATH=@PERLPATH@
# Sed command with which to edit sh scripts.
SH_SCRIPT_SED_CMD=@SH_SCRIPT_SED_CMD@
# Sed script to deal with OS dependencies in sh scripts.
SH_DEPS_SED_SCRIPT=$(top_builddir)/arch/misc/shdeps.sed
# The program to create directory hierarchies.
mkinstalldirs=$(top_srcdir)/mkinstalldirs
mkinstalldirs= $(SHELL) $(top_srcdir)/mkinstalldirs
PURIFY=purify
PURIFYCCFLAGS=
@ -330,6 +394,8 @@ PURIFYCCFLAGS=
# copy of $(MDEFINES) when making individual directories; this could
# cause the argument list to become too long on some systems.
MDEFINES= \
"ALT_AWK_PROGS=$(ALT_AWK_PROGS)" \
"ALT_GHOSTSCRIPT_PROGS=$(ALT_GHOSTSCRIPT_PROGS)" \
"AR=$(AR)" \
"BROKEN_SPOOLER_FLAGS=$(BROKEN_SPOOLER_FLAGS)" \
"CC=$(CC)" \
@ -338,6 +404,7 @@ MDEFINES= \
"CCFLAGS=$(CCFLAGS)" \
"CDEFINES=$(CDEFINES)" \
"CFLAGS=$(CFLAGS)" \
"CPPFLAGS=$(CPPFLAGS)" \
"DEVICE=$(DEVICE)" \
"DVIPRINT=$(DVIPRINT)" \
"ETAGS=$(ETAGS)" \
@ -357,16 +424,28 @@ MDEFINES= \
"OBJEXT=$(OBJEXT)" \
"OTHERDEVDIRS=$(OTHERDEVDIRS)" \
"PAGE=$(PAGE)" \
"GHOSTSCRIPT=$(GHOSTSCRIPT)" \
"PERLPATH=$(PERLPATH)" \
"PSPRINT=$(PSPRINT)" \
"PURIFY=$(PURIFY)" \
"PURIFYCCFLAGS=$(PURIFYCCFLAGS)" \
"RANLIB=$(RANLIB)" \
"SEP=$(SEP)" \
"RT_SEP=$(RT_SEP)" \
"SH_SEP=$(SH_SEP)" \
"SHELL=$(SHELL)" \
"SH_SCRIPT_SED_CMD=$(SH_SCRIPT_SED_CMD)" \
"SH_DEPS_SED_SCRIPT=$(SH_DEPS_SED_SCRIPT)" \
"TTYDEVDIRS=$(TTYDEVDIRS)" \
"XDEVDIRS=$(XDEVDIRS)" \
"XLIBDIRS=$(XLIBDIRS)" \
"XPROGDIRS=$(XPROGDIRS)" \
"X_CFLAGS=$(X_CFLAGS)" \
"X_LIBS=$(X_LIBS)" \
"X_EXTRA_LIBS=$(X_EXTRA_LIBS)" \
"X_PRE_LIBS=$(X_PRE_LIBS)" \
"YACC=$(YACC)" \
"YACCFLAGS=$(YACCFLAGS)" \
"appresdir=$(appresdir)" \
"bindir=$(bindir)" \
"common_words_file=$(common_words_file)" \
"datadir=$(datadir)" \
@ -379,6 +458,7 @@ MDEFINES= \
"fontpath=$(fontpath)" \
"g=$(g)" \
"htmldocdir=$(htmldocdir)" \
"pdfdocdir=$(pdfdocdir)" \
"indexdir=$(indexdir)" \
"indexext=$(indexext)" \
"indexname=$(indexname)" \
@ -390,6 +470,8 @@ MDEFINES= \
"localtmacdir=$(localtmacdir)" \
"make_html=$(make_html)" \
"make_install_html=$(make_install_html)" \
"make_pdfdoc=$(make_pdfdoc)" \
"make_install_pdfdoc=$(make_install_pdfdoc)" \
"man1dir=$(man1dir)" \
"man1ext=$(man1ext)" \
"man5dir=$(man5dir)" \
@ -413,12 +495,12 @@ MDEFINES= \
"top_srcdir=$(top_srcdir)" \
"version=$(version)"
SHELL=/bin/sh
INCDIRS=src/include
LIBDIRS=\
src/libs/libgroff \
src/libs/libdriver \
src/libs/libbib
src/libs/libbib \
$(XLIBDIRS)
CCPROGDIRS=\
src/roff/groff \
src/roff/troff \
@ -441,40 +523,42 @@ CCPROGDIRS=\
src/utils/indxbib \
src/utils/lkbib \
src/utils/addftinfo
CPROGDIRS=src/utils/pfbtops
PROGDIRS=$(CCPROGDIRS) $(CPROGDIRS)
CPROGDIRS=\
src/utils/pfbtops \
$(XPROGDIRS)
PROGDEPDIRS=arch/misc
PROGDIRS=$(PROGDEPDIRS) $(CCPROGDIRS) $(CPROGDIRS)
DEVDIRS=\
font/devps \
font/devdvi \
font/devX75 \
font/devX75-12 \
font/devX100 \
font/devX100-12 \
font/devhtml
ALLTTYDEVDIRS=\
font/devascii \
font/devlatin1 \
font/devutf8 \
font/devcp1047
# `doc' must be processed before `contrib/pdfmark'.
OTHERDIRS=\
man \
tmac \
src/utils/afmtodit \
src/roff/grog \
src/roff/nroff \
doc \
contrib/mm \
contrib/pic2graph \
contrib/eqn2graph \
contrib/grap2graph \
contrib/groffer \
contrib/mom \
doc
contrib/pdfmark \
contrib/gdiffmk
ALLDIRS=$(INCDIRS) $(LIBDIRS) $(PROGDIRS) \
$(DEVDIRS) $(OTHERDEVDIRS) $(TTYDEVDIRS) $(OTHERDIRS)
$(DEVDIRS) $(XDEVDIRS) $(OTHERDEVDIRS) $(TTYDEVDIRS) $(OTHERDIRS)
EXTRADIRS=\
font/devps/generate \
font/devdvi/generate \
font/devlj4/generate \
src/xditview \
doc
NOMAKEDIRS=\
arch/djgpp \
@ -482,9 +566,10 @@ NOMAKEDIRS=\
contrib/mm/mm \
contrib/mom/examples \
contrib/mom/momdoc \
contrib/gdiffmk/tests \
src/libs/snprintf
DISTDIRS=\
$(INCDIRS) $(LIBDIRS) $(PROGDIRS) $(DEVDIRS) $(OTHERDEVDIRS) \
$(INCDIRS) $(LIBDIRS) $(PROGDIRS) $(DEVDIRS) $(XDEVDIRS) $(OTHERDEVDIRS) \
$(ALLTTYDEVDIRS) $(OTHERDIRS) $(EXTRADIRS) $(NOMAKEDIRS)
TARGETS=all install install_bin install_data clean distclean mostlyclean \
realclean extraclean distfiles TAGS depend uninstall_sub
@ -493,8 +578,8 @@ TARGETS=all install install_bin install_data clean distclean mostlyclean \
# where Make needs to be case-sensitive to find files like BI and VERSION.
ENVSETUP=\
if test -f $(srcdir)/makefile.ccpg* && \
test -f $(srcdir)/Makefile.ccpg*; \
then FNCASE=y; export FNCASE; \
test -f $(srcdir)/Makefile.ccpg*; then \
FNCASE=y; export FNCASE; \
else :; \
fi
@ -515,9 +600,10 @@ dot: FORCE
$(LIBDIRS): FORCE
@$(ENVSETUP); \
if test $(srcdir) = .; \
then srcdir=.; \
else srcdir=`cd $(srcdir); pwd`/$@; \
if test $(srcdir) = .; then \
srcdir=.; \
else \
srcdir=`cd $(srcdir); pwd`/$@; \
fi; \
test -d $@ || $(mkinstalldirs) $@; \
cd $@; \
@ -530,9 +616,10 @@ $(LIBDIRS): FORCE
$(CPROGDIRS): FORCE
@$(ENVSETUP); \
if test $(srcdir) = .; \
then srcdir=.; \
else srcdir=`cd $(srcdir); pwd`/$@; \
if test $(srcdir) = .; then \
srcdir=.; \
else \
srcdir=`cd $(srcdir); pwd`/$@; \
fi; \
test -d $@ || $(mkinstalldirs) $@; \
cd $@; \
@ -545,9 +632,10 @@ $(CPROGDIRS): FORCE
$(CCPROGDIRS): FORCE
@$(ENVSETUP); \
if test $(srcdir) = .; \
then srcdir=.; \
else srcdir=`cd $(srcdir); pwd`/$@; \
if test $(srcdir) = .; then \
srcdir=.; \
else \
srcdir=`cd $(srcdir); pwd`/$@; \
fi; \
test -d $@ || $(mkinstalldirs) $@; \
cd $@; \
@ -558,11 +646,12 @@ $(CCPROGDIRS): FORCE
-f $(top_srcdir)/Makefile.ccpg \
-f Makefile.dep $(do)
$(DEVDIRS) $(OTHERDEVDIRS) $(TTYDEVDIRS): FORCE
$(DEVDIRS) $(XDEVDIRS) $(OTHERDEVDIRS) $(TTYDEVDIRS): FORCE
@$(ENVSETUP); \
if test $(srcdir) = .; \
then srcdir=.; \
else srcdir=`cd $(srcdir); pwd`/$@; \
if test $(srcdir) = .; then \
srcdir=.; \
else \
srcdir=`cd $(srcdir); pwd`/$@; \
fi; \
test -d $@ || $(mkinstalldirs) $@; \
cd $@; \
@ -571,11 +660,12 @@ $(DEVDIRS) $(OTHERDEVDIRS) $(TTYDEVDIRS): FORCE
-f $$srcdir/Makefile.sub \
-f $(top_srcdir)/Makefile.dev $(do)
$(INCDIRS) $(OTHERDIRS): FORCE
$(INCDIRS) $(PROGDEPDIRS) $(OTHERDIRS): FORCE
@$(ENVSETUP); \
if test $(srcdir) = .; \
then srcdir=.; \
else srcdir=`cd $(srcdir); pwd`/$@; \
if test $(srcdir) = .; then \
srcdir=.; \
else \
srcdir=`cd $(srcdir); pwd`/$@; \
fi; \
test -d $@ || $(mkinstalldirs) $@; \
cd $@; \
@ -605,7 +695,12 @@ dist:
$(MAKE) srcdir=. VPATH=. distfiles; \
$(MAKE) srcdir=. VPATH=. extraclean; \
for d in $(EXTRADIRS); do \
(cd $$d; $(MAKE) extraclean); \
(cd $$d; \
if test -f Makefile; then \
$(MAKE) extraclean; \
else \
$(MAKE) -f $(top_builddir)/$$d/Makefile extraclean; \
fi); \
done; \
rm -f Makefile; \
$(LN_S) $$srcdir/Makefile.init Makefile
@ -644,13 +739,37 @@ uninstall_dirs:
-rmdir $(man1dir) $(man5dir) $(man7dir) $(manroot) \
$(tmacdir) $(systemtmacdir) $(localtmacdir) \
$(fontdir) $(localfontdir) $(bindir) \
$(datasubdir) $(dataprogramdir) $(datadir) $(infodir) \
$(exampledir) $(htmldocdir) $(docdir) \
$(libprogramdir) $(libdir)
$(datasubdir) $(dataprogramdir) $(infodir) \
$(exampledir) $(htmldocdir) $(pdfdocdir) $(docdir) \
$(libprogramdir) $(libdir) \
$(datadir)/doc/groff $(datadir)/doc $(datadir) 2>/dev/null || :
.PHONY: check docheck
check: site.exp docheck
.PHONY: check
check:
docheck:
if $(SHELL) -c "runtest --version" > /dev/null 2>&1; then \
runtest; \
else \
echo "WARNING: could not find \`runtest'" 1>&2; \
fi
# This snippet has been taken from the automake package.
site.exp:
@echo "Making a new site.exp file..."
@echo "## these variables are automatically generated by make ##" >site.tmp
@echo "# Do not edit here. If you wish to override these values" >>site.tmp
@echo "# edit the last section" >>site.tmp
@echo "set tool groff" >>site.tmp
@echo "set srcdir $(srcdir)/testsuite" >>site.tmp
@echo "set objdir `pwd`" >> site.tmp
@echo "## All variables above are generated by configure. Do not edit! ##" >> site.tmp
@test ! -f site.exp \
|| sed '1,/^## All variables above are.*##/ d' site.exp >> site.tmp
@-rm -f site.bak
@test ! -f site.exp || mv site.exp site.bak
@mv site.tmp site.exp
FORCE:

2
contrib/groff/Makefile.init
View File

@ -15,7 +15,7 @@
#
# You should have received a copy of the GNU General Public License along
# with groff; see the file COPYING. If not, write to the Free Software
# Foundation, 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
# Foundation, 51 Franklin St - Fifth Floor, Boston, MA 02110-1301, USA.
SHELL=/bin/sh

13
contrib/groff/Makefile.sub
View File

@ -4,9 +4,12 @@ DISTCLEANFILES=\
config.cache \
stamp-h \
Makefile \
src/xditview/Imakefile \
$(srcdir)/src/xditview/gxditview._man \
src/include/config.h
test-groff \
src/include/config.h \
site.exp \
site.bak \
groff.sum \
groff.log
CLEANADD=Makefile.cfg conftest*
distfiles: configure
@ -26,3 +29,7 @@ $(srcdir)/stamp-h.in: configure.ac aclocal.m4
config.h: stamp-h
stamp-h: config.hin config.status
$(SHELL) config.status
# Always create the site-font directory as a guide to the user.
install_data:
-test -d $(localfontdir) || $(mkinstalldirs) $(localfontdir)

314
contrib/groff/NEWS
View File

@ -1,6 +1,309 @@
This file describes recent user-visible changes in groff. Bug fixes are not
described. There are more details in the man and info pages.
VERSION 1.19.2
==============
Troff
-----
o Analogously to the .ft and \f pair, two new requests `gcolor' and
`fcolor' (which pair with \m and \M, respectively) have been added to
set the glyph and background colours.
o A new read-only, string-valued register `.sty' returns the name of the
current style.
o Two new conditional operators `F <name>' and `S <name>' have been added.
`F' is true if a font <name> exists. `S' is true if a style <name> has
been registered.
o Cyrillic characters have been added to the `utf8' and `html' output
devices.
Pic
---
o The `by' argument in a `for' loop can now be negative if it is additive.
For the multiplicative case, it must be greater than zero.
Eqn
---
o The following keywords aren't new but haven't been documented previously:
undef NAME (to undefine a macro)
copy "FILE" (a synonym for `include')
space n (to modify the vertical spacing before and after
an equation)
o The following macros aren't new but haven't been documented previously:
Alpha, ..., Omega (the same as `ALPHA', ..., `OMEGA')
ldots (three dots on the base line)
dollar (a dollar glyph)
o The following keywords have been extended. Again, this isn't new but
hasn't been documented previously:
col n { ... }
lcol n { ... }
rcol n { ... }
ccol n { ... }
pile n { ... }
lpile n { ... }
rpile n { ... }
cpile n { ... } (set vertical spacing between rows to N)
Grohtml
-------
o This device driver has been raised to beta stage; its set of tags should
be stable now.
o New command line option `-s' to set the base point size.
o New command line option `-S' to set the split level while generating
multiple files.
Grotty
------
o Experimental support for zero-width and double-width characters.
Gxditview
---------
o On platforms which have the X Window System this program is now built and
installed automatically.
Xtotroff
--------
o This program to create font definition files for xditview isn't new but
hasn't been installed previously.
Groffer
-------
o A security problem (reported as CAN-2004-0969) has been fixed.
Gdiffmk
-------
o A new script contributed by Mike Bianchi. It compares two groff, nroff,
or troff documents and creates an output with added margin characters
(using `.mc') to indicate the differences.
Pdfroff
-------
o A new wrapper script contributed by Keith Marshall to easily create PDF
documents with groff.
Macro packages
--------------
o ms.tmac
. Support for fractional point sizes: A value for the `PS', `VS', `FPS',
and `VPS' register larger than or equal to 1000 is always divided by
1000. For example, `.nr PS 10250' sets the document's font size to
10.25 points.
. The `Ds' and `De' macros provided in ms since groff version 1.19 have
been removed; the equivalent `DS' and `DE' macros should be used
instead. X11 documents which actually use `Ds' and `De' always load a
specific macro file from the X11 distribution (`macros.t') which
provides proper definitions for the two macros.
. The following registers have been added for improving layout control:
PORPHANS
Defines number of lines following `LP', `PP', `QP', `IP' or `XP' which
must be kept together, before any automatic page break.
HORPHANS
Sets number of lines of following paragraph which must be kept with a
heading, defined by `NH' or `SH', before any automatic page break.
GROWPS
Sets the first level of heading (set with `NH') which will keep the
same point size as body text.
PSINCR
Sets the point size increment for each level of heading (set with
`NH'), below the threshold level set by `GROWPS'; e.g., if
\n[PS] = 10, \n[GROWPS] = 3 and \n[PSINCR] = 2.0p, then `.NH 1' will
produce 14pt headings, `.NH 2' will produce 12pt, and all other levels
will remain at 10pt (because \n[PS] = 10).
. The `SH' macro now accepts a numeric argument, to make heading size
match that of `NH' with same argument value when the `GROWPS'/`PSINCR'
feature is enabled.
Please refer to the documentation of the ms package for other, minor
improvements.
o me.tmac
The section type set with the `++' request is available in the `_M'
register. This isn't new but hasn't been documented before.
o www.tmac
The `HR' macro no longer causes an empty line for non-HTML devices.
A new macro `HEAD' has been added to directly add data to the
<head>...</head> block.
New macros `OLS' and `OLE' to start and end an ordered list.
New macros `DLS' and `DLE' to start and end a definition list.
Pdfmark
-------
o A new macro package contributed by Keith Marshall which implements PDF
marks. This is in alpha stage currently.
Miscellaneous
-------------
o Two new keywords to the DESC file have been added which are needed for
grohtml: `image_generator' and `unscaled_charwidths'. The former gives
the name of the program which creates PNG images, and the latter makes
troff always use unscaled character widths.
VERSION 1.19.1
==============
Groff
-----
o The argument of the command line option `-I' is now also passed to troff
and grops, specifying a directory to search for files on the command line,
files named in `so' and `psbb' requests, and files named in \X'ps: file'
and \X'ps: import' escapes.
o If option `-V' is used more than once, the commands will be both printed
on standard error and run.
Troff
-----
o Two new read-only, string-valued registers `.m' and `.M' return the
name of the current drawing and background color, respectively.
o New read-only register `.U' which is set to 1 if in safer mode and set
to 0 if in unsafe mode.
o An input encoding file for latin-5 (a.k.a. ISO 8859-9) has been added.
Example use:
groff -Tdvi -mlatin5 my_file > my_file.dvi
Note that some output devices don't support all glyphs of this encoding.
o If the `return' request is called with an argument, it exits twice,
namely the current macro and the macro one level higher. This is
used to define a wrapper macro for `return' in trace.tmac.
o For completeness, two new requests have been added: `dei1' and `ami1'.
They are equivalent to `dei' and `ami', respectively, but the macros
are executed with compatibility mode off (similar to `de1' and `am1').
o New command line option `-I' to specify a directory for files (both
those on the command line and those named in `psbb' requests). This is
also handled by the groff wrapper program.
o Since version 1.19 you can say `.vs 0'. Older versions emit a warning
and convert this to `.vs \n[.V]'.
This hasn't been documented properly. Note that `.vs 0' isn't saved in a
diversion since it doesn't result in vertical motion.
Pic
___
o Dashed and dotted ellipses have been implemented.
Tbl
---
o New key character `x' to make tbl call a user-defined macro on a table
cell. Patch by Heinz-Jürgen Oertel <hj.oertel@surfeu.de>.
Grap2graph
----------
o A new script contributed by Eric S. Raymond <esr@thyrsus.com>. It
converts a grap diagram into a cropped image. Since it uses gs and the
PNM library, virtually all graphics formats are available for output.
[Note that the grap program itself isn't part of the groff package;
see the file MORE.STUFF how to obtain grap.]
Grohtml
-------
o New option `-j' to emit output splitted into multiple files.
Grops
-----
o New command line option `-I' to specify a directory to search for files
on the command line and files named in \X'ps: import' and \X'ps: file'
escapes. This is also handled by the groff wrapper program.
o The default value for the `broken' keyword in the DESC file is now 0.
Grolj4
------
o A new man page `lj4_font(5)' documents how fonts are accessed with
grolj4.
o The built-in fonts for LJ4 and newer PCL 5 devices have been completely
revised, mainly to access as much glyphs as possible. The provided
metric files should be compatible with recent PCL 5 printers also.
Additionally, font description files have been added for the Arial and
Times New Roman family, the MS symbol, and Wingdings fonts.
Afmtodit
--------
o New option `-x' to prevent use of built-in Adobe Glyph List.
Hpftodit
--------
o Completely revised to handle HP TrueType metric files also. See the
hpftodit manual page for more details.
Groffer
-------
o This version is a rewrite of groffer in many parts, but it is kept in
the old single script style.
New options: --text, --mode text, --tty-viewer, --X, --mode X,
--X-viewer, --html, --mode html, --html-view, --apropos-data,
--apropos-devel, --apropos-progs.
New documentation file: README_SH.
Enhancement of the configuration files and the `apropos' handling.
Macro Packages
--------------
o www.tmac: New macro `JOBNAME' to split output into multiple files.
o In mdoc, multiple calls to `.Lb' are now supported in the LIBRARY
section.
VERSION 1.19
============
@ -17,9 +320,9 @@ o Input encoding files for latin-9 (a.k.a. latin-0 and ISO 8859-15) and
and latin-2 only for -Tdvi and -Tutf8.
o Composite glyphs are now supported. To do this, a subset of the Adobe
Glyph List (AGL) Algorithm as described in
Glyph List (AGL) Algorithm as described in
http://partners.adobe.com/asn/developer/typeforum/unicodegn.html
http://partners.adobe.com/asn/tech/type/unicodegn.jsp
is used to construct glyph names based on Unicode character codes. The
existing groff glyph names are frozen; no glyph names which can't be
@ -110,7 +413,10 @@ o The paper size is now emitted via the %%DocumentMedia and PageSize
mechanisms so that it is no longer required to tell `gv' or `ps2pdf'
about the paper size. The `broken' flag value 16 omits this feature
(the used PostScript command `setpagedevice' is a LanguageLevel 2
extension). Patch by Egil Kvaleberg <egil@kvaleberg.no>.
extension) -- if you intend to further process grops output to get an
encapsulated PS (EPS) file you must also use this option.
Patch by Egil Kvaleberg <egil@kvaleberg.no>.
o Non-slanted PostScript metrics have been changed again; they no longer
contain negative left italic correction values. This assures correct
@ -316,7 +622,7 @@ o Color support has been added to troff and pic (and to the device drivers
grops, grodvi, grotty, and grohtml -- other preprocessors and drivers will
follow). A new function `defcolor' defines colors; the escape sequence
`\m' sets the drawing color, the escape sequence `\M' specifies the
background color for closed objects created with \D'...' commands.
background color for closed objects created with \D'...' commands.
`\m[]' and `\M[]' switch back to the previous color. `\m' and `\M'
correspond to the new troff output command sets starting with `m' and
`DF'. The device-specific default color is called `default' and can't be

157
contrib/groff/PROBLEMS
View File

@ -11,6 +11,103 @@ Generic Problems
* Displaying a man page on a terminal with/without my favourite pager
only gives garbage.
groff by default now uses SGR escape sequences (`ANSI color') to
control the display attributes (bold, underlined, colour) on TTYs.
Some terminals (e.g. `kterm') don't understand SGR, and some pagers
(e.g. older versions of `less' or `less' without the -R option) don't
understand SGR either. There are three solutions to fix this, in order
of preference; please read the grotty man page for more details.
The fourth and probably best option is to update your terminal program
and pager to versions which can handle SGR.
1. Set the GROFF_NO_SGR environment variable.
2. Pass option -c to grotty.
3. Append the following fragment to the `troffrc' file:
--- start ---
.if n \{\
. nr _C \n(.C
. cp 0
.
. \" The following code sets a top-of-page trap to disable grotty's TTY
. \" mode. Since neither \X nor .output can be used before the first
. \" page has started, we must use a trap. To make it work with troff's
. \" -o option, we wait until the first printed page.
.
. de sgr@dummy
. .
.
. rn wh wh@old
.
. \" The stand-alone version. If no other trap is set, we can safely
. \" insert the truncated vertical space caused by the trap (if any).
. \" Otherwise we assume that the document's main macro package takes
. \" care of that. As soon as the trap has been executed, it is removed.
. de1 no@sgr
. if \\n[.P] \{\
. if (\\n[.t] == \\n[.p]) \{\
. rn wh@old wh
. rm no@sgr
. wh 0
. sp \\n[.trunc]
. nop \X'tty: sgr 0'
. sp -1
. \}\}
. .
.
. wh@old 0 no@sgr
.
. \" The piggyback version to be appended to macros planted with the
. \" modified `wh' request.
. de1 no@sgr1
. if \\n[.P] \{\
. rn wh@old wh
. ds no@sgr1
. nop \X'tty: sgr 0'
. sp -1
. \}
. .
.
. \" We redefine the `wh' request so that `no@sgr1' is appended to
. \" the trap macro.
. de1 wh
. am1 \\$2 sgr@dummy
. no@sgr1
. sgr@dummy
. wh@old \\$1 \\$2
. .
.
. cp \n[_C]
.\}
--- end ---
----------------------------------------------------------------------
* The UTF-8 output of grotty has strange characters for the minus, the
hyphen, and the right quote. Why?
The used Unicode characters (U+2212 for the minus sign and U+2010 for
the hyphen) are the correct ones, but many programs can't search them
properly. The same is true for the right quote (U+201D). To map those
characters back to the ASCII characters, insert the following code
snippet into the `troffrc' configuration file:
.if '\*[.T]'utf8' \{\
. char \- \N'45'
. char - \N'45'
. char ' \N'39'
.\}
----------------------------------------------------------------------
* My document says that the current year is 19100, not 2000.
In groff, as in traditional troff, the yr number register yields the
@ -295,7 +392,7 @@ Printing and Display Problems
A PostScript document must meet three requirements in order to be
included with the PSPIC macro: it must comply with the Adobe Document
Structuring Conventions; it must contain a BoundingBox line; it must
be ``well-behaved''. The BoundingBox line should be of the form:
be `well-behaved'. The BoundingBox line should be of the form:
%%BoundingBox: llx lly urx ury
@ -315,7 +412,7 @@ format. (This is available from the Adobe file server; send a message
with a body of `help' to ps-file-server@adobe.com.)
If an EPS file to be included via \X'ps: import' does not start with
%!PS-Adobe-...', gtroff will still include the file, but grops will
`%!PS-Adobe-...', gtroff will still include the file, but grops will
not add any fonts to the generated output file that are listed in the
EPS file, even though the files are listed in the `download' file and
are available in the devps directory.
@ -352,9 +449,13 @@ Make sure that the paper size is `letter'. See groff_tmac(5).
Error: Widget viewport has zero width and/or height
This error means you haven't correctly installed the application
defaults file, GXditview.ad; ``make install'' does this for you
automatically, so either you didn't do ``make install'', or you don't
have imake configured correctly.
defaults file, GXditview.ad; `make install' does this for you
automatically, so either you didn't do `make install', or you haven't
passed a good `--appresdir=<DIR>' argument to groff's configure script.
See the X(7) man page for information how and where application resource
files have to be located. Look for the XAPPLRESDIR and XUSERFILESEARCHPATH
environment variables.
----------------------------------------------------------------------
@ -362,7 +463,7 @@ have imake configured correctly.
the same as when I print the document with -Tps: the line and page
breaks come in different places.
Use groff -X -Tps.
Use `groff -X -Tps'.
----------------------------------------------------------------------
@ -532,13 +633,13 @@ as empty):
Create a script called 'eqn':
> #!/bin/sh
> #! /bin/sh
> if [ ${1:-""} = /usr/pub/eqnchar ] ; then shift ; fi
> geqn $*
and a script called 'neqn':
> #!/bin/sh
> #! /bin/sh
> if [ ${1:-""} = /usr/pub/eqnchar ] ; then shift ; fi
> geqn -Tascii $*
@ -558,7 +659,7 @@ To get PostScript output from 'man -t', you also need to create a
--- /usr/local/bin/psroff Sat Feb 13 17:45:46 1993
***************
*** 1,8 ****
#!/bin/sh
#! /bin/sh
! # Emulate nroff with groff.
prog="$0"
@ -567,7 +668,7 @@ To get PostScript output from 'man -t', you also need to create a
for i
--- 1,8 ----
#!/bin/sh
#! /bin/sh
! # Emulate psroff with groff.
prog="$0"
@ -697,12 +798,15 @@ argument is a const char *. Fix the declaration of open() in
This occurs because GNU make and Unix make handle VPATH differently,
and the groff build relies on GNU make's VPATH handling.
Use GNU make to work around the problem. In Solaris 8, GNU make is
on the Software Companion CD and is installed as /opt/sfw/bin/gmake.
Use GNU make <http://www.gnu.org/software/make/> to work around this.
In Solaris 8 and 9, GNU make is on the Software Companion CD in
package SFWgmake and is installed as /opt/sfw/bin/gmake. Prebuilt
versions of GNU make for Solaris are also available from
sunfreeware.com.
----------------------------------------------------------------------
* On Ultrix, the make stops with the message
* On Ultrix, the make program stops with the message
*** Error code 1
@ -773,11 +877,27 @@ directory and include that directory with a -I option.
----------------------------------------------------------------------
* I get errors when I try to compile groff with Sun C++ version 5.0
or 5.1.
* I get errors when I try to compile groff with Forte Development 6
or 6u1, or Sun C++ version 5.0 through 5.2.
This is a known problem; see Sun bug #4301919. As of this writing, no
patch is available. Use GCC 2.95.2 or later instead.
This is a known problem; see Sun bug #4301919. See Sun patches
109482, 109490, 109508, and 109509 for fixes.
----------------------------------------------------------------------
* I get warnings from the Sun linker while using gcc 3.4.0:
ld: warning: relocation error: R_SPARC_UA32:
file groff/src/libs/libgroff/libgroff.a(getopt.o): symbol optarg:
external symbolic relocation against non-allocatable
section .debug_info; cannot be processed at runtime:
relocation ignored
This seems to be a known problem (Sun bugs #4910101 and #4910810,
filed in September 2003; gcc bug #15599, filed May 2004) without a
public fix as of this writing. A work-around is to use option
`-gstabs+' instead of `-g' (and a high probability that the output is
only debuggable with gdb but not with Sun's debuggers).
----------------------------------------------------------------------
@ -790,6 +910,7 @@ Makefile. If that doesn't solve the problem, define INT_MIN as
----------------------------------------------------------------------
* When compiling on MacOS X, groff compiles but does not run well.
* When compiling on MacOS X, groff compiles but does not run well,
especially `eqn', causing many `can't break line' messages.
Use ./configure CXX=g++2 then make as usual.

6
contrib/groff/PROJECTS
View File

@ -9,8 +9,6 @@ Here are some things that would be useful additions to groff:
a page-makeup postprocessor and associated macro package
(like pm and -mpm)
a complete, self-contained manual -- first results can be found in
doc/groff.texinfo.
If you want to work on one of these, you should probably post to
gnu.groff.bug to see if anyone else has gotten there first.
gnu.groff.bug (or send email to bug-groff@gnu.org) to see if anyone else
has gotten there first.

143
contrib/groff/README
View File

@ -1,83 +1,134 @@
This is the GNU groff document formatting system. The version number
is given in the file VERSION.
This is the GNU `groff' document formatting system. The version
number is given in the file VERSION.
Included in this release are implementations of troff, pic, eqn, tbl,
grn, refer, -man, -mdoc, and -ms macros, and drivers for PostScript, TeX
dvi format, HP LaserJet 4 printers, Canon CAPSL printers, HTML format
(still alpha), and typewriter-like devices. Also included is a modified
version of the Berkeley -me macros, an enhanced version of the X11
xditview previewer, and an implementation of the -mm macros contributed
by Joergen Haegg (jh@axis.se).
Included in this release are implementations of `troff', `pic', `eqn',
`tbl', `grn', `refer', `-man', `-mdoc', `-mom', and `-ms' macros, and
drivers for `PostScript', `TeX dvi' format, `HP LaserJet 4' printers,
`Canon CAPSL' printers, `HTML' format (beta status), and
typewriter-like devices. Also included is a modified version of the
Berkeley `-me' macros, the enhanced version `gxditview' of the X11
`xditview' previewer, and an implementation of the `-mm' macros
contributed by Joergen Haegg (jh@axis.se).
See the file INSTALL for installation instructions. You will require a
C++ compiler.
See the file `INSTALL' for installation instructions. You will
require a C++ compiler.
The file NEWS describes recent user-visible changes to groff.
The file `NEWS' describes recent user-visible changes to `groff'.
Groff is free software. See the file COPYING for copying permission.
`groff' is free software. See the file `COPYING' for copying
permission.
The file PROBLEMS describes various problems that have been encountered
in compiling, installing, and running groff.
The file `PROBLEMS' describes various problems that have been
encountered in compiling, installing, and running `groff'.
For the moment, the documentation assumes that you are already familiar
with the Unix versions of troff, -ms, and the preprocessors.
The most recent released version of `groff' is always available by
anonymous ftp from `ftp.gnu.org' in the directory `gnu/groff'.
The most recent released version of groff is always available by
anonymous ftp from ftp.gnu.org in the directory pub/gnu/groff.
The current development version of `groff' is available from a `CVS'
repository. You can access it by first selecting a parent directory
in which to create a working copy (call it, say, `~/cvswork'), and
then executing the commands
A CVS repository is now available, containing the current development
version of groff. You can access it with the commands
cd ~/cvswork
CVS_RSH=ssh; export CVS_RSH
cvs -d:ext:anoncvs@savannah.gnu.org/cvsroot/groff -z5 co groff
export CVSROOT=:pserver:anoncvs@anoncvs.ffii.org:/var/cvs
cvs login
cvs -z9 co groff
(Note that you need an `ssh' client for security reasons.)
(if the prompt for the password appears, just press the enter key).
After a successful login you no longer need the first two commands; an
update of a checked out repository should be done with
This will create a subdirectory, `~/cvswork/groff', with a "checked
out" copy of the `CVS' repository. An update of this working copy may
be achieved, at any later time by invoking the commands
cvs -z9 update -dP
cd ~/cvswork/groff
CVS_RSH=ssh cvs -z5 update -dP
Please read the info pages of cvs for further details.
Please read the `CVS' info pages for further details.
Alternatively, you can download snapshots (which are updated twice a
day) from
Finally, it is possible to access the `CVS' with a web browser by
pointing it to
ftp://ftp.ffii.org/pub/groff/devel/groff-current.tar.gz
http://savannah.gnu.org/cvs/?group=groff
or a diff file relative to the latest official groff release as
Alternatively, you can download snapshots (which are updated twice a day).
The complete `groff' source as a single file is available at
ftp://ftp.ffii.org/pub/groff/devel/groff-<version>-current.diff.gz
http://groff.ffii.org/groff/devel/groff-current.tar.gz
Assuming that groff-<version>.tar.gz and
groff-<version>-current.diff.gz are in the same directory, do the
A diff file relative to `groff-<version>', the latest official `groff'
release is available at
http://groff.ffii.org/groff/devel/groff-<version>-current.diff.gz
Assuming that `groff-<version>.tar.gz' and
`groff-<version>-current.diff.gz' are in the same directory, do the
following to apply the diff file:
tar xzvf groff-<version>.tar.gz
cd groff-<version>
gunzip -c ../groff-<version>-current.diff.gz | patch -p1
Please report bugs using the form in the file BUG-REPORT; the idea of
Depending on your requirements, you may need at least some of the
following tools to build `groff' directly from its source:
ghostscript
the psutils package
the netpbm package
texinfo 4.8
bison >= 1.875b or byacc
Note that `texinfo' and `bison' or `byacc' are required only for
building from `CVS' sources (either a checked out working copy, or a
daily snapshot). They are not required for building from a stable
release tarball. Also note that the version numbers stated are the
minimum supported. No version of `texinfo' < 4.8 will work, and the
original release of `bison' 1.875 is known not to work; you *may* find
that `bison' releases < 1.875 will work, but in case of difficulty,
please update to a later version *before* posting a bug report.
For *all* sources, you need ghostscript for creation of either `PDF' or
`HTML' output; the `netpbm' and `psutils' packages are required only for
`HTML' output. If you don't intend to produce output in either of these
formats, then these packages are unnecessary.
In Linux Debian, the installation of `texinfo' is dangerous. For it
creates a file `install-info' that will block the system installation.
So the created `/usr/local/bin/install-info' must be renamed.
The `groff' configure script searches for the X11 headers and
libraries `Xaw' and `Xmu'. So the corresponding developer packages of
your system must be installed, otherwise `groff' does not install
`gxditview' and the `-TX*' devices. In Debian, the developer packages
are `libxaw7-dev' and `libxmu-dev'.
Please report bugs using the form in the file `BUG-REPORT'; the idea of
this is to make sure that FSF has all the information it needs to fix
the bug. At the very least, read the BUG-REPORT form and make sure
the bug. At the very least, read the `BUG-REPORT' form and make sure
that you supply all the information that it asks for. Even if you are
not sure that something is a bug, report it using BUG-REPORT: this will
not sure that something is a bug, report it using `BUG-REPORT': this will
enable us to determine whether it really is a bug or not.
Three mailing lists are available:
bug-groff@gnu.org for reporting bugs
groff@gnu.org for general discussion of groff
groff-commit@ffii.org a read-only list showing logs of
commitments to the CVS repository
groff-commit@gnu.org a read-only list showing commitments
to the CVS repository
Note that groff@gnu.org is an alias for groff@ffii.org; you must be
subscribed to the `groff' list to send mails.
You can post mails directly to the `bug-groff' list, without subscribing;
to post mails to the `groff' list you must subscribe to it.
To subscribe, send a mail to <list>-request@<domain> (example:
groff-request@ffii.org) with the word `subscribe' in either the subject
or body of the email (don't include the quotes).
groff-request@gnu.org for the `groff' list) with the word `subscribe'
in either the subject or body of the email (don't include the quotes).
Alternatively, you may subscribe by visiting the web pages at
GNU groff was written by James Clark <jjc@jclark.com>. It is now
http://lists.gnu.org/mailman/listinfo/bug-groff
http://lists.gnu.org/mailman/listinfo/groff
http://lists.gnu.org/mailman/listinfo/groff-commit
Each of these web pages also provides a link to a browseable archive of
postings to the corresponding mailing list.
GNU `groff' was written by James Clark <jjc@jclark.com>. It is now
maintained by Ted Harding <ted.harding@nessie.mcc.ac.uk> and Werner
Lemberg <wl@gnu.org>.

277
contrib/groff/README.MinGW Normal file
View File

@ -0,0 +1,277 @@
README.MinGW
============
Contributed by Keith Marshall (keith.d.marshall@ntlworld.com)
INTRODUCTION
------------
This file provides recommendations for building a Win32 implementation of
GNU Groff, using the MinGW port of GCC for Microsoft (TM) Windows-32
platforms. It is intended to supplement the standard installation
instructions (see file INSTALL); it does not replace them.
You require both the MinGW implementation of GCC and its supporting MSYS
toolkit, which provides a Win-32 implementation of the GNU bash shell, and a
few other essential utilities; these may be obtained from
http://sourceforge.net/projects/mingw
by following the appropriate download links, where they are available as
self-extracting executable installation packages. If installing both from
scratch, it is recommended that MinGW is installed first, as the MSYS
installer can then automatically set up the proper environment for running
MinGW.
Additionally, if you wish to compile groff with support for its HTML output
capability, some additional tools are required as decribed in the section
PREREQUISITES FOR HTML OUTPUT later in this file.
BUILDING GROFF WITH MINGW
-------------------------
Assuming that you have obtained the appropriate groff distribution, and that
you are already running an MSYS shell, then the configuration, compilation,
and installation of groff, using MinGW, is performed in much the same way as
it is described in the INSTALL file, which is provided with the groff
distribution. The installation steps are summarised below:
1. Change working directory to any suitable location where you may unpack
the groff distribution; you must be authorized for write access.
Approximately 30MB of free disk space are needed.
2. Unpack the groff distribution:
tar xzf <download-path>/groff-<version>.tar.gz
This creates a new sub-directory, groff-<version>, containing an image of
the groff source tree. You should now change directory, to make this
./groff-<version> your working directory.
3. If you are intending to build groff with support for HTML output, then
you must now ensure that the prerequisites described in the later section
PREREQUISITES FOR HTML OUTPUT are satisfied, before proceeding to build
groff; in particular, please ensure that all required support programs
are installed in the current PATH.
4. You are now ready to configure, build, and install groff. This is
accomplished using the conventional procedure, as described in the file
INSTALL, i.e.
./configure --prefix=<win32-install-path> ...
make
make install
Please observe the syntax for the configure command, indicated above; the
default value for --prefix is not suitable for use with MinGW, so the
--prefix=<win32-install-path> option must be specified, where
<win32-install-path> is the chosen MS-Windows directory in which the
groff application files are to be installed (see the later section
entitled CHOOSING AN INSTALLATION PATH). Any other desired configuration
options may also be specified, as described in the standard groff
installation instructions.
5. After completing the above, groff should be successfully installed; the
build directory is no longer required; it may be simply deleted in its
entirety. Alternatively, you may choose to keep it, but to remove all
files which can be reproduced later, by repeating the configure, make and
make install steps; this is readily accomplished by the command
make distclean
This completes the installation of groff; please read the final sections of
this file, GROFF RUNTIME ENVIRONMENT and CAVEATS AND BUGS, for advice on
setting up the runtime environment, and avoiding known runtime problems,
before running groff.
CHOOSING AN INSTALLATION PATH
-----------------------------
It may be noted that the above instructions indicate that the ./configure
command must be invoked with an argument specifying a preference for
--prefix=<win32-install-path>, whereas the standard groff installation
instructions indicate that this may be omitted, in which case it defaults to
--prefix=/usr/local.
In the case of building with MinGW, the default behaviour of configure is
not appropriate for the following reasons.
o The MSYS environment creates a virtual UNIX-like file system, with its
root mapped to the actual MS-Windows directory where MSYS itself is
installed; /usr is also mapped to this MSYS installation directory.
o All of the MSYS tools, and the MinGW implementation of GCC, refer to files
via this virtual file system representation; thus, if the
--prefix=<win32-install-path> is not specified when groff is configured,
`make install' causes groff to be installed in <MSYS-install-path>/local.
o groff needs to know its own installation path, so that it can locate its
own installed components. This information is compiled in, using the
exact form specified with the --prefix=<win32-install-path> option to
configure.
o Knowledge of the MSYS virtual file system is not imparted to groff; it
expects the compiled-in path to its components to be a fully qualified
MS-Windows path name (although UNIX-style slashes are permitted, and
preferred to the MS-Windows style backslashes, to demarcate the directory
hierarchy). Thus, when configuring groff, if
--prefix=<win32-install-path> is not correctly specified, then the
installed groff application looks for its components in /usr/local, and
most likely doesn't find them, because they are actually installed in
<MSYS-install-path>/local.
It is actually convenient, but by no means a requirement, to have groff
installed in the /usr/local directory of the MSYS virtual file system; this
makes it easy to invoke groff from the MSYS shell, since the virtual
/usr/local/bin is normally added automatically to the PATH (the default
PATH, as set in MSYS's /etc/profile), when MSYS is started.
In order to install groff into MSYS's /usr/local directory, it is necessary
to specify the fully qualified absolute MS-Windows path to this directory,
when configuring groff, i.e.
./configure --prefix=<MSYS-install-path>/local ...
For example, on a system where MSYS is installed in the MS-Windows directory
D:\MSYS\1.0, the MSYS virtual path /usr/local resolves to the absolute
MS-Windows native path D:\MSYS\1.0\local (the /usr component of the MSYS
virtual path does not appear in the resolved absolute native path name since
MSYS maps this directly to the root of the MSYS virtual file system). Thus,
the --prefix option should be specified to configure as
./configure --prefix=D:/MSYS/1.0/local ...
Note that the backslash characters, which appear in the native MS-Windows
form of the path name, are replaced by UNIX-style slashes in the argument to
configure; this is the preferred syntax.
Also note that the MS-Windows device designator (D: in this instance) is
prepended to the specified path, in the normal MS-Windows format, and that,
since upper and lower case distinctions are ignored in MS-Windows path
names, any combination of upper and lower case is acceptable.
PREREQUISITES FOR HTML OUTPUT
-----------------------------
If you intend to use groff for production of HTML output, then there are a
few dependencies which must be satisfied. Ideally, these should be resolved
before attempting to configure and build groff, since the configuration
script does check them.
In order to produce HTML output, you first require a working implementation
of Ghostscript; either the AFPL Ghostscript or the GNU Ghostscript
implementation for MS-Windows should be suitable, depending on your
licensing preference. It is highly recommended to use version 8.11 or
higher due to bugs in older versions. These may be obtained, in the form of
self-installing binary packages, by following the download links for the
chosen licensing option, from http://sourceforge.net/projects/ghostscript.
Please note that these packages install the Ghostscript interpreter required
by groff in the ./bin subdirectory of the Ghostscript installation
directory, with the name gswin32c.exe. However, groff expects this
interpreter to be located in the system PATH, with the name gs.exe. Thus,
to ensure that groff can correctly locate the Ghostscript interpreter, it is
recommended that the file gswin32c.exe should be copied from the Ghostscript
installation directory to the MSYS /usr/local/bin directory, where it should
be renamed to gs.exe.
In addition to a working Ghostscript interpreter, you also require several
image manipulation utilities, all of which may be scavenged from various
packages available from http://sourceforge.net/projects/gnuwin32, and which
should be installed in the MSYS /usr/local/bin directory, or any other
suitable directory which is specified in the PATH. These additional
prerequisites are
1. from the netpbm-<version>-bin.zip package:
netpbm.dll
pnmcrop.exe
pnmcut.exe
pnmtopng.exe
pnmtops.exe
2. from the libpng-<version>-bin.zip package:
libpng.dll
3. from the zlib-<version>-bin.zip package:
zlib-1.dll, which must be renamed to zlib.dll
4. from the psutils-<version>-bin.zip package:
psselect.exe
Note that it is not necessary to install the above four packages in their
entirety; of course, you may do so if you wish.
GROFF RUNTIME ENVIRONMENT
-------------------------
The runtime environment, provided to groff by MSYS, is essentially the same
as would be provided under a UNIX or GNU/Linux operating system; thus, any
environment variables which may be used to customize the groff runtime
environment have similar effects under MSYS, as they would in UNIX or
GNU/Linux, with the exception that any variable specifying a path should
adopt the same syntax as a native MS-Windows PATH specification.
There is, however, one known problem which is associated with the
implementation of the MS-Windows file system, and the manner in which the
Microsoft runtime library (which is used by the MinGW implementation of GCC)
generates names for temporary files. This known problem arises when groff
is invoked with a current working directory which refers to a network share,
for which the user does not have write access in the root directory, and
there is no environment variable set to define a writeable location for
creating temporary files. When these conditions arise, groff fails with a
`permission denied' error, as soon as it tries to create any temporary file.
To specify the location for creating temporary files, the standard UNIX or
GNU/Linux implementation of groff provides the GROFF_TMPDIR or TMPDIR
environment variables, whereas MS-Windows applications generally use TMP or
TEMP; furthermore, the MS-Windows implementations of Ghostscript apparently
support the use of only TEMP or TMPDIR.
To avoid problems with creation of temporary files, it is recommended that
you ensure that both TMP and TEMP are defined, with identical values, to
point to a suitable location for creating temporary files; many MS-Windows
boxes have them set already, and groff has been adapted to honour them, when
built in accordance with the preceding instructions, using MinGW.
CAVEATS AND BUGS
----------------
There are two known issues, observed when running groff in the MinGW/MSYS
environment, which would not affect groff in its native UNIX environment:
o Running groff with the working directory set to a subdirectory of a
network share, where the user does not have write permission in the root
directory of the share, causes groff to fail with a `permission denied'
exception, if the TMP environment variable is not appropriately defined;
it may also be necessary to define the TEMP environment variable, to avoid
a similar failure mode, when using the -Thtml output mode of groff. This
problem is more fully discussed in the preceding section, GROFF RUNTIME
ENVIRONMENT.
o When running groff (or nroff) to process standard input, where the
standard input stream is obtained directly from the RXVT console provided
with MSYS, groff cannot detect the end-of-file condition for the standard
input stream, and hangs. This appears to be caused by a fault in the MSYS
implementation of RXVT; it may be worked around by either starting MSYS
without RXVT (see the comments in the MSYS.BAT startup script); in this
case standard input is terminated by typing <Ctrl-Z> followed by <RETURN>,
on a new input line. Alternatively, if you prefer to use MSYS with RXVT,
you can enter the interactive groff command in the form
cat | groff ...
in which case <Ctrl-D> terminates the standard input stream, in just the
same way it does on a UNIX system; the cat executable provided with MSYS
does seem to trap the end-of-file condition, and properly signals groff
that the input stream has terminated.

2
contrib/groff/REVISION
View File

@ -1 +1 @@
0
2

8
contrib/groff/TODO
View File

@ -1,11 +1,5 @@
Unicode input:
Implementing \U'xxxx' to access Unicode characters directly.
Making groff 16bit input-clean.
Separating input and output encodings (similar to LaTeX).
Better selection of paper sizes with -Tps.
Making groff 21bit input-clean.
Make -Tlj4 work with -X.

1725
contrib/groff/aclocal.m4 vendored
View File

File diff suppressed because it is too large Load Diff

7294
contrib/groff/configure vendored
View File

File diff suppressed because it is too large Load Diff

132
contrib/groff/configure.ac
View File

@ -1,90 +1,126 @@
dnl Process this file with autoconf to produce a configure script.
# Autoconf configuration file for groff.
# Copyright (C) 1989-1995, 2001, 2002, 2003, 2004, 2005
# Free Software Foundation, Inc.
#
# This file is part of groff.
#
# groff is free software; you can redistribute it and/or modify it under
# the terms of the GNU General Public License as published by the Free
# Software Foundation; either version 2, or (at your option) any later
# version.
#
# groff is distributed in the hope that it will be useful, but WITHOUT ANY
# WARRANTY; without even the implied warranty of MERCHANTABILITY or
# FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
# for more details.
#
# You should have received a copy of the GNU General Public License along
# with groff; see the file COPYING. If not, write to the Free Software
# Foundation, 51 Franklin St - Fifth Floor, Boston, MA 02110-1301, USA.
#
# Process this file with autoconf to produce a configure script.
AC_INIT
AC_CONFIG_HEADERS(src/include/config.h:src/include/config.hin)
AC_PREREQ(2.59)
AC_CONFIG_HEADERS([src/include/config.h:src/include/config.hin])
AC_CONFIG_SRCDIR([src/roff/groff/groff.cpp])
dnl checks for programs
GROFF_SRCDIR
GROFF_BUILDDIR
# checks for programs
AC_PROG_CC
AC_PROG_CXX
GROFF_CXX_CHECK
GROFF_EBCDIC
GROFF_OS390
GROFF_X11
GROFF_APPRESDIR_OPTION
GROFF_APPRESDIR_DEFAULT
GROFF_PRINT
AC_PATH_PROG(PERLPATH, perl, /usr/bin/perl)
AC_PATH_PROG([PERLPATH], [perl], [/usr/bin/perl])
GROFF_PROG_YACC
AC_PROG_RANLIB
GROFF_INSTALL_SH
GROFF_INSTALL_INFO
AC_PROG_INSTALL
AC_PROG_LN_S
dnl use a dummy substitution if no csh hack is necessary to avoid errors
dnl with non-GNU sed programs
GROFF_CSH_HACK(SH_SCRIPT_SED_CMD='1s/.*/:/', SH_SCRIPT_SED_CMD='1s/a/a/')
AC_SUBST(SH_SCRIPT_SED_CMD)
dnl checks for headers
AC_CHECK_HEADERS(stdlib.h unistd.h dirent.h limits.h sys/dir.h \
string.h strings.h math.h sys/time.h)
# use a dummy substitution if no csh hack is necessary to avoid errors
# with non-GNU sed programs
GROFF_CSH_HACK([SH_SCRIPT_SED_CMD='1s/.*/:/'], [SH_SCRIPT_SED_CMD='1s/a/a/'])
AC_SUBST([SH_SCRIPT_SED_CMD])
# checks for headers
AC_CHECK_HEADERS([stdlib.h unistd.h dirent.h limits.h sys/dir.h \
string.h strings.h math.h sys/time.h direct.h process.h])
GROFF_ISC_SYSV3
GROFF_POSIX
# checks for header stuff
GROFF_SRAND
GROFF_NEED_DECLARATION(gettimeofday)
GROFF_NEED_DECLARATION(hypot)
GROFF_NEED_DECLARATION(popen)
GROFF_NEED_DECLARATION(pclose)
GROFF_NEED_DECLARATION(putenv)
GROFF_NEED_DECLARATION(rand)
GROFF_NEED_DECLARATION(snprintf)
GROFF_NEED_DECLARATION(srand)
GROFF_NEED_DECLARATION(strcasecmp)
GROFF_NEED_DECLARATION(strncasecmp)
GROFF_NEED_DECLARATION([gettimeofday])
GROFF_NEED_DECLARATION([hypot])
GROFF_NEED_DECLARATION([popen])
GROFF_NEED_DECLARATION([pclose])
GROFF_NEED_DECLARATION([putenv])
GROFF_NEED_DECLARATION([rand])
GROFF_NEED_DECLARATION([snprintf])
GROFF_NEED_DECLARATION([srand])
GROFF_NEED_DECLARATION([strcasecmp])
GROFF_NEED_DECLARATION([strncasecmp])
GROFF_NEED_DECLARATION([vfprintf])
GROFF_NEED_DECLARATION([vsnprintf])
GROFF_SYS_NERR
GROFF_SYS_ERRLIST
GROFF_OSFCN_H
GROFF_LIMITS_H
GROFF_STDINT_H
GROFF_INTTYPES_H
dnl checks for typedefs
# checks for typedefs
GROFF_UNSIGNED_LONG_LONG
GROFF_UINTMAX_T
GROFF_TIME_T
AC_TYPE_SIGNAL
GROFF_TYPE_SIGNAL
GROFF_STRUCT_EXCEPTION
dnl checks for libraries
# checks for libraries
GROFF_LIBC
GROFF_LIBM
dnl checks for functions
# checks for functions
AC_FUNC_MMAP
saved_libs="$LIBS"
LIBS="$LIBS -lc $LIBM"
AC_REPLACE_FUNCS(fmod getcwd putenv snprintf strcasecmp \
strerror strncasecmp strtol)
LIBS="$LIBS $LIBC $LIBM"
AC_REPLACE_FUNCS([fmod getcwd putenv snprintf strcasecmp \
strerror strncasecmp strtol])
# vsnprintf is in the same source file as snprintf
AC_CHECK_FUNCS([vsnprintf], [], [AC_LIBOBJ([snprintf])])
LIBS="$saved_libs"
AC_CHECK_FUNCS(gettimeofday isatty rename setlocale strsep)
AC_CHECK_FUNCS([gettimeofday isatty kill rename setlocale strsep])
GROFF_MKSTEMP
AC_DECL_SYS_SIGLIST
dnl checks for compiler characteristics
AC_CHECK_DECLS([sys_siglist])
# checks for compiler characteristics
GROFF_ARRAY_DELETE
GROFF_TRADITIONAL_CPP
dnl checks for operating system services
# checks for operating system services
GROFF_WCOREFLAG
dnl other random stuff
# other random stuff
GROFF_BROKEN_SPOOLER_FLAGS
GROFF_PAGE
GROFF_G
GROFF_TMAC
GROFF_TARGET_PATH_SEPARATOR
GROFF_HTML_PROGRAMS
GROFF_PDFDOC_PROGRAMS
GROFF_PNMTOPS_NOSETPAGE
AC_CONFIG_FILES(stamp-h, [echo timestamp > stamp-h])
AC_CONFIG_FILES([Makefile doc/Makefile src/xditview/Imakefile])
AC_CONFIG_FILES([stamp-h], [echo timestamp > stamp-h])
AC_CONFIG_FILES([Makefile doc/Makefile src/utils/xtotroff/Makefile])
AC_CONFIG_FILES([contrib/gdiffmk/tests/runtests],
[chmod +x contrib/gdiffmk/tests/runtests])
AC_CONFIG_FILES([test-groff], [chmod +x test-groff])
AC_OUTPUT
dnl
AC_MSG_NOTICE([
Configuration completed.
You can now say `make' to compile the groff package and `make install'
to install it afterwards.
If you want to compile xditview, change the directory to `src/xditview'
and follow the instructions given in the file `INSTALL'.
])
GROFF_APPRESDIR_CHECK

22
contrib/groff/contrib/eqn2graph/eqn2graph.man
View File

@ -1,4 +1,4 @@
.\" $Id: eqn2graph.man,v 1.2 2002/08/21 17:29:17 wlemb Exp $
.\" $Id: eqn2graph.man,v 1.4 2003/10/28 07:46:23 wlemb Exp $
.\" This documentation is released to the public domain.
.
.
@ -31,7 +31,7 @@ Reads an EQN equation (one line) as input; produces an image
file (by default in Portable Network Graphics format) suitable for the
Web as output.
.P
Your input EQN code should \fInot\fR have the .EQ/.EN preamble that
Your input EQN code should \fInot\fR have the \&.EQ/.EN preamble that
that normally precedes it within
.BR groff (@MAN1EXT@)
macros; nor do you need to have dollar-sign or other delimiters
@ -82,7 +82,25 @@ The
initialization file.
.
.
.SH ENVIRONMENT
.TP
.B GROFF_TMPDIR
The directory in which temporary files will be created.
If this is not set
.B eqn2graph
searches the environment variables
.BR \%TMPDIR ,
.BR TMP ,
and
.B TEMP
(in that order).
Otherwise, temporary files will be created in
.BR /tmp .
.
.
.SH "SEE ALSO"
.BR pic2graph (@MAN1EXT@),
.BR grap2graph (@MAN1EXT@),
.BR @g@eqn (@MAN1EXT@),
.BR groff (@MAN1EXT@),
.BR gs (1),

33
contrib/groff/contrib/eqn2graph/eqn2graph.sh
View File

@ -1,4 +1,4 @@
#!/bin/sh
#! /bin/sh
#
# eqn2graph -- compile EQN equation descriptions to bitmap images
#
@ -32,7 +32,7 @@
#
# Thus, we pass -U to groff(1), and everything else to convert(1).
#
# $Id: eqn2graph.sh,v 1.2 2002/07/17 04:55:46 wlemb Exp $
# $Id: eqn2graph.sh,v 1.5 2005/05/18 07:03:06 wl Exp $
#
groff_opts=""
convert_opts=""
@ -58,17 +58,34 @@ do
shift
done
# create temporary directory
tmp=
for d in "$GROFF_TMPDIR" "$TMPDIR" "$TMP" "$TEMP" /tmp; do
test -z "$d" && continue
tmp=`(umask 077 && mktemp -d -q "$d/eqn2graph-XXXXXX") 2> /dev/null` \
&& test -n "$tmp" && test -d "$tmp" \
&& break
tmp=$d/eqn2graph$$-$RANDOM
(umask 077 && mkdir $tmp) 2> /dev/null && break
done;
if test -z "$tmp"; then
echo "$0: cannot create temporary directory" >&2
{ (exit 1); exit 1; }
fi
trap 'exit_status=$?; rm -rf $tmp && exit $exit_status' 0 2 15
# Here goes:
# 1. Add .EQ/.EN.
# 2. Process through eqn(1) to emit troff markup.
# 3. Process through groff(1) to emit Postscript.
# 4. Use convert(1) to crop the Postscript and turn it into a bitmap.
tmp=/usr/tmp/eqn2graph-$$
trap "rm ${tmp}.*" 0 2 15
read equation
(echo ".EQ"; echo 'delim $$'; echo ".EN"; echo '$'"${equation}"'$') | \
groff -e $groff_opts -Tps >${tmp}.ps \
&& convert -crop 0x0 $convert_opts ${tmp}.ps ${tmp}.${format} \
&& cat ${tmp}.${format}
(echo ".EQ"; echo 'delim $$'; echo ".EN"; echo '$'"$equation"'$') | \
groff -e $groff_opts -Tps -P-pletter > $tmp/eqn2graph.ps \
&& convert -trim -crop 0x0 $convert_opts $tmp/eqn2graph.ps $tmp/eqn2graph.$format \
&& cat $tmp/eqn2graph.$format
# End

63
contrib/groff/contrib/gdiffmk/ChangeLog Normal file
View File

@ -0,0 +1,63 @@
2005-01-16 Mike Bianchi <MBianchi@Foveal.com>
* gdiffmk.sh (Usage): Fix typos.
<top>: Allow `-M<arg1> <arg2>' also.
* gdiffmk.man: Updated.
2005-01-13 Mike Bianchi <MBianchi@Foveal.com>
* gdiffmk.sh: Add the -D, -M, and -B options, which provide actions
akin to nrchbar.
Thanks to Larry Kollar (http://home.alltel.net/kollar/groff/).
* gdiffmk.man: Updated.
* tests/runtests.in: Added tests for gdiffmk's -D, -M, and -B
options.
* tests/baseline8, tests/baseline9, tests/baseline10: New files.
2004-12-16 Mike Bianchi <MBianchi@Foveal.com>
* tests/runtests.in: Fix typo (s/$(srcdir)/${srcdir}/).
2004-12-15 Werner LEMBERG <wl@gnu.org>
The configure script now generates tests/runtests.
* tests/tests.sh: Renamed to...
* tests/runtests.in: This.
Add proper $srcdir prefixes to make it run from build directory.
* README, Makefile.sub (CLEANADD), tests/test_baseline7: Updated.
2004-12-14 Werner LEMBERG <wl@gnu.org>
* gdiffmk.sh: Make sed pattern work with alternate result of GNU
diff's -D option, using `!' instead of `not' in #endif comments.
(Exit): Use prefix for each emitted message line.
2004-12-14 Mike Bianchi <MBianchi@Foveal.com>
* tests/*: New files for testing gdiffmk.
* README, gdiffmk.man, gdiffmk.sh: Updated.
Minor fixes.
2004-12-13 Mike Bianchi <MBianchi@Foveal.com>
Add `-x' command line option to select a diff program.
* gdiffmk.sh: Add code to handle `-x'.
Move test for working `diff' down.
Fix sed pattern -- `.mc *' needs to be followed by `.mc .'.
(Usage): Updated.
* gdiffmk.man: Updated.
2004-12-12 Mike Bianchi <MBianchi@Foveal.com>
* README: New file.
2004-12-11 Mike Bianchi <MBianchi@Foveal.com>
First import of gdiffmk files.

47
contrib/groff/contrib/gdiffmk/Makefile.sub Normal file
View File

@ -0,0 +1,47 @@
# Makefile.sub for `gdiffmk' (integration into the groff source tree)
# File position: <groff-source>/contrib/gdiffmk/Makefile.sub
# Last update: 12 December 2004
# Copyright (C) 2004 Free Software Foundation, Inc.
# Written by Mike Bianchi <MBianchi@Foveal.com <mailto:MBianchi@Foveal.com>>
# This file is part of the gdiffmk utility, which is part of groff.
# groff is free software; you can redistribute it and/or modify it
# under the terms of the GNU General Public License as published by
# the Free Software Foundation; either version 2, or (at your option)
# any later version.
# groff is distributed in the hope that it will be useful, but WITHOUT
# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
# or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public
# License for more details.
# You should have received a copy of the GNU General Public License
# along with groff; see the files COPYING and LICENSE in the top
# directory of the groff source. If not, write to the Free Software
# Foundation, 51 Franklin St - Fifth Floor, Boston, MA 02110-1301, USA.
########################################################################
MAN1=gdiffmk.n
CLEANADD=gdiffmk tests/runtests
all: gdiffmk
gdiffmk: gdiffmk.sh
rm -f $@; \
sed -e "s|@BINDIR@|$(bindir)|g" \
-e "s|@VERSION@|$(version)$(revision)|g" \
-e $(SH_SCRIPT_SED_CMD) $(srcdir)/gdiffmk.sh >$@; \
chmod +x $@
install_data: gdiffmk
-test -d $(bindir) || $(mkinstalldirs) $(bindir)
-rm -f $(bindir)/gdiffmk
$(INSTALL_SCRIPT) gdiffmk $(bindir)/gdiffmk
uninstall_sub:
-rm -f $(bindir)/gdiffmk

46
contrib/groff/contrib/gdiffmk/README Normal file
View File

@ -0,0 +1,46 @@
gdiffmk is approximately a recreation of the original Bell Labs/AT&T diffmk
command for troff/nroff documents, with enhancements.
It should not be confused with `diffmk' commands that operate on XML.
The inspiration for this code was a Perl 2 version written in 1989 by Randal
L. Schwartz. See
landfield.com/software/comp.sources.misc/archive-name/volume06/diffmk.p.gz
The command also attempts to reproduce some of the functionality of the old
`nrchbar' command. See
open-systems.ufl.edu/mirrors/ftp.isc.org/usenet/comp.sources.unix/volume10/nrchbar.Z
Thanks to Werner Lemberg for help in making the package more portable and
fit into the GNU groff source structure.
Gnu diff(1) with the -Dname option does all of the work and sed(1)
translates the output into something groff/troff/nroff can handle.
Note the BUGS on the man page.
The `tests' directory contains simple tests. `runtests run' runs them and
compares the output against baseline files. Calling `runtests' without
argument gives the usage.
----------------------------------------------------------------------------
Copyright (C) 2004, 2005 Free Software Foundation, Inc.
Written by Mike Bianchi <MBianchi@Foveal.com <mailto:MBianchi@Foveal.com>>
This file is part of the gdiffmk utility, which is part of groff.
groff is free software; you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2, or (at your option)
any later version.
groff is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public
License for more details.
You should have received a copy of the GNU General Public License
along with groff; see the files COPYING and LICENSE in the top
directory of the groff source. If not, write to the Free Software
Foundation, 51 Franklin St - Fifth Floor, Boston, MA 02110-1301, USA.

281
contrib/groff/contrib/gdiffmk/gdiffmk.man Normal file
View File

@ -0,0 +1,281 @@
.ig \"-*- nroff -*-
Copyright (C) 2004, 2005 Free Software Foundation, Inc.
This file is part of the gdiffmk utility, which is part of groff.
Written by Mike Bianchi <MBianchi@Foveal.com <mailto:MBianchi@Foveal.com>>
Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.
Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided that the
entire resulting derived work is distributed under the terms of a
permission notice identical to this one.
Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that this permission notice may be included in
translations approved by the Free Software Foundation instead of in
the original English.
..
.
.do mso www.tmac
.
.TH GDIFFMK @MAN1EXT@ "@MDATE@" "Groff Version @VERSION@"
.
.
.SH NAME
gdiffmk \- mark differences between groff/nroff/troff files
.
.
.SH SYNOPSIS
.nr a \n(.j
.ad l
.nr i \n(.i
.in +\w'\fBgdiffmk 'u
.ti \niu
.B gdiffmk
.de OP
. ie \\n(.$-1 .RI "[\ \fB\\$1\fP" "\\$2" "\ ]"
. el .RB "[\ " "\\$1" "\ ]"
..
.OP \-a \%addmark
.OP \-c \%changemark
.OP \-d \%deletemark
[\ \c
.B \-D
.OP \-B
.OP \-M "mark1 mark2"
]
.OP \-x \%diffcmd
.OP \-\-
.OP \-\-help
.OP \%\-\-version
.I \%file1
.I \%file2
[\ \c
.IR \%output \ \c
]
.br
.ad \na
.
.
.SH DESCRIPTION
.B gdiffmk
compares two
.BR groff (1),
.BR nroff (1),
or
.BR troff (1)
documents,
.I file1
and
.IR file2 ,
and creates an output which is
.I file2
with added `margin character' (.mc) commands that indicate the differences.
.
.LP
If the
.I output
filename is present,
the output is written there.
If it is
.B \-
or absent the output is written to the standard output.
.
.LP
If the
.I file1
or
.I file2
argument is
.B \-
the standard input is read for that input.
Clearly both cannot be
.BR \- .
.
.LP
Note that the output is not necessarily compatible with all macro packages
and all preprocessors.
See the
.B BUGS
section below.
.
.
.SH OPTIONS
.TP
.BI \-a addmark
Use the
.I addmark
for source lines not in
.I file1
but present in
.IR file2 .
Default:
.BR + .
.
.TP
.B \-B
By default, the deleted texts marked by the
.B \-D
option end
with an added troff break command,
.BR .br ,
to ensure that the deletions are marked properly.
This is the only way to guarantee that deletions and small
changes get flagged.
This option directs the program not to insert these breaks; it makes no
sense to use it without
.BR \-D .
.
.TP
.BI \-c changemark
Use the
.I changemark
for changed source lines.
Default:
.BR | .
.
.TP
.BI \-d deletemark
Use the
.I deletemark
for deleted source lines.
Default:
.BR * .
.
.TP
.B \-D
Show the deleted portions from changed and deleted text.
Default delimiting marks:
.BR "[[" " .\&.\&.\&. " "]]" .
.
.TP
.BI \-M "mark1 mark2"
Change the delimiting marks for the
.B \-D
option.
It makes no sense to use this option without
.BR \-D .
.
.TP
.BI \-x diffcmd
Use the
.I diffcmd
command to perform the comparison of
.I file1
and
.IR file2 .
In particular,
.I diffcmd
should accept the GNU
.B diff
.BI \-D name
option.
Default:
.BR diff (1).
.
.TP
.B \-\-
All the following arguments are treated as file names,
even if they begin with
.BR \- .
.
.TP
.B \-\-help
Print a usage message on standard error output and exit.
.
.TP
.B \-\-version
Print version information on the standard output and exit.
.
.
.SH BUGS
The output is not necessarily compatible with all macro packages
and all preprocessors.
A workaround that is often successful against preprocessor problems
is to run
.B gdiffmk
on the output of all the preprocessors instead of the input source.
.
.LP
.B gdiffmk
relies on the
.BI \-D name
option of GNU
.BR diff (1)
to make a merged `#ifdef' output format.
It hasn't been tested whether other versions of
.BR diff (1)
do support this option.
See also the
.BI \-x diffcmd
option.
.
.LP
Report bugs to bug-groff@gnu.org.
Include a complete, self-contained example that will allow the bug to
be reproduced, and say which version of
.B gdiffmk
you are using.
.
.
.SH AUTHORS
This document was written and is maintained by
.MTO MBianchi@Foveal.com "Mike Bianchi" .
.
.LP
This document is distributed under the terms of the FDL (GNU Free
Documentation License) version 1.1 or later.
You should have received a copy of the FDL on your system, it is also
available on-line at the
.URL http://\:www.gnu.org/\:copyleft/\:fdl.html "GNU copyleft site" .
.
.LP
.B gdiffmk
is part of the
.I groff
GNU free software project.
All parts of the
.I groff package
are protected by GNU copyleft licenses.
The software files are distributed under the terms of the GNU General
Public License (GPL), while the documentation files mostly use the GNU
Free Documentation License (FDL).
.
.
.SH COPYRIGHT
Copyright \(co 2004, 2005 Free Software Foundation, Inc.
.
.LP
.B gdiffmk
is free software; you can redistribute it and/or modify it under
the terms of the GNU General Public License as published by the Free
Software Foundation; either version 2, or (at your option) any later
version.
.
.LP
.B gdiffmk
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.
.
.LP
You should have received a copy of the GNU General Public License along
with groff; see the file COPYING.
If not, write to the Free Software
Foundation, 51 Franklin St - Fifth Floor, Boston, MA 02110-1301, USA.
.
.
.SH "SEE ALSO"
.BR groff (@MAN1EXT@),
.BR nroff (@MAN1EXT@),
.BR gtroff (@MAN1EXT@),
.BR diff (@MAN1EXT@)
.
.\" Local Variables:
.\" mode: nroff
.\" End:

346
contrib/groff/contrib/gdiffmk/gdiffmk.sh Normal file
View File

@ -0,0 +1,346 @@
#! /bin/sh
# Copyright (C) 2004, 2005 Free Software Foundation, Inc.
# Written by Mike Bianchi <MBianchi@Foveal.com <mailto:MBianchi@Foveal.com>>
# This file is part of the gdiffmk utility, which is part of groff.
# groff is free software; you can redistribute it and/or modify it
# under the terms of the GNU General Public License as published by
# the Free Software Foundation; either version 2, or (at your option)
# any later version.
# groff is distributed in the hope that it will be useful, but WITHOUT
# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
# or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public
# License for more details.
# You should have received a copy of the GNU General Public License
# along with groff; see the files COPYING and LICENSE in the top
# directory of the groff source. If not, write to the Free Software
# Foundation, 51 Franklin St - Fifth Floor, Boston, MA 02110-1301, USA.
# This file is part of GNU gdiffmk.
cmd=$( basename $0 )
function Usage {
if test "$#" -gt 0
then
echo >&2 "${cmd}: $@"
fi
echo >&2 "\
Usage: ${cmd} [ OPTIONS ] FILE1 FILE2 [ OUTPUT ]
Place difference marks into the new version of a groff/nroff/troff document.
FILE1 and FILE2 are compared, using \`diff', and FILE2 is output with
groff \`.mc' requests added to indicate how it is different from FILE1.
FILE1 Previous version of the groff file. \`-' means standard input.
FILE2 Current version of the groff file. \`-' means standard input.
Either FILE1 or FILE2 can be standard input, but not both.
OUTPUT Copy of FILE2 with \`.mc' commands added.
\`-' means standard output (the default).
OPTIONS:
-a ADDMARK Mark for added groff source lines. Default: \`+'.
-c CHANGEMARK Mark for changed groff source lines. Default: \`|'.
-d DELETEMARK Mark for deleted groff source lines. Default: \`*'.
-D Show the deleted portions from changed and deleted text.
Default delimiting marks: \`[[' .... \`]]'.
-B By default, the deleted texts marked by the \`-D' option end
with an added troff \`.br' command. This option prevents
the added \`.br'.
-M MARK1 MARK2 Change the delimiting marks for the \`-D' option.
-x DIFFCMD Use a different diff(1) command;
one that accepts the \`-Dname' option, such as GNU diff.
--version Print version information on the standard output and exit.
--help Print this message on the standard error.
"
exit 255
}
function Exit {
exitcode=$1
shift
for arg
do
echo >&2 "${cmd}: $1"
shift
done
exit ${exitcode}
}
# Usage: FileRead exit_code filename
#
# Check for existence and readability of given file name.
# If not found or not readable, print message and exit with EXIT_CODE.
function FileRead {
case "$2" in
-)
return
;;
esac
if test ! -e "$2"
then
Exit $1 "File \`$2' not found."
fi
if test ! -r "$2"
then
Exit $1 "File \`$2' not readable."
fi
}
# Usage: FileCreate exit_code filename
#
# Create the given filename if it doesn't exist.
# If unable to create or write, print message and exit with EXIT_CODE.
function FileCreate {
case "$2" in
-)
return
;;
esac
if ! touch "$2" 2>/dev/null
then
if test ! -e "$2"
then
Exit $1 "File \`$2' not created; " \
"Cannot write directory \`$( dirname "$2" )'."
fi
Exit $1 "File \`$2' not writeable."
fi
}
function WouldClobber {
case "$2" in
-)
return
;;
esac
if test "$1" -ef "$3"
then
Exit 3 \
"The $2 and OUTPUT arguments both point to the same file," \
"\`$1', and it would be overwritten."
fi
}
ADDMARK='+'
CHANGEMARK='|'
DELETEMARK='*'
MARK1='[['
MARK2=']]'
function RequiresArgument {
# Process flags that take either concatenated or
# separated values.
case "$1" in
-??*)
expr "$1" : '-.\(.*\)'
return 1
;;
esac
if test "$#" -lt 2
then
Exit 255 "Option \`$1' requires a value."
fi
echo "$2"
return 0
}
badoption=
DIFFCMD=diff
D_option=
br=.br
for OPTION
do
case "${OPTION}" in
-a*)
ADDMARK=$( RequiresArgument "${OPTION}" $2 ) &&
shift
;;
-c*)
CHANGEMARK=$( RequiresArgument "${OPTION}" $2 ) &&
shift
;;
-d*)
DELETEMARK=$( RequiresArgument "${OPTION}" $2 ) &&
shift
;;
-D )
D_option=D_option
;;
-M* )
MARK1=$( RequiresArgument "${OPTION}" $2 ) &&
shift
if [ $# -lt 2 ]
then
Usage "Option \`-M' is missing the MARK2 value."
fi
MARK2=$2
shift
;;
-B )
br=.
;;
-x* )
DIFFCMD=$( RequiresArgument "${OPTION}" $2 ) &&
shift
;;
--version)
echo "GNU ${cmd} (groff) version @VERSION@"
exit 0
;;
--help)
Usage
;;
--)
# What follows -- are file arguments
shift
break
;;
-)
break
;;
-*)
badoption="${cmd}: invalid option \`$1'"
;;
*)
break
;;
esac
shift
done
${DIFFCMD} -Dx /dev/null /dev/null >/dev/null 2>&1 ||
Usage "The \`${DIFFCMD}' program does not accept" \
"the required \`-Dname' option.
Use GNU diff instead. See the \`-x DIFFCMD' option."
if test -n "${badoption}"
then
Usage "${badoption}"
fi
if test "$#" -lt 2 -o "$#" -gt 3
then
Usage "Incorrect number of arguments."
fi
if test "1$1" = 1- -a "2$2" = 2-
then
Usage "Both FILE1 and FILE2 are \`-'."
fi
FILE1=$1
FILE2=$2
FileRead 1 "${FILE1}"
FileRead 2 "${FILE2}"
if test "$#" = 3
then
case "$3" in
-)
# output goes to standard output
;;
*)
# output goes to a file
WouldClobber "${FILE1}" FILE1 "$3"
WouldClobber "${FILE2}" FILE2 "$3"
FileCreate 3 "$3"
exec >$3
;;
esac
fi
# To make a very unlikely label even more unlikely ...
label=__diffmk_$$__
sed_script='
/^#ifdef '"${label}"'/,/^#endif \/\* '"${label}"'/ {
/^#ifdef '"${label}"'/ s/.*/.mc '"${ADDMARK}"'/
/^#endif \/\* '"${label}"'/ s/.*/.mc/
p
d
}
/^#ifndef '"${label}"'/,/^#endif \/\* [!not ]*'"${label}"'/ {
/^#else \/\* '"${label}"'/,/^#endif \/\* '"${label}"'/ {
/^#else \/\* '"${label}"'/ s/.*/.mc '"${CHANGEMARK}"'/
/^#endif \/\* '"${label}"'/ s/.*/.mc/
p
d
}
/^#endif \/\* \(not\|!\) '"${label}"'/ {
s/.*/.mc '"${DELETEMARK}"'/p
a\
.mc
}
d
}
p
'
if [ ${D_option} ]
then
sed_script='
/^#ifdef '"${label}"'/,/^#endif \/\* '"${label}"'/ {
/^#ifdef '"${label}"'/ s/.*/.mc '"${ADDMARK}"'/
/^#endif \/\* '"${label}"'/ s/.*/.mc/
p
d
}
/^#ifndef '"${label}"'/,/^#endif \/\* [!not ]*'"${label}"'/ {
/^#ifndef '"${label}"'/ {
i\
'"${MARK1}"'
d
}
/^#else \/\* '"${label}"'/ ! {
/^#endif \/\* [!not ]*'"${label}"'/ ! {
p
d
}
}
/^#else \/\* '"${label}"'/,/^#endif \/\* '"${label}"'/ {
/^#else \/\* '"${label}"'/ {
i\
'"${MARK2}"'\
'"${br}"'
s/.*/.mc '"${CHANGEMARK}"'/
a\
.mc '"${CHANGEMARK}"'
d
}
/^#endif \/\* '"${label}"'/ s/.*/.mc/
p
d
}
/^#endif \/\* \(not\|!\) '"${label}"'/ {
i\
'"${MARK2}"'\
'"${br}"'
s/.*/.mc '"${DELETEMARK}"'/p
a\
.mc
}
d
}
p
'
fi
diff -D"${label}" -- ${FILE1} ${FILE2} |
sed -n "${sed_script}"
# EOF

11
contrib/groff/contrib/gdiffmk/tests/file1 Normal file
View File

@ -0,0 +1,11 @@
.ll 25
.pl 20
.nf
file1 and file2 #1
file1 only
file1 and file2 #2
file1 and file2 #3
file1 only
file1 only
file1 and file2 #4
file1 and file2 #5

11
contrib/groff/contrib/gdiffmk/tests/file2 Normal file
View File

@ -0,0 +1,11 @@
.ll 25
.pl 20
.nf
file1 and file2 #1
file2 only
file2 only
file1 and file2 #2
file2 only
file1 and file2 #3
file1 and file2 #4
file1 and file2 #5

98
contrib/groff/contrib/gdiffmk/tests/runtests.in Normal file
View File

@ -0,0 +1,98 @@
#! /bin/sh
# A very simple function test for gdiffmk.sh.
srcdir=@srcdir@
command=../gdiffmk
# Test the number of arguments and the first argument.
case $#-$1 in
1-clean )
rm -fv test_result* tmp_file*
exit 0
;;
1-run )
;;
* )
echo >&2 "$0 [ clean | run ]
Run a few simple tests on \`${command}'."'
clean Remove the test_result? and tmp_file? files.
run Run the tests.
'
exit 255
;;
esac
function TestResult {
if cmp -s $1 $2
then
echo $2 PASSED
else
echo ''
echo $2 TEST FAILED
diff $1 $2
echo ''
fi
}
tmpfile=/tmp/$$
trap 'rm -f ${tmpfile}' 0 1 2 3 15
# Run tests.
# 3 file arguments
ResultFile=test_result1
${command} ${srcdir}/file1 ${srcdir}/file2 ${ResultFile} 2>${tmpfile}
cat ${tmpfile} >>${ResultFile}
TestResult ${srcdir}/test_baseline ${ResultFile}
# OUTPUT to stdout by default
ResultFile=test_result2
${command} ${srcdir}/file1 ${srcdir}/file2 >${ResultFile} 2>&1
TestResult ${srcdir}/test_baseline ${ResultFile}
# OUTPUT to stdout via - argument
ResultFile=test_result3
${command} ${srcdir}/file1 ${srcdir}/file2 - >${ResultFile} 2>&1
TestResult ${srcdir}/test_baseline ${ResultFile}
# FILE1 from standard input via - argument
ResultFile=test_result4
${command} - ${srcdir}/file2 <${srcdir}/file1 >${ResultFile} 2>&1
TestResult ${srcdir}/test_baseline ${ResultFile}
# FILE2 from standard input via - argument
ResultFile=test_result5
${command} ${srcdir}/file1 - <${srcdir}/file2 >${ResultFile} 2>&1
TestResult ${srcdir}/test_baseline ${ResultFile}
# Different values for addmark, changemark, deletemark
ResultFile=test_result6
${command} -aA -cC -dD ${srcdir}/file1 ${srcdir}/file2 >${ResultFile} 2>&1
TestResult ${srcdir}/test_baseline6 ${ResultFile}
# Test for accidental file overwrite.
ResultFile=test_result7
cp ${srcdir}/file2 tmp_file7
${command} -aA -dD -cC ${srcdir}/file1 tmp_file7 tmp_file7 \
>${ResultFile} 2>&1
TestResult ${srcdir}/test_baseline7 ${ResultFile}
# Test -D option
ResultFile=test_result8
${command} -D ${srcdir}/file1 ${srcdir}/file2 >${ResultFile} 2>&1
TestResult ${srcdir}/test_baseline8 ${ResultFile}
# Test -D and -M options
ResultFile=test_result9
${command} -D -M '<<<<' '>>>>' \
${srcdir}/file1 ${srcdir}/file2 >${ResultFile} 2>&1
TestResult ${srcdir}/test_baseline9 ${ResultFile}
# Test -D and -B options
ResultFile=test_result10
${command} -D -B ${srcdir}/file1 ${srcdir}/file2 >${ResultFile} 2>&1
TestResult ${srcdir}/test_baseline10 ${ResultFile}
# EOF

17
contrib/groff/contrib/gdiffmk/tests/test_baseline Normal file
View File

@ -0,0 +1,17 @@
.ll 25
.pl 20
.nf
file1 and file2 #1
.mc |
file2 only
file2 only
.mc
file1 and file2 #2
.mc +
file2 only
.mc
file1 and file2 #3
.mc *
.mc
file1 and file2 #4
file1 and file2 #5

26
contrib/groff/contrib/gdiffmk/tests/test_baseline10 Normal file
View File

@ -0,0 +1,26 @@
.ll 25
.pl 20
.nf
file1 and file2 #1
[[
file1 only
]]
.
.mc |
file2 only
file2 only
.mc
file1 and file2 #2
.mc +
file2 only
.mc
file1 and file2 #3
[[
file1 only
file1 only
]]
.
.mc *
.mc
file1 and file2 #4
file1 and file2 #5

17
contrib/groff/contrib/gdiffmk/tests/test_baseline6 Normal file
View File

@ -0,0 +1,17 @@
.ll 25
.pl 20
.nf
file1 and file2 #1
.mc C
file2 only
file2 only
.mc
file1 and file2 #2
.mc A
file2 only
.mc
file1 and file2 #3
.mc D
.mc
file1 and file2 #4
file1 and file2 #5

2
contrib/groff/contrib/gdiffmk/tests/test_baseline7 Normal file
View File

@ -0,0 +1,2 @@
gdiffmk: The FILE2 and OUTPUT arguments both point to the same file,
gdiffmk: `tmp_file7', and it would be overwritten.

26
contrib/groff/contrib/gdiffmk/tests/test_baseline8 Normal file
View File

@ -0,0 +1,26 @@
.ll 25
.pl 20
.nf
file1 and file2 #1
[[
file1 only
]]
.br
.mc |
file2 only
file2 only
.mc
file1 and file2 #2
.mc +
file2 only
.mc
file1 and file2 #3
[[
file1 only
file1 only
]]
.br
.mc *
.mc
file1 and file2 #4
file1 and file2 #5

26
contrib/groff/contrib/gdiffmk/tests/test_baseline9 Normal file
View File

@ -0,0 +1,26 @@
.ll 25
.pl 20
.nf
file1 and file2 #1
<<<<
file1 only
>>>>
.br
.mc |
file2 only
file2 only
.mc
file1 and file2 #2
.mc +
file2 only
.mc
file1 and file2 #3
<<<<
file1 only
file1 only
>>>>
.br
.mc *
.mc
file1 and file2 #4
file1 and file2 #5

19
contrib/groff/contrib/grap2graph/Makefile.sub Normal file
View File

@ -0,0 +1,19 @@
MAN1=grap2graph.n
CLEANADD=grap2graph
all: grap2graph
grap2graph: grap2graph.sh
rm -f $@; \
sed -e "s|@g@|$(g)|g" \
-e "s|@VERSION@|$(version)$(revision)|" \
-e $(SH_SCRIPT_SED_CMD) $(srcdir)/grap2graph.sh >$@; \
chmod +x $@
install_data: grap2graph
-test -d $(bindir) || $(mkinstalldirs) $(bindir)
-rm -f $(bindir)/grap2graph
$(INSTALL_SCRIPT) grap2graph $(bindir)/grap2graph
uninstall_sub:
-rm -f $(bindir)/grap2graph

105
contrib/groff/contrib/grap2graph/grap2graph.man Normal file
View File

@ -0,0 +1,105 @@
.\" $Id: grap2graph.man,v 1.3 2003/10/28 07:46:23 wlemb Exp $
.\" This documentation is released to the public domain.
.
.
.TH GRAP2GRAPH @MAN1EXT@ "@MDATE@" "Groff Version @VERSION@"
.IX grap2graph
.SH NAME
grap2graph \- convert a grap diagram into a cropped bitmap image
.
.
.SH SYNOPSIS
.B grap2graph
[
.B \-unsafe
]
[
.BI \-resolution\ M\fR|\fPMxN
]
[
.BI \-format\ fmt
]
.
.
.SH DESCRIPTION
Reads a grap program as input; produces an image file (by default in
Portable Network Graphics format) suitable for the Web as output.
For a description of the grap language, see
.BR grap (1).
.P
Your graph specification should \fInot\fR be wrapped with the \&.G1 and
\&.G2 macros that normally guard it within
.BR groff (@MAN1EXT@)
macros.
.P
The output image will be a black-on-white graphic clipped to the
smallest possible bounding box that contains all the black pixels.
By specifying command-line options to be passed to
.BR convert (1)
you can give it a border, set the background transparent, set the
image's pixel density, or perform other useful transformations.
.P
This program uses
.BR grap (1),
.BR @g@pic (@MAN1EXT@),
.BR groff (@MAN1EXT@),
and the ImageMagick
.BR convert (1)
program.
These programs must be installed on your system and accessible on your
$PATH for \fBgrap2graph\fR to work.
.
.
.SH OPTIONS
.TP
.B \-unsafe
Run
.BR @g@pic (@MAN1EXT@)
and
.BR groff (@MAN1EXT@)
in the `unsafe' mode enabling the PIC macro
.B sh
to execute arbitrary commands.
The default is to forbid this.
.TP
.BI \-format\ fmt
Specify an output format; the default is PNG (Portable Network Graphics).
Any format that
.BR convert (1)
can emit is supported.
.PP
Command-line switches and arguments not listed above are passed to
.BR convert (1).
.
.
.SH ENVIRONMENT
.TP
.B GROFF_TMPDIR
The directory in which temporary files will be created.
If this is not set
.B grap2graph
searches the environment variables
.BR \%TMPDIR ,
.BR TMP ,
and
.B TEMP
(in that order).
Otherwise, temporary files will be created in
.BR /tmp .
.
.
.SH "SEE ALSO"
.BR pic2graph (@MAN1EXT@),
.BR eqn2graph (@MAN1EXT@),
.BR @g@pic (@MAN1EXT@),
.BR groff (@MAN1EXT@),
.BR gs (1),
.BR convert (1).
.
.
.SH AUTHOR
Eric S. Raymond <esr@thyrsus.com>
.
.\" Local Variables:
.\" mode: nroff
.\" End:

85
contrib/groff/contrib/grap2graph/grap2graph.sh Normal file
View File

@ -0,0 +1,85 @@
#! /bin/sh
#
# grap2graph -- compile graph description descriptions to bitmap images
#
# by Eric S. Raymond <esr@thyrsus.com>, May 2003
#
# In Unixland, the magic is in knowing what to string together...
#
# Take grap description on stdin, emit cropped bitmap on stdout.
# The pic markup should *not* be wrapped in .G1/.G2, this script will do that.
# A -U option on the command line enables gpic/groff "unsafe" mode.
# A -format FOO option changes the image output format to any format
# supported by convert(1). All other options are passed to convert(1).
# The default format is PNG.
#
# Requires the groff suite and the ImageMagick tools. Both are open source.
# This code is released to the public domain.
#
# Here are the assumptions behind the option processing:
#
# 1. None of the options of grap(1) are relevant.
#
# 2. Only the -U option of groff(1) is relevant.
#
# 3. Many options of convert(1) are potentially relevant, (especially
# -density, -interlace, -transparency, -border, and -comment).
#
# Thus, we pass -U to groff(1), and everything else to convert(1).
#
# $Id: grap2graph.sh,v 1.4 2005/05/18 07:03:06 wl Exp $
#
groff_opts=""
convert_opts=""
format="png"
while [ "$1" ]
do
case $1 in
-unsafe)
groff_opts="-U";;
-format)
format=$2
shift;;
-v | --version)
echo "GNU grap2graph (groff) version @VERSION@"
exit 0;;
--help)
echo "usage: grap2graph [ option ...] < in > out"
exit 0;;
*)
convert_opts="$convert_opts $1";;
esac
shift
done
# create temporary directory
tmp=
for d in "$GROFF_TMPDIR" "$TMPDIR" "$TMP" "$TEMP" /tmp; do
test -z "$d" && continue
tmp=`(umask 077 && mktemp -d -q "$d/grap2graph-XXXXXX") 2> /dev/null` \
&& test -n "$tmp" && test -d "$tmp" \
&& break
tmp=$d/grap2graph$$-$RANDOM
(umask 077 && mkdir $tmp) 2> /dev/null && break
done;
if test -z "$tmp"; then
echo "$0: cannot create temporary directory" >&2
{ (exit 1); exit 1; }
fi
trap 'exit_status=$?; rm -rf $tmp && exit $exit_status' 0 2 15
# Here goes:
# 1. Add .G1/.G2.
# 2. Process through grap(1) to emit pic markup.
# 3. Process through groff(1) with pic preprocessing to emit Postscript.
# 4. Use convert(1) to crop the Postscript and turn it into a bitmap.
(echo ".G1"; cat; echo ".G2") | grap | groff -p $groff_opts -Tps -P-pletter | \
convert -trim -crop 0x0 $convert_opts - $tmp/grap2graph.$format \
&& cat $tmp/grap2graph.$format
# End

1089
contrib/groff/contrib/groffer/ChangeLog
View File

File diff suppressed because it is too large Load Diff

51
contrib/groff/contrib/groffer/Makefile.sub
View File

@ -1,47 +1,60 @@
# Makefile.sub for `groffer' (integration into the groff source tree)
# Makefile.sub for `groffer' (integration into the `groff' source tree)
# File position: <groff-source>/contrib/groffer/Makefile.sub
# Last update: 21 October 2002
# Copyright (C) 2001,2002,2005 Free Software Foundation, Inc.
# Written by Werner Lemberg <wl@gnu.org> and Bernd Warken.
# Copyright (C) 2001,2002 Free Software Foundation, Inc.
# Written by Werner Lemberg <wl@gnu.org>
# Last update: 15 August 2005
# This file is part of groff.
# This file is part of `groffer' which is part of `groff'.
# groff is free software; you can redistribute it and/or modify it
# `groff' is free software; you can redistribute it and/or modify it
# under the terms of the GNU General Public License as published by
# the Free Software Foundation; either version 2, or (at your option)
# any later version.
# groff is distributed in the hope that it will be useful, but WITHOUT
# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
# or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public
# License for more details.
# `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 file COPYING. If not, write to the
# Free Software Foundation, 59 Temple Place - Suite 330, Boston,
# MA 02111-1307, USA.
# along with `groff'; see the files COPYING and LICENSE in the top
# directory of the `groff' source. If not, write to the Free Software
# Foundation, 51 Franklin St - Fifth Floor, Boston, MA 02110-1301, USA.
########################################################################
MAN1=groffer.n
CLEANADD=groffer
# not all make programs have $(RM) predefined.
RM=rm -f
all: groffer
groffer: groffer.sh
rm -f $@; \
sed -e "s|@BINDIR@|$(bindir)|g" \
groffer: groffer.sh groffer2.sh $(SH_DEPS_SED_SCRIPT)
$(RM) $@;
sed -f $(SH_DEPS_SED_SCRIPT) \
-e "s|@g@|$(g)|g" \
-e "s|@BINDIR@|$(bindir)|g" \
-e "s|@libdir@|$(libdir)|g" \
-e "s|@VERSION@|$(version)$(revision)|g" \
-e $(SH_SCRIPT_SED_CMD) $(srcdir)/groffer.sh >$@; \
-e $(SH_SCRIPT_SED_CMD) $(srcdir)/groffer.sh >$@;
chmod +x $@
install_data: groffer
-test -d $(bindir) || $(mkinstalldirs) $(bindir)
-rm -f $(bindir)/groffer
-$(RM) $(bindir)/groffer
$(INSTALL_SCRIPT) groffer $(bindir)/groffer
-test -d $(libdir)/groff/groffer || \
$(mkinstalldirs) $(libdir)/groff/groffer
-$(RM) $(libdir)/groff/groffer/groffer2.sh
$(INSTALL_SCRIPT) $(srcdir)/groffer2.sh \
$(libdir)/groff/groffer/groffer2.sh
uninstall_sub:
-rm -f $(bindir)/groffer
-$(RM) $(bindir)/groffer
-$(RM) $(libdir)/groff/groffer/groffer2.sh
-rmdir $(libdir)/groff/groffer

117
contrib/groff/contrib/groffer/README
View File

@ -1,23 +1,104 @@
The `groffer' program is the easiest way to read `groff' documents.
All input is sent to `grog' and then to `groff' such that no special
`groff' arguments must be determined.
README
`groffer' also has many built-in `man' functionalities to find and
read the manual pages on UNIX and similar operating systems. It
accepts the information from an installed `man' program, but tries to
find a man path by itself if there isn't any.
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.
So far, `groffer' is a shell script. It should run on any POSIX or
Bourne style shell, but it runs the fastest if the `ash' shell is
installed on the system. This shell is found out and started
automatically. There are efforts to port part of the shell script to
C/C++ to increase the speed independent of the shell.
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', 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'
options and then to `groff'. So no special `groff' arguments must be
given. But all `groff' options can be specified when this seems to be
appropriate.
The following displaying modes for the output are available:
- Display formatted input with
-- the X `roff' viewer `gxditview',
-- a Postcript viewer,
-- a PDF viewer,
-- a DVI viewer,
-- a web browser,
-- 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 with `gxditview' as graphical
device in X; on non-X text terminals, the `tty' text mode with a pager
is tried by default.
Compatibility
`groffer' consists of two shell scripts. It should run on any POSIX
or Bourne style shell that supports shell functions. See file
`README_SH' for more information.
Mailing lists
For reporting bugs of `groffer', groff's free mailing list
<bug-groff@gnu.org> can be used. For a general discussion, the
<groff@gnu.org> is more useful; see the `README' file in the top
directory of the `groff' source package for more details on this
mailing list.
<bug-groff@gnu.org> can be used.
`groffer' is a `groff contrib' project that was written by Bernd
Warken <bwarken@mayn.de>.
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: 2 August 2005
Copyright (C) 2003,2004,2005 Free Software Foundation, Inc.
Written by Bernd Warken
This file is part of `groffer', which is part of `groff'.
`groff' is free software; you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2, or (at your option)
any later version.
`groff' is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
for more details.
You should have received a copy of the GNU General Public License
along with `groff'; see the files COPYING and LICENSE in the top
directory of the `groff' source. If not, write to the Free Software
Foundation, 51 Franklin St - Fifth Floor, Boston, MA 02110-1301, USA.
####### Emacs settings
Local Variables:
mode: text
End:

268
contrib/groff/contrib/groffer/README_SH Normal file
View File

@ -0,0 +1,268 @@
Additional description for the shell version of `groffer'
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 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 sending kill signals, see $_PROCESS_ID
and error().
Function Definitions in `groffer2.sh'
Each funtion in groffer2.sh has a description that starts with the
function name and symbols for its arguments in paranthesis `()'. Each
`<>' construction gives an argument name that just gives a hint on
what the argument is meant to be; these argument names are otherwise
irrelevant. The `>' sign can be followed by another character that
shows how many of these arguments are possible.
<arg> exactly 1 of this argument
<arg>? 0 or 1 of these arguments
<arg>* arbitrarily many such arguments, incl. none
<arg>+ one or more such arguments
<arg>... one or more such arguments
[...] optional arguments
A function that starts with an underscore `_' is an internal function
for some other function. The internal functions are defined just
after their corresponding function.
External Environment Variables
The groffer.sh script uses the following external system variables.
It is supposed that these variables are already exported outside of
groffer.sh; otherwise they do not have a value within the script.
external system environment variables that are explicitly used
$DISPLAY: Presets the X display.
$LANG: For language specific man pages.
$LC_ALL: For language specific man pages.
$LC_MESSAGES: For language specific man pages.
$PAGER: Paging program for tty mode.
$PATH: Path for the programs called (`:' separated list).
groffer native environment variables
$GROFFER_OPT preset options for groffer.
all groff environment variables are used, see groff(1)
$GROFF_BIN_PATH: Path for all groff programs.
$GROFF_COMMAND_PREFIX: '' (normally) or 'g' (several troffs).
$GROFF_FONT_PATH: Path to non-default groff fonts.
$GROFF_TMAC_PATH: Path to non-default groff macro files.
$GROFF_TMPDIR: Directory for groff temporary files.
$GROFF_TYPESETTER: Preset default device.
all GNU man environment variables are used, see man(1).
$MANOPT: Preset options for man pages.
$MANPATH: Search path for man pages (: list).
$MANROFFSEQ: Ignored because of grog guessing.
$MANSECT: Search man pages only in sections (:).
$SYSTEM: Man pages for different OS's (, list).
Object-oriented Functions
The groffer script provides an object-oriented construction (OOP). In
object-oriented terminology, a type of object is called a `class'; a
function that handles objects from a class is named `method'.
In the groffer script, the object is a variable name whose content is
the object's data. Methods are functions that have an object as first
argument.
The basic functions for object handling are obj_*().
The class `list' represents an array structure, see list_*().
Shell Compatibility
The `groffer' shell scripts are compatible to both the GNU and the
POSIX shell and utilities. Care was taken to restrict the programming
technics used here in order to achieve POSIX compatibility as far back
as POSIX P1003.2 Draft 11.2 of September 1991. This draft is
available at http://www.funet.fi/pub/doc/posix/p1003.2/d11.2 in the
internet.
The POSIX draft does not include `local' variables for functions. So
this concept was replaced by global variables with a prefix that
differs for each function. The prefix is chosen from the function
name. These quasi-local variables are unset before each return of the
function.
The `groffer' scripts were tested under the shells `ash', `bash',
`bash-minimal', `dash', 'ksh', `mksh', `pdksh', 'posh', and `zsh'
without problems in Linux Debian. A shell can be tested by the
`groffer' option `--shell', but that will run only with groffer2.sh.
To start it directly from the beginning under this shell the following
command can be used.
<shell-name> groffer.sh --shell=<shell-name> <argument>...
Some shells are not fully POSIX compatible. For them the following
restrictions were done. For more information look at the
documentation `Portable shells' in the `info' page of `autoconf'
(look-up in Emacs-Help-Manuals_Info).
- The command parts `then', `else', and `do' must be written each on a
line of their own.
- Replace `for i in "$@"' by `for i' and remove internal `;' (kah).
- Replace `set -- ...' by `set x ...; shift'. After the first
non-option argument, all arguments including those starting with `-'
are accepted as non-option. For variables or `$()' constructs with
line-breaks, use `eval set' without quotes. That transforms a
line-break within a variable to a space.
- The name of the variable in `for' is chosen as a single character
(old ash). The content of such variables is not safe because it can
also occur in other functions. So it is often stored in an
additional quasi-local variable.
- `echo' is not portable on options; some `echo' commands have many
options, others have none. So `echo -n' cannot be used, such that
the output of each function has complete lines. There are two
methods to avoid having `-' as the first character of any argument.
Either a character such as `x' can be prepended to the argument;
this must later on be removed by `sed'. Otherwise, `echo' can be
replaced by `cat <<EOF'.
- `ls' has problems. Old UNIX systems echoed the error message to
standard output. So handle the output with `sed'. If the output
contains `not found' map it to an empty string.
- As `test -e' is not available in Solaris 2.5 replace it by
`test -f || test -d'.
- As `unset' is not supported by all shells replace it by `eval
${_UNSET}' where this variable is `unset' if it exists and `:'
otherwise.
- Some shells have problems with options in `eval'. So quoting must
be done right to hide the options from `eval'.
- In backquote calls `` avoid the backquote ` in comments.
- Replace `true' by `:', `false' isn't used.
- Do not redefine builtins as functions (ash).
- Avoid `[^...]' in `case' patterns (ash).
- `trap' does not allow error code 127.
The scripts call the following commands with all options used:
.
:
apropos
break
bzip2 -c -d -t
cat
catz
cd
continue
echo
eval
expr
grep
groff -v
grog -T -X -Z
gs -c -d -f -q -s
gzip -c -d -f
less -r -R
ls
man -k --apropos
mkdir
mv
pwd
return
rm -f -r
rmdir
sed -e -n
set -e
sh -c
shift
test -c -d -f -r -s -w -x
trap
umask
unset
Bugs
If the `groffer' run is interrupted by Crtl-C the clean up is not done
by all shells. The `trap' commands work for the shells `bash',
`bash-minimal', and 'ksh'; they do not work for `ash', `dash',
`pdksh', `posh', and `zsh'.
####### License
Last update: 19 August 2005
Copyright (C) 2003,2004,2005 Free Software Foundation, Inc.
Written by Bernd Warken
This file is part of `groffer', which is part of `groff'.
`groff' is free software; you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2, or (at your option)
any later version.
`groff' is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public
License for more details.
You should have received a copy of the GNU General Public License
along with `groff'; see the files COPYING and LICENSE in the top
directory of the `groff' source. If not, write to the Free Software
Foundation, 51 Franklin St - Fifth Floor, Boston, MA 02110-1301, USA.
####### Emacs settings
Local Variables:
mode: text
End:

98
contrib/groff/contrib/groffer/TODO
View File

@ -1,56 +1,58 @@
# TODO file for `groffer'
TODO file for `groffer'
# File position: <groff-source>/contrib/groffer/TODO
File position: <groff-source>/contrib/groffer/TODO
# Last update: 22 Jan 2003
# Copyright (C) 2001,2002,2003 Free Software Foundation, Inc.
# Written by Bernd Warken <bwarken@mayn.de>
# This file is part of groff.
# groff is free software; you can redistribute it and/or modify it
# under the terms of the GNU General Public License as published by
# the Free Software Foundation; either version 2, or (at your option)
# any later version.
# groff is distributed in the hope that it will be useful, but WITHOUT
# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
# or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public
# License for more details.
# You should have received a copy of the GNU General Public License
# along with groff; see the file COPYING. If not, write to the
# Free Software Foundation, 59 Temple Place - Suite 330, Boston,
# MA 02111-1307, USA.
########################################################################
TODO
Optimization:
- Optimize man path determination in manpath_add_lang_sys() for speed
by building-up the man path only by and by as far as necessary
(not trivial).
- To increase the running speed write part of the groffer shell script
in C/C++.
Features:
- Revise option handling of `grog'.
- `gxditview' needs a complete shower.
####### TODO
Revision:
- Should there be a native implementation for `--apropos'?
- Revise the `--all' feature to better reflect GNU man.
- The debug function stack is buggy (no effect on normal operation).
- The actual `groff' and `grog' do not support file arguments each
of which has a different macro package (except `man' and `doc'). So
`roffer' should create several display files for such arguments.
Optimization:
- Optimize `man' path determination in manpath_add_lang_sys() for speed
by building-up the `man' path only by and by as far as necessary
(not trivial).
- To increase the running speed write part of the `groffer' shell
script in C/C++.
Features of external programs:
- Revise option handling of `grog'.
Documentation:
- Improve the documentation of the search algorithm for man pages in
both the groffer script and the man page `groffer.man'.
- In `groff.man', add more documentation for parts that were taken over
from GNU `man'.
- Improve the documentation of the search algorithm for `man' pages in
both the `groffer' scripts and the `man' page `groffer.man'.
- In `groffer.man', add more documentation for parts that were taken
over from GNU `man'.
- The documentation in the headers for some function definitions in
`groffer.sh' needs to be updated.
`groffer2.sh' needs to be updated.
####### License
Last update: 16 August 2005
Copyright (C) 2003,2004,2005 Free Software Foundation, Inc.
Written by Bernd Warken
This file is part of `groffer', which is part of `groff'.
`groff' is free software; you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2, or (at your option)
any later version.
`groff' is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public
License for more details.
You should have received a copy of the GNU General Public License
along with `groff'; see the files COPYING and LICENSE in the top
directory of the `groff' source. If not, write to the Free Software
Foundation, 51 Franklin St - Fifth Floor, Boston, MA 02110-1301, USA.
####### Emacs settings
Local Variables:
mode: text
End:

3757
contrib/groff/contrib/groffer/groffer.man
View File

File diff suppressed because it is too large Load Diff

4634
contrib/groff/contrib/groffer/groffer.sh
View File

File diff suppressed because it is too large Load Diff

5854
contrib/groff/contrib/groffer/groffer2.sh Normal file
View File

File diff suppressed because it is too large Load Diff

34
contrib/groff/contrib/mm/ChangeLog
View File

@ -1,3 +1,37 @@
Thu May 26 08:23:40 2005 Werner LEMBERG <wl@gnu.org>
* m.tmac: Load devtag.tmac.
Wed Mar 16 06:56:02 2005 Larry Kollar <kollar@alltel.net>
Add rudimentary support for grohtml.
* m.tmac (H): Call DEVTAG-NH and DEVTAG-EO-H.
(pg@enable-trap, pg@header): Do nothing for devhtml.
Sun Mar 7 16:34:46 2004 Jeff Conrad <jeff_conrad@msn.com>
* m.tmac (S): Improve debug message.
Wed Mar 05:38:57 2004 Joergen Haegg <jh@axis.com>
* Changed default value for Hy in manual to 0
* Check Hy at each new page
Mon Mar 1 22:16:38 2004 Jeff Conrad <jeff_conrad@msn.com>
* m.tmac (S): Fix scaling indicator for vertical spacing.
Tue Nov 05:14:45 2003 Joergen Haegg <jh@axis.com>
* another patch from ulrich lauther to fix the
TOC up to 14 heading levels.
Mon Oct 13:48:25 2003 Joergen Haegg <jh@axis.com>
* problem with more than 7 levels of headings fixed with
patch from ulrich lauther.
Wed Apr 06:42:35 2003 Joergen Haegg <jh@axis.com>
* the footer was not adjusted by VM due to a missing

28
contrib/groff/contrib/mm/groff_mm.man
View File

@ -1,5 +1,5 @@
.\"
.\" $Id: groff_mm.man,v 2.9 2003/03/19 22:05:11 wlemb Exp $
.\" $Id: groff_mm.man,v 2.13 2004/07/03 12:46:56 wlemb Exp $
.\"
.de T2
.if t .ne 2v
@ -7,12 +7,14 @@
\\$1
.sp -1
..
.
.de T3
.if t .ne 2v
.ti -.5i
\fB\\$1\fP
.br
..
.
.TH GROFF_MM @MAN7EXT@ "@MDATE@" "Groff Version @VERSION@"
.SH NAME
groff_mm \- groff mm macros
@ -612,7 +614,7 @@ See \fBINITR\fP.
.TP
.B "H level [heading-text [heading-suffix]]"
Numbered section heading.
Section headers can have a level between 1 and 7, level 1 is the
Section headers can have a level between 1 and 14, level 1 is the
top level.
The text is given in \fIheading-text\fP, and must be
surrounded by double quotes if it contains spaces.
@ -679,8 +681,8 @@ is centerered.
The font of each heading level is controlled by string \fBHF\fP.
It contains a fontnumber or fontname for each level.
Default
is \fB2\ 2\ 2\ 2\ 2\ 2\ 2\fP (all headings in italic).
Could also be written as \fBI\ I\ I\ I\ I\ I\ I\fP.
is \fB2\ 2\ 2\ 2\ 2\ 2\ 2\ 2\ 2\ 2\ 2\ 2\ 2\ 2\fP (all headings in italic).
Could also be written as \fBI\ I\ I\ I\ I\ I\ I\ I\ I\ I\ I\ I\ I\ I\fP.
Note that some other implementations use \fB3\ 3\ 2\ 2\ 2\ 2\ 2\fP as the
default value.
All omitted values are presumed to be a 1.
@ -690,7 +692,7 @@ All omitted values are presumed to be a 1.
String \fBHP\fP controls the pointsize of each heading, in the
same way as \fBHF\fP controls the font.
A value of 0 selects the default point size.
Default value is \fB0\ 0\ 0\ 0\ 0\ 0\ 0\fP.
Default value is \fB0\ 0\ 0\ 0\ 0\ 0\ 0\ 0\ 0\ 0\ 0\ 0\ 0\ 0\fP.
Beware that only the
point size changes, not the vertical size.
That can be controlled by the user specified macro \fBHX\fP and/or
@ -698,7 +700,7 @@ That can be controlled by the user specified macro \fBHX\fP and/or
.sp
\fBHeading counters\fP
.br
Seven number registers, named \fBH1\fP thru \fBH7\fP contains
Fourteen number registers, named \fBH1\fP thru \fBH14\fP contains
the counter for each heading level.
The values are printed using arabic numerals, this can be changed
with the macro \fBHM\fP (see below).
@ -771,7 +773,7 @@ Resets to the default if called without argument.
Hyphenation can be turned off by setting number
register \fBHy\fP to 0 in the beginning of the file.
.TP
.B "HM [arg1 [arg2 [... [arg7]]]]"
.B "HM [arg1 [arg2 [... [arg14]]]]"
Heading mark style.
Controls the type of marking for printing of the heading counters.
Default is 1 for all levels.
@ -1276,7 +1278,7 @@ the header in letters or other special texts.
This macro must be used before any text to inhibit the pageheader
on the first page.
.TP
.B PIC [-L] [-C] [-R] [-I n] filename [width [height]]
.B "PIC [-L] [-C] [-R] [-I n] filename [width [height]]"
\fBPIC\fP includes a Postscript file in the document.
The macro depends on \fBmmroff\fP and \fBINITR\fP.
\fB-L\fP, \fB-C\fP, \fB-R\fP and \fB-I n\fP adjusts the picture
@ -1803,7 +1805,7 @@ No output will occur if \fBAph\fP is zero, but there will always
be an appendix-entry in the 'List of contents'.
.TP
.B Cl
Contents level [0:7], contents saved if heading level <= Cl, default 2.
Contents level [0:14], contents saved if heading level <= Cl, default 2.
.TP
.B Cp
Eject page between LIST OF XXXX if Cp == 0, default 0.
@ -1850,10 +1852,10 @@ just before the page break.
Useful in user defined header macros.
.TP
.B Hb
Heading break level [0:7], default\ 2.
Heading break level [0:14], default\ 2.
.TP
.B Hc
Heading centering level, [0:7].
Heading centering level, [0:14].
Default\ 0.
.TP
.B Hi
@ -1885,7 +1887,7 @@ is less than or equal to \fBHps\fP.
Value is in units, normally\ 1.
.TP
.B Hs
Heading space level [0:7], default\ 2.
Heading space level [0:14], default\ 2.
.TP
.B Hss
This is the number of lines that follows \fB.H\fP when the heading-level
@ -1902,7 +1904,7 @@ Heading numbering type, default 0.
Unnumbered heading level, default 2.
.TP
.B Hy
Hyphenation in body, default 1.
Hyphenation in body, default 0.
.br
0\ ->\ no hyphenation
.br

60
contrib/groff/contrib/mm/m.tmac
View File

@ -3,11 +3,12 @@
.ds RE \\$2
..
.\"
.\" $Id: m.tmac,v 2.18 2003/04/02 04:44:59 jhaegg Exp $
.@revision $Revision: 2.18 $
.\" $Id: m.tmac,v 2.26 2005/05/26 06:28:38 wl Exp $
.@revision $Revision: 2.26 $
.ig
Copyright (C) 1991-2000 Free Software Foundation, Inc.
Copyright (C) 1991-2000, 2001, 2002, 2003, 2004, 2005
Free Software Foundation, Inc.
mgm is written by Jörgen Hägg <jh@axis.com>
mgm is free software; you can redistribute it and/or modify it under
@ -36,8 +37,9 @@ Index array!index
.do if d PH .nx
.if \n(.C .ab The groff mm macros do not work in compatibility mode.
.if (\n[.warn] == 65543) .warn
.mso devtag.tmac
.\" ######## init #######
.\" Contents level [0:7], contents saved if heading level <= Cl
.\" Contents level [0:14], contents saved if heading level <= Cl
.nr Cl 2
.\" Eject page between LIST OF XXXX if Cp == 0
.nr Cp 0
@ -66,20 +68,27 @@ Index array!index
.nr H5 0 1
.nr H6 0 1
.nr H7 0 1
.\" Heading break level [0:7]
.nr H8 0 1
.nr H9 0 1
.nr H10 0 1
.nr H11 0 1
.nr H12 0 1
.nr H13 0 1
.nr H14 0 1
.\" Heading break level [0:14]
.nr Hb 2
.\" heading centering level, [0:7]
.\" heading centering level, [0:14]
.nr Hc 0
.\" header format
.ds HF 2 2 2 2 2 2 2
.ds HF 2 2 2 2 2 2 2 2 2 2 2 2 2 2
.\" heading temp. indent [0:2]
.\" 0 -> 0 indent, left margin
.\" 1 -> indent to right , like .P 1
.\" 2 -> indent to line up with text part of preceding heading
.nr Hi 1
.\" header pointsize
.ds HP 0 0 0 0 0 0 0
.\" heading space level [0:7]
.ds HP 0 0 0 0 0 0 0 0 0 0 0 0 0 0
.\" heading space level [0:14]
.nr Hs 2
.\" heading numbering type
.\" 0 -> multiple (1.1.1 ...)
@ -637,15 +646,21 @@ in=\\n[.i] fi=\\n[.u] .d=\\n[.d] nl=\\n[nl] pg=\\n[%]
.if !'\\*[misc*b]'C' \{\
. ie '\\*[misc*b]'P' .vs \\n[misc*S-vs]u
. el \{\
. ie '\\*[misc*b]'D' .vs \\n[.ps]u+2p
. ie '\\*[misc*b]'D' .vs \\n[.ps]s+2p
. el .vs \\*[misc*b]
. if \\n[D]>2 .tm S: .vs \\*[misc*b]
. \}
.\}
.nr @ps \\n[.ps]
.nr @psu \\n[.ps]s
.nr @vs \\n[.v]
.nr @vsp \\n[.v]u/1p
.nr @res 1i
.\"
.if \\n[D]>1 .tm S(\\$*): ma:\\*[misc*a], mb:\\*[misc*b] => ps:\\n[@ps]u, vs:\\n[@vs]u
.if \\n[D]>1 \{\
. tmc "S(\\$*): ma:\\*[misc*a], mb:\\*[misc*b]
. tm1 " => ps:\\n[.s]p (\\n[@psu]u), vs:\\n[@vsp]p (\\n[@vs]u) (res:\\n[@res])
.\}
.nr misc*S-ps \\n[misc*S-ps1]
.nr misc*S-vs \\n[misc*S-vs1]
.nr misc*S-ps1 \\n[@ps]
@ -930,7 +945,7 @@ in=\\n[.i] fi=\\n[.u] .d=\\n[.d] nl=\\n[nl] pg=\\n[%]
.\"
.\" clear lower counters
.nr hd*i 1 1
.while \\n+[hd*i]<8 .if \\n[hd*level]<\\n[hd*i] .nr H\\n[hd*i] 0 1
.while \\n+[hd*i]<15 .if \\n[hd*level]<\\n[hd*i] .nr H\\n[hd*i] 0 1
.\"
.\" save last text for use in TP
.if \\n[hd*level]=1 .ds H1txt \\$2\\$3
@ -962,7 +977,7 @@ in=\\n[.i] fi=\\n[.u] .d=\\n[.d] nl=\\n[nl] pg=\\n[%]
.if \\n[hd*level]>1 .as hd*mark \\n[H2]
.\"
.nr hd*i 2 1
.while \\n+[hd*i]<8 .if \\n[hd*level]>(\\n[hd*i]-1) .as hd*mark .\\n[H\\n[hd*i]]
.while \\n+[hd*i]<15 .if \\n[hd*level]>(\\n[hd*i]-1) .as hd*mark .\\n[H\\n[hd*i]]
.if \\n[Ht] .ds hd*mark \\n[H\\n[hd*level]].
.\"
.\" special case, no dot after level one heading if not H1dot true
@ -1025,6 +1040,7 @@ in=\\n[.i] fi=\\n[.u] .d=\\n[.d] nl=\\n[nl] pg=\\n[%]
.\"---------- user macro HY -------------
.\" user macro to reset indents
.if d HY .HY \\n[hd*level] \\n[hd*arg1] "\\$2\\$3"
.DEVTAG-NH \\n[hd*level] \" HTML: mark beginning of heading
.\"--------------------------------------
.nr hd*mark-size \w@\\*[hd*mark]@
.if (\\n[hd*level]<=\\n[Hc])&\\n[hd*htype] .ce\" center if level<=Hc
@ -1072,11 +1088,12 @@ in=\\n[.i] fi=\\n[.u] .d=\\n[.d] nl=\\n[nl] pg=\\n[%]
.nr hd*last-pos \\n[nl]
.nr hd*last-hsize \\n[.k]
.nr par@ind-flag 0
.DEVTAG-EO-H \" HTML: end of heading
..
.\"--------
.de HM
.nr hd*i 0 1
.while \\n+[hd*i]<8 .af H\\n[hd*i] \\$[\\n[hd*i]] 1
.while \\n+[hd*i]<15 .af H\\n[hd*i] \\$[\\n[hd*i]] 1
..
.\"----------------------
.\" set page-nr, called from header
@ -1134,9 +1151,12 @@ in=\\n[.i] fi=\\n[.u] .d=\\n[.d] nl=\\n[nl] pg=\\n[%]
.if \\n[D]>2 .tm pg*last-pos \\n[@pl]u-(\\n[pg*block-size]u+\\n[pg*foot-margin]u+\\n[pg*footer-size]u+\\n[pg*extra-footer-size]u) = \\n[pg*last-pos]
..
.de pg@enable-trap
.\" Disable in HTML mode
.if !'\*[.T]'html' \{\
.wh \\n[pg*foot-trap]u pg@footer
.if \\n[D]>2 .tm pg@enable-trap .t=\\n[.t] nl=\\n[nl]
.if \\n[D]>2 .ptr
.\}
..
.de pg@disable-trap
.ch pg@footer
@ -1185,7 +1205,12 @@ in=\\n[.i] fi=\\n[.u] .d=\\n[.d] nl=\\n[nl] pg=\\n[%]
.\"------------------------------------------------------------
.\" HEADER
.de pg@header
.\" Disable in HTML mode
.if !'\*[.T]'html' \{\
.if \\n[D]>1 .tm Page# \\n[%] (\\n[.F]:\\n[c.])
.\" check if Hy has been changed
.ie \\n[Hy] 'hy 14
.el 'nh
.if \\n[Idxf] \{\
.tl '<pagenr\ \\n[%]>'''
.\}
@ -1241,6 +1266,7 @@ in=\\n[.i] fi=\\n[.u] .d=\\n[.d] nl=\\n[nl] pg=\\n[%]
.\}
.if \\n[pg*top-enabled]<0 .nr pg*top-enabled 1
.nr hd*cur-bline \\n[nl] \" .H needs to know if output has occured
.\}
..
.\"---------------------------------------------------------
.\" FOOTER
@ -2426,8 +2452,8 @@ in=\\n[.i] fi=\\n[.u] .d=\\n[.d] nl=\\n[nl] pg=\\n[%]
.\" .toc@read-Ci lev1 lev2 lev3 lev4 ... lev7
.de toc@read-Ci
.nr toc*i 0 1
.while \\n+[toc*i]<8 \{\
. nr toc*hl!\\n[toc*i] \\$\\n[toc*i]
.while \\n+[toc*i]<15 \{\
. nr toc*hl!\\n[toc*i] \\$[\\n[toc*i]]
.\}
..
.\"-----------
@ -2883,7 +2909,7 @@ in=\\n[.i] fi=\\n[.u] .d=\\n[.d] nl=\\n[nl] pg=\\n[%]
.\}
.\" clear lower counters
.nr app*i 1 1
.while \\n+[app*i]<8 .nr H\\n[app*i] 0 1
.while \\n+[app*i]<15 .nr H\\n[app*i] 0 1
..
.\"------------
.de app@index

2
contrib/groff/contrib/mm/mmroff.pl
View File

@ -1,4 +1,4 @@
#!/usr/bin/perl
#! /usr/bin/perl
use strict;
# runs groff in safe mode, that seems to be the default

229
contrib/groff/contrib/mom/BUGS
View File

@ -2,15 +2,238 @@ Assume that anything that doesn't work or behaves oddly is a bug.
The documentation should be taken as the authoritative source for
how things ought to be.
Post to the groff mailing list (groff@ffii.org) with bug reports,
questions and suggestions, or contact me directly at:
Post to the groff mailing list with bug reports, questions and
suggestions, or contact me directly at:
df191@ncf.ca
peter@faustus.dyn.ca
or
ptpi@golden.net
If writing me directly, please include the word "groff" or "mom" in
the Subject line or you risk my spam filters nuking your message.
Also, please--no html email. That, too, gets nuked.
--Peter Schaffter
========================================================================
Version 1.3
===========
Persistent error in html coding of docs (<nobr> tag).
---Fixed---
Version 1.2-f
============
Multiple line subheads near page bottom sometimes printing one line
of subhead at page bottom, and subsequent lines on next page.
---Fixed---
Post-quote spacing still wonky when paragraph spacing is turned on.
---Fixed--- (for good would be nice)
RULE not always resetting quad and quad value.
---Fixed---
Version 1.2-e
=============
Some string definitions in om.tmac had superfluous spaces after
them (e.g. $COVERTITLE).
---Fixed---
Spacing under quotes not correct when paragraph spacing is turned
on.
---Fixed---
First word of last line before footnotes is getting chopped.
---Fixed---
Version 1.2-d
=============
HEADER_FAMILY not changing header family.
---Fixed---
FAMILY, after COLLATE, not changing the family of all and every
page element or tag.
---Fixed---
Heads and subheads at the start of docs are printing one line lower
than they should.
---Fixed---
Gaps are appearing at the bottom of pages when there's a linebreak
followed by a subhead.
---Fixed---
When LS is invoked after a single text line at the top of a page
containing a T_MARGIN (set with T_MARGIN or PAGE), mom is performing
spacing adjustments as if the first line doesn't exist.
---Fixed---
Changes made to ALD and LS in version 1.2-c should not apply when
the document processing macros are used. There is a significant
conflict with the internal use of ALD when the docheader is only
one line long (as, for example, when DOCTYPE is CHAPTER).
---Fixed, pending discovery of further conflicts---
Version 1.2-c
=============
Deferred footnotes not always being output, and groff complains
"ending diversion FN_OVERFLOW on exit."
---Fixed---
First .LS call after a top margin has been set (with .T_MARGIN
or .PAGE) causing mom to move off the top margin baseline. Also,
there are conflicts between ALD, LS and T_MARGIN.
---Fixed---
DROPCAP not properly restoring a running \*[COND] or \*[EXT] after
COND or EXT are given as arguments to DROPCAP.
---Fixed---
Version 1.2
===========
.PAD not co-operating with mom's fontstyles, esp. when a full
family+fontstyle is given to .FT.
---Fixed---
.DROPCAP -- ditto the above.
---Fixed---
Version 1.1.9
=============
Footnote markers not resetting properly on new pages when COLUMNS
is enabled.
---Fixed---
When overflowed footnote material is the only footnote material on
the page or in the column, no footnotes are output.
---Fixed---
The AUTOLEAD used in FOOTNOTE not being disabled after FOOTNOTES
are output, or after PROCESS_FN_LEFTOVER/PROCESS_FN_IN_DIVER.
---Fixed---
COL_NEXT and COL_BREAK, when invoked during the last column on a
page, are overprinting the last column instead of breaking to a new
page when there are footnotes in the column.
---Fixed---
BR_AT_LINE_KERN not "break-and-spreading" text when used in
justified copy.
---Fixed---
Version 1.1.8
=============
BLOCKQUOTE_FAMILY not changing blockquote family.
---Fixed---
FOOTNOTE, whether in column mode or not, was using
#FN_COUNT_FOR_COLS for all footnote markers and handling.
---Fixed---
Deferred footnotes that occured on the second to last page of
documents not printing.
---Fixed---
Version 1.1.7-a
===============
Suite number in DOCTYPE LETTER not printing.
---Fixed---
Footer elements not always vertically aligning.
---Fixed---
Footer rule gap not always correctly observed.
---Fixed---
Page numbering, when at top of page, not always falling on
HDRFTR_MARGIN.
---Fixed---
Default page numbering style for COPYSTYLE draft is DIGIT instead
of roman.
---Fixed---
Hyphens around page numbering when style is DIGIT, ROMAN or ALPHA
not vertically centered.
---Fixed---
EXT arg not working with DROPCAP.
---Fixed---
DOC_QUAD not automatically set immediately after START
---Fixed--
Tabs behaving erratically during document processing.
---Fixed---
Version 1.1.7
=============
When DOCHEADER OFF <distance> is given, if <distance> falls short
of the top margin of running text, <distance> is not respected and
bottom margin falls low.
---Fixed---
Version 1.1.6-e
===============
The " mark (doublequote), when entered while not in document
processing mode (i.e. just straightforward typesetting), outputs
nothing unless SMARTQUOTES is invoked explicitly.
---Fixed---
Version 1.1.6-c
===============
In document processing mode, docs that use *none* of the
docprocessing tags being ignored.
---Fixed---
Version 1.1.6-b
===============
String tabs not picking up #L_MARGIN when #L_MARGIN not explicitly
set with L_MARGIN, PAPER or PAGE.
---Fixed---
Infinite loop when B_MARGIN is set lower than FOOTER_MARGIN during
doc processing.
---Fixed---
Version 1.1.6-a
===============
Mom partially broken when run with groff 1.19.1. Don't know yet
what this is, whether bad coding in mom, or a problem with 1.19.1.
Only solution for now: run mom 1.1.6 with groff 1.18.
----Fixed---
Top margin of endnotes pages after the first endnotes page when
PRINTSTYLE is TYPEWRITE and endnotes single-spacing is turned on
falling one line too high.
---Fixed---
Version 1.1.6
=============
DOCHEADER OFF (distance) not being respected.
---Fixed---
FINIS killing ENDNOTES page numbering and heads.
---Fixed---
Version 1.1.5
=============

418
contrib/groff/contrib/mom/ChangeLog
View File

@ -1,3 +1,396 @@
*Thu Aug 11 2005
o Makefile.sub (HTMLDOCFILES): Add `refer.html'
*Mon Jun 20 2005
o Makefile.sub (HTMLDOCFILES_, EXAMPLEFILES_, PROCESSEDEXAMPLEFILES_): New
variables.
(install_data): Install files in `mom' subdirectories.
Make it work actually.
(uninstall_sub): Updated.
*Thu Jun 16 2005
o Makefile.sub (install_data, uninstall_sub): Use $(exampledir) for example
files. Reported by Keith Marshall.
*Mon May 16 2005
o Update groff_mom.man.
*Thu May 12 2005
o Added margin notes capability
o Added mom-specific refer support; refer calls can be embedded in
running text, sent to footnotes or endnotes, or collected for
output on a bibliography page; also added mom-specific refer
control macros
o Added bibliography page capability, with full suite of control
macros
o Added referencing of footnotes and endnotes by line number
o Added capability to have footnotes run on when footnotes are
being referenced by line number
o Added a post footnote space option, in case users want a little
space between their footnotes
o Added ENDNOTE_MARKER_STYLE, so user can choose between endnotes
identified by a numerical marker in the text, or by line number
o Added control macros to accommodate differing needs for endnotes
identified by line number
o Added ENDNOTE_TITLE_SPACE, so user can control starting position
of the endnotes page title
o Extended LIST so that it accepts lowercase alpha, uppercase roman
numeral and lowercase roman numeral enumerators; also added a
"prefix" argument (which comes *after* the separator argument)
o Changed RESET_LIST so that it can reset a list to any number,
letter, or roman numeral, instead of just 1, a, A, I and i
o Change to handling of footnote/endnote markers in text; input
lines before FOOTNOTE still require \c, but input line after
FOOTNOTE OFF must be entered as a literal continuation of the
line before FOOTNOTE, including any required word space or
punctuation (this so users can get the footnote marker in text
either before or after the punctuation without hassle)
o Added QUOTE_AUTOLEAD and BLOCKQUOTE_AUTOLEAD, so user can have
quotes and blockquotes leaded differently from running text
o Reworked QUOTE and BLOCKQUOTE to accommodate _AUTOLEAD control;
spacing above and below quotes is equalized *on a per quote
basis* (not completely happy with this, but at least it gives
users some flexibility in designing (block)quotes)
*Fri Mar 18 2005
o Added mom.vim to /examples
*Thu Jan 20 2005
o Added \*[TB+] and \*[B] to give inline functionality of .TN and
.EL, respectively.
o Added SECTION and SECTION_CHAR as aliases of LINEBREAK and
LINEBREAK_CHAR
o Added a NOBREAK option to PAD, so when PAD is called, it's possible
to instruct mom not to advance on the page.
*Wed Jan 19 2005
o New macro, ADD_SPACE, so that extra space can be added at the
top of a new page in document processing; the .ns call in HEADER
was making additional space impossible
o Reworked handling of ALD/SPACE/SP and LS when they're used at
the tops of pages during pure (i.e. non-docprocessing)
typesetting. First lines were still wandering. Should also be
more intuitive: ALD after LS advances the specified distance from
the top baseline; LS after ALD doesn't change the position of the
first baseline (i.e. merely sets the lead for the text that
follows).
*Tue Dec 14 2004
o Fixed a small problem with spacing under quotes when paragraph
spacing is turned on.
*Fri Dec 10 2004
o Put all calls in VFP_CHECK inside their own environment. Without
the .ev call, the trap invoked VFP_CHECK was chopping off the
first word of the last line before footnotes.
*Dec 6 2004
o Small fixes to elvis_syntax.new (dealing with strings, \{\ and \}
o Changed
. ie \\n[#START] \{\
. if \\n[#DOC_HEADER]=0 \{ . \}
. \}
in HEAD to
. ie \\n[#START] \{\
. if \\n[#DOC_HEADER]=0 \{ .RLD 1v \}
. \}
so that HEADs at the start of docs with no docheaders falls on
the correct baseline.
*Dec 3 2004
o Removed spurious parens from if ( \\n[#TRAP_DISTANCE] < \\n[#DOC_LEAD]*2 )
in SUBHEAD.
*Oct 14 2004
o Reworked the LL macro so that the argument can take a prepended +
or - sign (i.e. the argument is relative to the current line
length).
*Oct 13 2004
o Added an .if \\n(.n=0 if to the ie clause in LS that controls how mom
responds to initial LS invocation at page top if T_MARGIN has
been set. Now, if there's text on the "top" baseline, LS behaves
as expected when invoked afterwards.
*Oct 11 2004
o Added an ie !r#DOCS clause to the processing of "top baseline"
ALDs. ALD is used extensively (internally) in the document
processing macros, and does not need to check--indeed, should not
check--for top baseline placement prior to execution.
*Sep 29 2004
o Additions to elvis_syntax.new
*Sep 12 2004
o Small fixes to the documentation.
*Aug 21 2004
o Removed superfluous second arguments from strings UP, DOWN, FWD
and BCK
*Aug 8 2004
o Version changed from the 1.1.x series to 1.2. All of the
features I originally wanted mom to have originally have been
implemented, and appear to be stable.
o Major overhaul to the setting of page traps and the handling of
footnotes, both "normal" footnotes and footnotes that occur
inside QUOTE, BLOCKQUOTE and EPIGRAPH.
o Addtion of font "styles" to om.tmac, plus changes to the FAMILY
and FT macros to manage them. New section in the doc appendices
on adding fonts and managing the new font styles.
o Mom now uses a "fallback font" whenever there's an illegal call
to FAMILY.
o RW and EW now affect only the font in effect. A change of family
or font disables them.
o BR_AT_LINE_KERN now properly does a .brp (spread and break) when
used in justified text.
o NEWPAGE, which used to be an alias for .bp, has been moved into
its own macro, in order to make it more responsive to some unusal
situations.
o Some changes to elvis_syn.new, including that the file extensions
recognized by elvis now include both .mom and .tmac. This makes
om.tmac much easier to read.
*Jul 6 2004
o FT and FAM(ILY) reworked to take advantage of if S, if F and
\n[.sty] additions to groff (1.19.2). Warnings are emitted if a
style hasn't been registered, or if a font style doesn't exist in
the current family. Invalid .FAM(ILY) calls now use a "fallback"
font" (although no warning is issued); fallback is user-settable
o New macro, FALLBACK_FONT. Not only controls the fallback font
for invalid family calls, but also controls whether mom aborts on
invalid .FT calls after issuing a warning.
o RW/EW now affect only the current font (or font style)
o BR_AT_LINE_KERN now (properly) does a break-and-spread when text
is justified.
o Fairly extensive list of .sty's added to om.tmac. Hopefully,
this will make life easier for users wishing to add new fonts
and/or entire new families to their groff site-font/devps
directory.
*Jun 6 2004
o Altered kerning slightly for footnote markers in text. Daggers
and double-daggers were getting a bit jammed
*Fri Jun 4 2004
o Makefile.sub (HTMLDOCFILES, EXAMPLEFILES, PROCESSEDEXAMPLEFILES): Updated.
*Thu Jun 3 2004
o Rewrote the routines dealing with _FAMILY, _FONT, _SIZE, _COLOR
and _QUAD. A single macro for each checks for the calling alias
(e.g. TITLE_FAMILY in _FAMILY), and performs the appropriate
action.
o All "COLOUR" aliases of "COLOR", no matter where, have been
removed.
o Added cover and doc cover page generation.
o Added reference macros COVERTITLE, DOC_COVERTITLE, MISC and
COPYRIGHT (for use with covers only)
o Fixed EL and TN so they don't spring page traps; in nofill modes
the preceding input line must be terminated by \c.
o Added #T_MARGIN_LEAD_ADJ to DO_B_MARGIN, DO_T_MARGIN and NEWPAGE
to ensure accurate placement of first lines on new pages when
docprocessing is not taking place.
o Made NEWPAGE it's own macro; formerly just an alias of .bp.
o Made BREAKQUOTE obsolete; rewrote sections of footnote handling,
including adding support macros to deal with processing of
footnotes that were started inside quotes, blockquotes and
epigraphs.
o Added a TERMINATE .em to docprocessing (except letters) to ensure
that deferred footnotes print on the last page of a doc.
*Mar 15 2004
o Added color support
o Adjusted vertical placement of hyphens around page numbering
so that they are better centered on the height of the page
number.
o Re-wrote portions of the document processing macros so that tabs
behave in a consistent and intuitive manner. Tab structures are
now properly preserved from page to page and column to column.
*Feb 20 2004
o Rewrote the macros associated with DOCTYPE LETTER so that the
user can enter DATE, TO and FROM in any order s/he likes. For
backward compatibility, if the older, fixed order (DATE-TO-FROM)
is used, the date goes flush right with two linespaces after
it, while the other fields go flush left with a single linespace
separating them.
o Fixed handling of DOCHEADER OFF <distance> when <distance> fell
short of the top margin of running text (the change is actually
in the SHIM macro, which is called by DOCHEADER).
o Added a selection of iso 639 two-letter language codes as
optional arguments to SMARTQUOTES, so that the use can enter
her/his language code to get language specific quoting styles
o Changed the way the strings for \*[ST<n>], \*[ST<n>X], \*[FU<n>]
and \*[BU<n>] are read. Formerly, they were entered literally.
Now they're entered as an array.
*Jan 24 2004
o Added lists and associated macros. Mom now does (nested) lists.
o Added German-style lowered double quotes and two styles of
guillemets to SMARTQUOTES.
o Added macro SIZE, intended to be called inline as \*[SIZE <n>].
This is to bring mom's inline size change syntax into line with
her other inlines.
o Added ESC_CHAR as an alias of .ec
o Added doc entries for lists.
o Updated SMARTQUOTES entry in docs.
o Updated reserved words in docs.
o Fixed a few more typos in docs.
*Tue Oct 21 2003
o Changed \n[#DRAFT] and \n[#REVISION] to strings \*[$DRAFT] and
\*[$REVISION], allowing for the possibility of blank entries that
don't mess up headers/footers with zeros if user doesn't want any
numbers.
o Extended handling of draft and revision numbers and strings in
headers/footers for increased flexibility. It's possible now to
have just about any combo of DRAFT_STRING, DRAFT, REVISION_STRING
and REVISION, and have them come out in headers/footers as one
intuitively expects/wants.
*Fri Jul 25 2003
o Added a .bp after .if \\n[#START]=1 in FOOTER. Without it,
in document processing mode, documents that use *none* of the
docprocessing tags (yes, there are times when users want to do
this) ignored the footer trap.
*Fri Jun 6 2003
o Changed register #DOCHEADER_LEAD_ADJ to string
*Wed May 21 2003
o DOC_TITLE changed to be used exclusively with DOCTYPE DEFAULT
o Fixed problem with restoration of previous doc pagenum
style when endnotes use a different pagenum style (set with
ENDNOTES_PAGENUM_STYLE)
o Fixed handling of headers/footers with respect to endnotes. Now,
when either headers or footers are on, mom picks up the correct
page header/footer on the last page prior to ENDNOTES, gets the
pageheaders correct for endnotes pages *including the last one*,
and picks up correct page headers/footers for the subsequent docs
after COLLATE
*Sat May 17 2003
o Added TOC (finally) and a nearly complete set of associated
control macros
o Added new control macros to endnotes:
ENDNOTES_STRING_CAPS - capitalize the endnotes string
ENDNOTES_NO_COLUMNS - allows docs in columns and endnotes not
ENDNOTES_PAGENUM_STYLE - set page numbering style for endnotes
ENDNOTES_FIRST_PAGENUMBER - set first pagenumber for endnotes
ENDNOTES_ALLOWS_HEADERS - page headers on endnotes pages off or on
ENDNOTES_NO_FIRST_PAGENUM - allows non-printing first page number when page footers are being used instead of headers
ENDNOTES_SINGLE_SPACE - for TYPEWRITE, if doc double-spaced
SUSPEND/RESTORE_PAGINATION - turns page numbering off for endnotes
o Added an ADJUST option to ENDNOTE_LEAD
o Added DOC_TITLE (like TITLE, but sets document-wide title for collated docs)
o Added HDRFTR_CENTER_PAD, to allow adjustments to placement of
HDRFTR_CENTER_STRING
o Added BLANKPAGE macro, to output blank pages (silently numbered)
o Extensive changes to DEFAULTS, START, COLLATE, HEAD, SUBHEAD and
PARAHEAD because of new TOC and extended flexibility of ENDNOTES
page design
o Fixed DOCHEADER OFF (distance), FINIS
-----------------------------------------------------------------------
*Sat Feb 22 2003
o (Re)-fixed handling of post epigraph spacing after #START for
TYPEWRITE double-spaced.
------------------------------------------------------------------------
*Sun Feb 16 2003
o Added James Ramsey's proposed CHAPTER_TITLE macro, along with his
@ -57,6 +450,8 @@ o Changed handling of inline horizontal and vertical movements.
The older forms \*[FP#] and \*[BP#] still work (horizontals), as do
\*[ALD#] and \*[RLD#] (verticals).
------------------------------------------------------------------------
*Mon Aug 19 2002
o Fixed ENDNOTES so footnotes output properly when ENDNOTES is called
@ -72,15 +467,6 @@ o Added .nf to top of PAD, with a test beforehand for current fill
processing. Updated reserved.html to include number register
#FILL_MODE.
*Mon Jul 29 2002
o Makefile.sub (FFLAG, TFLAG): Add paths to source directories.
*Wed Jul 24 2002
o Makefile.sub (groff_bin_path): Don't use ' \+' but ' *' for sed.
(GROFF): Set GROFF_COMMAND_PREFIX to empty value.
*Fri Jul 12 2002
o More fixes to underlining.
@ -111,10 +497,6 @@ o Fixed the character translations for UNDERLINE so they work properly
o Expanded docprocessing.html entry "Special Note on Chapters". Tidied
up html a bit.
*Tue Jun 18 2002
o examples/macros.mom: Fix path to penguin.ps.
*Sat Jun 15 2002
o Small fix to PAD to make the use of inlines within the pad string
@ -123,17 +505,17 @@ o Small fix to PAD to make the use of inlines within the pad string
o Added \*[RULE] ( = \l'\n(.lu' ) so that full measure rules (either to
full line length or within tabs) are easier to set.
*Sat Jun 8 2002
*Sat Jun 8 2002
o Macro .PS renamed to .PT_SIZE. Alias .TS removed.
o .tr bits in .CAPS rewritten in the form .tr é\['E].
o .tr bits in .CAPS rewritten in the form .tr é\[`E].
o General cleanup of docs to reflect changes.
o General cleanup of docs to reflect changes
o Small changes/additions to `elvis_syntax'.
o Small changes/additions to elvis_syn
*Thu Jun 6 2002
*Thu Jun 6 2002
o In DOCTYPE, in .if '\\$1'LETTER', added .FOOTER_RIGHT_SIZE +0.
Without it, the suite page was printing at the default

74
contrib/groff/contrib/mom/Makefile.sub
View File

@ -1,4 +1,4 @@
# Copyright (C) 2002, 2003 Free Software Foundation, Inc.
# Copyright (C) 2002, 2003, 2004, 2005 Free Software Foundation, Inc.
# Written by Werner Lemberg (wl@gnu.org)
#
# This file is part of groff.
@ -15,11 +15,11 @@
#
# You should have received a copy of the GNU General Public License along
# with groff; see the file COPYING. If not, write to the Free Software
# Foundation, 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
# Foundation, 51 Franklin St - Fifth Floor, Boston, MA 02110-1301, USA.
# These may be overridden if cross-compiling.
GROFFBIN=$(top_builddir)/src/roff/groff/groff
GROFF_BIN_PATH=`echo $(groff_bin_dirs) | sed -e 's| *|:|g'`
GROFF_BIN_PATH=`echo $(groff_bin_dirs) | sed -e 's| *|$(SH_SEP)|g'`
groff_bin_dirs=\
$(top_builddir)/src/roff/groff \
@ -44,6 +44,7 @@ NORMALFILES=\
HTMLDOCFILES=\
momdoc/appendices.html \
momdoc/color.html \
momdoc/cover.html \
momdoc/definitions.html \
momdoc/docelement.html \
@ -53,7 +54,9 @@ HTMLDOCFILES=\
momdoc/inlines.html \
momdoc/intro.html \
momdoc/letters.html \
momdoc/macrolist.html \
momdoc/rectoverso.html \
momdoc/refer.html \
momdoc/reserved.html \
momdoc/toc.html \
momdoc/typemacdoc.html \
@ -62,36 +65,42 @@ HTMLDOCFILES=\
EXAMPLEFILES=\
examples/letter.mom \
examples/macros.mom \
examples/typeset.mom \
examples/typewrite.mom \
examples/README.mom \
examples/sample_docs.mom \
examples/typesetting.mom \
examples/README.txt \
examples/elvis_syntax \
examples/elvis_syntax.new \
examples/penguin.ps
PROCESSEDEXAMPLEFILES=\
examples/letter.ps \
examples/macros.ps \
examples/typeset.ps \
examples/typewrite.ps
examples/sample_docs.ps \
examples/typesetting.ps
HTMLDOCFILES_=`echo $(HTMLDOCFILES) | sed 's|momdoc/||g'`
EXAMPLEFILES_=`echo $(EXAMPLEFILES) | sed 's|examples/||g'`
PROCESSEDEXAMPLEFILES_=`echo $(PROCESSEDEXAMPLEFILES) | sed 's|examples/||g'`
CLEANADD=\
penguin.ps \
$(PROCESSEDEXAMPLEFILES)
$(PROCESSEDEXAMPLEFILES) \
examples/stamp
.SUFFIXES: .mom .ps
.mom.ps:
$(GROFF) -Tps -mom $< >$@
all: make_examples
all: $(PROCESSEDEXAMPLEFILES)
.PHONY: make_examples
make_examples: prepare_make_examples $(PROCESSEDEXAMPLEFILES)
$(PROCESSEDEXAMPLEFILES): penguin.ps examples/stamp
prepare_make_examples: examples/penguin.ps
penguin.ps:
cp $(srcdir)/examples/penguin.ps .
examples/stamp:
test -d examples || $(mkinstalldirs) examples
test -f penguin.ps || cp $(srcdir)/examples/penguin.ps .
touch $@
install_data: $(NORMALFILES) $(HTMLDOCFILES) \
$(EXAMPLEFILES) $(PROCESSEDEXAMPLEFILES)
@ -100,29 +109,30 @@ install_data: $(NORMALFILES) $(HTMLDOCFILES) \
rm -f $(tmacdir)/$$f; \
$(INSTALL_DATA) $(srcdir)/$$f $(tmacdir)/$$f; \
done
-test -d $(htmldocdir)/momdoc || $(mkinstalldirs) $(htmldocdir)/momdoc
for f in $(HTMLDOCFILES); do \
rm -f $(htmldocdir)/$$f; \
$(INSTALL_DATA) $(srcdir)/$$f $(htmldocdir)/$$f; \
-test -d $(htmldocdir)/mom || $(mkinstalldirs) $(htmldocdir)/mom
for f in $(HTMLDOCFILES_); do \
rm -f $(htmldocdir)/mom/$$f; \
$(INSTALL_DATA) $(srcdir)/momdoc/$$f $(htmldocdir)/mom/$$f; \
done
-test -d $(exampledir) || $(mkinstalldirs) $(exampledir)
for f in $(EXAMPLEFILES); do \
rm -f $(exampledir)/$$f; \
$(INSTALL_DATA) $(srcdir)/$$f $(docdir)/$$f; \
-test -d $(exampledir)/mom || $(mkinstalldirs) $(exampledir)/mom
for f in $(EXAMPLEFILES_); do \
rm -f $(exampledir)/mom/$$f; \
$(INSTALL_DATA) $(srcdir)/examples/$$f $(exampledir)/mom/$$f; \
done
for f in $(PROCESSEDEXAMPLEFILES); do \
rm -f $(exampledir)/$$f; \
$(INSTALL_DATA) $$f $(docdir)/$$f; \
for f in $(PROCESSEDEXAMPLEFILES_); do \
rm -f $(exampledir)/mom/$$f; \
$(INSTALL_DATA) examples/$$f $(exampledir)/mom/$$f; \
done
uninstall_sub:
-for f in $(NORMALFILES); do \
rm -f $(tmacdir)/$$f; \
done
-for f in $(HTMLDOCFILES); do \
rm -f $(htmldocdir)/$$f; \
-for f in $(HTMLDOCFILES_); do \
rm -f $(htmldocdir)/mom/$$f; \
done
-rmdir $(htmldocdir)/momdoc
-for f in $(EXAMPLEFILES) $(PROCESSEDEXAMPLEFILES); do \
rm -f $(docdir)/$$f; \
-rmdir $(htmldocdir)/mom
-for f in $(EXAMPLEFILES_) $(PROCESSEDEXAMPLEFILES_); do \
rm -f $(exampledir)/mom/$$f; \
done
-rmdir $(exampledir)/mom

237
contrib/groff/contrib/mom/NEWS
View File

@ -1,3 +1,240 @@
Release 1.3
-----------
Added line numbering capabilities, with controls.
Footnotes and endnotes can now be referenced by line number.
Added ability to adjust vertical position of the title that appears
on the first endnotes page.
Footnotes can run on when being referenced by line number.
Footnotes now have a post-footnote spacing option, for adding
a little space between footnotes.
Extended LIST so it accepts alpha, ROMAN and roman enumerators.
Added margin notes capability.
Added refer support.
Added bibliography page support.
Added QUOTE_AUTOLEAD and BLOCKQUOTE_AUTOLEAD, so user can have
quotes and blockquotes leaded differently from running text.
Change: the input line immediately after FOOTNOTE OFF must be
entered as a literal continuation of the line prior to FOOTNOTE,
including any initial spaces or punctuation marks. This allows
for hassle-free placing of footnote markers in running text either
before or after punctuation marks.
Release 1.2-f
-------------
Added ADD_SPACE, to permit users to insert space at the top of
running text (after the first page) when using the docprocessing
macros.
Releases 1.2-a and 1.2-b
------------------------
My personal email address has changed. 1.2-a and -b have been
updated to reflect that. Additionally, I made some small changes
to the documentation.
Release 1.2
-----------
As of 1.2, the recommended version of groff to use with mom has
been bumped up from groff, 1.18 to groff, 1.19.2. Although mom will
continue to work with groff, 1.18, her handling of .FAM(ILY) and .FT
is now slightly different, therefore users of groff 1.18 may have to
update documents created with mom so that every .FAM(ILY) request is
followed by a .FT request before any text is input, otherwise mom
will set the text after .FAM(ILY) in Courier (until she encounters a
.FT request). People running groff, >= 1.19.2 don't have to worry
about this, but I recommend that, regardless of which version you're
running, you have a look at the document entries for FAMILY and FT
in order to see how mom will be handling .FAMILY and .FT from now
on.
When used with groff >=1.19.2, mom now emits warnings if a style
hasn't been registered, or if a font style doesn't exist in the
current family. Invalid .FAM(ILY) calls now use a "fallback" font"
(although no warning is issued). The fallback is user-settable.
Mom's macro file, om.tmac, now sets up a fairly extensive list of
font "styles," thus expanding the range of arguments that can be
passed to .FT (formerly, just R, I, B and BI, unless users had
already rolled their own solution to the problem of extensive type
families containing fonts like condensed, demibold, black, light, etc).
Users are advised to read the documentation sections on FAM(ILY),
FT and FALLBACK_FONT, as well as the new appendix section, "Adding
PostScript fonts to groff", for information on using mom's style
extensions (and how to disable them, should they conflict with a
user's present groff site-font/devps setup).
A new macro, FALLBACK_FONT, has been added. It controls not only
the fallback font for invalid .FAMILY calls, but also whether mom
aborts on invalid .FT calls after issuing a warning, or continues
processing using the fallback.
Release 1.1.9
-------------
Added the (optional) generation of cover pages and document cover
pages, plus a full suite of control macros for all cover page
elements.
Added new reference macros that apply to covers: COVERTITLE,
DOC_COVERTITLE, COPYRIGHT and MISC.
The need for TRAP OFF/TRAP to deal with ELs and TNs that fall at
the bottom page has been obsoleted. However, both EL and TN, when
invoked in any "nofill" mode (LEFT, RIGHT, CENTER, or the L | R | C
arguments to TAB_SET or ST when no QUAD argument is given), must now
have the input line preceding the EL or TN terminated by \c. Fill
modes do not have this requirement, i.e. no \c is required.
Footnotes that occur inside quotes, blockquotes and epigraphs now
work just like regular footnotes, with no user intervention
required. This obsoletes the macro BREAK_QUOTE.
Removed all aliases that used the word COLOUR. Users must use
COLOR wherever COLOR is needed. COLOUR, as a replacement/alias, is
no longer supported.
NEWPAGE, which used to be an alias of .bp, is now its own macro.
Release 1.1.8
-------------
Added text color support. Users can now define or initialize a color,
and afterwards change text color with an inline of the form
\*[<colorname>], or with the macro .COLOR. In document processing,
the docelement tag control macros have been expanded to include
_COLOR, e.g. .HEAD_COLOR <predefined colorname> will colorize
heads, PAGENUM_COLOR <predefined colorname) will colorize page
numbering, etc.
Adjusted vertical placement of hyphens around page numbering when
PAGENUM_STYLE is DIGIT, ROMAN or ALPHA so that the hyphens appear
properly centered on the page numbering character.
Changed tab handling in document processing so that tab structures
are preserved from page to page and column to column.
Release 1.1.7-a
---------------
Increased the flexibility of SMARTQUOTES so that they handle quoting
styles by language, entered as a 2-digit language code argument to
SMARTQUOTES. See docs.
Re-wrote the DOCTYPE LETTER macros so that DATE, TO and FROM can be
entered in any order the user wishes, with output that matches
input. (Should have done this in the first place.)
Release 1.1.7
-------------
Finally got around to writing "list" macros. See the docs.
Added German-style lowered double quotes and two styles of
guillemets to SMARTQUOTES.
Added macro SIZE, intended to be called inline as \*[SIZE <n>].
This brings mom's inline size change syntax into line with her other
inlines. \*S[<n>] can still be used for the same thing.
The file elvis_syntax (for elvis prior to 2.2h) is no longer being
maintained. It was getting messy and long in the tooth. The
official elvis syntax file is elvis_syntax.new, which works for
2.2h of elvis (and higher, one hopes). elvis users are encouraged
to update to 2.2h or higher.
Release 1.1.6-e
---------------
Extended handling of draft and revision numbers and strings in
headers/footers for increased flexibility. It's possible now to
have just about any combo of DRAFT_STRING, DRAFT, REVISION_STRING
and REVISION, and have them come out in headers/footers as one
intuitively expects/wants.
Also added a new set of syntax highlighting rules for the vi clone,
elvis. Version 2-2h-beta of elvis finally made possible the
highlighting of \*[...] inline escapes, whether or not they're
separated from surrounding text by spaces. This is a terrific
improvement in elvis, and makes for greatly improved readability of
mom files.
Release 1.1.6-b - 1.1.6d
------------------------
Trivial changes to documentation and some cleanups of the main
om.tmac file, including:
Added a .bp after .if \\n[#START]=1 in FOOTER. Without it,
in document processing mode, documents that use *none* of the
docprocessing tags (yes, there are times when users want to do
this) ignored the footer trap.
Changed register #DOCHEADER_LEAD_ADJ to string
$DOCHEADER_LEAD_ADJ. This means that .DOCHEADER_LEAD no longer
requires a unit of measure; points is assumed.
Release 1.1.6-b
---------------
Added a SHIM macro that calculates and moves to the next "legal"
baseline during document processing (useful if user starts playing
around with spacing/leading on a page and needs to get the leading
back on track).
Fixed handling of DOCHEADER OFF <distance> so that the first line of
running text falls on a "legal" baseline when <distance> is given.
Release 1.1.6-a
---------------
Problem with groff 1.19.1 fixed by Werner (.return handled arguments
incorrectly).
Fixed handling of page numbering style restoration in endnotes, so
that (collated) docs have the correct page numbering style when the
style has been changed for endnotes (with ENDNOTES_PAGENUM_STYLE).
DOC_TITLE has been made for use exclusively with DOCTYPE DEFAULT.
Fixed handling of headers/footers with respect to endnotes. Now,
when either headers or footers are on, mom picks up the correct
page header/footer on the last page prior to ENDNOTES, gets the
pageheaders correct for endnotes pages *including the last one*, and
picks up correct page headers/footers for the subsequent docs after
COLLATE.
Release 1.1.6
-------------
BAD NEWS: mom appears to be crippled in some areas when run with
groff 1.19.1. Pending a solution, mom must be run with groff 1.18
***NEW***
Added TOC capabilities.
Extended range of endnotes control macros. See the documentation
on endnotes control macros.
Added a new DOC_TITLE macro, to deal with collated documents that
have an overall title, while each doc has its own separate doc
title (from TITLE).
Release 1.1.5
-------------

30
contrib/groff/contrib/mom/TODO
View File

@ -1,3 +1,20 @@
As of version 1.2, the items on this TODO list will only be dealt
with if users request they be implemented.
UNDERLINING
-----------
Explore "the ultimative underline macro" for possible inclusion
into mom.
NUMBERED HEADS, SUBHEADS and PARAHEADS
--------------------------------------
Macros to set numbering style (roman, arabic, alpha, etc)?
FOOTNOTES
---------
In columnar docs, maybe give user the choice of gathering all
footnotes at the bottom of the last column?
CONTROL MACROS -- _INDENT
--------------
Let user be able to enter decimal fractions as the argument to _INDENT
@ -5,17 +22,4 @@ control macros, or, instead, let user be able to enter absolute
values with a unit of measure in addition to current behaviour,
which is relative.
LISTS
-----
Possbility of indented, nested lists, html-style. Options for numbered,
alpha-ed, bulleted, dashed. Again, not sure how useful these would be
for mom's target users. As things stand now, it's easy enough to
set up lists with string tabs or hanging indents.
BIBLIOGRAPHY
------------
Thinking about macros to *assist* in user-written bibliographies (i.e.
not biblios that get generated automatically at the ends of docs). Style
considerations are a nightmare, though.
------------------------------------------------------------------------

10
contrib/groff/contrib/mom/copyright
View File

@ -1,15 +1,15 @@
AUTHOR
------
Peter Schaffter (df191@ncf.ca)
15, chemin Brunette
RR 2, CP 406
Ste-Cécile-de-Masham (Québec)
Peter Schaffter (peter@faustus.dyn.ca) (ptpi@golden.net)
320 Gordon St.
Fergus, Ontario
CANADA
N1M 2W3
========================================================================
The groff macro file om.tmac and the html documentation pertaining
to it are copyright (c) 2002 Peter Schaffter.
to it are copyright (c) 2004, 2005 Peter Schaffter.
om.tmac is issued under the GNU General Public License, a full copy of
which can be had at

115
contrib/groff/contrib/mom/examples/README.txt Normal file
View File

@ -0,0 +1,115 @@
The files in this directory show mom in action.
If you have downloaded and untarrred a version of mom from her
homepage, you'll see that none of the example files come with
corresponding PostScript (.ps) files, as they do with pre-compiled
versions of groff, or groff built from source.
I haven't included the PostScript output because I want to
keep the mom archive as lean as possible. To view the PostScript
output, process the files with groff and either
a) send the output to a separate file for previewing with a
PostScript viewer such as gv (ghostview), or
b) to your printer.
Using the file sample_docs.mom as an example, you would
accomplish a) like this:
groff -mom -Tps sample_docs.mom > sample_docs.ps
gv sample_docs.ps
Accomplishing b) depends on your printer setup, but a fairly
standard way to do it would be
groff -mom -Tps sample_docs.mom | lpr
or
groff -mom -Tps -l sample_docs.mom
Note: I don't recommend previewing with gxditview because it doesn't
render some of mom's effects properly.
The files themselves
--------------------
All are set up for 8.5x11 inch paper (US letter).
***typesetting.mom**
The file, typesetting.mom, demonstrates the use of typesetting tabs,
string tabs, line padding, multi-columns and various indent styles,
as well as some of the refinements and fine-tuning available via
macros and inline escapes.
Because the file also demonstrates a "cutaround" using a small
picture (of everybody's favourite mascot, Tux), the PostScript file,
penguin.ps has been included in the directory.
***sample_docs.mom***
The file, sample_docs.mom, shows examples of three of the document
styles available with the mom's document processing macros, as well
as demonstrating the use of COLLATE.
The PRINTSTYLE of this file is TYPESET, to give you an idea of mom's
default behaviour when typesetting a document.
The last sample, set in 2 columns, shows off mom's flexibility
when it comes to designing documents.
If you'd like to see how mom handles exactly the same file when the
PRINTSTYLE is TYPEWRITE (i.e. typewritten, double-spaced), simply
change
.PRINTSTYLE TYPESET
to
.PRINTSTYLE TYPEWRITE
near the top of the file.
***letter.mom***
This is just the tutorial example from the momdocs, ready for
previewing.
***elvis_syntax.new***
For those who use the vi clone, elvis, you can paste this file into
your elvis.syn. Provided your mom documents have the extension
.mom, they'll come out with colorized syntax highlighting. The
rules in elvis_syntax aren't exhaustive, but they go a LONG way to
making mom files more readable.
The file elvis_syntax (for pre-2.2h versions of elvis) is no longer
being maintained. Users are encouraged to update to elvis 2.2h or
higher, and to use elvis_syntax.new for mom highlighting.
I'll be very happy if someone decides to send me syntax highlighting
rules for emacs. :)
***mom.vim***
Christian V. J. Brüssow has kindly contributed a set of mom syntax
highlighting rules for use with vim. Copy the file to your
~/.vim/syntax directory, then, if your vim isn't already set up to
do so, enable mom syntax highlighting with
:syntax enable
or
:syntax on
Please note: I don't use vim, so I won't be making changes to this
file myself. Christian Brüssow is the maintainer of the ruleset,
which is available on the Web at
http://www.cvjb.de/comp/vim/mom.vim
Contact Christian (cvjb@cvjb.de) if you have any suggestions or
requests.

216
contrib/groff/contrib/mom/examples/elvis_syntax
View File

@ -1,130 +1,90 @@
#Mom
language mom
extension .mom
startword .\
inword _(
keyword .ALD .ALIAS .ALWAYS_FULLSPACE_QUOTES .ATTRIBUTE_STRING
keyword .AUTHOR .AUTHOR_FAMILY .AUTHOR_FONT .AUTHOR_SIZE .AUTOLEAD
keyword .BLOCKQUOTE .BLOCKQUOTE_FAMILY .BLOCKQUOTE_FONT .BLOCKQUOTE_QUAD .BLOCKQUOTE_SIZE
keyword .B_MARGIN .BR .BR_AT_LINE_KERN .BREAK_QUOTE
keyword .CAPS .CENTER .CENTRE
keyword .CHAPTER .CHAPTER_TITLE CHAPTER_STRING .CITATION .CITE .CLOSING
keyword .COLLATE .COL_BREAK .COL_BREAK .COL_NEXT .COLUMNS
keyword .COMMENT .CONDENSE .COPYSTYLE
keyword .DATE .DEFAULTS
keyword .DOC_FAM .DOC_FAMILY .DOCHEADER
keyword .DOCHEADER_ADVANCE .DOCHEADER_LEAD
keyword .DOC_LEAD .DOC_LEAD_ADJUST .DOC_LEFT_MARGIN .DOC_LINE_LENGTH
keyword .DOC_LLENGTH .DOC_L_LENGTH .DOC_L_MARGIN .DOC_LMARGIN
keyword .DOC_LS .DOC_PS .DOC_PT_SIZE .DOC_QUAD
keyword .DOC_RIGHT_MARGIN .DOC_R_MARGIN .DOC_RMARGIN
keyword .DOCTYPE .DOCTYPE_FAMILY .DOCTYPE_FONT .DOCTYPE_SIZE
keyword .DRAFT .DRAFT_STRING .DRAFT_WITH_PAGENUMBER
keyword .DROPCAP .DROPCAP_ADJUST .DROPCAP_FAMILY .DROPCAP_FONT .DROPCAP_GUTTER .DROPCAP_OFF
keyword .EL
keyword .ENDNOTE .ENDNOTES
keyword .ENDNOTE_FAMILY .ENDNOTE_FONT .ENDNOTE_PT_SIZE .ENDNOTE_LEAD .ENDNOTE_QUAD
keyword .ENDNOTE_STRING .ENDNOTE_STRING_FAMILY .ENDNOTE_STRING_FONT .ENDNOTE_STRING_SIZE
keyword .ENDNOTE_STRING_QUAD .ENDNOTE_STRING_UNDERSCORE
keyword .ENDNOTE_TITLE .ENDNOTE_TITLE_FAMILY .ENDNOTE_TITLE_FONT .ENDNOTE_TITLE_SIZE
keyword .ENDNOTE_TITLE_QUAD .ENDNOTE_TITLE_UNDERSCORE
keyword .ENDNOTE_NUMBER_FAMILY .ENDNOTE_NUMBER_FONT .ENDNOTE_NUMBER_SIZE
keyword .ENDNOTE_NUMBERS_ALIGN_RIGHT .ENDNOTE_NUMBERS_ALIGN_LEFT
keyword .ENDNOTE_PARA_INDENT .ENDNOTE_PARA_SPACE .ENDNOTES_FOOTER_CENTER .ENDNOTES_HEADER_CENTER
keyword .EPIGRAPH .EPIGRAPH_AUTOLEAD .EPIGRAPH_FAMILY .EPIGRAPH_FONT
keyword .EPIGRAPH_INDENT .EPIGRAPH_QUAD .EPIGRAPH_SIZE
keyword .EW .EXTEND
keyword .FAM .FAMILY
keyword .FINIS .FINIS_STRING
keyword .FOOTER .FOOTER_CENTER .FOOTER_CENTER_CAPS .FOOTER_CENTER_FAM .FOOTER_CENTER_FAMILY
keyword .FOOTER_CENTER_FONT .FOOTER_CENTER_FT .FOOTER_CENTER_PS .FOOTER_CENTER_SIZE
keyword .FOOTER_CENTRE .FOOTER_CENTRE_CAPS .FOOTER_CENTRE_FAM .FOOTER_CENTRE_FAMILY
keyword .FOOTER_CENTRE_FT .FOOTER_CENTRE_PS .FOOTER_CENTRE_SIZE .FOOTER_FAM
keyword .FOOTER_FAMILY .FOOTER_GAP .FOOTER_LEFT .FOOTER_LEFT_CAPS .FOOTER_LEFT_FAM
keyword .FOOTER_LEFT_FAMILY .FOOTER_LEFT_FONT .FOOTER_LEFT_FT .FOOTER_LEFT_PS
keyword .FOOTER_LEFT_SIZE .FOOTER_MARGIN .FOOTER_ON_FIRST_PAGE .FOOTER_PLAIN
keyword .FOOTER_RECTO .FOOTER_RIGHT .FOOTER_RIGHT_CAPS .FOOTER_RIGHT_FAM .FOOTER_RIGHT_FAMILY
keyword .FOOTER_RIGHT_FONT .FOOTER_RIGHT_FT .FOOTER_RIGHT_PS .FOOTER_RIGHT_SIZE
keyword .FOOTER_RULE .FOOTER_RULE_GAP .FOOTERS .FOOTER_SIZE .FOOTER_VERSO
keyword .FOOTNOTE .FOOTNOTE_AUTOLEAD .FOOTNOTE_FAMILY .FOOTNOTE_FONT .FOOTNOTE_MARKERS
keyword .FOOTNOTE_MARKER_STYLE .FOOTNOTE_QUAD .FOOTNOTE_RULE .FOOTNOTE_RULE_ADJ
keyword .FOOTNOTE_RULE_LENGTH .FOOTNOTE_SIZE
keyword .FROM .FT
keyword .GREETING
keyword .HDRFTR_CENTER .HDRFTR_CENTER .HDRFTR_CENTER_CAPS .HDRFTR_CENTER_FAMILY
keyword .HDRFTR_CENTER_FONT .HDRFTR_CENTER_SIZE .HDRFTR_FAMILY .HDRFTR_GAP
keyword .HDRFTR_LEFT .HDRFTR_LEFT .HDRFTR_LEFT_CAPS .HDRFTR_LEFT_FAMILY
keyword .HDRFTR_LEFT_FONT .HDRFTR_LEFT_SIZE .HDRFTR_MARGIN .HDRFTR_PLAIN
keyword .HDRFTR_RIGHT .HDRFTR_RIGHT_CAPS .HDRFTR_RIGHT_FAMILY .HDRFTR_RIGHT_FONT
keyword .HDRFTR_RIGHT_SIZE .HDRFTR_RULE .HDRFTR_RULE_GAP .HDRFTR_RULE_INTERNAL
keyword .HDRFTR_RULE_INTERNAL .HDRFTR_SIZE
keyword .HEAD .HEAD_CAPS .HEADER .HEADER_CENTER .HEADER_CENTER_CAPS
keyword .HEADER_CENTER_FAM .HEADER_CENTER_FAMILY .HEADER_CENTER_FONT
keyword .HEADER_CENTER_FT .HEADER_CENTER_PS .HEADER_CENTER_SIZE .HEADER_CENTRE
keyword .HEADER_CENTRE_CAPS .HEADER_CENTRE_FAM .HEADER_CENTRE_FAMILY
keyword .HEADER_CENTRE_FONT .HEADER_CENTRE_FT .HEADER_CENTRE_PS .HEADER_CENTRE_SIZE
keyword .HEADER_FAM .HEADER_FAMILY .HEADER_GAP
keyword .HEADER_LEFT .HEADER_LEFT_CAPS .HEADER_LEFT_FAM .HEADER_LEFT_FAMILY
keyword .HEADER_LEFT_FONT .HEADER_LEFT_FT .HEADER_LEFT_PS .HEADER_LEFT_SIZE
keyword .HEADER_MARGIN .HEADER_PLAIN
keyword .HEADER_RECTO .HEADER_RIGHT .HEADER_RIGHT_CAPS .HEADER_RIGHT_FAM .HEADER_RIGHT_FAMILY
keyword .HEADER_RIGHT_FONT .HEADER_RIGHT_FT .HEADER_RIGHT_PS .HEADER_RIGHT_SIZE .HEADER_VERSO
keyword .HEADER_RULE .HEADER_RULE_GAP .HEADERS .HEADER_SIZE
keyword .HEAD_FAMILY .HEAD_FONT .HEAD_QUAD .HEAD_SIZE .HEAD_SPACE .HEAD_UNDERLINE
keyword .HI .HY .HYPHENATE .HYPHENATION .HY_SET
keyword .IB .IBX .IBQ .IH .IL .ILX .ILQ
keyword .IQ .IR .IRX .IRQ .IT .IX
keyword .INDENT_FIRST_PARAS .ITALIC_MEANS_ITALIC
keyword .JUSTIFY
keyword .KERN
keyword .LEADER_CHARACTER .LEFT .LIG .LIGATURES .LINEBREAK .LL .LL .L_MARGIN .LS
keyword .MCO .MCR .MCX
keyword .NEWPAGE .NEW_PAGE .NO_SUITE .NUMBER_HEADS .NUMBER_PARAHEADS .NUMBER_SUBHEADS
keyword .PAD .PADMARKER .PAD_STRING .PAGE .PAGE_LENGTH .PAGELENGTH .PAGEWIDTH
keyword .PAGENUM .PAGENUM_FAMILY .PAGENUM_FONT .PAGENUM_HYPHENS
keyword .PAGENUM_ON_FIRST_PAGE .PAGENUM_POS .PAGENUM_SIZE .PAGENUM_STYLE
keyword .PAGINATE .PAGINATION .PAPER
keyword .PARAHEAD .PARAHEAD_FAMILY .PARAHEAD_FONT .PARAHEAD_INDENT .PARAHEAD_SIZE
keyword .PARA_INDENT .PARA_SPACE
keyword .PP .PP_FONT .PP_FT .PT_SIZE .PSPIC
keyword .PRINTSTYLE
keyword .QUAD
keyword .QUOTE .QUOTE_FAMILY .QUOTE_FONT .QUOTE_INDENT .QUOTE_SIZE
keyword .RECTO_VERSO
keyword .RESET_FOOTNOTE_NUMBER .RESET_HEAD_NUMBER .RESET_PARAHEAD_NUMBER
keyword .RESET_SUBHEAD_NUMBER
keyword .REVISION .REVISION_STRING .RIGHT .RLD .R_MARGIN .RW
keyword .SETBOLDER .SETSLANT .SILENT .SLANT_MEANS_SLANT .SMARTQUOTES .SP .SPACE
keyword .SPREAD .SS .ST .START .STRING .SUBHEAD .SUBHEAD_FAMILY .SUBHEAD_FONT .SUBHEAD_SIZE
keyword .SUBTITLE .SUBTITLE_FAMILY .SUBTITLE_FONT .SUBTITLE_SIZE
keyword .SWITCH_FOOTERS .SWITCH_HDRFTR .SWITCH_HEADERS
keyword .TAB_SET .TAB .TABSET .TB .TI
keyword .TITLE .TITLE_FAMILY .TITLE_FONT .TITLE_SIZE .T_MARGIN
keyword .TN .TO .TQ .TRAP .TYPESIZE
keyword .UNDERLINE .UNDERLINE_ITALIC .UNDERLINE_QUOTES .UNDERLINE_SLANT
keyword .UNDERSCORE .UNDERSCORE_2 .UNDERSCORE2
keyword .WS
font fixed DEFAULT CHAPTER NAMED LETTER
font fixed TYPESET TYPEWRITE
font fixed FINAL DRAFT
font fixed BLOCK QUAD
font fixed LEFT RIGHT CENTER CENTRE JUSTIFY TOP BOTTOM
font fixed OFF QUIT END EXIT DONE NO
font fixed PAGE NUMBER STAR
font fixed COND EXT
font fixed LETTER LEGAL EXECUTIVE LEDGER TABLOID QUARTO FOLIO
font fixed 10x14 A3 A4 A5 B4 B5
font fixed SINGLESPACE
font fixed FACTOR
font underlined \/ \/. \/? \/! \/, \/; \/:
font underlined \, \,. \,? \,! \,, \,; \,:
font underlined \\ \~ \% \0 \: \( \| \^ \& \%
font underlined \b \c \C \d \D \e \f \f( \h \l \L \p \r \s \s+ \s- \S \u \v \w
font fixed \(bu \(co \(ct \(de \(dg \(di \(em \(en \(mu \(pl \(rg \(sc \(sq
font fixed \(14 \(12 \(34 \(+-
font fixed # ' ^
font italic "
character \]
comment \#
comment \"
comment \!
extension .mom .tmac
startword .
color startword normal
inword _.'
color inword normal
other initialpunct
mostly normal
backslash none
color args like fixed
color braces like char
color brackets like underlined
color chars like emphasized
color decimals like number
color ellipsis normal
color escapes like keyword
color math like cursor
color misc like string
color operators like string
color parens like comment
color reg_string like math
color tmac_escapes like keyword
color single_slash like char
font args DA DE EN ES FR IT NL NO PT SV
font args DEFAULT CHAPTER NAMED LETTER
font args TYPESET TYPEWRITE
font args FINAL DRAFT
font args BLOCK QUAD
font args LEFT RIGHT CENTER CENTRE JUSTIFY TOP BOTTOM L R C J
font args OFF QUIT END EXIT DONE NO ALL
font args PAGE NUMBER STAR
font args LETTER LEGAL EXECUTIVE LEDGER TABLOID QUARTO FOLIO
font args 10x14 A3 A4 A5 B4 B5
font args SINGLESPACE
font args FACTOR
font args DASH BULLET ALPHA DIGIT USER
font args RGB CYM CMYK GRAY GREY
font args COND CONDX EXT EXTX SUP SUPX CONDSUP CONDSUPX EXTSUP EXTSUPX
font args BOLDER BOLDERX SLANT SLANTX
font args UP DOWN BCK FWD BU BP FU FP
font args ROM IT BD BDI PREV
font args ST
font args SUSPEND RESUME
prefix { \{ \{\
font braces { \{ \{\
prefix [ ]
font brackets [ ]
prefix \(bu \(co \(ct \(de \(dg \(di \(em \(en \(mu \(pl \(rg \(sc \(sq \(lq \(rq
font chars \(bu \(co \(ct \(de \(dg \(di \(em \(en \(mu \(pl \(rg \(sc \(sq \(lq \(rq
prefix \(14 \(12 \(34 \(+-
font chars \(14 \(12 \(34 \(+-
prefix \fR \fB \fI \fP \f0 \f1 \f2 \f3
font chars \fR \fB \fI \fP \f0 \f1 \f2 \f3
prefix .0 .1 .2 .3 .4 .5 .6 .7 .8 .9
font decimals . .0 .1 .2 .3 .4 .5 .6 .7 .8 .9
prefix \/ \/. \/? \/! \/, \/; \/:
font escapes \/ \/. \/? \/! \/, \/; \/:
prefix \, \,. \,? \,! \,, \,; \,:
font escapes \, \,. \,? \,! \,, \,; \,:
prefix \~ \0 \: \| \^ \& \% \!
font escapes \~ \0 \: \| \^ \& \% \!
prefix \b \c \C \d \D \e \f \f( \h \l \L \p \r \s \s+ \s- \S \u \v \w
font escapes \b \c \C \d \D \e \f \f( \h \l \L \p \r \s \s+ \s- \S \u \v \w
prefix ...
font ellipsis ...
prefix + - * / = == < > <= >= <? >? %
font math + - * / = == < > <= >= <? >? %
prefix |
font misc |
prefix ! : &
font operators ! : &
prefix ( )
font parens ( )
prefix # * $
font reg_string # * $
prefix \n \* \[
font single_slash \n \* \[
prefix \\n \\* \\$
font tmac_escapes \\n \\* \\$
comment \#
comment \"

106
contrib/groff/contrib/mom/examples/elvis_syntax.new Normal file
View File

@ -0,0 +1,106 @@
" Steve Kirkendall has thoughtfully reworked elvis's syntax
" highlighting so that it now supports nroff constructs like \fBword
" and \(emword, with \fB and \(em being highlighted while "word" is
" not.
"
" There are some other enhancements as well, making it possible
" to have any word beginning with punctuation (i.e. groff
" requests) highlighted. I've decided to take advantage of these
" improvements, which apply to elvis-2.2h onwards, and write a new
" simplified set of syntax highlighting rules for mom. Just plug
" this file at the end of /etc/elvis/elvis.syn to use them.
"
" If you're using an older version of elvis, stick with the
" highlighting rules in the files elvis_syntax.
#Mom
language mom
extension .mom .tmac
startword .
color startword normal
inword _.'
color inword normal
other initialpunct
mostly normal
backslash none
color args like fixed
color braces like char
color brackets like underlined
color chars like emphasized
color decimals normal
color ellipsis normal
color escapes like keyword
color math like cursor
color misc like string
color operators like string
color parens like comment
color reg_string like math
color tmac_escapes like keyword
color single_slash like char
font args DA DE EN ES FR IT NL NO PT SV
font args DEFAULT CHAPTER NAMED LETTER
font args TYPESET TYPEWRITE
font args FINAL DRAFT
font args BLOCK QUAD
font args LEFT RIGHT CENTER CENTRE JUSTIFY TOP BOTTOM L R C J
font args OFF QUIT END EXIT DONE NO ALL
font args PAGE NUMBER STAR LINE
font args LETTER LEGAL EXECUTIVE LEDGER TABLOID QUARTO FOLIO
font args 10x14 A3 A4 A5 B4 B5
font args SINGLESPACE
font args FACTOR
font args DASH BULLET ALPHA DIGIT USER ROMAN roman alpha
font args SUSPEND RESUME
font args RGB CYM CMYK GRAY GREY
font args COND CONDX EXT EXTX SUP SUPX CONDSUP CONDSUPX EXTSUP EXTSUPX
font args BOLDER BOLDERX SLANT SLANTX
font args UP DOWN BCK FWD BU BP FU FP FN_MARK EN_MARK
font args ROM IT BD BDI PREV
font args ST
prefix { \{ \} \{\ }
font braces { \{ \} \{\ }
prefix [ ]
font brackets [ ]
prefix \(bu \(co \(ct \(de \(dg \(di \(em \(en \(mu \(pl \(rg \(sc \(sq \(lq \(rq
font chars \(bu \(co \(ct \(de \(dg \(di \(em \(en \(mu \(pl \(rg \(sc \(sq \(lq \(rq
prefix \(14 \(12 \(34 \(+-
font chars \(14 \(12 \(34 \(+-
prefix \fR \fB \fI \fP \f0 \f1 \f2 \f3
font chars \fR \fB \fI \fP \f0 \f1 \f2 \f3
prefix .0 .1 .2 .3 .4 .5 .6 .7 .8 .9
font decimals . .0 .1 .2 .3 .4 .5 .6 .7 .8 .9
prefix \/ \/. \/? \/! \/, \/; \/:
font escapes \/ \/. \/? \/! \/, \/; \/:
prefix \, \,. \,? \,! \,, \,; \,:
font escapes \, \,. \,? \,! \,, \,; \,:
prefix \~ \0 \: \| \^ \& \% \!
font escapes \~ \0 \: \| \^ \& \% \!
prefix \b \c \C \d \D \e \f \f( \h \l \L \p \r \s \s+ \s- \S \u \v \w
font escapes \b \c \C \d \D \e \f \f( \h \l \L \p \r \s \s+ \s- \S \u \v \w
prefix ...
font ellipsis ...
prefix + - * / = == < > <= >= <? >? %
font math + - * / = == < > <= >= <? >? %
prefix |
font misc |
prefix ! : &
font operators ! : &
prefix ( )
font parens ( )
prefix # * $
font reg_string # * $
prefix \n \*
font single_slash \n \*
prefix \\n \\* \\$
font tmac_escapes \\n \\* \\$
character \]'
comment \#
comment \"

574
contrib/groff/contrib/mom/examples/sample_docs.mom Normal file
View File

@ -0,0 +1,574 @@
\# This file contains three greeked documents collated together:
\#
\# i) two pages of a novelist's outline
\# ii) two pages of a chapter using COPYSTYLE DRAFT
\# iii) three pages of an academic paper, set in two columns
\#
\# Mom's defaults are used throughout, except for iii), which
\# demonstrates some of the ways you can design your own documents.
\#
\# Since the text throughout is greeked, and groff doesn't know how
\# to hyphenate all that pseudo-latinate nonsense, I've inserted
\# discretionary hyphens (\%) into a large number of the the words.
\# Normally, this isn't necessary.
\#
\# The PRINTSTYLE is TYPESET. If you'd like to see what mom does
\# with the documents when the PRINTSTYLE is TYPEWRITE, change
\# PRINTSTYLE TYPESET, below, to PRINTSTYLE TYPEWRITE. Also, in the
\# third example, comment out PARA_INDENT and QUOTE_INDENT (lines
\# 332 and 333).
\#
\# ===================================================================
\#
\# First, a sample "NAMED" document--in this case, an outline.
\# A novelist wouldn't normally write an outline with numbered heads,
\# subheads and paraheads. I've turned the feature on merely to
\# demonstrate it.
\#
\# Reference macros
\#
.TITLE "Lake Attica's Shores"
.SUBTITLE "A Romance Novel"
.AUTHOR "Rosemary Winspeare"
.DRAFT 1 \" Ignored because COPYSTYLE is FINAL
.REVISION 2 \" Ignored because COPYSTYLE is FINAL
.COPYRIGHT "2004 Alma Podborski
\#
\# Reference macros for the document cover
\#
.DOC_COVERTITLE "Sample mom Documents"
.MISC "Three types of mom documents" "assembled and collated by mom's author"
\#
\# Docstyle macros
\#
.DOCTYPE NAMED "Outline"
.PRINTSTYLE TYPESET \" Or TYPEWRITE to preview "typewritten, double-spaced"
\#
.DOC_COVER COVERTITLE MISC
.COVER TITLE AUTHOR DOCTYPE COPYRIGHT
\#
\# Additional setup macros
\#
.NUMBER_PARAHEADS
\#
.START
.PP
.PARAHEAD "A note on the setting"
Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam
nonumy eirmod tempor invidunt ut labore et do\%lo\%re magna ali\%quyam erat,
sed diam voluptua. Stet clita kasd gubergren, no sea takimata sanctus est.
At vero eos et accusam et justo duo do\%lo\%re et ea rebum.
.PP
Stet clita kasd gubergren, no sea takimata sanctus est. Lorem ipsum
dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod
tempor invidunt ut labore et do\%lo\%re magna ali\%quyam erat, sed diam
voluptua.
.PP
Consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt
ut labore et do\%lo\%re magna ali\%quyam erat, sed diam voluptua. At
vero, eos et accusam et justo duo do\%lo\%res et ea rebum. Consetetur
sadipscing elitr, sed diam nonumy.
.LINEBREAK
.PP
.PARAHEAD "About historical personnages"
At vero eos et accusam et justo duo do\%lo\%res et ea rebum. Stet clita
kasd gubergren, no sea takimata sanctus est. Tempor invidunt ut
labore et do\%lo\%re magna ali\%quyam erat, sed diam voluptua.
.PP
Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam
nonumy eirmod tempor invidunt ut labore et do\%lo\%re magna ali\%quyam erat,
sed diam voluptua. Consetetur sadipscing elitr, sed diam nonumy
eirmod tempor invidunt ut labore et do\%lo\%re magna. Tempor invidunt
ut labore et do\%lo\%re magna ali\%quyam erat, sed diam voluptua.
.NUMBER_HEADS
.NUMBER_SUBHEADS
.HEAD "Part One"
.SUBHEAD "Chapter 1"
.PP
Lorem ipsum dolor sit amet, consetetur sadipscing elitr,
sed diam nonumy eirmod tempor invidunt ut labore et do\%lo\%re magna
ali\%quyam erat, sed diam voluptua. At vero eos et accusam et
justo duo do\%lo\%res et ea rebum.
.PP
At vero eos et accusam et justo duo do\%lo\%res et ea rebum. Stet clita
kasd gubergren, no sea takimata sanctus est. Lorem ipsum dolor sit
amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor
invidunt ut labore et do\%lo\%re magna ali\%quyam erat, sed diam voluptua.
Stet clita kasd gubergren, no sea takimata sanctus est.
.SUBHEAD "Chapter 2"
.PP
Stet clita kasd gubergren, no sea takimata sanctus est. Lorem ipsum
dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod
tempor invidunt ut labore et do\%lo\%re magna ali\%quyam erat, sed diam
voluptua. At vero eos et accusam et justo duo do\%lo\%res et ea rebum.
.PP
Lorem ipsum dolor sit amet, consetetur sadipscing elitr,
sed diam nonumy eirmod tempor invidunt. Ut labore et do\%lo\%re magna
ali\%quyam erat, sed diam voluptua at vero.
.SUBHEAD "Chapter 3"
.PP
Eos et accusam et justo duo do\%lo\%res et ea rebum. Stet clita kasd
gubergren, no sea takimata sanctus est lorem ipsum dolor sit amet.
Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam
nonumy eirmod tempor invidunt ut labore et do\%lo\%re magna ali\%quyam erat,
sed diam voluptua. At vero eos et accusam et justo duo do\%lo\%res et
ea rebum.
.HEAD "Part Two"
.SUBHEAD "Chapter 4"
.PP
Stet clita kasd gubergren, no sea takimata sanctus est
lorem ipsum dolor sit amet. Lorem ipsum dolor sit amet, consetetur
sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore
et do\%lo\%re magna ali\%quyam erat, sed diam voluptua.
.PP
At vero eos et accusam et justo duo do\%lo\%res et ea rebum. Stet clita
kasd gubergren, no sea takimata sanctus est lorem ipsum dolor sit amet.
.PP
Nonumy eirmod tempor invidunt ut labore et do\%lo\%re magna ali\%quyam erat,
sed diam voluptua. At vero eos et accusam et justo duo do\%lo\%res et
ea rebum. Lorem ipsum dolor sit amet, consetetur sadipscing elitr,
sed diam nonumy eirmod tempor invidunt ut labore et do\%lo\%re magna
ali\%quyam erat, sed diam voluptua. At vero eos et accusam et justo
duo do\%lo\%res et ea rebum. Stet clita kasd gubergren, no sea takimata
sanctus est lorem ipsum dolor sit amet. Consetetur sadipscing elitr,
sed diam nonumy eirmod tempor invidunt.
.SUBHEAD "Chapter 5"
.PP
Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed
diam nonumy eirmod tempor invidunt ut labore et do\%lo\%re magna
ali\%quyam erat, sed diam voluptua. At vero eos et accusam et
justo duo do\%lo\%res et ea rebum. Stet clita kasd gubergren,
no sea takimata sanctus est lorem ipsum dolor sit amet.
.PP
Consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt
ut labore et do\%lo\%re magna ali\%quyam erat, sed diam voluptua. At vero
eos et accusam et justo duo do\%lo\%res et ea rebum. Stet clita kasd
gubergren, no sea takimata sanctus.
.PP
At vero eos et accusam et justo duo do\%lo\%res et ea rebum. Stet clita
kasd gubergren. Sea takimata sanctus est lorem ipsum dolor
sit amet. Accusam et justo duo do\%lo\%res et ea rebum
.SPREAD
.RIGHT
\*[BD]\&...end of sample outline\c
.EL
.COLLATE
\#
\# The .EL after the line "...end of sample outline" ensures that
\# mom doesn't spring the page trap, which would deposit a header at
\# the top of the next page. COLLATE doesn't print a page header
\# on the first page of a collated document, but if the page trap
\# has already deposited one there, COLLATE can't undo it.
\#
\# Normally, this isn't necessary; here we require it because the
\# line falls right at the bottom of the page, and would therefore
\# normally spring the page trap. Sorry for the fussiness, but at
\# least now you know what to do if you ever encounter the problem
\# of a page header printing at the top of a collated document.
\#
\# Please notice, too, the use of "\&" before "..." Whenever an
\# input line begins with either a period, an apostrophe or a space,
\# you must precede it with \&, otherwise the line will disappear,
\# even when, as here, there's an inline escape that starts the
\# line.
\#
\# =====================================================================
\#
\# Next, two pages of a chapter, set in DRAFT style, showing
\# the use of the EPIGRAPH BLOCK macro and the QUOTE macro.
\#
\# You'll notice that the starting page number of this "draft" is 1 (in
\# roman numerals). COPYSTYLE DRAFT always numbers the first page of a
\# document 1.
\#
\# Reference macros
\#
.TITLE "Lake Attica's Shores"
.SUBTITLE "A Romance Novel"
.AUTHOR "Rosemary Winspeare"
.CHAPTER 1
.CHAPTER_TITLE "The Bonny Blue Yonder"
.DRAFT 1
.REVISION 2
.MISC "Draft 1, 2nd revision"
\#
\# Docstyle macros
\#
.DOCTYPE CHAPTER
.COPYSTYLE DRAFT
\#
\# Additional style macros
\#
.EPIGRAPH_FONT I \" Epigraphs are normally set in roman
.DRAFT_WITH_PAGENUMBER \" Draft/revision info usually goes in the header
.COVER_MISC_QUAD RIGHT \" Change default position of the cover "misc" line
\#
.COVER CHAPTER+TITLE MISC
\#
.START
.EPIGRAPH BLOCK
Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam
nonumy eirmod tempor invidunt ut labore et do\%lo\%re magna ali\%quyam erat,
sed diam voluptua.
.RIGHT
\*[ROM]\(emJoseph E. Blough
.EPIGRAPH OFF
.PP
Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam
nonumy eirmod tempor invidunt ut labore et do\%lo\%re magna ali\%quyam erat,
sed diam voluptua. At vero eos et accusam et justo duo do\%lo\%res et
ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est.
At vero eos et accusam et justo duo do\%lo\%res et ea rebum. Lorem ipsum
dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod
tempor invidunt ut labore et do\%lo\%re magna ali\%quyam erat, sed diam
voluptua. At vero eos et accusam et justo duo do\%lo\%res et ea rebum.
Stet clita kasd gubergren, no sea takimata sanctus est. At vero eos
et accusam et justo duo do\%lo\%res et ea rebum.
.PP
Stet clita kasd gubergren, no sea takimata sanctus est. Lorem ipsum
dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod
tempor invidunt.
.PP
"Consetetur sadipscing elitr," dixit ea.
.PP
"Sed diam nonumy eirmod tempor invidunt ut labore," dixit eum.
.PP
Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam
nonumy eirmod tempor invidunt ut labore et do\%lo\%re magna ali\%quyam erat,
sed diam voluptua. Consetetur sadipscing elitr, sed diam nonumy
eirmod tempor invidunt ut labore et do\%lo\%re magna.
.PP
"Lorem ipsum dolor sit amet," dixit ea.
.PP
"At vero eos et accusam et justo duo do\%lo\%res et ea rebum. Stet clita
kasd gubergren, no sea takimata sanctus est," dixit eum. "Sed diam
nonumy eirmod tempor invidunt ut labore et do\%lo\%re magna ali\%quyam erat,
sed diam voluptua."
.PP
Consetetur sadipscing elitr, sed diam nonumy eirmod tempor:
.QUOTE
Invidunt ut labore et do\%lo\%re
Magna ali\%quyam erat sed diam
Voluptua stet clita kasd gubergren
No sea takimata sanctus est.
.QUOTE OFF
.PP
Justo duo do\%lo\%res et ea rebum. Stet clita kasd gubergren, no
sea takimata sanctus est. Lorem ipsum dolor sit amet, consetetur
sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore
et do\%lo\%re magna ali\%quyam erat, sed diam voluptua.
.PP
"Stet clita kasd gubergren," dixit ea.
.PP
"No sea takimata sanctus est," dixit eum.
.PP
Nonumy eirmod tempor invidunt ut labore et do\%lo\%re magna. Aliquyam erat
sed diam voluptua. At vero eos et accusam et justo, duo do\%lo\%res et
ea rebum.
.PP
Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam
nonumy eirmod tempor invidunt. Ut labore et do\%lo\%re magna ali\%quyam
erat, sed diam voluptua at vero. Stet clita kasd gubergren, no sea
takimata sanctus est. Consetetur sadipscing elitr, sed diam nonumy
eirmod tempor invidunt ut labore et do\%lo\%re magna.
.PP
Invidunt ut labore et do\%lo\%re magna ali\%quyam erat, sed diam voluptua.
At vero eos et accusam et justo duo do\%lo\%res et ea rebum. Stet clita
kasd gubergren, no sea takimata sanctus est. At vero eos et accusam et
justo duo do\%lo\%res et ea rebum. Lorem ipsum dolor sit amet, consetetur
sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore
et do\%lo\%re magna ali\%quyam erat, sed diam voluptua. At vero eos et
accusam et justo duo do\%lo\%res et ea rebum. Stet clita kasd gubergren,
no sea takimata sanctus est. At vero eos et accusam et justo duo
do\%lo\%res et ea rebum.
.RIGHT
\*[BD]\&...end of sample chapter
.COLLATE
\#
\# =====================================================================
\#
\# Finally, a sample academic article, set in two columns with a
\# 1.5-pica gutter between them. This example also uses QUOTES,
\# BLOCKQUOTES and FOOTNOTES. In addition, it's set RECTO_VERSO,
\# with differing left and right margins that alternate from page to
\# page. (The header also flips from right to left, which you can
\# see on the 2nd and 3rd pages).
\#
\# In order to accomodate the narrow measure of the columns, there's also
\# a demonstration of things you can change with both the typesetting
\# macros and the document processing "control" macros.
\#
\# Reference macros
\#
.TITLE "CONTROL EQUALS CHAOS"
.SUBTITLE "\*[ALD1]The Psychological and Auditory \
Impact of Serial vs. Aleatoric Music\*[RLD1]"
.AUTHOR "Joe Chang" "and" "Brad Hegel Connors"
.COPYRIGHT "2004 J. Chang, B.H. Connors
.MISC "Submitted June 3, 2004" "\*[IT]Piano Quarterly\*[PREV]"
\#
\# Docstyle macros
\#
.DOCTYPE DEFAULT
.COPYSTYLE FINAL
\#
\# Additional style macros -- general type parameters
\#
.L_MARGIN 6P
.R_MARGIN 4P+6p
.PT_SIZE 10
.AUTOLEAD 1.5
\#
\# Additional style macros -- change mom's default behaviour
\#
.RECTO_VERSO
.PAGENUM 1
.HEADER_LEFT "Chang, Connors" \" Because we have two authors
.COLUMNS 2 1P+6p
.SUBTITLE_SIZE +1.5
.AUTHOR_SIZE +.5
.DOCHEADER_LEAD +2p
.HEADER_SIZE +1
.PARA_INDENT 1P \" Comment this out if previewing PRINTSTYLE TYPEWRITE
.QUOTE_INDENT 2 \" Comment this out if previewing PRINTSTYLE TYPEWRITE
.SUBHEAD_SIZE +0
.BLOCKQUOTE_FAMILY H
.BLOCKQUOTE_SIZE -2
.NUMBER_HEADS OFF \" Because we turned them on in the first example
.NUMBER_SUBHEADS OFF \" Ibid
\#
.COVER TITLE AUTHOR COPYRIGHT MISC
\#
.START
.PP
Lorem ipsum dolor sit amet, consetetur sadipscing elitr. Sed diam
nonumy eirmod tempor invidunt ut labore et do\%lo\%re magna. Ali\%quyam
erat, sed diam voluptua.
.PP
At vero eos et accusam et justo duo do\%lo\%res et ea rebum. Stet clita
kasd gubergren no sea takimata. Sanctus est, lorem ipsum dolor sit
amet. Consetetur sadipscing elitr, sed diam nonumy. Eirmod tempor
invidunt ut labore et do\%lo\%re magna ali\%quyam erat. Sed diam voluptua
at vero eos et accusam et justo.
\#
.BLOCKQUOTE
Stet clita kasd gubergren, no sea takimata sanctus est lorem.
Ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy
eirmod tempor. Invidunt ut labore et do\%lo\%re magna ali\%quyam erat,
sed diam voluptua at vero. Eos et accusam et justo duo do\%lo\%res et
ea rebum stet clita.\c
.FOOTNOTE \" Note the use of \c, above, to keep the word and footnote marker together.
Clita ipsum dolor sit amet, consetetur sadipscing elitr.
.FOOTNOTE OFF
.BLOCKQUOTE OFF
\#
.PP
Duo do\%lo\%res et ea rebum, stet clita kasd gubergren. No sea takimata
sanctus est lorem ipsum dolor sit amet, consetetur sadipscing elitr.
Sed diam nonumy eirmod tempor invidunt ut labore et do\%lo\%re magna
ali\%quyam. Erat sed diam voluptua at. Vero eos et accusam et justo
duo do\%lo\%res et ea rebum stet. Clita kasd gubergren no sea takimata
sanctus est.
.PP
Nonumy eirmod tempor invidunt, ut labore et do\%lo\%re magna ali\%quyam
erat? At vero eos et accusam et justo duo do\%lo\%res et ea. Rebum stet
clita kasd gubergren no sea takimata sanctus. Est lorem ipsum dolor
sit amet. Sadipscing\c
.FOOTNOTE
Sadipscing diam nonumy eirmod tempor invidunt ut labore et do\%lo\%re magna
ali\%quyam erat, sed diam voluptua.
.FOOTNOTE OFF
elitr sed diam nonumy eirmod tempor invidunt. Ut labore et do\%lo\%re
magna ali\%quyam erat, sed diam voluptua. At vero eos et accusam et
justo duo do\%lo\%res et ea rebum. Stet clita kasd gubergren no sea.
\#
.SUBHEAD "Schoenberg\(em" "The Origins of Serial Pitch Organization"
\#
.PP
Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam
nonumy eirmod tempor invidunt ut labore et do\%lo\%re magna ali\%quyam erat,
sed diam voluptua. At vero eos et accusam et justo duo do\%lo\%res et ea
rebum. Stet clita kasd gubergren, no sea takimata sanctus est lorem.
Ipsum dolor sit amet consetetur sadipscing. Elitr, sed diam nonumy,
eirmod tempor invidunt ut labore et do\%lo\%re magna. Ali\%quyam erat sed
diam voluptua, at vero eos. Et accusam et justo duo do\%lo\%res et ea
rebum stet clita kasd gubergren lorem ipsum. Dolor sit amet
consetetur, sadipscing elitr, sed diam. Nonumy eirmod tempor invidunt
ut labore et do\%lo\%re. Magna ali\%quyam erat sed diam voluptua at vero.
Eos et accusam et justo duo do\%lo\%res et ea rebum stet clita kasd.
Gubergren no sea takimata sanctus est.
.PP
Amet consetetur sadipscing elitr sed diam nonumy eirmod. Tempor
invidunt ut labore. Et dolor\%e magna ali\%quyam erat, sed diam voluptua,
at vero. Eos et accusam et justo duo do\%lo\%res et ea rebum. Stet clita
kasd gubergren.
.PP
No sea takimata\c
.FOOTNOTE
Takimata sadipscing elitr, sed diam nonumy eirmod tempor invidunt
ut labore et do\%lo\%re magna ali\%quyam erat, sed diam voluptua.
.FOOTNOTE OFF
sanctus est lorem. Ipsum dolor sit amet, consetetur
sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore
et do\%lo\%re magna ali\%quyam erat, sed diam voluptua. At vero eos et
accusam et justo duo do\%lo\%res et ea rebum amet. Consetetur sadipscing
elitr sed diam nonumy eirmod tempor invidunt ut labore, et do\%lo\%re
magna ali\%quyam erat. Sed diam voluptua, at vero, eos et accusam et
justo duo do\%lo\%res et ea rebum.
\#
.SUBHEAD "Messiaen to Stockhausen\(em" "The Quest for Absolute Control"
\#
.PP
Vero eos et accusam et justo duo do\%lo\%res et ea rebum amet:
.QUOTE
Eirmod tempor invidunt
Ut labore et do\%lo\%re magna ali\%quyam erat
Sed diam voluptua
At vero eos et accusam et justo duo do\%lo\%res.
.QUOTE OFF
Lorem ipsum dolor sit amet, consetetur sadipscing elitr
sed diam. Nonumy eirmod tempor invidunt ut labore et do\%lo\%re magna.
Aliquyam erat, sed diam voluptua at vero eos et accusam. Et
justo duo do\%lo\%res et ea rebum stet.
.PP
Elitr sed diam nonumy eirmod tempor. Invidunt ut labore et do\%lo\%re
magna ali\%quyam erat sed. Diam voluptua at vero eos et accusam et
justo duo do\%lo\%res et ea rebum.
\#
.BLOCKQUOTE
Sanctus est lorem ipsum dolor sit amet, consetetur sadipscing. Elitr,
sed diam nonumy eirmod tempor, invidunt ut labore et do\%lo\%re magna
ali\%quyam. Erat sed diam voluptua, at vero eos et accusam et justo
rebum amet. Consetetur sadipsc\%ing elitr sed diam nonumy eirmod
sed diam nonumy, eirmod tempor. Invidunt tempor invidunt ut labore.\c
.FOOTNOTE
Labore diam nonumy eirmod tempor, invidunt ut labore et do\%lo\%re
magna ali\%quyam. Erat sed diam voluptua, at vero eos et accusam et
justo.
.FOOTNOTE OFF
Et do\%lo\%re et magna ali\%quyam erat, sed diam voluptua, at vero.
Eos et accusam et justo duo.
.BLOCKQUOTE OFF
\#
.PP
Lorem ipsum dolor sit amet, consetetur sadipscing elitr. Sed diam
nonumy eirmod tempor invidunt ut labore et do\%lo\%re magna.
.PP
Nonumy eirmod tempor invidunt, ut labore et do\%lo\%re magna ali\%quyam
erat? At vero eos et accusam et justo duo do\%lo\%res et ea. Rebum stet
clita kasd gubergren no sea takimata sanctus. Est lorem ipsum dolor
sit amet. Sadipscing elitr sed diam nonumy eirmod tempor invidunt.
Ut labore et do\%lo\%re magna ali\%quyam erat, sed diam voluptua.
At vero eos et accusam et justo duo do\%lo\%res et ea rebum.
Stet clita kasd gubergren no sea. Ali\%quyam erat, sed diam voluptua.
\#
.SUBHEAD "John Cage\(em" "Leaving It All to Chance"
\#
.PP
Sit amet, consetetur sadipscing elitr, sed diam nonumy. Eirmod tempor
invidunt ut labore et do\%lo\%re magna. Ali\%quyam erat, sed diam
voluptua at vero. Eos et accusam et justo duo dolores et ea rebum.
Stet clita kasd gubergren, no sea taki\%mata sanctus est.
.PP
Consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt
ut labore et do\%lo\%re magna ali\%quyam erat, sed diam voluptua. At vero
eos et accusam et justo duo do\%lo\%res et ea rebum. Stet clita kasd
gubergren, no sea takimata sanctus est lorem. Ipsum dolor sit amet,
consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt
ut labore et do\%lo\%re magna ali\%quyam erat, sed diam voluptua. At vero
eos et accusam et justo duo do\%lo\%res et ea rebum.
.PP
Stet clita kasd gubergren. No sea takimata sanctus est lorem ipsum
dolor sit. Amet consetetur sadipscing elitr, sed diam nonumy eirmod
tempor. Invidunt ut labore et do\%lo\%re magna ali\%quyam erat, sed diam
voluptua, at vero. Eos et accusam et justo duo do\%lo\%res et ea rebum.
Stet clita kasd gubergren, no sea takimata. Sanctus est lorem ipsum
dolor sit amet consetetur. Sadipscing elitr sed diam nonumy eirmod
tempor invidunt. Ut labore et do\%lo\%re magna ali\%quyam erat, sed diam
voluptua. At vero eos et accusam et justo duo do\%lo\%res et ea rebum.
\#
.BLOCKQUOTE
.PP
Stet clita kasd gubergren no sea. Takimata sanctus est lorem ipsum
dolor sit amet. Consetetur sadipscing elitr sed diam nonumy eirmod
tempor invidunt ut labore et do\%lo\%re. Magna ali\%quyam\c
.FOOTNOTE
Aliquyam nonumy eirmod tempor invidunt ut labore.
.FOOTNOTE OFF
erat, sed diam
voluptua at vero eos et accusam. Et justo duo do\%lo\%res et ea rebum,
stet clita kasd gubergren, no sea takimata.
.PP
Sanctus est lorem ipsum. Dolor sit amet consetetur sadipscing
elitr. Sed diam nonumy eirmod tempor invidunt ut labore. Et
do\%lo\%re magna ali\%quyam erat, sed diam voluptua. At vero eos et
accusam et justo duo. Dolores et ea rebum stet clita kasd gubergren
no sea.
.PP
Takimata lorem ipsum dolor sit amet consetetur sadipscing elitr.
Sed diam, nonumy eirmod tempor, invidunt ut labore et do\%lo\%re magna.
Aliquyam erat sed diam voluptua. At vero eos et accusam et
justo.\c
.FOOTNOTE
Justo vero eos et accusam et justo duo.
.FOOTNOTE OFF
.BLOCKQUOTE OFF
\#
.PP
Duo do\%lo\%res et ea rebum, stet clita kasd gubergren, no sea takimata
sanctus. Est lorem ipsum. Dolor sit amet, consetetur sadipscing elitr,
sed diam nonumy. Eirmod tempor invidunt ut labore et do\%lo\%re magna
ali\%quyam erat, sed diam voluptua. At vero eos et accusam.
.PP
Et justo duo do\%lo\%res et ea rebum stet clita kasd. Gubergren
no sea takimata sanctus est. Lorem ipsum dolor sit amet, consetetur
sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore
et dolore magna ali\%quyam erat, sed diam voluptua. At vero eos et
accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren,
no sea takimata sanctus est.
\#
.SUBHEAD "Beyond Cage\(em" "Catching the Midnight Train"
\#
.PP
Lorem ipsum dolor sit amet, consetetur sadipscing elitr. Sed diam
nonumy eirmod tempor invidunt ut labore et do\%lo\%re magna. Ali\%quyam
erat, sed diam voluptua.
.PP
At vero eos et accusam et justo duo do\%lo\%res et ea rebum. Stet clita
kasd gubergren no sea takimata. Sanctus est, lorem ipsum dolor sit
amet. Consetetur sadipscing elitr, sed diam nonumy. Eirmod tempor
invidunt ut labore et do\%lo\%re magna ali\%quyam erat. Sed diam voluptua
at vero eos et accusam et justo.
.PP
Duo do\%lo\%res et ea rebum, stet clita kasd gubergren. No sea takimata
sanctus est lorem ipsum dolor sit amet, consetetur sadipscing elitr.
Sed diam nonumy eirmod tempor invidunt ut labore et do\%lo\%re magna
ali\%quyam. Erat sed diam voluptua at. Vero eos et accusam et justo
duo do\%lo\%res et ea rebum stet. Clita kasd gubergren no sea takimata
sanctus est.
.PP
Nonumy eirmod tempor invidunt, ut labore et do\%lo\%re magna ali\%quyam
erat? At vero eos et accusam et justo duo do\%lo\%res et ea. Rebum stet
clita kasd gubergren no sea takimata sanctus. Est lorem ipsum dolor
sit amet. Sadipscing\c
.FOOTNOTE
Sadipscing diam nonumy eirmod tempor invidunt ut labore et do\%lo\%re magna
ali\%quyam erat, sed diam voluptua.
.FOOTNOTE OFF
elitr sed diam nonumy eirmod tempor invidunt. Ut labore et do\%lo\%re
magna ali\%quyam erat, sed diam voluptua. At vero eos et accusam et
justo duo do\%lo\%res et ea rebum. Stet clita kasd gubergren no sea
takimata lorem. Ipsum dolor sit amet, consetetur sadipscing elitr.
Sed diam nonumy eirmod tempor invidunt ut labore et do\%lo\%re magna.
Ali\%quyam erat, sed diam voluptua. At vero eos et accusam et justo
duo do\%lo\%res et ea rebum. Stet clita kasd gubergren, no sea
takimata sanctus est.
.PP
Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed
diam nonumy eirmod tempor invidunt ut labore et do\%lo\%re magna
ali\%quyam erat, sed diam voluptua. At vero eos et accusam et justo
duo do\%lo\%res et ea rebum. Stet clita kasd gubergren, no sea
takimata sanctus est.
.RIGHT
\*[BD]\&...end of sample article\*[PREV]
.FINIS

673
contrib/groff/contrib/mom/examples/typesetting.mom Normal file
View File

@ -0,0 +1,673 @@
\# Most mom users rely on mom's document processing macros to format
\# their work. The doc processing macros take care of all things
\# typographic and are simple, clear and easy to learn. The kind of
\# "by hand" typesetting this file shows off is really geared toward
\# professional typographers. Bear in mind, though, that the full
\# power of mom's typesetting capabilities can be brought to bear
\# on document processing as well.
\#
\# Basic page setup
\#
.PAGE 8.5i 11i \" Printer sheet size
.L_MARGIN 1i \" Left margin 1 inch
.R_MARGIN 1i \" Right margin 1 inch (calculates the line length)
\#
\# Basic type parameters
\#
.FAMILY T \" Times Roman family
.FT B \" Bold font
.PT_SIZE 12 \" Point size
.LS 14 \" Leading (line spacing)
.LEFT \" Set lines flush left, nofill mode
\#
\# Refinements
\#
.HY \" Hyphenate
.KERN \" Automatic pairwise kerning
.LIGATURES \" Automatic ligature generation
.SMARTQUOTES \" Enable smartquotes
.SS 0 \" No extra space between sentences
\#
.ALD 1i-1v \" Advance 1 inch from top of paper to first baseline
Example 1\*[BU 2]:
.ALD .25v \" Advance an extra 1/4 linespace
.UNDERSCORE 3.75p "T\*[BU 4]asting notes using padding, string tabs \
and multi-columns"
\#
.SP \" Add an extra line space
\#
.FAM H \" Helvetica family
.PT_SIZE 10
.LS 11 \" New leading
\#
\# The following uses a combination of padding, string tabs, and the
\# FWD escape to set up five tabs with 1-pica gutters stretched over
\# the full line length.
\#
.SILENT \" Don't print the next line
.PAD "\*[ST1]VIN#\*[ST1X]\*[FWD 1P]\*[ST2]ROBE#\*[ST2X]\*[FWD 1P]\*[ST3]NEZ#\*[ST3X]\*[FWD 1P]\*[ST4]BOUCHE#\*[ST4X]\*[FWD 1P]\*[ST5]COMMENTAIRES\*[ST5X]"
.SILENT OFF \" Resume normal printing of text
\#
\# Now that the string tabs have been marked off, we "set" them.
\#
.ST 1 L \" First string tab flush left, nofill mode (no need for .BR's between input lines)
.ST 2 L QUAD \" Remaining tabs are flush left/rag right, fill mode
.ST 3 L QUAD
.ST 4 L QUAD
.ST 5 L QUAD
\#
.TAB 1 \" Call first tab
.UNDERSCORE "VIN"
.TN \" Move to next tab and stay on the same baseline
.UNDERSCORE "ROBE"
.TN \" Ibid
.UNDERSCORE "NEZ"
.TN \" Ibid
.UNDERSCORE "BOUCHE"
.TN \" Ibid
.UNDERSCORE "COMMENTAIRES"
.TQ \" Quit tabs
\#
.ALD 6p \" Advance an extra 6 points
.FT R \" Change font to roman (medium)
.MCO \" Turn multi-column mode on
\#
.TAB 1 \" Notice that this tab gets set line-for-line
\*[IT]Peelee Island \" Set italic
\*[PREV]Gewürztraminer \" Revert to former font (roman)
2000
(Canada)
.MCR \" Return to top of column
.TAB 2 \" Call tab 2; in multi-column mode, don't use .TN
Jaune pâle.
.MCR
.TB 3 \" Notice that from here on, we use the alias TB instead of TAB
Frais, fruité, ci\%tronné, arômes fortes de lichee et de fruits
tropicaux.
.MCR
.TB 4
Doux, fruité, bien équilibré avec une bonne acidité.
.MCR
.TB 5
Bon apéro. Servir avec des plats
.RW .1 \" Reduce Whitespace between letters to tighten this line
indiens ou \%chinois.
.RW 0 \" Back to normal spacing between letters
.BR
Excellent rapport qualité/prix.
.MCX 8p \" Multi-column mode off; advance an extra 8 points
.MCO \" Re-invoke multi-columns for next wine description
.TB 1
\*[IT]Carau Pujol
\*[ROM]Tannat
1995
(Uraguay)
.MCR
.TB 2
Rubis foncé, vio\%lacée, presque opaque.
.MCR
.TB 3
Belles arômes de fruits foncés (prunes, cerises noires, cassis).
Odeurs tertiares de cuir, cèdre, violets, eucalyptus, avec une trace
exotique de Band-Aid*\*[BU 12].
\#
\# The \*[BU 12], above, pulls the period back so that it falls
\# underneath the asterisk. \*[BP<n>] could have been used instead
\# if you prefer to use points rather than kern units.
\#
.MCR
.TB 4
Très rond, tannins mûres et veloutés, avec un long finis fruité et
doucement alcoolique.
.MCR
.TB 5
Superbe\|! Une aubaine à ne pas manquer. Prêt à boire maintenant.
.MCX 1v \" Multi-columns off; advance an extra linespace
\#
\# Now, an example of a hanging indent. This is excessively fussy
\# from a typographic standpoint in that it hangs the asterisk outside
\# the current left margin so that the text following it lines up with
\# with the text in the tasting notes. Notice that in order to use a
\# hanging indent, you must first set a left indent.
\#
.FT I \" Change font to italic
.PT_SIZE -.5 \" Reduce point size by 1/2 point
.LS -.5 \" Reduce leading by 1/2 point
.JUSTIFY \" Set text justified
\#
\# Now, move the left margin back by the width of an asterisk plus 2 points...
\#
.L_MARGIN -(\w'*'+2p)
\#
\# ...and set a left indent equal to the width of an asterisk plus 2 points
\#
.IL \w'*'+2p
\#
\# Now, set the hanging indent equal to the left indent, effectively pulling
\# the first line of the following text back to the new left margin.
\# Subsequent output lines will be indented by the .IL amount.
\# Notice that when using the \w inline escape, there's no need to append
\# a unit of measure to it.
\#
.HI \w'*'+2p
*\*[FWD 1p]The term "Band-Aid" means the slightly sweet, vaguely chemical
smell associated with medical-grade plastics. It is often found in
wines from terroirs in South America. Provided a wine has a sufficient
concentration of fruit
.RW .04 \" Kern the whole next line slightly, so "lipstick" doesn't hyphenate.
aromas and complex tertiary characteristics, Band-Aid is a Good Thing.
Otherwise, it smells like cheap lipstick.
.RW 0 \" Reset kerning to 0
\#
\# Notice, above, that although the values for IL and HI are the width
\# of an asterisk plus 2 points, when setting the first line of text
\# (the one with the asterisk at the beginning), we put only 1 point of
\# space after the *. This is to compensate for the fact that in the
\# italic font, the letter T doesn't align visually with the rest of
\# the text. As already noted, this is an extremely fussy example. :)
\#
.IQ CLEAR \" Cancel and clear stored indent values
.L_MARGIN 1i \" Reset left margin to its original value.
\#
.ALD 2P \" Add 2-picas extra space before next example
\#
.FAM T
.FT B
.PT_SIZE 12
.LS 14
\#
Example 2:
.ALD .25v
\#
.COMMENT \" COMMENT lets you enter comments without using \# or \"
In the next line, because the string to be underscored must be
enclosed in double-quotes, you can't use the double-quote character
itself around the word "Massaging". We circumvent this by using the
groff inline escapes \(lq and \(rq (leftquote and rightquote).
.COMMENT OFF \" Remember to turn COMMENT off!
\#
.UNDERSCORE 3.75p "\(lqMassaging\(rq \*[BCK 1p]a passage of rag right text"
.SP \" Add an extra linespace
\#
.PT_SIZE 12.5
.LS 14
.PT_SIZE -1 \" Reduce point size by 1 point
Passage using groff spacing defaults
\#
.ALD .5v \" Add an extra 1/2 line space
\#
.PT_SIZE +1 \" Restore point size
.QUAD LEFT \" Set quad left, fill mode
.IB 3P \" Indent 3 picas from both the left and right margins
.FT R
The thousand injuries of Fortunato I had borne as I best 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. \*[IT]At length\*[PREV] I would be
avenged; this was a point definitively settled\(embut the very
definitiveness with which it was resolved, precluded the idea of
risk. I must not only punish, but punish with impunity. A
wrong is unredressed when retribution overtakes its redresser.
It is equally unredressed when the avenger fails to make himself
felt as such to him who has done the wrong.
.ALD 6p
\#
\# The next line is set quad right, nofill mode, 1/2 point smaller
\# than the preceding text (using the \*[SIZE <n>] inline escape.
\#
.RIGHT
\*[SIZE -.5]\(emEdgar Allen Poe, \*[IT]The Cask of Amontillado\*[PREV]\*[SIZE +.5]
.SP \" Extra linespace
.IBQ \" Disable "indent both"
\#
\# The passage above, while acceptable in a longer document, exhibits a
\# few typographic flaws. The shape of the right margin rag exhibits
\# a decidedly "rounded" appearance. The word "I" stands alone at the
\# end of the third line. The space between the 1st and 2nd sentences
\# ("...revenge. You...") is too large, owing to the letter "Y" that
\# begins the 2nd sentence. The spacing between "A wrong..." (line 6)
\# is equally too large because of the way "A" and "w" fit together.
\# The em-dash before Edgar isn't vertically centered with the letter "E".
\# And so on. The most important correction below is fixing the rag
\# so that longer and shorter lines alternate. This is accomplished by
\# manually breaking lines and then slightly lengthening and shortening
\# them until a pleasing rag is achieved. The remainder of the little
\# flaws are fixed with inline escapes.
\#
.FT B
.PT_SIZE -1
.LEFT
The same passage, \*[BU 4]"massaged"
\#
.ALD .5v
\#
.FT R
.PT_SIZE +1
.QUAD LEFT
.HY OFF \" Turn automatic hyphenation off
.BR_AT_LINE_KERN \" Automatically insert a line break (.BR) with each invocation of .RW and .EW
.WS +1 \" Increase word space slightly
.IB \" Turn "indent both" back on; values are the same as before
\#
The thousand injuries of Fortunato I had borne as I best could; but
when he ventured upon insult, I \*[BU 2]vowed revenge. \*[BU 4]Y\*[BU 6]ou,
\*[BU 4]who so \*[BU 2]well know the nature
.EW .2
of my soul, \*[BU 2]will not suppose, however, that I gave utterance to
a threat. \*[IT]At
.EW .2
length\*[PREV] I would be avenged; this was a point definitively
settled\(embut the
.EW .2
v\*[BU 1]ery definitiveness with which it was resolved, precluded the idea
of risk.
.EW 0
I must not only punish, but punish with impunity. A \*[BCK 1p]wrong is
unredressed
.EW .1
when retribution overtakes its redresser. It is equally unredressed
when the
.RW .1
avenger fails to make himself felt as such to him \*[BU 2]who has done
the wrong.
.RW 0 \" Restore normal kerning
.WS +0 \" Restore normal wordspacing
.ALD 6p
.PT_SIZE -.5
.RIGHT
\*[UP 1.5p]\(em\*[DOWN 1.5p]\*[BCK 1p]Edgar \*[BCK 1p]Allen Poe, \*[IT]The Cask of Amontillado\*[PREV]
.IQ CLEAR \" Cancel and clear stored values of all indents
\#
\#
.NEWPAGE \" Start a new page
.T_MARGIN 1i \" Set top margin to 1i (approx. equivalent to .ALD 1i-1v above)
\#
.FAM T
.FT B
.PT_SIZE 12
.LS 14
.LEFT
\#
Example 3:
.ALD .25v
.UNDERSCORE 3.75p "A \*[BU 2]recipe for enumerated lists using indents"
.SP .5v \" Add an extra half line space
.FAM N \" New Century Schoolbook family
.FT R
.PT_SIZE 11
.LS 13
.HY \" Turn hyphenation back on
.JUSTIFY \" Justify text
This example demonstrates the use of left and hanging indents for
simple enumerated lists. Nested lists are possible, as the example
shows; however, the more complex the nesting, the wiser it becomes
to use (string) tabs, as seen in Example 4.
.TI 1.5m
\*[BD]Please note: mom\*[PREV] has macros that allow you to set
enumerated lists automatically. These examples merely show hanging
indents and string tabs in use.
\#
.JUSTIFY \" Justify text
.IL \w'\0.\0' \" Establish a left indent equal to the width of 2 figure spaces plus a period.
.HI \w'\0.\0' \" Establish a hanging indent equal to the size of the left indent.
.ALD 6p
\#
\#
1.\0This is the first item in the list. N\*[BU 2]otice how the first line
"hangs" back from the remaining text, which is otherwise
indented by the width of by two figure-spaces (digit-width
spaces) and a period.
.BR
.HI \" Notice that HI doesn't require an argument once the value's been set
.ALD 6p
2.\0This is the second item in the list. As with the above item,
notice the use of the \*[BU 8]\\0 escape sequence in the input text. It's
there to ensure that the space after the number/period combination
always remains the same (i.e. doesn't stretch when the line is
justified). That way, the text of each item always lines up perfectly.
\#
.COMMENT
Now we're going to set a bullet-point list, indented from the text
above by 1 pica. IL arguments are always added to whatever value
is in already effect for IL, hence all we have to do is tell mom to
indent (from the current left indent) 1 pica plus the width of the
bullet character ( \(bu ). \*[FWD 3p] puts three points of space after
the bullet so that the bullet and the text are visually separated.
.COMMENT OFF
\#
\#
.IL 1P+\w'\(bu\*[FWD 3p]'
\#
\# Hanging indents are always relative to the current left indent.
\# The additional 1-pica indent, above, already having been taken
\# care of, we only want to hang the first lines of bullet list items
\# back by the width of the bullet character plus its 3 extra
\# points of space.
\#
.ALD 6p
.HI \w'\(bu\*[FWD 3p]'
\*[DOWN 1p]\(bu\*[UP 1p]\*[FWD 3p]This is the first line of a sublist with bullets.
N\*[BU 2]otice how the first line (the one with the bullet) is indented
exactly one pica from the text of the list item above it, while the
remaining lines align with the left indent we set above.
.ALD 6p
.HI
\*[DOWN 1p]\(bu\*[UP 1p]\*[FWD 3p]This is the second item of the sublist with bullets. \*[BU 4]We
could go on indefinitely, but let's go back to the top level (numbered)
list...
\#
\# The easiest way to return to a previous indent value is by subtraction.
\# The argument to IL, above, was 1P+\w'\(bu\*[FWD 3p]', so we just reverse
\# it by putting a minus sign in front. The parentheses are required
\# for groff to evaluate the expression properly.
\#
.IL -(1P+\w'\(bu\*[FWD 3p]')
.HI \w'\0.\0' \" Reset hanging indent for use with numbered items.
.ALD 6p
3.\0...and here we are.
.HI \" Again, notice that once HI has been set, you don't have to keep passing it an argument.
.ALD 6p
4.\0In order not to make the example too long, we'll stop here.
.IQ CLEAR \" Don't forget to cancel and/or clear indents!
\#
.FAM T
.FT B
.PT_SIZE 12
.LS 14
.LEFT
.SP
\#
Example 4:
.ALD .25v
.UNDERSCORE 3.75p "A \*[BU 2]recipe for nested lists using string tabs"
.SP .5v
.FAM N
.FT R
.PT_SIZE 11
.LS 13
.JUSTIFY
Although setting up string tabs is a bit more complex than setting
up indents, it's \*[BU 3]well worth the effort, especially for nested lists.
.ALD 6p
\#
.COMMENT
The PAD line, below, sets up two string tabs. The first (ST1)
is exactly the length of two figure spaces and a period. The
second (ST2) is simply "the remainder of the line."
.COMMENT OFF
\#
.SILENT \" Don't print any of this
.PAD "\*[ST1]\0.\0\*[ST1X]\*[ST2]#\*[ST2X]"
.ST 1 L \" String tabs must be "set" after being marked off in a line
.ST 2 J \" ST 1 will be set flush left, nofill; ST 2 will be justified.
.SILENT OFF \" Restore printing
\#
.TB 1
1.
.TN \" Use .TN here so text stays on the same baseline as the number in tab 1
This is the first item in the list. N\*[BU 2]otice how, just as in Example 3,
the first line hangs back from the remaining text, which is otherwise
indented.
.ALD 6p
.TB 1
2.
.TN
This is the second item in the list. N\*[BU 2]otice that when setting "lists"
with tabs, there's no need to use the \*[BU 8]\\0 escape sequence after
the number/period combination in the input text.
.ALD 6p
\#
.COMMENT
Now, set up the indented bullet-point sublist. The PAD line
says: move forward 12 points (1 pica), then mark off a string
tab (ST3) that's the length of the bullet character; move foward
another three points, then make the next string tab (ST4) the
length of remainder of the line.
.COMMENT OFF
\#
.SILENT
.PAD "\*[FWD 12p]\*[ST3]\(bu\*[ST3X]\*[FWD 3p]\*[ST4]#\*[ST4X]"
.ST 3 L
.ST 4 J
.SILENT OFF
.ALD 6p
.TB 3
\*[DOWN 1p]\(bu\*[UP 1p]
.TN
This is the first line of a sublist with bullets. N\*[BU 2]otice how the
bullets and the text line up exactly the same as in Example 3.
.ALD 6p
.TB 3
\*[DOWN 1p]\(bu\*[UP 1p]
.TN
This is the second item of the sublist with bullets. For the fun of
it, lets add in an
.SPREAD
en-dashed sub-sublist.
.BR \" We're in a fill mode right now, so you *must* terminate the line with BR
\#
.SILENT
.PAD "\*[FWD 12p]\*[ST5]\(en\*[ST5X]\*[FWD 4p]\*[ST6]#\*[ST6X]"
.ST 5 L
.ST 6 J
.SILENT OFF
.ALD 6p
.TB 5
\*[UP .75p]\(en\*[DOWN .75p]
.TN
Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam
nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat,
sed diam voluptua.
.ALD 6p
.TB 5
\*[UP .75p]\(en\*[DOWN .75p]
.TN
At \*[BU 3]vero eos et accusam et justo duo dolores et ea rebum. Stet clita
kasd gubergren, no sea takimata sanctus est lorem ipsum dolor sit amet.
.ALD 6p
.TB 1
3.
.TN
And here we are, back at the top-level numbered list with a minimum
of muss and fuss,
.ALD 6p
.TB 1
4.
.TN
Generally speaking, once you get the hang of string tabs and the
\*[BD]PAD\*[PREV] macro, you'll find setting up complex nested lists
(or anything similar to them) easier than with hanging indents.
.TQ
\#
.NEWPAGE
.FAM T
.FT B
.PT_SIZE 12
.LS 14
.LEFT
\#
Example 5:
.ALD .25v
.UNDERSCORE 3.75p "Word spacing"
.ALD 8p
.FAM P \" Palatino family
.PT_SIZE 11
.LS 14
\#
\# The "label" lines for the following are set in Helvetica bold, one
\# point smaller than the examples themselves. This demonstrates the
\# use of the groff inline escape \f[...] to change both family and
\# font inline. It also shows using the mom inline \*S[...], which is
\# an alternate form of the inline, \*[SIZE <n>]
\#
\f[HB]\*S[-1]Normal word spacing\*S[+1]\*[PREV]
.FT R
N\*[BU 1]o\*[BU 1]w \*[BU 1]is the time for all good men to come to the aid of the party.
.ALD 4p
\f[HB]\*S[-1]Word spacing adjusted by \*[UP 1p]\*[BU 3]+\*[DOWN 1p]\*[BU 1]2\*S[+1]\*[PREV]
.FT R
.WS +2
N\*[BU 1]o\*[BU 1]w \*[BU 1]is the time for all good men to come to the aid of the party.
.WS +0
.ALD 4p
\f[HB]\*S[-1]Word spacing adjusted by \*[UP 1p]\*[BU 3]+\*[DOWN 1p]4\*S[+1]\*[PREV]
.FT R
.WS +4
N\*[BU 1]o\*[BU 1]w \*[BU 1]is the time for all good men to come to the aid of the party.
.WS +0
.ALD 4p
\f[HB]\*S[-1]Word spacing adjusted by \*[UP 1p]\*[BU 3]+\*[DOWN 1p]6\*S[+1]\*[PREV]
.FT R
.WS +6
N\*[BU 1]o\*[BU 1]w \*[BU 1]is the time for all good men to come to the aid of the party.
.WS +0
.SP 1.5v
\#
.FAM T
.FT B
.PT_SIZE 12
.LS 14
\#
.LEFT
Example 6:
.ALD .25v
.UNDERSCORE 3.75p "Line kerning"
.ALD 8p
.FAM P \" Palatino family
.FT R
.PT_SIZE 11
.LS 15
\#
\# Here, we set up some tabs so the examples can go into facing columns.
\#
.TAB_SET 1 0 19.5P L
.TAB_SET 2 19.5P 19.5P L
\#
.MCO \" Turn multi-columns on
.TB 1
\f[HB]\*S[-1]Unkerned line\*S[+1]\*[PREV]
.FT R
"But this is \*[IT]important!\/"\*[PREV]she exclaimed.
.ALD 4p
\f[HB]\*S[-1]Line "tightened" \(en .RW .1\*S[+1]\*[PREV]
.RW .1
"But this is \*[IT]important!\/"\*[PREV]she exclaimed.
.ALD 4p
\#
\# In the next line, notice that because it uses a different family
\# (Helvetica instead of Palatino), the RW macro doesn't affect it.
\#
\f[HB]\*S[-1]Line "tightened" \(en .RW .2\*S[+1]\*[PREV]
.RW .2
"But this is \*[IT]important!\/"\*[PREV]she exclaimed.
.ALD 4p
\f[HB]\*S[-1]Line "tightened" \(en .RW .3\*S[+1]\*[PREV]
.RW .3
"But this is \*[IT]important!\/"\*[PREV]she exclaimed.
.MCR
.TB 2
\f[HB]\*S[-1]Unkerned line\*S[+1]\*[PREV]
"But this is \*[IT]important!\/"\*[PREV]she exclaimed.
.ALD 4p
\f[HB]\*S[-1]Line "loosened" \(en .EW .1\*S[+1]\*[PREV]
.EW .1
"But this is \*[IT]important!\/"\*[PREV]she exclaimed.
.ALD 4p
\f[HB]\*S[-1]Line "loosened" \(en .EW .2\*S[+1]\*[PREV]
.EW .2
"But this is \*[IT]important!\/"\*[PREV]she exclaimed.
.ALD 4p
\f[HB]\*S[-1]Line "loosened" \(en .EW .3\*S[+1]\*[PREV]
.EW .3
"But this is \*[IT]important!\/"\*[PREV]she exclaimed.
.MCX 1.5v
\#
.FAM T
.FT B
.PT_SIZE 12
.LS 14
.LEFT
\#
Example 7:
.ALD .25v
.UNDERSCORE 3.75p "Cutaround using left\*[FU 2]/right indents, multi columns \
and a dropcap"
.SP
\#
.FT R
.PT_SIZE 11
.LS 12
.BR_AT_LINE_KERN OFF \" In justified text, it's best to have this OFF
\#
.TAB_SET 1 0 18.5P J
.TAB_SET 2 20.5P 18.5P J
.MCO
.ALD 5P+9p
\#
\# The little picture of tux.
\#
.PSPIC penguin.ps
.MCR
.TAB 1
.XCOLOR red \" Initialize the X11 color, red
.DROPCAP_COLOR red
.DROPCAP_FONT B
.DROPCAP L 3 COND 80 \" i.e. the letter L dropped 3 lines, condensed to 80% of its normal width
.EW .2
orem ipsum dolor sit amet, consetetur sa\%dip\%scing elitr, sed diam
nonumy eir\%mod tempor invidunt ut labore et dolore magna aliquyam erat,
sed diam voluptua.
.EW 0
.TI 1P
At vero eos et accusam et justo duo dolores et ea rebum. Stet clita
kasd gubergren, no sea taki-
.SPREAD \" Force justify preceding line before starting indent
.IR 3.5P
kimata sanctus est lorem ipsum dolor sit amet.
Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam
nonumy eirmod tempor.
.EW .2
.TI
Invidunt ut labore et dolore magna ali\%qu\%yam erat, sed diam voluptua.
At
.EW 0
vero eos et accusam et justo duo dolores et ea rebum.
.TI
Stet clita kasd gubergren, no sea ta-
.SPREAD \" Force justify preceding line before quitting indent
.IRQ
kimata sanctus est lorem ipsum dolor sit amet. Lorem ipsum dolor
sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor
in\%vi\%dunt ut labore et dolore magna aliquyam erat. Sed diam voluptua,
at vero eos et accusam et justo duo
.SPREAD
.EW .3
dolores et ea rebum. Stet clita no kasd guber-
.SPREAD
.MCR
.TB 2
gren, no sea takimata sanctus est lorem ipsum
.EW 0
dolor sit amet. Consetetur sadipscing elitr, sed diam nonumy eirmod
tempor invidunt ut labore et dolore.
.TI
Magna aliquyam erat, sed diam voluptua, at vero eos et accusam.
Et justo duo dolores et ea
.SPREAD
.IL 3.5P
rebum, stet clita kasd gubergren. No sea
takimata sanctus est, lorem ipsum dolor sit amet.
.TI
Sit amet, consetetur sadipscing elitr, sed diam. Nonumy eirmod tempor
in\%vi-
.EW .3
dunt ut labore et dolore magna. Ali-
.EW 0
quyam erat sed diam voluptua.
At vero eos et accusam et justo duo dolores et ea rebum stet.
.ILQ
.TI
Dolores et ea rebum stet clita kasd gubergren, no sea takimata
sanctus. Sadipscing elitr sed diam, nonumy eirmod tempor, invidunt
ut labore et dolore magna aliquyam erat. Sed diam voluptua, at vero
eos et accusam et justo duo dolores et ea rebum.

12
contrib/groff/contrib/mom/groff_mom.man
View File

@ -1,7 +1,7 @@
.ig
This file is part of groff, the GNU roff type-setting system.
Copyright (C) 2002 Free Software Foundation, Inc.
Copyright (C) 2002, 2003, 2005 Free Software Foundation, Inc.
written by Werner Lemberg <wl@gnu.org>
Permission is granted to copy, distribute and/or modify this document
@ -14,6 +14,9 @@ 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
.
.mso www.tmac
.
.de TQ
@ -85,10 +88,13 @@ mom comes with her own (very) complete documentation in HTML format.
.
.B mom
was written by
.MTO df191@ncf.ca "Peter Schaffter" .
.MTO peter@faustus.dyn.ca "Peter Schaffter" .
Please send bug reports to the
.MTO bug-groff@gnu.org "groff bug mailing list"
or directly to the author.
or directly to the author, either at the address above or to
.MTO ptpi@golden.net "" .
.
.cp \n[groff_mom_C]
.
.\" Local Variables:
.\" mode: nroff

561
contrib/groff/contrib/mom/momdoc/appendices.html
View File

@ -1,3 +1,4 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html>
<head>
<meta http-equiv="content-type" content="text/html;charset=iso-8859-1">
@ -7,8 +8,10 @@
<!====================================================================>
<a href="typemacdoc.html#TOP">Prev</a>&nbsp;&nbsp;
<a href="reserved.html#TOP">Next</a>&nbsp;&nbsp;
<a href="macrolist.html#TOP">Prev</a>&nbsp;&nbsp;
<a href="toc.html">Back to Table of Contents</a>
<p>
<a name="TOP"></a>
<a name="APPENDICES">
@ -17,9 +20,13 @@
<ul>
<li><a href="#MOREDOC">Further notes on this documentation</a>
<li><a href="#FONTS">Adding PostScript fonts to groff</a>
<ul>
<li><a href="#HOWTO">How to create a PostScript font for use with groff</a>
</ul>
<li><a href="#CODENOTES">Some reflections on mom, with an apology</a>
<li><a href="reserved.html">List of reserved words</a>
<li><a href="#CONTACT">Contact the author</a>
<li><a href="reserved.html">List of reserved words</a>
</ul>
<a name="MOREDOC">
@ -58,30 +65,517 @@ basic (text only) html. I may have written <strong>mom</strong>,
but I still regularly call on her documentation. Elvis, with its
html capabilities, lets me write and format <strong>mom</strong>
documents AND peruse her documentation, clicking on links as
necessary, without ever leaveing the comfy confines of my
necessary, without ever leaving the comfy confines of my
text editor.
<p>
Not everyone, of course, uses an editor with html capabilities.
For them, firing up a browser is obviously necessary for reading
<strong>mom</strong>'s documentation. Browsers being what they are,
and not everyone on the globe having the cash for muscle machines
to run Galeon, or Konqueror, or Mozilla, or Netscape, their browser
needs to be one that's fast and light -- Lynx, in other words.
to run Galeon, or Konqueror or Mozilla, their browser
needs to be fast and light--and probably &quot;text-only&quot;.
<p>
Some <strong>mom</strong> users may notice the absence of graphics,
frames, and (for the most part) tables in this documentation.
The reason is simple: Lynx. People who, for whatever reason (choice
or necessity), use Lynx to read the documentation must be able to make
sense of it. All of it. Graphical examples of <strong>mom</strong>
in action might have made some parts of the documenation easier to
write, but would have excluded Lynx-only users. And it goes
without saying that the documentation looks fine if you're
reading it in a graphical browser.
frames, and (for the most part) tables in this documentation. The
reason is simple: text-only browsers. People who, for whatever
reason (choice or necessity), use lynx, or links or w3m to read
the documentation must be able to make sense of it. All of it.
Graphical examples of <strong>mom</strong> in action might have made
some parts of the documentation easier to write, but would have
excluded text-only browser users. And it goes without saying that
the documentation looks fine if you're reading it in a graphical
browser.
<br>
<hr>
<!=====================================================================>
<a name="FONTS">
<h2><u>Adding PostScript fonts to groff</u></h2>
</a>
<a name="SMALL_NOTE"></a>
<em><strong>Small note:</strong> the term &lt;prefix&gt; in this
section refers to the directory in which groff is installed,
typically something like /usr/share/groff/&lt;version#&gt;
(for distro-specific, pre-compiled groff packages) or
/usr/local/share/groff/&lt;version#&gt; (if you've built groff
from source).</em>
<p>
Groff comes with a small library of PostScript
<a href="definitions.html#TERMS_FAMILY">families</a>
(see the
<a href="typesetting.html#FAMILY">FAMILY</a>
macro for a list). The families have four
<a href="definitions.html#TERMS_FONT">fonts</a>
associated with them. These fonts are a combination of
<a href="definitions.html#TERMS_WEIGHT">weight</a>
and
<a href="definitions.html#TERMS_SHAPE">shape</a>:
<br>
<ul>
<li><strong>R</strong> (Roman, usually Medium weight),
<li><strong>I</strong> (Italic, usually Medium weight),
<li><strong>B</strong> (Bold, usually Roman shape) and
<li><strong>BI</strong> (Bold Italic).
</ul>
<p>
If you do a lot of document processing or typesetting with
<strong>mom</strong>, you'll find, sooner or later, that these
families and their associated fonts aren't sufficient. You'll want
to supplement them, either with more fonts for the families already
provided--"Damn! I need Helvetica Bold Condensed Italic!"--or with
entire new families.
<p>
Without going into the gory details (yet), while it's true that
adding fonts to groff is a relatively straightforward
process, extending existing families or adding new ones requires
some planning.
<p>
The traditional approach to extending groff families has been
to create new families for non-default weights and
shapes (e.g. Light, which is a weight; Condensed, which is a
shape), then to associate them with groff's predefined <strong>R,
I, B</strong> and <strong>BI</strong> font styles. An example
of this can be seen in the groff PostScript font library itself
(&lt;prefix&gt;/font/devps/): there's one &quot;family&quot; for
Helvetica (HR, HI, HB, HBI) and another for Helvetica Narrow (HNR,
HNI, HNB, HNBI).
<p>
The difficulty with this approach is that typographers
tend to think of &quot;families&quot; as referring to the
entire set of font weights and shapes associated with a
particular family name. For example, when a typesetter says
&quot;the Helvetica family&quot;, s/he is including the <a
href="definitions.html#TERMS_WEIGHT">weights</a> Helvetica Thin,
Helvetic Light, Helvetica Regular, Helvetica Bold, Helvetica Heavy,
etc, and all their associated
<a href="definitions.html#TERMS_SHAPE">shapes</a>
(Roman,
Italic, Condensed, Narrow, Extended, Outline, etc).
<p>
Thus, intuitively, when a typesetter gives <strong>mom</strong> a
<kbd>.FAM(ILY)</kbd> directive, s/he reasonably expects that any
subsequent <kbd>.FT</kbd> directive will access the desired font
from the Helvetica family--without the need to state explicitly both
family and font to <kbd>.FT</kbd>, as it is explained one can do in
the
<a href="typesetting.html#FAMILY">FAMILY</a>
and
<a href="typesetting.html#FONT">FT</a>
sections of these documents.
<p>
If one had, say, the fonts, Helvetica Light Roman
and Helvetica Light Italic as well as Helvetica Light Condensed
Roman and Helvetica Light Condensed Italic, the traditional
approach would require two &quot;partial&quot; families: HLR/HLI and
HLCDR/HLCDI. Accessing these family/font combos
routinely throughout a document would then require
changing family (with <kbd>.FAM(ILY)</kbd>) and selecting the
desired font (with <kbd>.FT R</kbd> or <kbd>.FT I</kbd>), or
passing <kbd>.FT</kbd> the lengthy family+fontname (.e.g. <kbd>.FT
HLCDI</kbd>).
<p>
Fortunately, groff provides a mechanism whereby it's possible to
extend the basic <strong>R, I, B</strong> and <strong>BI</strong>
fonts (&quot;styles&quot; in groff-speak) so that one can, in
fact, create extensive type families, and access all the fonts
in them with <kbd>.ft</kbd> (groff) or <kbd>.FT</kbd> (mom).
<p>
<strong>mom</strong> uses this mechanism to offer, in addition to
groff's default PostScript font styles, the following:
<p>
<a name="STYLE_EXTENSIONS"></a>
<pre>
Mom's extensions to groff's basic font styles
=============================================
L = Light Roman
LI = Light Italic
LCD = Light Condensed Roman
LCDI = Light Condensed Italic
LEX = Light Extended Roman
LEXI = Light Extended Italic
CD = Medium/Book Condensed Roman
CDI = Medium/Book Condensed Italic
EX = Medium/Book Extended Roman
EXI = Medium/Book Extended Italic
DB = DemiBold Roman
DBI = DemiBold Italic
BCD = Bold Condensed Roman
BCDI = Bold Condensed Italic
BEX = Bold Extended Roman
BEXI = Bold Extended Italic
HV = Heavy Roman
HVI = Heavy Italic
HVCD = Heavy Condensed Roman
HVCDI = Heavy Condensed Italic
HVEX = Heavy Extended Roman
HVEXI = Heavy Extended Italic
BL = Black Roman
BLI = Black Italic
BLCD = Black Condensed Roman
BLCDI = Black Condensed Italic
BLEX = Black Extended Roman
BLEXI = Black Extended Italic
UBL = Ultra-Black Roman
UBLI = Ultra-Black Italic
</pre>
Thus, with <strong>mom</strong>, if you've installed, say, some
extra Helvetica fonts and named them according to the convention FS
(where &quot;F&quot; means family and &quot;S&quot; means font
style), once having entered
<p>
<pre>
.FAMILY H
or
.FAM H
</pre>
you can access any of those Helvetica fonts simply by
passing the correct argument from the list above to
<a href="typesetting.html#FONT">FT</a>.
<p>
For example, if you were working in Medium Roman (<kbd>.FT R</kbd>)
and you needed Medium Condensed Italic for a while (assuming it's
installed), you'd just type
<p>
<pre>
.FT CDI
</pre>
to access the Medium Condensed Italic font from the Helvetica
family.
<p>
<strong>Mom</strong>'s list of font styles doesn't pretend to
be exhaustive, but rather tries to cover the basic weight/shape
combinations likely to be found in any reasonably complete type
family.
<p>
The actual extension names are arbitrary and can be used in a
flexible manner. For example, if you create a family that has a
DemiBold font (DB) but no Bold font (B), you might find it more
convenient to give the DemiBold font the extension &quot;B&quot;.
Equally, if the family has an ExtraBold font, you might find it more
convenient to use the extension &quot;HV&quot; (Heavy).
<a name="REGISTER_STYLE"></a>
<p>
However, you may, at needs, want to add to <strong>mom</strong>'s
list of font styles. You can do this by editing the file, om.tmac.
Near the top, you'll see lines of the form
<p>
<pre>
.sty \n[.fp] L \" Light Roman
.sty \n[.fp] LI \" Light Italic
.sty \n[.fp] LCD \" Light Condensed Roman
</pre>
Simply add your new font style by imitating what you see and
plugging in your new font style (having, of course, first created the
font, correctly named, in groff's PostScript font directory; see
<a href="#HOWTO">How to create a PostScript font for use with groff</a>).
<p>
For example, if you already have some fonts from the Univers
family installed and have called the family UN, you might decide at
some point to add the Bold Outline font (UNBO). In which case,
you'd add
<p>
<pre>
.sty \n[.fp] BO \" Bold Outline
</pre>
to the <kbd>.sty \n[.fp] &lt;font style&gt;</kbd> list in om.tmac.
<p>
Be careful, though, that any styles you add do not conflict
with <strong><u>family</u></strong> names that already exist.
&quot;C&quot;, for example, conflicts with the Courier family
(CR, CI, CB, CI). Were you to create a font style &quot;C&quot;,
thinking that <kbd>.FT C</kbd> would give you access to font style
once you'd given a <kbd>.FAM(ILY)</kbd> directive, you'd get a nasty
surprise: your type would come out in Courier Roman!
<p>
<strong>VERY IMPORTANT NOTE: mom</strong>'s font extensions are
not &quot;user-space&quot; controllable via a macro. If you've
been using groff for a long time, and have already rolled your own
solution to adding PostScript families, fonts, weights, shapes, etc. to
groff, you may find that <strong>mom</strong>'s font extensions
conflict with your own scheme. Should that be the case, comment out
the <kbd>.sty \n[.fp] &lt;font style&gt;</kbd> lines found near the
top of the om.tmac file.
<a name="HOWTO"><h3><u>How to create a PostScript font for use with groff</u></h3></a>
These instructions aren't meant to cover all possibilities, merely
to present one way of making PostScript families/fonts available to
groff and <strong>mom</strong>.
<p>
GNU/Linux distributions being what they are, directory locations may
differ and the presence of some executables can't be guaranteed.
I run a Debian system. The instructions reflect that. Users of
other distros will have to interpret them according to the way their
distro operates.
<p>
What you need before you start:
<br>
<ul>
<li>groff, version 1.18 or higher
<br>
(Debian package: groff)
<li>a full installation of gs and associated tools
<br>
(Debian package: gs or gs-gpl)
<li>a library of gs fonts
<br>
(Debian package: gsfonts)
<li>a utility for converting TrueType fonts to Type1 fonts
<br>
(Debian package: ttf2pt1)
<li>a font manager
<br>
(Debian packages: defoma, psfontmgr, dfontmgr)
<li>perl
<br>
(Debian package: perl)
</ul>
<br>
A reasonably complete installation of any major GNU/Linux distro
should already have these on your system, except perhaps for the
utility to convert TrueType fonts to Type1 fonts.
<p>
Initial preparation (you only have to do this once):
<br>
<ol>
<li>If you don't already have one, create a directory in your
home directory to hold new fonts. Any directory name will do.
I use ~/Fonts, with subdirectories for Type1, TrueType and Groff
fonts.
<a name="SITE-FONT"></a>
<li>Locate the groff directory, site-font. The exact location is
difficult to predict, owing to differences between distros
and whether you're using a pre-packaged groff or have built
it from source. Some typical locations are
<br>
<ul>
<li>/usr/share/groff,
<li>/usr/local/share/groff
<li>/etc/groff
</ul>
<p>
If you can't find the site-font directory, locate
groff's site-tmac directory, and, as root, create site-font
in the same directory as the one that holds site-tmac.
E.g., if you find site-tmac in /usr/share/groff, create
site-font in /usr/share/groff.
<li>Locate the file <kbd>&lt;prefix&gt;/font/devps/generate/textmap</kbd>
and symlink it to <kbd>textmap</kbd> in the directory that
contains your personal collection of PostScript fonts. (See the
<a href="#SMALL_NOTE">Small Note</a>,
above, for the meaning of &lt;prefix&gt;). On my system,
at the time of writing, &lt;prefix&gt; is
/usr/local/share/groff/1.19.2/, therefore, I symlink it in
~/Fonts/Type1 with
<br>
<pre>
ln -s /usr/local/share/groff/1.19.2/font/devps/generate/textmap textmap
</pre>
<li>Locate the file &lt;prefix&gt;/font/devps/text.enc and
symlink it to <kbd>text.enc</kbd> in your personal font
directory. On my system, in ~/Fonts/Type1
<pre>
ln -s /usr/local/share/groff/1.19.2/font/devps/text.enc text.enc
</pre>
<li>Make sure you know which directory/ies holds your gs fonts.
You'll need the information later. On a Debian box, some
typical locations are
<br>
<ul>
<li>/usr/lib/ghostscript/fonts
<li>/usr/share/ghostscript/fonts
<li>/usr/share/fonts/type1/gsfonts
</ul>
</ol>
<br>
Font creation/installation:
<br>
<ol>
<li>Acquire the font in either Type1 (.pfb) or TrueType
(.ttf) format.
<li>Place the font in your personal font directory; for me,
that's ~/Fonts/Type1 or ~/Fonts/TrueType.
<li>In your personal font directory, run one of the following:
<br>
<ul>
<li>For Type1 fonts
<br>
<ul>
<li><kbd>getafm fontfilename.pfb | gsnd - > fontfilename.afm</kbd>
<br>
For Type1 fonts, this will generate something called
an .afm (Adobe Font Metrics) file, which is
required to create PostScript fonts for groff.
</ul>
<li>For TrueType fonts
<br>
<ul>
<li><kbd>ttf2pt1 \-b fontfilename.ttf</kbd>
<br>
For TrueType fonts, this will generate a PostScript
.pfb file as well as an .afm file.
</ul>
</ul>
<li>Still in your personal font directory, run
<br>
<ul>
<li><kbd>afmtodit -e text.enc fontfilename.afm textmap GROFF_FONTNAME</kbd>
</ul>
<p>
Q: <em>How do I choose a GROFF_FONTNAME?</em>
<p>
A: Start by considering the
<a href="definitions.html#TERMS_FAMILY">family</a>
to which the font belongs. If you're adding to a family that
already exists in groff's &lt;prefix&gt;/font/devps
directory, that will be the first part of the font name.
(See
<a href="typesetting.html#FAMILY">here</a>
for a list of families already installed, along with their groff
names.) Add to that name the appropriate weight/style extension,
listed
<a href="#STYLE_EXTENSIONS">here</a>.
<p>
For example, if you're adding Helvetica Light Roman, your
GROFF_FONTNAME would be <strong>HL</strong>. If you're
adding Helvetica Light Italic, your GROFF_FONTNAME would be
<strong>HLI</strong>.
<p>
If you're adding a font not already in groff's PostScript
families, first choose a meaningful name for the
<a name="definitions.html#TERMS_FAMILY">family</a>
to which the font belongs. The name can be anything you like. If,
for example, the family is Garamond, you could choose GARAMOND,
GARA, GD, or even just plain G as the family name. Then tack on the
appropriate style/weight extension. Thus, if you were installing
Garamond Bold Condensed Italic and had chosen <strong>GD</strong>
as the family name for Garamond, your GROFF_FONTNAME would be
<strong>GDBCDI</strong>.
<p>
In <strong>mom</strong>, you can then access the Garamond
family with <kbd>.FAM GD</kbd>, and the Bold Condensed
Italic font wth <kbd>.FT BCDI</kbd>.
<p>
<strong>Note:</strong> The family name need not be in upper
case, and there's no limit to the length of the name.
&quot;Garamond&quot;, for example, could be the name you
give the Garamond family. In fact, you might find it
preferable, since a) you wouldn't have to remember how
you'd named the family, and b) should you be scanning
your
<a href="#SITE-FONT">site-font directory</a>,
something like GaramondBCDI will be more meaningful than,
say, GDBCDI.
<li>Copy or move GROFF_FONTNAME to your
<a href="#SITE-FONT">site-font directory</a>,
or change to the site-font directory and make a symlink to
GROFF_FONTNAME in your personal directory.
<li>Copy or move the .pfb file to the directory that
holds your gs fonts, or change to that directory and make a
symlink to the .pfb file in your personal directory.
<li>Do whatever your system or distro requires in order to
register the new PostScript font (the .pfb file). On a
Debian system, as root, you can run dfontmgr for a
graphical interface that will take care of registering the
font.
</ol>
<p>
Written out in full, adding fonts looks like a lot of work. It
isn't. Basically, it's just:
<br>
<ul>
<li>acquire the font
<li>generate an .afm file for the font
<li>create the groff font
<li>put the groff font in &lt;prefix&gt;/font/devps
<li>make sure gs knows about the font
</ul>
<br>
After you've done it a couple of times, it all makes sense, and is
really quite easy. Not to mention that once you understand the
process, you can write a bash script to automate the process.
Here's an example, which you can adapt to your own needs. The
script requires an argument (the .pfb filename), then prompts for
the GROFF_FONTNAME.
<p>
<pre>
#! /bin/bash
# A script for installing Type1 fonts.
#
# Builds .afm files from .pfb files, generates a groff font from the
# .afm file, makes a symlink in /usr/lib/ghostscript/font/ to the
# .pfb file, and a symlink in site-font to the groff font
# .pfb filename, stripped of .pfb extension
FONT=`basename $1 .pfb`
# Directory holding my personal collection of type1 fonts
FONTDIR="$HOME/Fonts/Type1"
# Directory holding system ghostscript fonts
GS_FONTDIR="/usr/lib/ghostscript/fonts"
# Location of site-font/devps
GROFF_SITE_FONTDIR="/usr/local/share/groff/site-font/devps"
# Personal groff fonts directory
GROFF_FONTS="$HOME/Fonts/Groff"
# Symlinks to textmap and text.enc
TEXTMAP="$FONTDIR/textmap"
TEXTENC="$FONTDIR/text.enc"
if [ ! `pwd` = "$FONTDIR" ] ; then
echo "Changing into $FONTDIR directory.."
cd $FONTDIR
sleep 1
else
sleep 1
fi
echo -n "Groff name for this font: "
read FONTNAME
sleep 1
echo "Getting .afm.."
getafm $FONT.pfb | gsnd - > $FONT.afm
sleep 1
echo "Creating $FONTNAME.."
afmtodit -e $TEXTENC $FONTDIR/$FONT.afm $TEXTMAP $FONTNAME
mv -i $FONTNAME $GROFF_FONTS
sudo ln -s $GROFF_FONTS/$FONTNAME $GROFF_SITE_FONTDIR/$FONTNAME
sleep 1
echo "Linking $FONT in $GS_FONTDIR.."
cd $GS_FONTDIR
sudo ln -s $FONTDIR/$FONT.afm $FONT.afm
sudo ln -s $FONTDIR/$FONT.pfb $FONT.pfb
sleep 1
# This next bit is Debian specific. If you're not running a
# Debian system, replace it with whatever your distro requires
# in order to register Type1 fonts.
if [ !`pidof -x /usr/bin/dfontmgr` ] ; then
echo "I will now run dfontmgr so you can register the font."
exec sudo dfontmgr &
else
echo "You may now register the font with dfontmgr."
fi
</pre>
<hr>
<!=====================================================================>
<a name="CODENOTES">
<h2><u>Some reflections on mom</u></h2>
</a>
@ -99,12 +593,14 @@ scratching a personal itch, then <strong>mom</strong> can truly be
called open source, even if, a mere humble set of macros standing on
the shoulders of a giant named troff, she isn't programming at all.
<p>
As a writer living in a perpeptual state of penury, all the computers
As a writer living in a perpetual state of penury, all the computers
I've ever owned have been hand-me-downs -- several generations
out-of-date and &quot;resource challenged&quot;. Disk space has
always been an issue, as has processor speed and available RAM.
One of the reasons I run Linux is that it has helped enormously to
get the most out of my poor little boxes.
One of the reasons I run GNU/Linux is that it has helped enormously
to get the most out of my poor little boxes. (It has been pointed
out to me that NetBSD might be an even better choice of operating
systems for computers with limited resources.)
<p>
In Linux-land, the choice of typesetting systems basically comes down
to groff or TeX. Both are wonderful -- monumental achievements if you
@ -122,7 +618,7 @@ However, groff has always had a liability: it's incredibly geeky.
Owing to its very long history, it -- and its &quot;power users&quot;
-- have remained stuck in a time warp. Most common macro packages
still look as they did in those decades when memory was exorbitantly
expensive, and every byte mattered. Documentation -- not always
expensive and every byte mattered. Documentation -- not always
easy to find -- is written as if all readers are computer whizzes,
or at least have a university degree in one of the higher sciences.
<p>
@ -132,6 +628,13 @@ ambiguity of groff's documentation. Making sense of certain primitives
has often involved days of testing, interpreting the documentation
instead of just using the primitive.
<p>
(ADDENDUM to the previous two paragraphs: A tremendous amount of
effort has gone into creating a groff manual that can be read with
"info," as well as creating truly useful man pages. The info
manual is clear and well-written, so my comments are actually out
of date. I leave them in for the benefit of groff newbies, who may
still find the documents a bit intimidating.)
<p>
For some time now, groff users and macro writers have had the
option to use &quot;long&quot; names, yet have mostly chosen not to.
With long names, it's possible to create macro sets that are humanly
@ -145,15 +648,11 @@ newbies and old hands alike.
and a host of other groff goodies that have become part of the
whole groff picture under the unflagging guidance of groff's current
maintainer, Werner Lemberg. Nearly every macro, number register and
string is &quot;recognisable&quot; simply by its name. The file is
string is &quot;recognizable&quot; simply by its name. The file is
heavily commented. A consistent, if idiosyncratic, indenting style
is used as well, significantly improving readability. Anyone
wanting to futz around with <strong>mom</strong>'s macros should be
able to do so with a minimum of head scratching.
<p>
To all you groff-jocks out there who love the aracana of
groff-as-it-used-to-be, I apologise. To everyone else, I simply say:
Welcome, and enjoy.
<br>
<hr>
@ -171,14 +670,22 @@ groff mailing list at
(subscription information available
<a href="http://ffii.org/mailman/listinfo/groff/">here</a>)
or contact me, Peter Schaffter, directly at
<p>
<address align="center">
<a href="mailto:df191@ncf.ca">df191@ncf.ca</a>
</address>
<i>&#112;&#101;&#116;&#101;&#114;&#64;&#102;&#97;&#117;&#115;&#116;&#117;&#115;&#46;&#100;&#121;&#110;&#46;&#99;&#97;</i>
or
<i>&#112;&#116;&#112;&#105;&#64;&#103;&#111;&#108;&#100;&#101;&#110;&#46;&#110;&#101;&#116;</i>.
<p>
Please include the word &quot;mom&quot; or &quot;groff&quot; in the
Subject: line of any message sent to my personal address, or you
risk the wrath of my implacable spam filters. :)
<p>
If you want to visit <strong>mom</strong>'s homepage, you'll find
it
<a href="http://faustus.dyn.ca/mom/mom.html">here</a>.
<p>
<hr>
<a href="typemacdoc.html#TOP">Prev</a>&nbsp;&nbsp;
<a href="reserved.html#TOP">Next</a>&nbsp;&nbsp;
<a href="macrolist.html#TOP">Prev</a>&nbsp;&nbsp;
<a href="#TOP">Top</a>&nbsp;&nbsp;
<a href="toc.html">Back to Table of Contents</a>
</body>

338
contrib/groff/contrib/mom/momdoc/color.html Normal file
View File

@ -0,0 +1,338 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html>
<head>
<meta http-equiv="content-type" content="text/html;charset=iso-8859-1">
<title>Mom -- Colour</title>
</head>
<body bgcolor="#dfdfdf">
<!====================================================================>
<a href="docprocessing.html#TOP">Next</a>&nbsp;&nbsp;
<a href="inlines.html#TOP">Prev</a>&nbsp;&nbsp;
<a href="toc.html">Back to Table of Contents</a>
<a name="TOP"></a>
<h1 align="center">
<a name="COLOR_INTRO"><u>Coloured text</u></a>
</h1>
<p>
<a href="#INTRO_COLOR">Introduction to coloured text</a>
<br>
<a href="#MACROS_COLOR">Index of colour macros</a>
<p>
<a name="INTRO_COLOR">
<h2><u>Introduction to coloured text</u></h2>
</a>
<strong>Mom</strong>'s support for coloured text is straightforward.
You begin by telling <strong>mom</strong> about the colours you want
with
<a href="#NEWCOLOR">NEWCOLOR</a>
or
<a href="#XCOLOR">XCOLOR</a>.
Afterward, any time you want text to be coloured, you either colour
it with an
<a href="definitions.html#TERMS_INLINES">inline escape</a>
that contains the colour name (e.g. <kbd>\*[red]</kbd> or
<kbd>\*[blue]</kbd>) or invoke the macro,
<a href="#COLOR">COLOR</a>,
with the name of the colour you want.
<a name="COLOR_EXAMPLE"></a>
<p>
For example, say you want to have the name &quot;Jack&quot; in the
sentence &quot;All work and no play makes Jack a dull boy&quot;
appear in yellow. You'd begin by telling <strong>mom</strong> about
the colour, yellow. There are two ways of doing this; see
<a href="#NEWCOLOR">NEWCOLOR</a>
and
<a href="#XCOLOR">XCOLOR</a>
for a full explanation of the difference between the two. If you
use <strong>XCOLOR</strong>, you'd enter this:
<p>
<pre>
.XCOLOR yellow
</pre>
If you use <strong>NEWCOLOR</strong>, you might enter
<p>
<pre>
.NEWCOLOR yellow RGB #FFFF00
</pre>
<a name="COLOR_EXAMPLE2"></a>
After &quot;defining&quot; (or &quot;initializing&quot;) the colour
&quot;yellow&quot;, you'd colourize the name, Jack, either with an
inline escape
<p>
<pre>
All work and no play makes \*[yellow]Jack\*[black] a dull boy.
</pre>
or with the <strong>COLOR</strong> macro
<p>
<pre>
All work and no play makes
.COLOR yellow
Jack
.COLOR black
a dull boy.
</pre>
Notice, in both examples, that a) you have to set the colour back to
black after &quot;Jack&quot;, and b) you don't have to define or
intialize the colour, black. <strong>Mom</strong> predefines
&quot;black&quot;, &quot;BLACK&quot;, &quot;white&quot; and
&quot;WHITE&quot; for you.
<p>
For information on using colour during
<a href="docprocessing.html#INTRO_MACROS_DOCPROCESSING">document processing</a>,
see
<a href="docprocessing.html#COLOR">Colour support in document processing</a>.
<p>
<strong>Please note: Mom</strong>'s colour support is for text only.
She doesn't support &quot;fill&quot; (or &quot;background&quot;)
colour for drawn objects. Please also note that if you're
accustomed to using groff's <kbd>.defcolor</kbd> to define colours,
and groff's inline <kbd>\m[&lt;colorname&gt;]</kbd> to call them, you may
continue to do so without confusing <strong>mom</strong>.
<p>
<a name="MACROS_COLOR"><h3><u>Index of colour macros</u></h3></a>
<ul>
<li><a href="#NEWCOLOR">NEWCOLOR</a>
<li><a href="#XCOLOR">XCOLOR</a>
<li><a href="#COLOR">COLOR</a>
<li><a href="#COLOR_INLINE">\*[&lt;colorname&gt;]</a> inline escape
</ul>
<p>
<!---NEWCOLOR--->
<hr width="66%" align="left">
<a name="NEWCOLOR"><h3><u>Creating (initializing) a colour with NEWCOLOR</u></h3></a>
<br>
<nobr>Macro: <strong>NEWCOLOR</strong> &lt;colour name&gt; [&lt;colour scheme&gt;] &lt;colour components&gt;</nobr>
<p>
<strong>NEWCOLOR</strong> lets you create a colour, rather like an
artist mixing paint on a palette. The colour isn't used
immediately; <strong>NEWCOLOR</strong> merely tells
<strong>mom</strong> how to mix the colour when you need it. If
you haven't invoked <strong>NEWCOLOR</strong> (or
<a href="#XCOLOR">XCOLOR</a>),
<strong>mom</strong> doesn't have a clue what you mean when you
reference a colour (with
<a href="#COLOR">COLOR</a>
or
<a href="#COLOR_INLINE">\*[&lt;color name&gt;]</a>).
<p>
The first argument to <strong>NEWCOLOR</strong> is a name for your
colour. It can be anything you like--provided it's just one word
long--and can be caps, lower case, or any combination of the two.
<p>
The second argument, which is entirely optional, is the &quot;colour
scheme&quot; you want <strong>mom</strong> to use when mixing the
colour. Valid arguments are <strong>RGB</strong> (3 components,
red green blue), <strong>CYM</strong> (3 components cyan yellow
magenta), <strong>CMYK</strong> (4 components cyan magenta yellow
black) or <strong>GRAY</strong> (1 component). If you omit the
second argument, <strong>mom</strong> assumes you want RGB.
<p>
The final argument is the components of your colour. This can be
hexadecimal string starting with a pound sign (#) (for colour values
in the 0-255 range) or two pound signs (##) (for colour values
in the 0-65535 range), or it can be a series of decimal digits,
separated by spaces, one digit per component, with the argument
enclosed in double quotes. (If this is all gibberish to you, see
<a href="#COLOR_TIP">Tips for newbies</a>.)
<p>
Thus, to tell <strong>mom</strong> about a colour named
&quot;YELLOW&quot;, you could enter one of the following:
<p>
<pre>
.NEWCOLOR YELLOW #FFFF00 \"or ##FFFFFFFF0000 or "1 1 0"
.NEWCOLOR YELLOW RGB #FFFF00 \"or ##FFFFFFFF0000 or "1 1 0"
.NEWCOLOR YELLOW CYM #00FF00 \"or ##0000FFFF0000 or "0 1 0"
.NEWCOLOR YELLOW CYMK #00FF0000 \"or ##0000FFFF00000000 or "1 1 0"
</pre>
After you've told <strong>mom</strong> about a colour, you can then get
her to set text in that colour either with the inline escape
<a href="#COLOR_INLINE">\*[&lt;colorname&gt;]</a>
or the macro
<a href="#COLOR">COLOR</a>.
(See the
<a href="#COLOR_EXAMPLE">example</a>,
above.)
<br>
<h3><u>Tips for newbies</u></h3>
Colour manipulation can be tremendously confusing if you don't have
a background in graphic arts or computing. My advice, if color
intimidates you, is to stick to using <strong>mom</strong>'s
default RGB colour scheme, and to fire up a color chooser that
gives you the RGB values you want for the colour you select. Plug
those values into the components argument to
<strong>NEWCOLOR</strong>, and you'll get the colour you want.
Both the KDE and gnome desktops have colour selectors that provide
you with the shorter RGB hexadecimal string. If you're not running
KDE or gnome, the X utility, xcolorsel, provides you with a similar
functionality, although it only provides RGB values for 256
pre-defined colours. If you use xcolorsel, be sure to click the
button &quot;Display format&quot; and select &quot;8 bit truncated
rgb&quot;.
<p>
Alternatively, you can use <strong>mom</strong>'s simpler
<a href="#XCOLOR">XCOLOR</a>
macro to initialize one of the 256 pre-defined X colours by
supplying the name of the color as an argument.
<br>
<!---XCOLOR--->
<hr width="33%" align="left">
<a name="XCOLOR"><h3><u>Initializing a colour with XCOLOR</u></h3>
<br>
<nobr>Macro: <strong>XCOLOR</strong> &lt;X color name&gt; [&lt;alias&gt;]</nobr>
<br>
<em>*&lt;X color name&gt; must be all one word, all lower case.
<br>
(See
<a href="#XCOLOR_NAMES">Finding X color names</a>
for how to get a list of valid colour names.)
</em>
<p>
<strong>XCOLOR</strong> is similar to <strong>NEWCOLOR</strong> in
that it tells <strong>mom</strong> to initialize a colour, but it's
easier to use. All you have to do is pass it, as an argument, the
legal name of one of the 256 pre-defined X colours. The name must
be all one word, and, breaking with <strong>mom</strong> policy, it
must be entered in lower case.
<p>
For example, if you want to intialize the X colour, coral, all you
have to do is enter
<br>
<pre>
.XCOLOR coral
</pre>
Afterwards
<p>
<pre>
.COLOR coral
</pre>
will colourize subsequent text coral until you instruct
<strong>mom</strong> to return to black, or some other pre-defined
initialized colour. (The
<a href="definitions.html#TERMS_INLINES">inline escape</a>
<kbd>\*[coral]</kbd> will equally colourize text coral after you've
initialized the colour with <strong>XCOLOR</strong>.)
<p>
The downside of <strong>XCOLOR</strong> is that you can't create
custom colours. This restriction, however, is mitigated by the
fact that for many users, 256 colours is more than enough to play
around with.
<p>
While some X colours have fanciful names (peachpuff, papayawhip,
thistle, snow), many are self-explanatory and self-descriptive in
ordinary colour terms. &quot;blue&quot; is pure (rgb) blue,
&quot;green&quot; is pure (rgb) green, and so on. Furthermore, for
many X colors, there exist four variants, each representing
increasingly darker shades of the same colour. For example,
&quot;blue&quot; (and &quot;blue1&quot;) are the brightest forms of
(rgb) blue; &quot;blue2&quot;, &quot;blue3&quot; and &quot;blue4&quot;
are increasingly darker shades of the same blue. For that reason,
you may find <strong>XCOLOR</strong> is a better choice than
<strong>NEWCOLOR</strong> when it comes to initializing common
colors.
<p>
The whimsical nature of X colour names sometimes makes for names
that are long to type in, e.g. &quot;mediumspringgreen&quot;.
The optional second argument to <strong>XCOLOR</strong> allows you
to come up with more convenient name by which to reference the
colour. For example, you could enter
<p>
<pre>
.XCOLOR mediumspringgreen mygreen
or
.XCOLOR mediumspringgreen MYGREEN
</pre>
so that whenever you want text mediumspringgreen-ed, you can use
either <kbd>.COLOR mygreen</kbd> (or <kbd>.COLOR MYGREEN</kbd>) or
the inline escape <kbd>\*[mygreen]</kbd> (or
<kbd>\*[MYGREEN]</kbd>.)
<p>
<a name="XCOLOR_NAMES"><h3><u>Finding X color names</u></h3></a>
<br>
There are two ways of finding the names of the pre-defined X
colours. One is to consult the file, rgb.txt, included with
all X11 installations. The location of the file on a Debian
GNU/Linux distribution is typically /etc/X11/rgb.txt. Other
distributions and other X installations may have the file in
another location. The file lists the colour names, but doesn't
show you what the colours actually look like.
<p>
A better way to get the colour names, as well as to see what the
colours look like, is to fire up a colour chooser (like xcolorsel)
that both lists the colour names and shows a swatch of the colour
as well.
<p>
Whichever method you use to find X color names, remember that the
names, passed as arguments to <strong>XCOLOR</strong>, <em>must</em>
be all one word, all in lower case.
<br>
<!---COLOR--->
<hr width="33%" align="left">
<a name="COLOR"><h3><u>Invoking a color</u></h3>
<br>
<nobr>Macro: <strong>COLOR</strong> &lt;colorname&gt;</nobr>
<br>
<a name="COLOR_INLINE">Inline: <strong>\*[&lt;colorname&gt;]</strong></a>
<p>
<a name="COLOR_INLINE"></a>
Once you've told <strong>mom</strong> about a colour (via
<strong>NEWCOLOR</strong> or <strong>XCOLOR</strong>), you use either
the macro, <strong>COLOR</strong>, or the
<a href="definitions.html#TERMS_INLINES">inline escape</a>,
<kbd>\*[&lt;colorname&gt;]</kbd>, to cause <strong>mom</strong> to
set subsequent text in that colour. See the
<a href="#COLOR_EXAMPLE2">example</a>,
above, which shows both in action.
<p>
<strong>NOTE:</strong> You can use the
<kbd>\*[&lt;colorname&gt;]</kbd> inline escape in any
<a href="docprocessing.html#TOP">document processing</a>
macro that takes a
<a href="definitions.html#TERMS_STRINGARGUMENT">string argument</a>.
However, you must remember to reset the colour at the end of the
argument (typically with <kbd>\*[black]</kbd>) unless you want all
subsequent invocations of that particular macro to be colourized.
<p>
Furthermore, if you use <kbd>\*[&lt;colorname&gt;]</kbd> in the
string argument passed to
<a href="docelement.html#HEAD">.HEAD</a>,
<a href="docelement.html#SUBHEAD">.SUBHEAD</a>
or
<a href="docelement.html#PARAHEAD">.PARAHEAD</a>,
and you've requested that any of these types of heads be numbered,
the numbers themselves will not be coloured, only the text you
passed the macro. If you wish the numbers to be colourized as
well, you must explicitly tell <strong>mom</strong> that you wish
all of the head(s), subhead(s) or parahead(s), including the
numbers, colourized by invoking the appropriate
<a href="docelement.html#DOCELEMENT_CONTROL">control macro</a>.
<br>
<hr>
<a href="docprocessing.html#TOP">Next</a>&nbsp;&nbsp;
<a href="inlines.html#TOP">Prev</a>&nbsp;&nbsp;
<a href="#TOP">Top</a>&nbsp;&nbsp;
<a href="toc.html">Back to Table of Contents</a>
</body>
</html>

509
contrib/groff/contrib/mom/momdoc/cover.html
View File

@ -1,3 +1,4 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html>
<head>
<meta http-equiv="content-type" content="text/html;charset=iso-8859-1">
@ -7,41 +8,503 @@
<!====================================================================>
<a href="letters.html#TOP">Next</a>&nbsp;&nbsp;
<a href="refer.html#TOP">Next</a>&nbsp;&nbsp;
<a href="rectoverso.html#TOP">Prev</a>&nbsp;&nbsp;
<a href="toc.html">Back to Table of Contents</a>
<p>
<a name="TOP"></a>
<a name="COVER">
<h2 align="center"><u>CREATING A COVER PAGE</u></h2>
<a name="TOP">
<h1 align="center"><u>CREATING A COVER PAGE</u></h1>
</a>
<ul>
<li><a href="#COVER_INTRO">Introduction to cover pages</a>
<ul>
<li><a href="#PLEASE">Important note -- please read</a>
<li><a href="#DESC">Description of what mom does on cover pages</a>
<li><a href="#PAGINATION">A note on headers/footers and pagination</a>
<li><a href="#DESIGN">What to do if you want to design your
own cover pages</a>
</ul>
<li><a href="#COVER">The cover and document cover macros</a>
<ul>
<li><a href="#COVER">COVER/DOC_COVER</a>
<ul>
<li><a href="#REQUIRED">The required argument</a>
<li><a href="#CHAPTER">How the CHAPTER argument and friends work</a>
<li><a href="#OPTIONAL">The optional arguments</a>
<li><a href="#DOCTYPE">What the DOCTYPE argument means</a>
</ul>
</ul>
<li><a href="#ON_OFF">Enabling/disabling automatic generation of cover pages</a>
<li><a href="#COVER_CONTROL">Control macros--changing the
defaults for covers and document covers</a>
</ul>
<a name="COVER_INTRO"><h2><u>Introduction to cover pages</u></h2></a>
<p>
At present, <strong>mom</strong> provides no mechanism for
automatically generating cover pages. It's a situation not likely
to change, given that what's needed on document covers changes from
document to document, both in terms of style and content. And,
more often than not, what goes on covers is matter of personal taste.
As of version 1.19 of <strong>mom</strong>, you can now have cover
pages generated automatically.
<p>
If you want a document to begin with a cover page, typeset the cover
(using the
<a href="typesetting.html#MACROS_TYPESETTING">typesetting macros</a>).
At the end, invoke
<a href="typesetting.html#NEWPAGE">NEWPAGE</a>,
then set up your document <em>in full</em> (see
<a href="docprocessing.html#DOCPROCESSING_TUT">Tutorial -- Setting up a mom document</a>),
invoking
<a href="docprocessing.html#START">START</a>
as usual once you're done. The cover page (and any typesetting
commands on it) will have no effect on <strong>mom</strong>'s
processing of the document itself, the first page of which, moreover,
will be numbered &quot;1&quot; unless you instruct her otherwise
Though identical in treatment, <strong>mom</strong> provides two
kinds of cover pages: section cover pages (which I shall refer to
simply as &quot;cover pages&quot;) and document cover pages
(&quot;doc covers&quot;).
<p>
A document cover page
(<a href="#DOC_COVER">doc cover</a>)
is what you'd most likely use at the start of a <a
href="rectoverso.html#COLLATE_INTRO">collated</a> document, where
you might want the name of the complete document, the author(s) and
the copyright line to appear. Another place you might use a doc
cover is for a novel, where you want the title of the novel, not
the chapter title or chapter number, as the first cover page.
<p>
A section
<a href="#COVER">cover</a>
page is what you'd use for cover pages that separate sections of a
collated document. A section cover page (but not a doc cover page)
in a collated document could, for example, simply read &quot;PART
I&quot;.
<p>
In non-collated documents (say, an essay) you can use either a
section cover or a doc cover to generate a cover sheet.
<p>
In addition, nothing prevents you from generating both a doc cover
page and a section cover page for every document in a collated
document. Or you can selectively disable the automatic generation
of either doc covers or section covers in a collated document,
on-the-fly.
<p>
<a name="PLEASE"><strong>Important note:</strong></a>
automatic generation of cover or doc cover pages after the first
one(s) only takes place if you are working with collated documents.
<strong>Mom</strong> provides no mechanism for saying &quot;print
a section cover here even though I'm still working on the same
(non-collated) document.&quot;
<a name="DESC"><h3><u>Description of what mom does on cover pages</u></h3></a>
By default, <strong>mom</strong> typesets cover (and doc cover)
pages identically to
<a href="definitions.html#TERMS_DOCHEADER">docheaders</a>
(see
<a href="docprocessing.html#DOCHEADER_CONTROL">How to change the look of docheaders</a>
for a description of what a docheader looks like). The only
differences are
<br>
<ul>
<li>the position on the page where the information is output
<li>the (optional) addition of copyright and miscellaneous
information
<li>there's no running text underneath
</ul>
<p>
You tell <strong>mom</strong> what you want to appear on the cover
pages through the arguments you pass to
<a href="#COVER">COVER</a>
and/or
<a href="#COVER">DOC_COVER</a>.
Provided you have already given <strong>mom</strong> the
appropriate references macro (e.g.
<a href="docprocessing.html#TITLE">TITLE</a>
or
<a href="docprocessing.html#AUTHOR">AUTHOR</a>),
she will output cover (and doc cover) pages identically to how she
would output docheaders containing the same information.
<p>
By default, <strong>mom</strong> starts cover (and doc cover) pages
one-third of the way down the page. This can be changed through
the use of the control macros
<a href="#COVER_CONTROL_INDEX">COVER_ADVANCE/DOC_COVER_ADVANCE</a>.
<p>
If you request copyright information (and have already given
<strong>mom</strong> the reference macro,
<a href="docprocessing.html#COPYRIGHT">COPYRIGHT</a>),
she sets it, by default, in a smaller
<a href="definitions.html#TERMS_PS">point size</a>
in the bottom right hand corner of the cover (or doc cover) page.
The default point size and the position can be controlled
with
<a href="#COVER_CONTROL_INDEX">COVER_COPYRIGHT_SIZE/DOC_COVER_COPYRIGHT_SIZE</a>
and
<a href="#COVER_CONTROL_INDEX">COVER_COPYRIGHT_QUAD/DOC_COVER_COPYRIGHT_QUAD</a>.
<p>
Similarly, if you request miscellaneous information (and have already given
<strong>mom</strong> the reference macro,
<a href="docprocessing.html#MISC">MISC</a>),
she sets it, by default, in a smaller point size in the bottom left
hand corner of the cover (or doc cover) page. The default point
size is dependent on
<strong>COVER_COPYRIGHT_SIZE/DOC_COVER_COPYRIGHT_SIZE</strong>,
but the position can be controlled with
<a href="#COVER_CONTROL_INDEX">COVER_MISC_QUAD/DOC_COVER_MISC_QUAD</a>.
<a name="PAGINATION"></a>
<p>
<strong>NOTE: mom</strong> does not set any
<a href="definitions.html#TERMS_HEADER">headers</a>
or
<a href="definitions.html#TERMS_FOOTER">footers</a>
on cover pages. Neither does she set any page numbers. From the
point of pagination, cover (and doc cover) pages are considered
&quot;null&quot; pages; if you wish them to be included in the
pagination scheme (even though no page numbers appear), you must
set the page number of each first page following a
<a href="rectoverso.html#COLLATE">COLLATE</a>
manually with
<a href="headfootpage.html#PAGENUMBER">PAGENUMBER</a>.
<a name="DESIGN"></a>
<p>
Finally, if you want to design your own cover page(s), you can
always typeset them (using the
<a href="typesetting.html#MACROS_TYPESETTING">typesetting macros</a>),
invoke
<a href="typesetting.html#NEWPAGE">NEWPAGE</a>,
set up your document <em>in full</em> (see
<a href="docprocessing.html#DOCPROCESSING_TUT">Tutorial -- Setting up a mom document</a>),
and lastly invoke
<a href="docprocessing.html#START">START</a>.
The cover page (and any typesetting commands on it) will have no
effect on <strong>mom</strong>'s processing of the document itself,
the first page of which, moreover, will be numbered &quot;1&quot;
unless you instruct her otherwise with
<a href="headfootpage.html#PAGENUMBER">PAGENUMBER</a>.
<p>
<!---COVER--->
<hr width="66%" align="left">
<p>
<a name="COVER"></a>
Macro: <strong>COVER</strong>
<br>
Macro: <strong>DOC_COVER</strong>
<br>
Required argument: <nobr>TITLE | DOCTITLE | COVERTITLE | CHAPTER | CHAPTER_TITLE | CHAPTER+TITLE</nobr>
<br>
Optional arguments: <nobr>[ SUBTITLE AUTHOR DOCTYPE COPYRIGHT MISC ]</nobr>
<p>
<em>*Note: these macros should be placed in the
&quot;style-sheet&quot; section of your document setup (see the
<a href="docprocessing.html#DOCPROCESSING_TUT">Tutorial -- Setting up a mom document</a>),
i.e. after PRINTSTYLE (and/or DOCTYPE and/or COPYSTYLE), but
before START.</em>
</a>
<p>
<strong>COVER</strong> and <strong>DOC_COVER</strong> behave
identically. The reason <strong>mom</strong> provides two macros
for automatic cover page generation is so that you can have two
different kinds of covers with different information on each.
<p>
Imagine, for a moment, you've written a document comprised of three
sections. When you
<a href="rectoverso.html#COLLATE">COLLATE</a>
the document for output, you could use <strong>DOC_COVER</strong>
to generate a cover page that contained the name of the entire
document, your (the author's) name, and perhaps the copyright date.
Subsequently, you could use <strong>COVER</strong>, after each
<strong>COLLATE</strong> but before each
<a href="docprocessing.html#START">START</a>,
to generate a cover page (or cover &quot;sheet&quot;, if you prefer)
containing just the name of the section.
<br>
<a name="REQUIRED"><h3><u>The required argument</u></h3></a>
Both <strong>COVER</strong> and <strong>DOC_COVER</strong>, whenever
invoked, require a first argument, as listed above. This first argument
will become the first bit of information <strong>mom</strong>
prints on the cover (or doc cover) page (i.e. it will be the
&quot;title&quot;).
<p>
In order for the information to appear, you must, of course, first
have given <strong>mom</strong> the appropriate
<a href="docprocessing.html#REFERENCE_MACROS">reference macro</a>.
A list of arguments with their equivalent reference macros follows.
<br>
<dl>
<dt>TITLE
<dd>-means the argument you gave to
<a href="docprocessing.html#TITLE">TITLE</a>
<dt>DOCTITLE
<dd>-means the argument you gave to
<a href="docprocessing.html#DOCTITLE">DOCTITLE</a>
<dt>COVERTITLE
<dd>-means the argument you gave to
<a href="docprocessing.html#COVERTITLE">COVERTITLE</a>
or
<a href="docprocessing.html#DOC_COVERTITLE">DOC_COVERTITLE</a>
<dt>CHAPTER, CHAPTER_TITLE, CHAPTER+TITLE
<dd>-see below (How the CHAPTER argument and friends work)
</dl>
<br>
<a name="CHAPTER"><h3><u>How the CHAPTER argument and friends work</u></h3></a>
<kbd>CHAPTER</kbd>, by itself, will print the <a
href="docprocessing.html#CHAPTER_STRING">CHAPTER_STRING</a> as well
as the chapter number that you gave to
<a href="docprocessing.html#CHAPTER">CHAPTER</a>.
For example, assuming a vanilla setup for your chapter
<p>
<pre>
\# Reference macros
.CHAPTER 1
.CHAPTER_TITLE "The Bonny Blue Yonder"
&lt;other stuff&gt;
.COVER CHAPTER \" (or .DOC_COVER CHAPTER)
.START
</pre>
will simply print
<p>
<pre>
Chapter 1
</pre>
<kbd>CHAPTER_TITLE</kbd> will print the chapter title you
gave to
<a href="docprocessing.html#CHAPTER_TITLE">CHAPTER_TITLE</a>.
For example, assuming a vanilla setup for your chapter
<p>
<pre>
\# Reference macros
.CHAPTER 1
.CHAPTER_TITLE "The Bonny Blue Yonder"
&lt;other stuff&gt;
.COVER CHAPTER_TITLE \" (or .DOC_COVER CHAPTER_TITLE)
.START
</pre>
will simply print
<p>
<pre>
The Bonny Blue Yonder
</pre>
<p>
<kbd>CHAPTER+TITLE</kbd> will print <strong>both</strong> the
chapter string + number AND the chapter title. For example,
assuming a vanilla setup for your chapter
<p>
<pre>
\# Reference macros
.CHAPTER 1
.CHAPTER_TITLE "The Bonny Blue Yonder"
&lt;other stuff&gt;
.COVER CHAPTER+TITLE \" (or .DOC_COVER CHAPTER+TITLE)
.START
</pre>
will print
<p>
<pre>
Chapter 1
The Bonny Blue Yonder
</pre>
<a name="OPTIONAL"><h3><u>The optional arguments</u></h3></a>
The remainder of the arguments to <strong>COVER</strong> and
<strong>DOC_COVER</strong> are optional. They refer specifically
to the information you gave the
<a href="docprocessing.html#REFERENCE_MACROS">reference macros</a>
bearing the same name as the arguments.
<p>
You may enter as many or as few as you would like to see on your
cover (or doc cover) page. The only hitch is--PAY ATTENTION,
CLASS!--they must be entered in the order given above. For
example, if you want <kbd>TITLE</kbd>, <kbd>AUTHOR</kbd>,
<kbd>COPYRIGHT</kbd> and <kbd>MISC</kbd>
<p>
<pre>
.COVER TITLE AUTHOR COPYRIGHT MISC
</pre>
is correct, while
<p>
<pre>
.COVER TITLE AUTHOR MISC COPYRIGHT
</pre>
is not.
<br>
<a name="DOCTYPE"><h3><u>What the DOCTYPE argument means</u></h3></a>
When you pass <strong>COVER</strong> or <strong>DOC_COVER</strong>
the argument, <kbd>DOCTYPE</kbd>, it refers to the argument you
gave to
<a href="docprocessing.html#DOCTYPE">DOCTYPE</a>&nbsp;<kbd>NAMED</kbd>.
For example, if, in your
<a href="docprocessing.html#DOCSTYLE_MACROS">docstyle macros</a>
you gave a
<p>
<pre>
.DOCTYPE NAMED "Abstract"
</pre>
the argument, <kbd>DOCTYPE</kbd>, in the <strong>COVER</strong> or
<strong>DOC_COVER</strong> macros, would mean that you wanted the
word, Abstract, to appear on the cover (or doc cover), just as it
would in the
<a href="docprocessing.html#DOCHEADER">docheader</a>.
<br>
<!---ENABLING/DISABLING--->
<hr width="66%" align="left">
<p>
<a name="ON_OFF"></a>
<nobr>Macro: <strong>COVERS</strong> &lt;toggle&gt;</nobr>
<br>
<nobr>Macro: <strong>DOC_COVERS</strong> &lt;toggle&gt;</nobr>
</a>
<p>
By default, if you give <strong>mom</strong> a
<a href="#COVER">COVER</a>
or
<a href="#DOC_COVER">DOC_COVER</a>
macro, she will print it. In a document that contains sections,
articles or chapters formerly treated as &quot;one-off's&quot; but
now being
<a href="rectoverso.html#COLLATE_INTRO">collated</a>,
such behaviour may not be desirable.
<p>
<strong>Mom</strong> lets you selectively enable or disable the
generation of covers and/or doc covers with the toggle macros
<strong>COVERS</strong> and <strong>DOC_COVERS</strong>. Because
they're toggle macros, simply invoking them by themselves enables
automatic cover (or doc cover) generation, while invoking them
with any argument at all (<strong>OFF, QUIT, X</strong>, etc)
disables cover (or doc cover) generation.
<p>
<strong>NOTE:</strong> You must place these macros prior to any
instance of
<a href="docprocessing.html#START">START</a>. Since they're
&quot;on&quot; by default, there's no need to use them if you want
covers. However, if you don't, especially in the kind of scenario
described above, the best place to put them (most likely with an
<strong>OFF, NO, X</strong>, etc. argument), is immediately after the
first invocation of <strong>START</strong>. By doing so, you ensure
they precede all subsequent instances of <strong>START</strong>.
<p>
<hr>
<p>
<a name="COVER_CONTROL"><h3><u>Control macros--changing the defaults for covers and document covers</u></h3></a>
The default typographic appearance of the items on a cover (or doc
cover) page is identical to that of the items in a
<a href="definitions.html#TERMS_DOCHEADER">docheader</a>.
(See
<a href="docprocessing.html#DOCHEADER_CONTROL">How to change the look of docheaders</a>
for a description of the defaults.)
<p>
<a href="docprocessing.html#COPYRIGHT">COPYRIGHT</a>
and
<a href="docprocessing.html#MISC">MISC</a>,
which do not appear in docheaders, have the following default
characteristics:
<br>
<ol>
<li>The copyright line is set in the bottom right hand corner
of the page, 2
<a href="definitions.html#TERMS_PS">point sizes</a>
smaller than the size of
<a href="definitions.html#TERMS_RUNNING">running text</a>
<li>The &quot;misc&quot; line is set in the bottom left hand
corner of the page, in the same family, font and point size
as the copyright line.
</ol>
<p>
With the exception of the copyright and &quot;misc&quot; lines, the
defaults for the entirety of cover (and doc cover) pages, and all
the elements thereon, can be changed with control macros whose
behaviour and arguments are identical to
<a href="docprocessing.html#DOCHEADER_CONTROL_INDEX">the control macros used for docheaders</a>.
The only difference is the name by which you invoke the control
macro(s).
<p>
The complete list of cover (and doc cover) page control macros
follows; please refer to the
<a href="docprocessing.html#DOCHEADER_CONTROL_INDEX">docheader control macros index</a>
in order to understand how to use them.
<p>
<a name="COVER_CONTROL_INDEX"><h3><u>Index of cover and doc cover control macros</u></h3></a>
<pre>
<a name="COVER_ADVANCE">.COVER_ADVANCE .DOC_COVER_ADVANCE</a> -+
<a name="COVER_FAMILY">.COVER_FAMILY .DOC_COVER_FAMILY</a> | like DOCHEADER_
<a name="COVER_LEAD">.COVER_LEAD .DOC_COVER_LEAD</a> -+
.COVER_TITLE_FAMILY .DOC_COVER_TITLE_FAMILY -+
.COVER_TITLE_FONT .DOC_COVER_TITLE_FONT | like
.COVER_TITLE_COLOR .DOC_COVER_TITLE_COLOR | TITLE_
.COVER_TITLE_SIZE .DOC_COVER_TITLE_SIZE -+
.COVER_CHAPTER_TITLE_FAMILY .DOC_COVER_CHAPTER_TITLE_FAMILY -+
.COVER_CHAPTER_TITLE_FONT .DOC_COVER_CHAPTER_TITLE_FONT | like
.COVER_CHAPTER_TITLE_COLOR .DOC_COVER_CHAPTER_TITLE_COLOR | CHAPTER_TITLE_
.COVER_CHAPTER_TITLE_SIZE .DOC_COVER_CHAPTER_TITLE_SIZE -+
.COVER_SUBTITLE_FAMILY .DOC_COVER_SUBTITLE_FAMILY -+
.COVER_SUBTITLE_FONT .DOC_COVER_SUBTITLE_FONT | like
.COVER_SUBTITLE_COLOR .DOC_COVER_SUBTITLE_COLOR | SUBTITLE_
.COVER_SUBTITLE_SIZE .DOC_COVER_AUTHOR_SIZE -+
.COVER_ATTRIBUTE_COLOR .DOC_COVER_ATTRIBUTE_COLOR - like ATTRIBUTE_COLOR
- the macro, .ATTRIBUTE_STRING, controls the attribution string
for both docheaders and cover pages; cover pages have no
separate ATTRIBUTE_STRING macro
.COVER_AUTHOR_FAMILY .DOC_COVER_AUTHOR_FAMILY -+
.COVER_AUTHOR_FONT .DOC_COVER_AUTHOR_FONT | like
.COVER_AUTHOR_COLOR .DOC_COVER_AUTHOR_COLOR | AUTHOR_
.COVER_AUTHOR_SIZE .DOC_COVER_AUTHOR_SIZE -+
.COVER_DOCTYPE_FAMILY .DOC_COVER_DOCTYPE_FAMILY -+
.COVER_DOCTYPE_FONT .DOC_COVER_DOCTYPE_FONT | like
.COVER_DOCTYPE_COLOR .DOC_COVER_DOCTYPE_COLOR | DOCTYPE_
.COVER_DOCTYPE_SIZE .DOC_COVER_DOCTYPE_SIZE -+
.COVER_COPYRIGHT_FAMILY .DOC_COVER_COPYRIGHT_FAMILY -+
.COVER_COPYRIGHT_FONT .DOC_COVER_COPYRIGHT_FONT | like any
.COVER_COPYRIGHT_COLOR .DOC_COVER_COPYRIGHT_COLOR | of the above
.COVER_COPYRIGHT_SIZE .DOC_COVER_COPYRIGHT_SIZE -+
.COVER_COPYRIGHT_QUAD .DOC_COVER_COPYRIGHT_QUAD
- the copyright quad can be either L (left) or R (right); default is left
.COVER_MISC_COLOR .DOC_COVER_MISC_COLOR - like any of the above _COLOR
.COVER_MISC_QUAD .DOC_COVER_MISC_QUAD
- the misc quad can be either L (left) or R (right); default is right
</pre>
<strong>Note: COVER_MISC</strong> and
<strong>DOC_COVER_MISC</strong> have only two control macros,
<strong>_COLOR</strong> and <strong>_QUAD</strong>. The
family, font and size of the <kbd>MISC</kbd> argument to
<strong>COVER</strong> or <strong>DOC_COVER</strong> are always the
same as for <kbd>COPYRIGHT</kbd>. Should you wish the family, font
or size to be different from <kbd>COPYRIGHT</kbd>, I suggest setting
the type specs for <kbd>COPYRIGHT</kbd> to the ones you want for
<kbd>MISC</kbd>, then altering them for <kbd>COPYRIGHT</kbd> using
<a href="inlines.html#INDEX_INLINES">inline escapes</a>
in the
<a href="definitions.html#TERMS_STRINGARGUMENT">string argument</a>
you pass to the macro,
<a href="docprocessing.html#COPYRIGHT">COPYRIGHT</a>. (Of course,
you could always do the reverse, but if you pass several arguments
to
<a href="docprocessing.html#MISC">MISC</a>,
it's more likely you want to get <strong>MISC</strong> right first.)
<p>
<hr>
<a href="letters.html#TOP">Next</a>&nbsp;&nbsp;
<a href="refer.html#TOP">Next</a>&nbsp;&nbsp;
<a href="rectoverso.html#TOP">Prev</a>&nbsp;&nbsp;
<a href="#TOP">Top</a>&nbsp;&nbsp;
<a href="toc.html">Back to Table of Contents</a>

405
contrib/groff/contrib/mom/momdoc/definitions.html
View File

@ -1,3 +1,4 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html>
<head>
<meta http-equiv="content-type" content="text/html;charset=iso-8859-1">
@ -10,7 +11,7 @@
<a href="using.html#TOP">Next</a>&nbsp;&nbsp;
<a href="intro.html#TOP">Prev</a>&nbsp;&nbsp;
<a href="toc.html">Back to Table of Contents</a>
<p>
<a name="TOP"></a>
<a name="TERMS">
<h1 align="center"><u>DEFINITIONS OF TERMS USED IN THIS MANUAL</u></h1>
@ -26,9 +27,8 @@ I use a number of typesetting-specific and groff-specific terms
throughout this documentation, as well as a few terms that apply
to <strong>mom</strong> herself. To make life easier, I'll explain
them here. Refer back to this section should you encounter a word
or concept you're not familiar with. Words in these definitions that
are defined elsewhere in this section are marked with asterisks.
<br>
or concept you're not familiar with.
<p>
<hr>
<a name="TERMS_TYPESETTING">
@ -61,14 +61,16 @@ are defined elsewhere in this section are marked with asterisks.
<li><a href="#TERMS_PS">Point Size</a>
<li><a href="#TERMS_QUAD">Quad</a>
<li><a href="#TERMS_RAG">Rag</a>
<li><a href="#TERMS_SHAPE">Shape</a>
<li><a href="#TERMS_SOLID">Solid/set solid</a>
<li><a href="#TERMS_TRACKKERNING">Track kerning/Line kerning</a>
<li><a href="#TERMS_UNBREAKABLESPACE">Unbreakable space</a>
<li><a href="#TERMS_WEIGHT">Weight</a>
<li><a href="#TERMS_WORDSPACE">Word space</a>
<li><a href="#TERMS_XHEIGHT">x-height</a>
</ul>
<dl>
<dl>
<dt><a name="TERMS_ASCENDER"><em>Ascender</em></a>
<dd>The portion of a letter that extends above the bowl. For example,
the letters a, c, and e have no ascenders. The letters b, d, and h
@ -79,8 +81,9 @@ do.
bowls of lower case letters rest.
<dt><a name="TERMS_BALLOTBOX"><em>Ballot box</em></a>
<dd>An unfilled square, usually <strong>*cap-height</strong> in size,
typically placed beside items in a checklist.
<dd>An unfilled square, usually
<a href="#TERMS_CAPHEIGHT">cap-height</a>
in size, typically placed beside items in a checklist.
<dt><a name="TERMS_BULLET"><em>Bullet</em></a>
<dd>A small, filled circle typically found beside items or points in
@ -88,12 +91,14 @@ a list.
<dt><a name="TERMS_CAPHEIGHT"><em>Cap-height</em></a>
<dd>The height of the tallest capital letter in a given
<strong>*font</strong> at the current <strong>*point
size</strong>.
<a href="#TERMS_FONT">font</a>
at the current
<a href="#TERMS_PS">point size</a>.
<dt><a name="TERMS_DESCENDER"><em>Descender</em></a>
<dd>The portion of a letter that extends beneath the
<strong>*baseline</strong> (j, q, y are letters with descenders).
<a href="#TERMS_BASELINE">baseline</a>
(j, q, y are letters with descenders).
<dt><a name="TERMS_DISCRETIONARYHYPHEN"><em>Discretionary hyphen</em></a>
<dd>A symbol inserted between two syllables of a word that indicates to a
@ -121,25 +126,30 @@ letter until the bottom of the drop cap is reached, at which
point text reverts to the left margin.
<dt><a name="TERMS_EM"><em>Em/en</em></a>
<dd>A relative measurement equal to the width of the letter M at a
given <strong>*point size</strong> in a given <strong>*font</strong>.
<dd>An em is a relative measurement equal to the width of the
letter M at a given
<a href="#TERMS_PS">point size</a>
in a given
<a href="#TERMS_FONT">font</a>.
Since most Ms are designed square, an em is usually (but sometimes
erroneously) considered to be the same size as the current point size
(i.e. if the point size of the type is 12, one em equals 12 points).
An en is equal to the width of a letter N (historically 2/3 of an em,
although groff treats an en as 1/2 of an em). Typically, ems and
ens are used to measure indents, or to define the length of dashes
(long hyphens).
erroneously) considered to be the same size as the current point
size (i.e. if the point size of the type is 12, one em equals 12
points). An en is equal to the width of a letter N (historically
2/3 of an em, although groff treats an en as 1/2 of an em).
Typically, ems and ens are used to measure indents, or to define the
length of dashes (long hyphens).
<dt><a name="TERMS_FAMILY"><em>Family</em></a>
<dd>The collective name by which a collection of
<strong>*fonts</strong> are known, e.g. Helvetica, Times Roman,
Garamond.
<a href="#TERMS_FONT">fonts</a>
are known, e.g. Helvetica, Times Roman, Garamond.
<dt><a name="TERMS_FIGURESPACE"><em>Figure space/Digit space</em></a>
<dd>A <strong>*fixed width space</strong> that has the width of one digit. Used for
aligning numerals in, say, columns or numbered lists. In groff,
the figure space is entered with
<dd>A
<a href="#TERMS_FIXEDWIDTHSPACE">fixed width space</a>
that has the width of one digit. Used for aligning numerals in,
say, columns or numbered lists. In groff, the figure space is
entered with
<p>
<pre>
\0
@ -148,9 +158,11 @@ the figure space is entered with
(backslash followed by a zero).
<dt><a name="TERMS_FIXEDWIDTHSPACE"><em>Fixed width space</em></a>
<dd>Equal to <strong>*word space</strong>, but does not expand or
contract when text is <strong>*justified</strong>. In groff, fixed
width space is entered with
<dd>Equal to
<a href="#TERMS_WORDSPACE">word space</a>,
but does not expand or contract when text is
<a href="#TERMS_JUST">justified</a>.
In groff, fixed width space is entered with
<p>
<pre>
\&lt;space&gt;
@ -159,17 +171,25 @@ width space is entered with
where &lt;space&gt; means "hit the spacebar on your keyboard."
<dt><a name="TERMS_FONT"><em>Font</em></a>
<dd>The specific style of type within a <strong>*family</strong>,
e.g. roman, italic. Groff understands four fonts within any given
family: roman, italic, bold, and bold italic.
<dd>The specific
<a href="#TERMS_WEIGHT">weight</a>
and
<a href="#TERMS_SHAPE">shape</a>
of type within a
<a href="#TERMS_FAMILY">family</a>,
e.g. light, medium, bold (which are weights), and roman, italic,
condensed (which are shapes). By default, groff knows of four fonts
within its default set of families: R (medium roman), I (medium
italic), B (bold roman) and BI (bold italic).
<dt><a name="TERMS_FORCE"><em>Force justify
</em></a>
<dd>Sometimes, in <strong>*justified</strong> text, a line needs to be
broken short of the right margin. Force justifying means telling a
typesetting program (like groff) that you want the line broken early
AND that you want the line's word spacing stretched to force the line
flush with the right margin.
<dd>Sometimes, in
<a href="#TERMS_JUST">justified</a>
text, a line needs to be broken short of the right margin. Force
justifying means telling a typesetting program (like groff) that you
want the line broken early AND that you want the line's word spacing
stretched to force the line flush with the right margin.
<dt><a name="TERMS_GUTTER"><em>Gutter</em></a>
<dd>The vertical whitespace separating columns of type.
@ -179,7 +199,8 @@ flush with the right margin.
right margins. Justification is the act of making both margins flush.
Some people use the terms "left justified" and "right justified"
to mean type where only the left (or right) margins align. I don't.
See <strong>*quad</strong>.
See
<a href="#TERMS_QUAD">quad</a>.
<dt><a name="TERMS_KERN"><em>Kerning</em></a>
<dd>Moving pairs of letters closer together to remove excess
@ -187,7 +208,7 @@ whitespace between them. In the days before phototypesetting,
type was set from small, rectangular blocks of wood or metal, each
block having exactly one letter. Because the edge of each block
determined the edge of each letter, certain letter combinations (TA,
for example) didn't fit together well and had to be morticed by hand
for example) didn't fit together well and had to be mortised by hand
to bring them visually closer. Modern typesetting systems usually
take care of kerning automatically, but they're far from perfect.
Professional typesetters still devote a lot of time to fitting letters
@ -195,31 +216,37 @@ and punctuation together properly.
<dt><a name="TERMS_KERNUNIT"><em>Kern Units</em></a>
<dd>A relative distance equal to 1/36 of the current
<strong>*point size</strong>. Used between individual letters
for <strong>*kerning</strong>. Different typesetting systems use
different values (1/54 is popular), and sometimes call kern units by
a different name.
<a href="#TERMS_PS">point size</a>.
Used between individual letters
for
<a href="#TERMS_KERN">kerning</a>.
Different typesetting systems use different values (1/54 is
popular), and sometimes call kern units by a different name.
<p>
<strong>Experts:
<br></strong>A kern unit has nothing to do with groff
machine units.
<dt><a name="TERMS_LEADING"><em>Lead/leading</em></a>
<dd>The distance from the <strong>*baseline</strong> of one line of
type to the line of type immediately beneath it. Pronounced "ledding."
Also called line spacing. Usually measured in <strong>*points</strong>.
<dd>The distance from the
<a href="#TERMS_BASELINE">baseline</a>
of one line of type to the line of type immediately beneath it.
Pronounced "ledding." Also called line spacing. Usually measured
in
<a href="#TERMS_PICASPOINTS">points</a>.
<p>
<em>In case you're interested...</em> In previous centuries,
lines of type were separated by thin strips of -- you guessed it
-- lead. Lines of type that had no lead between them were said to
lines of type were separated by thin strips of--you guessed
it--lead. Lines of type that had no lead between them were said to
be &quot;set solid.&quot; Once you began separating them with strips
of lead, they were said to be &quot;leaded&quot;, and the spacing was
expressed in terms of the number of <strong>*points</strong> of lead.
For this reason, &quot;leading&quot; and &quot;line spacing&quot;
aren't, historically speaking, synonymous. If type was set 10 on 12,
for example, the leading was 2 points, not 12. Nowadays, however,
the two terms are used interchangeably to mean the distance from
baseline to baseline.
expressed in terms of the number of
<a href="#TERMS_PICASPOINTS">points</a>
of lead. For this reason, &quot;leading&quot; and &quot;line
spacing&quot; aren't, historically speaking, synonymous. If type
was set 10 on 12, for example, the leading was 2 points, not 12.
Nowadays, however, the two terms are used interchangeably to mean
the distance from baseline to baseline.
<dt><a name="TERMS_LEADER"><em>Leaders</em></a>
<dd>Single characters used to fill lines, usually to their end.
@ -247,29 +274,60 @@ have always used their own system of measurement for weight (carats),
typographers have always used their own system of measurement for type.
<dt><a name="TERMS_PS"><em>Point Size</em></a>
<dd>The nominal size of type, measured in <strong>*points</strong>,
from the bottom of the longest <strong>*descender</strong> to the top
of the highest <strong>*ascender</strong>. In reality, type is always
fractionally smaller than its point size.
<dd>The nominal size of type, measured in
<a href="#TERMS_PICASPOINTS">points</a>
from the bottom of the longest
<a href="#TERMS_DESCENDER">descender</a>
to the top of the highest
<a href="#TERMS_ASCENDER">ascender</a>.
In reality, type is always fractionally smaller than its point size.
<dt><a name="TERMS_QUAD"><em>Quad</em></a>
<dd>When only one margin of type is flush, lines of type are quadded in
the direction of the flush margin. Therefore, quad left means the
left margin is flush, the right isn't. Quad right means the right
margin is flush, the left isn't. Quad center means neither the left
margin is flush, the left isn't. Quad centre means neither the left
nor the right margin is flush; rather, lines of type are quadded on
both sides so that type appears centered on the page.
both sides so that type appears centred on the page.
<dt><a name="TERMS_RAG"><em>Rag</em></a>
<dd>Describes a margin that isn't flush. Rag right means the right
margin isn't flush. Rag left means the left margin isn't flush.
The expression "flush left/rag right" is sometimes used to describe
type that is <strong>*quadded</strong> left.
type that is
<a href="#TERMS_QUAD">quadded</a>
left.
<dt><a name="TERMS_SHAPE"><em>Shape</em></a>
<dd>The degree of slant and/or the width of characters.
(Technically speaking, this is not a proper typesetting term;
however, it may help clarify some concepts presented in these
documents.)
<p>
Some typical shapes are:
<ul>
<li>&quot;Roman&quot;, which has no slant, and has letterforms of
average width
<li>&quot;Italic&quot;, which is slanted, and has letterforms
of average width
<li>&quot;Condensed&quot;, which has no slant, but has
letterforms narrower than the average represented by Roman
<li>&quot;Condensed Italic&quot;, which is slanted, with letterforms narrower
than average
</ul>
The term
<a href="#TERMS_FONT">font</a>,
as it is used in these documents, refers to a combination of
<a href="#TERMS_WEIGHT">weight</a>
and shape.
<dt><a name="TERMS_SOLID"><em>Solid/set solid</em></a>
<dd>When no <strong>*lead</strong> is added between lines of type
(i.e. the <strong>*point size</strong> and linespacing are the
same), the lines are said to be &quot;set solid.&quot;
<dd>When no
<a href="#TERMS_LEADING">lead</a>
is added between lines of type (i.e. the
<a href="#TERMS_PS">point size</a>
and linespacing are the same), the lines are said to be &quot;set
solid.&quot;
<dt><a name="TERMS_TRACKKERNING"><em>Track kerning/Line kerning</em></a>
<dd>Sometimes, it's advantageous to increase or decrease the amount of
@ -279,10 +337,13 @@ The correct term is letter spacing, but track kerning and line kerning
(and sometimes, just "kerning") have come to mean the same thing.
<dt><a name="TERMS_UNBREAKABLESPACE"><em>Unbreakable space</em></a>
<dd>Equal to <strong>*word space</strong>, however words separated by
an unbreakable space will always be kept together on the same line.
Expands and contracts like word space. Useful for proper names, which
should never be broken. In groff, unbreakable space is entered with
<dd>Equal to
<a href="#TERMS_WORDSPACE">word space</a>,
however words separated by an unbreakable space will always be kept
together on the same line. Expands and contracts like word space.
Useful for proper names, which one should, whenever possible, avoid
splitting onto two lines. In groff, unbreakable space is entered
with
<p>
<pre>
\~
@ -290,16 +351,26 @@ should never be broken. In groff, unbreakable space is entered with
(backslash followed by a tilde).
<dt><a name="TERMS_WEIGHT"><em>Weight</em></a>
<dd>The thickness of the strokes of letterforms. Medium and Book
have average thicknesses and are the weights used for most of the
text in books, magazines, newspapers, etc. Light has strokes
slightly thinner than Medium or Book, but is still acceptable for
most text. Semibold, Bold, Heavy and Black all have strokes of
increasing thickness, making them suitable for heads, subheads,
headlines and the like.
<dt><a name="TERMS_WORDSPACE"><em>Word space</em></a>
<dd>The amount of whitespace between words. When text is
<strong>*justified</strong>, word space expands or contracts to make
the margins flush.
<a href="#TERMS_JUST">justified</a>,
word space expands or contracts to make the margins flush.
<dt><a name="TERMS_XHEIGHT"><em>x-height</em></a>
<dd>The height of a lower case letter x in a given font at a given
point size. Generally used to mean the average height of the bowl
of lower case letters.
</dl>
<p>
<hr>
<a name="TERMS_GROFF">
@ -326,20 +397,23 @@ of lower case letters.
<dl>
<dt><a name="TERMS_ALIAS"><em>Alias</em></a>
<dd>A <strong>*macro</strong> invoked by a name different from its
&quot;official&quot; name. For example, the official name of the
macro to change <strong>*family</strong> is <strong>FAMILY</strong>.
Its alias is <strong>FAM</strong>. Aliases may be created for any
macro (via the
<dd>A
<a href="#TERMS_MACROS">macro</a>
invoked by a name different from its &quot;official&quot;
name. For example, the official name of the macro to change
<a href="#TERMS_FAMILY">family</a>
is <strong>FAMILY</strong>. Its alias is
<strong>FAM</strong>. Aliases may be created for any macro (via the
<a href="goodies.html#ALIAS">ALIAS</a>
macro) provided the alias uses a name not already taken
by the <strong>mom</strong> macros or one of the groff
<strong>*primitives</strong>. For a complete list of alias names
you must not use, see the
<a href="#TERMS_PRIMITIVES">primitives</a>.
For a complete list of words or names you must not use, see the
<a href="reserved.html#RESERVED">list of reserved words</a>.
<dt><a name="TERMS_ARGUMENTS"><em>Arguments</em></a>
<dd>Parameters or information needed by a <strong>*macro</strong>
<dd>Parameters or information needed by a
<a href="#TERMS_MACROS">macro</a>
to do its job. For example, in the macro
<p>
<pre>
@ -356,32 +430,42 @@ LEFT is the argument. Arguments are separated from macros by spaces.
Some macros require several arguments; each is separated by a space.
<dt><a name="TERMS_COMMENTLINES"><em>Comment Lines</em></a>
<dd><strong>*Input lines</strong> introduced with the comment character
<dd><a href="#TERMS_INPUTLINE">Input lines</a>
introduced with the comment character
<p>
<pre>
\#
</pre>
When processing output, groff silently ignores everything on the
line after the comment character.
When processing output, groff silently ignores everything on a
line that begins with the comment character.
<dt><a name="TERMS_CONTROLLINES"><em>Control Lines</em></a>
<dd>Instructions to groff that appear on a line by themselves,
which means that &quot;control lines&quot; are either
<strong>*macros</strong> or <strong>*groff primitives</strong>.
<a href="#TERMS_MACROS">macros</a>
or groff
<a href="#TERMS_PRIMITIVES">primitives</a>.
Control lines begin with a period or, occasionally, an apostrophe.
<dt><a name="TERMS_FILLED"><em>Filled lines/fill mode</em></a>
<dd>Automatic <strong>*justification</strong> or
<strong>*quadding</strong>. In fill mode, the ends of lines as they
appear in your text editor are ignored. Instead, words from adjoining
<strong>*input lines</strong> are added one at a time to the output
line until no more words fit. Then, depending whether text is to
be <strong>*justified</strong> or <strong>*quadded</strong> (left,
right, or center), and depending on whether automatic hyphenation
is turned on, groff attempts to hyphenate the last word, or, barring
that, spreads and breaks the line (when justification is turned on) or
breaks and quads the line (when quadding is turned on).
<dd>Automatic
<a href="#TERMS_JUST">justification</a>
or
<a href="#TERMS_QUAD">quadding</a>.
In fill mode, the ends of lines as they appear in your text editor
are ignored. Instead, words from adjoining
<a href="#TERMS_INPUTLINE">input lines</a>
are added one at a time to the output line until no more words fit.
Then, depending whether text is to be
<a href="#TERMS_JUST">justified</a>
or
<a href="#TERMS_QUAD">quadded</a>
(left, right, or centre), and depending on whether automatic
hyphenation is turned on, groff attempts to hyphenate the last word,
or, barring that, spreads and breaks the line (when justification
is turned on) or breaks and quads the line (when quadding is turned
on).
<p>
<a name="TERMS_NOFILL"></a>
Nofill mode (non-filled text) means that groff respects the ends
@ -389,25 +473,30 @@ of lines as they appear in your text editor.
<dt><a name="TERMS_INLINES"><em>Inline escapes</em></a>
<dd>Instructions issued to groff that appear as part of an
<strong>*input line</strong> (as opposed to <strong>*macros</strong>,
which must appear on a line by themselves). Inline escapes are always
introduced by the backslash character. For example,
<a href="#TERMS_INPUTLINE">input line</a>
(as opposed to
<a href="#TERMS_MACROS">macros</a>,
which must appear on a line by themselves). Inline escapes are
always introduced by the backslash character. For example,
<p>
<pre>
A line of text with the word T\*[BU 2]oronto in it
</pre>
contains the inline escape \*[BU 2] (which means &quot;move the letter
'o' 2 <strong>*kern units</strong> closer to the letter 'T'&quot;).
'o' 2
<a href="#TERMS_KERNUNIT">kern units</a>
closer to the letter 'T'&quot;).
<p>
<strong>Mom</strong>'s inline escapes always take the form
<strong>\*[</strong><i>ESCAPE</i><strong>]</strong>, where <i>ESCAPE</i>
is composed of capital letters, sometimes followed immediately
by a digit, sometimes followed by a space and a <strong>*numeric
argument</strong>. <strong>Groff</strong>'s escapes begin with the
backslash character but typically have no star and are in lower case.
For example, the <strong>mom</strong> escapes to move forward 6 points
on a line are either
by a digit, sometimes followed by a space and a
<a href="#TERMS_NUMERICARGUMENT">numeric argument</a>.
<strong>Groff</strong>'s escapes begin with the backslash character
but typically have no star and are in lower case. For example, the
<strong>mom</strong> escapes to move forward 6 points on a line are
either
<p>
<pre>
\*[FP6]&nbsp;&nbsp;or&nbsp;&nbsp;\*[FWD 6p]
@ -426,20 +515,26 @@ while the <strong>groff</strong> escape for the same thing is
<dd>Instructions embedded in a document that determine how groff processes
the text for output. <strong>mom</strong>'s macros always begin with a
period, on a line by themselves, and must be typed in capital letters.
Typically, macros contain complex commands issued to groff -- behind
the scenes -- via groff <strong>*primitives</strong>.
Typically, macros contain complex commands issued to groff--behind
the scenes--via groff
<a href="#TERMS_PRIMITIVES">primitives</a>.
<dt><a name="TERMS_UNITS"><em>Machine units</em></a>
<dd>A machine unit is 1/1000 of a <strong>*point</strong> when the
groff device is ps. (&quot;ps&quot; means &quot;PostScript&quot; --
the default device for which groff prepares output, and the device for
which <strong>mom</strong> was specifically designed.)
<dd>A machine unit is 1/1000 of a
<a href="#TERMS_PICASPOINTS">point</a>
when the groff device is ps. (&quot;ps&quot; means
&quot;PostScript&quot;--the default device for which groff
prepares output, and the device for which <strong>mom</strong> was
specifically designed.)
<dt><a name="TERMS_NUMERICARGUMENT"><em>Numeric argument</em></a>
<dd>An <strong>*argument</strong> that has the form of a digit.
Numeric arguments can be built out of arithmetic expressions using
+, -, *, and / for plus, minus, times, and divided-by respectively.
If a numeric argument requires a <strong>*unit of measure</strong>,
<dd>An
<a href="#TERMS_ARGUMENT">argument</a>
that has the form of a digit. Numeric arguments can be built out
of arithmetic expressions using +, -, *, and / for plus, minus,
times, and divided-by respectively. If a numeric argument requires
a
<a href="#TERMS_UNITOFMEASURE">unit of measure</a>,
a unit of measure must be appended to <em>every</em> digit in the
argument. For example:
<p>
@ -461,9 +556,12 @@ or minus sign when using <strong>mom</strong>'s macros is slim.
native command language, and out of which macros are built.
<dt><a name="TERMS_STRINGARGUMENT"><em>String Argument</em></a>
<dd>Technically, any <strong>*argument</strong> that is not numeric.
In this documentation, string argument means an argument that requires
the user to input text. For example, in the <strong>*macro</strong>
<dd>Technically, any
<a href="#TERMS_ARGUMENTS">argument</a>
that is not numeric. In this documentation, string argument means
an argument that requires the user to input text. For example, in
the
<a href="#TERMS_MACROS">macro</a>
<p>
<pre>
.TITLE "My Pulitzer Novel"
@ -473,21 +571,22 @@ the user to input text. For example, in the <strong>*macro</strong>
<p>
Because string arguments must be enclosed by double-quotes, you can't
use double-quotes as part of the string argument. If you need
double-quotes to be part of a string argument, use the <strong>*inline
escapes</strong> <strong> \(lq</strong> and <strong>\(rq</strong>
(leftquote and rightquote respectively) in place of the double-quote
character (").
double-quotes to be part of a string argument, use the
<a href="#TERMS_INLINES">inline escapes</a>
<strong>\(lq</strong> and <strong>\(rq</strong> (leftquote and rightquote
respectively) in place of the double-quote character (").
<dt><a name="TERMS_UNITOFMEASURE"><em>Unit of measure</em></a>
<dd>The single letter after a <strong>*numeric argument</strong>
<dd>The single letter after a
<a href="#TERMS_NUMERICARGUMENT">numeric argument</a>
that tells <strong>mom</strong> what measurement scale the argument
should use. Commonly valid units are:
should use. Common valid units are:
<p>
<table valign="baseline" summary="unitsofmeasure">
<tr><td><strong>i</strong><td> = <td>inches
<tr><td><strong>p</strong><td> = <td>points
<tr><td><strong>P</strong><td> = <td>picas
<tr><td><strong>c</strong><td> = <td>centimeters
<tr><td><strong>c</strong><td> = <td>centimetres
<tr><td><strong>m</strong><td> = <td>ems
<tr><td><strong>n</strong><td> = <td>ens
<tr><td><strong>v</strong><td> = <td>the current leading (line space)</td></tr>
@ -510,7 +609,8 @@ that set the size or measure of something MUST be given a unit of
measure. <strong>mom</strong>'s macros do not have default units
of measure. There are a couple of exceptions, the most notable of
which are <strong>PT_SIZE</strong> and <strong>LS</strong>. Both use
<strong>*points</strong> as the default unit of measure, which means
<a href="#TERMS_PICASPOINTS">points</a>
as the default unit of measure, which means
you don't have to append &quot;p&quot; to their argument.
<p>
You can enter decimal values for any unit of measure. Different units
@ -523,10 +623,15 @@ and 5 points. If you want 12 picas and 5 points, you have to
enter the measure as 12P+5p.
<dt><a name="TERMS_ZEROWIDTHCHARACTER"><em>Zero-width character</em></a>
<dd>The <strong>*inline escape</strong> that allows you to print a
literal period, apostrophe and, if <strong>*output lines</strong>
are <strong>*filled</strong>, a space that falls at the beginning of
an <strong>*input line</strong>. It looks like this:
<dd>The
<a href="#TERMS_INLINES">inline escape</a>
that allows you to print a literal period, apostrophe and, if
<a href="#TERMS_OUTPUTLINE">output lines</a>
are
<a href="#TERMS_FILLED">filled</a>,
a space that falls at the beginning of an
<a href="#TERMS_INPUTLINE">input line</a>.
It looks like this:
<p>
<pre>
\&amp;
@ -535,15 +640,17 @@ an <strong>*input line</strong>. It looks like this:
(backslash followed by an ampersand).
<p>
Normally, groff interprets a period (or an apostrophe) at the beginning
of an input line as meaning that what follows is a <strong>*control
line</strong>. In fill modes, groff treats a space at the beginning
of an input line as meaning &quot;start a new line and put a space
at the beginning of it.&quot; If you want groff to interpret periods
and apostrophes at the beginning of input lines literally (ie. print
of an input line as meaning that what follows is a
<a href="#TERMS_CONTROLLINES">control line</a>.
In fill modes, groff treats a space at the beginning of an input
line as meaning &quot;start a new line and put a space at the
beginning of it.&quot; If you want groff to interpret periods and
apostrophes at the beginning of input lines literally (i.e. print
them), or spaces at the beginning of input lines as just garden
variety word spaces, you must start the line with the zero-width
character.
</dl>
<p>
<hr>
<a name="TERMS_MOM">
@ -567,16 +674,19 @@ character.
</ul>
<dl>
<dt><a name="TERMS_BLOCKQUOTE"><em>Blockquote</em></a>
<dd>Cited material other than <strong>*quotes</strong>.
<dd>Cited material other than
<a href="#TERMS_QUOTE">quotes</a>.
Typically set at a smaller point size than paragraph text, indented
from the left and right margins. Blockquotes are
<strong>*filled</strong>.
<a href="#TERMS_FILLED">filled</a>.
<dt><a name="TERMS_CONTROLMACRO"><em>Control macro</em></a>
<dd>Macros used in
<a href="docprocessing.html#DOCPROCESSING">document processing</a>
to control/alter the appearance of document elements (e.g. heads,
quotes, footnotes, <strong>*headers</strong>, etc.).
quotes, footnotes,
<a href="#TERMS_HEADER">headers</a>,
etc.).
<dt><a name="TERMS_DOCHEADER"><em>Document header/docheader</em></a>
<dd>Document information (title, subtitle, author, etc) output
@ -590,7 +700,7 @@ beginning of a chapter, story, or other document.
<dd>Document information (frequently author and title) output in
the bottom margin of pages <em>after</em> page one. Not to be
confused with footnotes, which are considered part of
<strong>*running text</strong>.
<a href="#TERMS_RUNNING">running text</a>.
<dt><a name="TERMS_HEAD"><em>Head</em></a>
<dd>A title that introduces a major section of a document.
@ -600,20 +710,23 @@ confused with footnotes, which are considered part of
the top margin of pages <em>after</em> page one.
<p>
<strong>NOTE:</strong> In terms of content and style, headers and
<strong>*footers</strong> are the same; they differ only in their
placement on the page. In most places in this documentation,
references to the content or style of headers applies equally to
footers.
<a href="#TERMS_FOOTER">footers</a>
are the same; they differ only in their placement on the page. In
most places in this documentation, references to the content or
style of headers applies equally to footers.
<dt><a name="TERMS_LINEBREAK"><em>Linebreak/author linebreak</em></a>
<dd>A horizontal gap in <strong>*running text</strong>, frequently
set off by typographic symbols such as asterisks or daggers. Used to
indicate a shift in the content of a document (e.g. a scene change in a
short story).
<dd>A horizontal gap in
<a href="#TERMS_RUNNING">running text</a>,
frequently set off by typographic symbols such as asterisks or
daggers. Used to indicate a shift in the content of a document
(e.g. a scene change in a short story). Also commonly called a
scene break or a section break.
<dt><a name="TERMS_PARAHEAD"><em>Paragraph head</em></a>
<dd>A title joined to the body of a paragraph; hierarchically one
level beneath <strong>*subheads</strong>.
level beneath
<a href="#TERMS_SUBHEAD">subheads</a>.
<dt><a name="TERMS_QUOTE"><em>Quote</em></a>
<dd>A quote, to <strong>mom</strong>, is a line-for-line setting
@ -625,14 +738,16 @@ with quotes.
<dt><a name="TERMS_RUNNING"><em>Running text</em></a>
<dd>In a document formatted with <strong>mom</strong>, running
text means text that forms the body of the document, including
elements such as heads and subheads. <strong>*Docheaders,
*headers, *footers</strong> and page numbers are NOT part of
running text.
elements such as heads and subheads.
<a href="#TERMS_DOCHEADER">Docheaders</a>,
<a href="#TERMS_HEADER">headers</a>,
<a href="#TERMS_FOOTER">footers</a>
and page numbers are NOT part of running text.
<dt><a name="TERMS_SUBHEAD"><em>Subhead</em></a>
<dd>A title used to introduce secondary sections of a document;
hierarchically one level beneath sections introduced by
<strong>*heads</strong>.
<a href="#TERMS_HEAD">heads</a>.
<dt><a name="TERMS_TOGGLE"><em>Toggle</em></a>
<dd>A macro or tag that, when invoked without an argument,

3211
contrib/groff/contrib/mom/momdoc/docelement.html
View File

File diff suppressed because it is too large Load Diff

1059
contrib/groff/contrib/mom/momdoc/docprocessing.html
View File

File diff suppressed because it is too large Load Diff

276
contrib/groff/contrib/mom/momdoc/goodies.html
View File

@ -1,3 +1,4 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html>
<head>
<meta http-equiv="content-type" content="text/html;charset=iso-8859-1">
@ -10,16 +11,16 @@
<a href="inlines.html#TOP">Next</a>&nbsp;&nbsp;
<a href="typesetting.html#TOP">Prev</a>&nbsp;&nbsp;
<a href="toc.html">Back to Table of Contents</a>
<p>
<a name="TOP"></a>
<a name="GOODIES">
<h2><u>Goodies</u></h2>
<h1 align="center"><u>Goodies</u></h1>
</a>
<p>
<a name="INTRO_GOODIES"></a>
The macros in this section are a collection of useful (and sometimes
nearly indispensible) routines to simplify typesetting.
nearly indispensable) routines to simplify typesetting.
<p>
<a name="INDEX_GOODIES">
<h3><u>Goodies list</u></h3>
</a>
@ -28,8 +29,9 @@ nearly indispensible) routines to simplify typesetting.
<li><a href="#ALIAS">ALIAS</a> (rename macros)
<li><a href="#SILENT">SILENT</a> (&quot;hide&quot; input lines from output)
<li><a href="#TRAP">TRAP</a> (suspend/re-invoke traps)
<li><a href="#SMARTQUOTES">SMARTQUOTES</a>
<li><a href="#SMARTQUOTES">SMARTQUOTES</a> (convert typewriter doublequotes to proper doublequotes)
<li><a href="#CAPS">CAPS</a> (convert to upper case)
<li><a href="#STRING">STRING</a> (user-definable strings)
<br>
<li><strong>Underscore/underline</strong>
<ul>
@ -56,14 +58,24 @@ nearly indispensible) routines to simplify typesetting.
<li><a href="#DROPCAP_FAMILY">DROPCAP_FAMILY</a> (change drop cap family)
<li><a href="#DROPCAP_FONT">DROPCAP_FONT</a> (change drop cap font)
<li><a href="#DROPCAP_ADJUST">DROPCAP_ADJUST</a> (alter size of drop cap)
<li><a href="#DROPCAP_COLOR">DROPCAP_COLOR</a> (change colour of drop cap)
<li><a href="#DROPCAP_GUTTER">DROPCAP_GUTTER</a> (change space between drop cap and running text)
</ul>
</ul>
<li><strong>Superscript</strong>
<li><strong>Superscripts</strong>
<ul>
<li><a href="#SUP">\*[SUP]</a> (set superscript)
<li><a href="#CONDSUP">\*[CONDSUP]</a> (set condensed superscript)
<li><a href="#EXTSUP">\*[EXTSUP}</a> (set extended superscript)
<li><a href="#EXTSUP">\*[EXTSUP]</a> (set extended superscript)
</ul>
<li><strong>Lists</strong>
<ul>
<li><a href="docelement.html#LIST_INTRO">Introduction to lists</a>
<li><a href="docelement.html#LIST">LIST</a>
<li><a href="docelement.html#ITEM">ITEM</a>
<li><a href="docelement.html#SHIFT_LIST">SHIFT_LIST</a>
<li><a href="docelement.html#RESET_LIST">RESET_LIST</a>
<li><a href="docelement.html#PAD_LIST_DIGITS">PAD_LIST_DIGITS</a>
</ul>
</ul>
@ -72,7 +84,7 @@ nearly indispensible) routines to simplify typesetting.
<hr width="66%" align="left">
<a name="ALIAS"><h3><u>Rename macros</u></h3></a>
<br>
Macro: <strong>ALIAS</strong> <var>&lt;new name&gt; &lt;old name&gt;</var>
<nobr>Macro: <strong>ALIAS</strong> &lt;new name&gt; &lt;old name&gt;</nobr>
<p>
The <strong>ALIAS</strong> macro may well be your best friend. With it,
@ -142,14 +154,14 @@ of your documents, please.
<strong>EXPERTS:</strong> <strong>ALIAS</strong> is an alias of
<code>.als</code>. You can use either, or mix 'n' match with
impunity.
<br>
<p>
<!---SILENT--->
<hr width="66%" align="left">
<a name="SILENT"><h3><u>Hide input lines from output</u></h3></a>
<br>
Macro: <strong>SILENT</strong> <var>toggle</var>
<nobr>Macro: <strong>SILENT</strong> toggle</nobr>
<br>
Alias: <strong>COMMENT</strong>
@ -195,14 +207,14 @@ or
to which you've passed the <strong>J</strong> or <strong>QUAD</strong>
argument. You must insert <code>.BR</code> yourself, or risk a
portion of your text disappearing into a black hole.
<br>
<p>
<!---TRAP--->
<hr width="66%" align="left">
<a name="TRAP"><h3><u>Suspend/re-invoke traps</u></h3></a>
<br>
Macro: <strong>TRAP</strong> <var>toggle</var>
<nobr>Macro: <strong>TRAP</strong> toggle</nobr>
<p>
Traps are vertical positions on the output page at which you or
@ -211,13 +223,8 @@ something automatically. Commonly, this is near the bottom of
the page, where automatic behind-the-scenes processing is needed
in order for one page to finish and another to start.
<p>
Sometimes, traps get sprung when you don't want them, notably
when using the
<a href="#EL">EL</a>
and
<a href="#TN">TN</a>
macros. If this happens, surround just the offending macros and
input lines with
Sometimes, traps get sprung when you don't want them. If this
happens, surround just the offending macros and input lines with
<p>
<pre>
.TRAP OFF
@ -229,22 +236,27 @@ input lines with
turns it off (i.e. suspends the trap), and no argument turns it
(back) on.
<p>
Have a look at the <strong>IMPORTANT</strong> sections
of <strong>EL</strong> and <strong>TN</strong> to see
<strong>TRAP</strong> in action.
<br>
<!---SMARTQUOTES--->
<hr width="66%" align="left">
<a name="SMARTQUOTES"><h3><u>Smartquotes</u></h3></a>
<a name="SMARTQUOTES"><h3><u>Convert typewriter doublequotes to proper doublequotes</u></h3></a>
<br>
Macro: <strong>SMARTQUOTES</strong> <var>toggle</var>
<nobr>Macro: <strong>SMARTQUOTES</strong> [&lt;off&gt;] [ ,, | &gt;&gt; | &lt;&lt; ]</nobr>
<br>
or
<br>
<nobr>Macro: <strong>SMARTQUOTES</strong> DA | DE | ES | FR | IT | NL | NO | PT | SV</nobr>
<p>
<strong>SMARTQUOTES</strong> converts all instances of the
inch-mark, (<kbd>"</kbd> -- also called a &quot;doublequote&quot;),
into the appropriate instances of true open- and close-doublequotes.
If you invoke <strong>SMARTQUOTES</strong> without an argument,
<strong>mom</strong> converts all instances of the inch-mark,
(<kbd>"</kbd> -- also called a &quot;doublequote&quot;), into
the appropriate instances of true Anglo-American open- and
close-doublequotes. (See
<a href="#SQ_INTERNATIONAL">Internationalization</a>
for how to get SMARTQUOTES to behave correctly for non-English
quoting styles.)
<p>
Typographically, there is a difference between the inch-mark and
doublequotes -- a BIG difference. Sadly, typewriters and computer
@ -255,20 +267,83 @@ typeset copy. Failure to turn inches into quotes is the first thing
a professional typesetter notices in documents prepared by amateurs.
And you don't want to look like an amateur, do you?
<p>
When preparing documents for typesetting, by all means, use the
inch-mark. Just make sure to turn <strong>SMARTQUOTES</strong>
on. <strong>SMARTQUOTES</strong> is a toggle, so invoking it with
no argument turns it on, and invoking it with any argument at all
turns it off.
<a name="SQ_INTERNATIONAL"><h3>Internationalization</h3></a>
<p>
If you invoke <strong>SMARTQUOTES</strong> with one of the optional
arguments (<kbd>,,</kbd> or <kbd>&gt;&gt;</kbd> or
<kbd>&lt;&lt;</kbd>) you can use <kbd>&quot;</kbd> as &quot;cheap&quot;
open- and close-quotes when inputting text in a language other than
English, and have <strong>mom</strong> convert them, on output,
into the chosen open- and close-quote style.
<p>
<kbd>,,</kbd> opens quotes with &quot;lowered doublequotes&quot; and
closes them with &quot;raised doublequotes&quot;, as in this ascii
approximation:
<p>
<pre>
,,Hilfe !``
</pre>
<kbd>&gt;&gt;</kbd> opens quotes with guillemets pointing to the
right, and closes them with guillemets pointing to the left, as in
this ascii approximation:
<p>
<pre>
&gt;&gt;Zurück !&lt;&lt;
</pre>
<kbd>&lt;&lt;</kbd> opens quotes with guillemets pointing to the
left, and closes them with guillemets pointing to the right, as in
this ascii approximation:
<p>
<pre>
&lt;&lt;Mais monsieur! Je ne suis pas ce genre de fille!&gt;&gt;
</pre>
Please note: the above arguments to <strong>SMARTQUOTES</strong>
are literal ASCII characters. <kbd>,,</kbd> is two commas,
<kbd>&lt;&lt;</kbd> is two less-than signs and <kbd>&gt;&gt;</kbd>
is two greater-than signs.
<p>
Alternatively, you can pass <strong>SMARTQUOTES</strong> the
two-letter, ISO 639 abbreviation for the language you're writing in,
and <strong>mom</strong> will output the correct quotes.
<p>
<pre>
.SMARTQUOTES DA = Danish &gt;&gt;text&lt;&lt;
.SMARTQUOTES DE = German ,,text``
.SMARTQUOTES ES = Spanish ``text´´
.SMARTQUOTES FR = French &lt;&lt; text &gt;&gt;
.SMARTQUOTES IT = Italian &lt;&lt; text &gt;&gt;
.SMARTQUOTES NL = Dutch ´´text´´
.SMARTQUOTES NO = Norwegian &lt;&lt;text&gt;&gt;
.SMARTQUOTES PT = Portuguese &lt;&lt;text&gt;&gt;
.SMARTQUOTES SV = Swedish &gt;&gt;text&gt;&gt;
</pre>
<p>
Turn <strong>SMARTQUOTES</strong> off by passing it any argument
<em>not</em> in the argument list (e.g. <strong>OFF</strong>,
<strong>QUIT</strong>, <strong>X</strong>, etc.)
<p>
If you're using the
<a href="docprocessing.html#DOCPROCESSING">document processing macros</a>
with
<a href="#PRINTSTYLE">PRINTSTYLE TYPESET</a>,
<strong>SMARTQUOTES</strong> is on by default; with
<strong>SMARTQUOTES</strong> is on by default (in the Anglo-American
style); with
<a href="#PRINTSTYLE">PRINTSTYLE TYPEWRITE</a>,
it's off by default (and should probably stay that way).
<p>
Finally, if you're fussy about the kerning of quote marks in
relation to the text they surround, or have special quoting needs,
you have to enter quote marks by hand using groff's native
<a href="definitions.html#TERMS_INLINES">inline escapes</a>
for special characters (see man groff_char for a complete list of
special characters). Entering quote marks this way allows you to
use <strong>mom</strong>'s
<a href="inlines.html#INLINE_KERNING_MOM">inline kerning escapes</a>
to fine-tune the look of quotes.
<p>
<strong>NOTE:</strong> <strong>SMARTQUOTES</strong> does not work on
single quotes, which most people input with the apostrophe (found at
the right-hand end of the &quot;home row&quot; on a QWERTY keyboard).
@ -289,14 +364,14 @@ the foot- and inch-marks, when you need them, with the
<a href="definitions.html#TERMS_INLINES">inline escapes</a>
<strong>\*[FOOT]</strong> and <strong>\*[INCH]</strong>, instead
of <kbd>'</kbd> and <kbd>"</kbd>.
<br>
<p>
<!---CAPS--->
<hr width="66%" align="left">
<a name="CAPS"><h3><u>Convert to upper case</u></h3></a>
<br>
Macro: <strong>CAPS</strong> <var>toggle</var>
<nobr>Macro: <strong>CAPS</strong> toggle</nobr>
<p>
<strong>CAPS</strong> converts all lower case letters to upper
@ -318,12 +393,57 @@ produces, on output
ALL WORK AND NO PLAY MAKES JACK A DULL BOY.
</pre>
<!---STRING--->
<hr width="66%" align="left">
<a name="STRING"><h3><u>User-defined strings</u></h3></a>
<br>
<nobr>Macro: <strong>STRING</strong> &lt;name&gt; &lt;what you want in the string&gt;</nobr>
<p>
You may find sometimes that you have to type out portions of text
repeatedly. If you'd like not to wear out your fingers, you can
define a &quot;string&quot; that, whenever you call it by name,
outputs whatever you put into it.
<p>
For example, say you're creating a document that repeatedly uses
the phrase &quot;the Montreal/Windsor corridor&quot;. Instead of
typing all that out every time, you could define a string, like
this:
<p>
<pre>
.STRING mw the Montreal/Windsor corridor
</pre>
Once a string is defined, you can call it any time with the
<a href="definitions.html#INLINES">inline escape</a>
<kbd>\*[&lt;stringname&gt;]</kbd>. Using the example string above
<p>
<pre>
The schedule for trains along \*[mw]:
</pre>
produces, on output
<p>
<pre>
The schedule for trains along the Montreal/Windsor corridor:
</pre>
<strong>NOTE:</strong> Be very careful not to put any spaces at the
ends of strings you're defining, unless you want them. Everything
after the name argument you pass to <strong>STRING</strong> goes
into the string, including trailing spaces.
<p>
<strong>Experts: STRING</strong> is an alias for <strong>ds</strong>.
You can use either, or mix 'n' match with impunity.
<p>
<!---UNDERSCORE--->
<hr width="66%" align="left">
<a name="UNDERSCORE"><h3><u>Single underscore</u></h3></a>
<br>
Macro: <strong>UNDERSCORE</strong> <var>[ &lt;distance below baseline&gt; ] &quot;&lt;string&gt;&quot;</var>
<nobr>Macro: <strong>UNDERSCORE</strong> [ &lt;distance below baseline&gt; ] &quot;&lt;string&gt;&quot;</nobr>
<br>
<em>*Optional argument requires a <a href="definitions.html#TERMS_UNITOFMEASURE">unit of measure</a></em>
@ -383,14 +503,14 @@ no solution to the occasional problems with justified copy.
printed, looks fine. Generally, I recommend using <strong>gv</strong>
to preview files anyway. See the section on
<a href="#PREVIEWING">previewing</a>.
<br>
<p>
<!---UNDERSCORE2--->
<hr width="66%" align="left">
<a name="UNDERSCORE2"><h3><u>Double underscore</u></h3></a>
<br>
Macro: <strong>UNDERSCORE2</strong> <var>[ &lt;distance below baseline&gt; [ &lt;distance between rules&gt; ] ] &quot;&lt;string&gt;&quot;</var>
<nobr>Macro: <strong>UNDERSCORE2</strong> [ &lt;distance below baseline&gt; [ &lt;distance between rules&gt; ] ] &quot;&lt;string&gt;&quot;</nobr>
<br>
<em>*Optional arguments require a <a href="definitions.html#TERMS_UNITOFMEASURE">unit of measure</a></em>
@ -427,20 +547,20 @@ to <strong>UNDERSCORE2</strong> as to
<strong>UNDERSCORE</strong>. See the
<a href="#NOTES_UNDERSCORE">NOTES</a>
for <strong>UNDERSCORE</strong>.
<br>
<p>
<!---UNDERLINE--->
<hr width="66%" align="left">
<a name="UNDERLINE"><h3><u>Underline text -- Courier font only!</u></h3></a>
<br>
Macro: <strong>UNDERLINE</strong> <var>toggle</var>
<nobr>Macro: <strong>UNDERLINE</strong> toggle</nobr>
<p>
If your font is Courier, or you're using the document processing macro
<a href="#PRINTSTYLE">PRINTSTYLE TYPEWRITE</a>,
<strong>UNDERLINE</strong> allows you to underline words and
passages that, in typeset copy, would be italicised. You invoke
passages that, in typeset copy, would be italicized. You invoke
<strong>UNDERLINE</strong> as you do with all toggle macros --
by itself (i.e. with no argument) to initiate underlining, and
with any argument to turn underlining off.
@ -453,7 +573,7 @@ readable copy than a solid underline.
<a href="definitions.html#TERMS_INLINES">inline</a>
with the escapes
<a href="#UL">\*[UL]...\*[ULX].</a>
<br>
<p>
<!---UL--->
@ -466,7 +586,7 @@ Inline: <strong>\*[UL]...\*[ULX]</strong>
If your font is Courier, or you're using the document processing macro
<a href="#PRINTSTYLE">PRINTSTYLE TYPEWRITE</a>,
<strong>\*[UL]...\*[ULX]</strong> underlines words and
passages that, in typeset copy, would be italicised.
passages that, in typeset copy, would be italicized.
<p>
<strong>\*[UL]</strong> underlines all letters, words and numbers
following it, but not punctuation or spaces. This makes for more
@ -512,11 +632,13 @@ produces the same result as
<hr width="66%" align="left">
<a name="PAD"><h3><u>Insert space into lines</u></h3></a>
<br>
Macro: <strong>PAD</strong> <var>&quot;&lt;string with pad markers inserted&gt;&quot;</var>
<nobr>Macro: <strong>PAD</strong> &quot;&lt;string with pad markers inserted&gt;&quot; [NOBREAK]</nobr>
<p>
With <strong>PAD</strong>, you can insert unspecified amounts of
whitespace into a line.
whitespace into a line. The optional <strong>NOBREAK</strong>
argument tells <strong>mom</strong> not to advance on the page
after the <strong>PAD</strong> macro has been invoked.
<p>
<strong>PAD</strong> calculates the difference between the length of
text on the line and the distance remaining to its end, then inserts
@ -560,55 +682,50 @@ particularly useful in conjunction with
<a href="#STRING_TABS">string tabs</a>.
The following uses the Date/Signature example above, but adds
rules into the whitespace through the use of string tabs and
<strong>mom</strong>'s
<a href="definitions.html#TERMS_INLINES">inline escape</a>
<a href="inlines.html#INLINE_RULE_MOM">\*[RULE]</a>.
(Instead of <strong>\*[RULE]</strong>,
groff's line drawing function,
<a href="#INLINE_LINEDRAWING_GROFF">\l</a>.
<a href="inlines.html#INLINE_LINEDRAWING_GROFF">\l</a>
could be used.)
<p>
<pre>
.LL 30P
.PAD "Date\*[ST1]#\*[ST1X]Signature\*[ST2]###\*[ST2X]"
.EL
.PAD "Date \*[ST1]#\*[ST1X] Signature \*[ST2]###\*[ST2X]" NOBREAK
.ST 1 J
.ST 2 J
.TAB 1
\l'\n(.lu'
\*[RULE]
.TN
\l'\n(.lu'
\*[RULE]
.TQ
</pre>
If you're not a typesetter, and if you're new to groff, the
example probably looks like gibberish. My apologies. However,
remember that typesetting is a craft, and without having studied
the craft, it takes a while to grasp its concepts. Also,
although <strong>mom</strong> tries very hard to provide
consistent-looking, comprehensible alternatives to groff's
native
<a href="definitions.html#TERMS_INLINES">inline escapes</a>,
<strong>mom</strong> has not yet found a replacement for
<strong>\l</strong>.
the craft, it takes a while to grasp its concepts.
<p>
Basically, what the example does is:
<br>
<ol>
<li>Pads the Date/Signature line (using the pad marker #),
encloses the padded space with two string tabs markers,
and outputs the line
and outputs the line.
<br>
<li>Sets the two string tabs (notice the use of
<a href="#EL">EL</a>
beforehand; you don't want <strong>mom</strong>
to advance a line at this point)
to advance a line at this point).
<br>
<li>Calls the first string tab and draws a rule to its full
length (<kbd>\l'\n(.lu'</kbd>; for an easier way to draw a rule
that fills a tab, see
<a href="inlines.html#INLINE_RULE_MOM">Full measure
rules</a>).
length.
<br>
<li>Calls the second tab with
<a href="#TN">TN</a>
(which moves to tab 2 and stays on the same baseline)
then draws a rule to the full length of string tab 2
then draws a rule to the full length of string tab 2.
</ol>
<br>
Often, when setting up string tabs this way, you don't want the
@ -632,14 +749,14 @@ this is to use the groff
<strong>\(lq</strong> and <strong>\(rq</strong> (leftquote and
rightquote respectively) whenever double-quotes are required in the
string passed to <strong>PAD</strong>.
<br>
<p>
<!---PAD_MARKER--->
<hr width="66%" align="left">
<a name="PAD_MARKER"><h3><u>Change/set the marker used with PAD</u></h3></a>
<br>
Macro: <strong>PAD_MARKER</strong> <var>&lt;character to use as the pad marker&gt;</var>
<nobr>Macro: <strong>PAD_MARKER</strong> &lt;character to use as the pad marker&gt;</nobr>
<p>
If you need to change <strong>mom</strong>'s default pad marker
@ -658,7 +775,7 @@ Once you've changed the pad marker, the new marker remains in
effect for every instance of
<a href="#PAD">PAD</a>
until you change it again (say, back to the pound sign).
<br>
<p>
<!---\*[LEADER]--->
@ -714,7 +831,7 @@ with leaders. The result looks like this:
<hr width="66%" align="left">
<a name="LEADER_CHARACTER"><h3><u>Change/set the leader character</u></h3></a>
<br>
Macro: <strong>LEADER_CHARACTER</strong> <var>&lt;character&gt;</var>
<nobr>Macro: <strong>LEADER_CHARACTER</strong> &lt;character&gt;</nobr>
<p>
<strong>LEADER_CHARACTER</strong> takes one argument: a single
@ -736,7 +853,7 @@ default (a period) to the underscore character, enter
<hr width="66%" align="left">
<a name="DROPCAP"><h3><u>Drop caps</u></h3></a>
<br>
Macro: <strong>DROPCAP</strong> <var>&lt;dropcap letter&gt; &lt;number of lines to drop&gt; [ COND &lt;percentage&gt; | EXT &lt;percentage&gt; ]</var>
<nobr>Macro: <strong>DROPCAP</strong> &lt;dropcap letter&gt; &lt;number of lines to drop&gt; [ COND &lt;percentage&gt; | EXT &lt;percentage&gt; ]</nobr>
<p>
The first two arguments to <strong>DROPCAP</strong> are the letter you
@ -812,6 +929,8 @@ rest she solves with macros that change the default behaviour of
<br>
<a href="#DROPCAP_FONT">DROPCAP_FONT</a>,
<br>
<a href="#DROPCAP_COLOR">DROPCAP_COLOR</a>,
<br>
<a href="#DROPCAP_ADJUST">DROPCAP_ADJUST</a>
<br>
and
@ -862,10 +981,22 @@ e.g.
<a href="definitions.html#TERMS_PICASPOINTS">points</a>,
therefore do not append any
<a href="definitions.html#TERMS_UNITOFMEASURE">unit of measure</a>
to the argument. And always be sure to preprend the plus or
to the argument. And always be sure to prepend the plus or
minus sign, depending on whether you want the drop cap larger or
smaller.
<h3><a name="DROPCAP_COLOR"><u>DROPCAP_COLOR</u></a></h3>
If you'd like your drop cap colourized, simply invoke
<strong>DROPCAP_COLOR</strong> with the name of a colour you've already
created (&quot;initialized&quot;) with
<a href="color.html#NEWCOLOR">NEWCOLOR</a>
or
<a href="color.html#XCOLOR">XCOLOR</a>. Only the drop cap will be
colourized; all other text will remain at the current colour
default (usually black).
<h3><a name="DROPCAP_GUTTER"><u>DROPCAP_GUTTER</u></a></h3>
By default, <strong>mom</strong> puts three points of space
@ -916,7 +1047,6 @@ I'm neither a mathematician nor a chemist, so I don't need them.
Of course, anyone who wishes to contribute a subscript routine to
<strong>mom</strong> will receive eternal blessings not only in this
lifetime, but in all lifetimes to come.
<p>
<hr>
<a href="inlines.html#TOP">Next</a>&nbsp;&nbsp;

537
contrib/groff/contrib/mom/momdoc/headfootpage.html
View File

File diff suppressed because it is too large Load Diff

441
contrib/groff/contrib/mom/momdoc/inlines.html
View File

@ -1,3 +1,4 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html>
<head>
<meta http-equiv="content-type" content="text/html;charset=iso-8859-1">
@ -7,19 +8,19 @@
<!====================================================================>
<a href="docprocessing.html#TOP">Next</a>&nbsp;&nbsp;
<a href="color.html#TOP">Next</a>&nbsp;&nbsp;
<a href="goodies.html#TOP">Prev</a>&nbsp;&nbsp;
<a href="toc.html">Back to Table of Contents</a>
<a name="TOP"></a>
<h2>
<h1 align="center">
<a name="INLINE_ESCAPES"><u>Inline escapes</u></a>
</h2>
</h1>
<p>
<a href="#INLINE_ESCAPES_INTRO">Introduction to inline escapes</a>
<br>
<a href="#INDEX_INLINES">Index of inline escapes</a>
<br>
<p>
<a name="INLINE_ESCAPES_INTRO">
<h2><u>Introduction to inline escapes</u></h2>
@ -52,14 +53,14 @@ backslash character as part of a line of text, simply enter it twice
character." (You can also use <strong>\e</strong> to print a literal
backslash.)
<p>
Groff has a number of ways of recognising what constitutes a complete
Groff has a number of ways of recognizing what constitutes a complete
escape sequence. This is both a boon and a curse; some escape
sequences have no terminating delimiter and consequently become
difficult to distinguish from real input text. Others require
the use of an opening parenthesis with no corresponding closing
parenthesis. Still others need to be enclosed in square brackets.
<p>
<strong>Mom</strong> recognises that certain escapes get used more
<strong>Mom</strong> recognizes that certain escapes get used more
often than others. For these, she has a consistent input style that
takes the form \*[...], which makes them stand out well from the text
of your documents. These escapes are the ones listed under
@ -88,6 +89,8 @@ that take
<li><a href="#INLINE_KERNING_MOM">Pairwise kerning</a>
<li><a href="#INLINE_HORIZONTAL_MOM">Horizontal movement</a>
<li><a href="#INLINE_VERTICAL_MOM">Vertical movement</a>
<li><a href="#B">Terminate a line without advancing on the page</a>
<li><a href="#TB+">Call the next sequential tab without advancing on the page</a>
<li><a href="#INLINE_RULE_MOM">Full measure rules</a>
</ul>
<li><a name="INLINES_GROFF"><strong>Groff inline escapes</strong></a>
@ -100,6 +103,7 @@ that take
<li><a href="#INLINE_CHARACTERS_GROFF">Special characters</a>
</ul>
</ul>
<p>
<hr>
<!---INLINE_FONTS_MOM--->
@ -109,27 +113,43 @@ that take
<a name="INLINE_FONTS_MOM"><h3><u>Changing fonts</u></h3></a>
<p>
<strong>Mom</strong> provides five inlines to change fonts
inline.
<strong>Mom</strong> provides five escapes for changing fonts
inline:
<p>
<table valign="baseline" summary="inlinefonts">
<tr><td width="15"><td><strong>\*[ROM]</strong><td>Change font to roman
<tr><td><td><strong>\*[IT]</strong><td>Change font to italic
<tr><td><td><strong>\*[BD]</strong><td>Change font to bold
<tr><td><td><strong>\*[BDI]</strong><td>Change font to bold italic
<tr><td><td><strong>\*[PREV]</strong><td>Revert to previous font</td></tr>
<table valign="baseline" cellpadding="10" summary="inlinefonts">
<tr>
<td><strong>\*[ROM]</strong></td>
<td>Change font to medium roman</td>
</tr>
<tr>
<td><strong>\*[IT]</strong></td>
<td>Change font to medium italic</td>
</tr>
<tr>
<td><strong>\*[BD]</strong></td>
<td>Change font to bold roman</td>
</tr>
<tr>
<td><strong>\*[BDI]</strong></td>
<td>Change font to bold italic</td>
</tr>
<tr>
<td><strong>\*[PREV]</strong></td>
<td>Revert to previous font</td>
</tr>
</table>
<p>
See also
<a href="#INLINE_FONTS_GROFF">font control with \f</a>
for other ways to change fonts inline.
These escapes are provided for merely for convenience, legibility,
and consistency when typesetting with <strong>mom</strong>. For
more complete and flexible inline font control, please see
<a href="#INLINE_FONTS_GROFF">font control with \f</a>.
<p>
<strong>NOTE:</strong> If you're using the
<a href="docprocessing.html#DOCPROCESSING">document processing macros</a>,
inline font changes remain in effect only for the duration of the
current macro.
<br>
current document element tag.
<p>
<!---INLINE_SIZE_MOM--->
@ -137,42 +157,59 @@ current macro.
<a name="INLINE_SIZE_MOM"><h3><u>Changing point size</u></h3></a>
<p>
<strong>Mom</strong>'s inline escape for changing point
size, sadly, does not observe her normal inline syntax
<strong>\*[whatever]</strong>. It's the only exception, and there's
no way around it. The escape for changing point size looks like this:
<strong>Mom</strong> has two inline escapes for changing point
size:
<p>
<pre>
\*S[size]
\*[SIZE &lt;size&gt;]
</pre>
where &quot;size&quot; is the new size you want. For example, to
change the point size inline to 12 points, you'd enter
and
<p>
<pre>
\*[S&lt;size&gt;]
</pre>
where &quot;size&quot; is the new size you want. You can use
either; they behave exactly the same way. For example, to change
the point size of type inline to 12 points, you could enter either
<p>
<pre>
\*[SIZE 12]
</pre>
or
<p>
<pre>
\*S[12]
</pre>
Notice that the new size does not require a
The advantage of the first form is that it's easy to remember, and
follows <strong>mom</strong>'s usual inline syntax. The advantage
of the second is that it's more concise.
<p>
Notice that in both cases, the new size does not require a
<a href="definitions.html#TERMS_UNITOFMEASURE">unit of measure</a>;
<a href="definitions.html#TERMS_PICASPOINTS">points</a>
is assumed. However, a unit of measure may be appended to the size,
is assumed. However, a unit of measure may be appended to the size
if that's what you wish. Fractional sizes are, of course, allowed.
<p>
The size given to <strong>\*S</strong> may be expressed in plus
or minus terms, which can be very useful. In the following
example, the word &quot;mom&quot; will be output 2 points larger
than the point size of the rest of the line.
The size given to <strong>\*[SIZE&nbsp;&lt;size&gt;]</strong> or
<strong>\*S[&lt;size&gt;]</strong> may be expressed in plus or minus
terms, which can be very useful. In the following examples, the word
&quot;mom&quot; will be output 2 points larger than the point size
of the rest of the line.
<p>
<pre>
While she isn't perfect, \*S[+2]mom\*S[-2] isn't half bad.
While she isn't perfect, \*[SIZE +2]mom\*[SIZE -2] isn't half bad.
</pre>
<strong>NOTE:</strong> If you're accustomed to groff's usual way
of handling inline size requests (<kbd>\sN, \s±N, \s(NN, \s±(NN,
\s[NNN], \s±[NNN]</kbd>), feel free to continue with your old habits.
<strong>Mom</strong> doesn't care.
<br>
<p>
<!---INLINE_KERNING_MOM--->
@ -187,16 +224,20 @@ for more details).
<p>
<strong>Mom</strong> permits inline pairwise
kerning through the use of the inline escapes
<p>
<table valign="baseline" summary="inlinekerning">
<tr><td width="15"><td><strong>\*[BU #]<td></strong>Closes the space between letters (<strong>B</strong>ack <strong>U</strong>nits).
<tr><td><td><strong>\*[FU #]</strong><td>Opens the space between letters (<strong>F</strong>orward <strong>U</strong>nits).
<table valign="baseline" cellpadding="10" summary="inlinekerning">
<tr>
<td><pre>\*[BU n]</pre></td>
<td>Closes the space between letters (<strong>B</strong>ack <strong>U</strong>nits).</td>
</tr>
<tr>
<td><pre>\*[FU n]</pre></td>
<td>Opens the space between letters (<strong>F</strong>orward <strong>U</strong>nits).</td>
</tr>
</table>
<br>
"<strong>#</strong>" is the number of <a
href="definitions.html#TERMS_KERNUNIT">kern units</a>
by which to close or open the space between letters. Decimal fractions
are allowed.
&quot;<strong>n</strong>&quot; is the number of
<a href="definitions.html#TERMS_KERNUNIT">kern units</a>
by which to close or open the space between letters.
<p>
For example,
<p>
@ -210,14 +251,15 @@ to the letter W. Additionally, the letter T in "WATER" is moved 5 kern
units closer to the letter A.
<p>
For backward compatibility, the forms
<p>
<table valign="baseline" summary="inlinekerningold">
<tr><td width="15"><td><strong>\*[BU1]...\*[BU36]</strong><td>
Move back 1...36
<a href="definitions.html#TERMS_KERNUNIT">kern units</a>
<tr><td><td><strong>\*[FU1]...\*[FU36]</strong><td>
Move forward 1...36
<a href="definitions.html#TERMS_KERNUNIT">kern units</a>
<table valign="baseline" cellpadding="10" summary="inlinekerningold">
<tr>
<td><pre>\*[BU1]...\*[BU36]</pre></td>
<td>Move back 1...36 <a href="definitions.html#TERMS_KERNUNIT">kern units</a></td>
</tr>
<tr>
<td><pre>\*[FU1]...\*[FU36]</pre></td>
<td>Move forward 1...36 <a href="definitions.html#TERMS_KERNUNIT">kern units</a></td>
</tr>
</table>
<br>
also exist (i.e. with no space before the number of kern units desired,
@ -227,7 +269,7 @@ up to a limit of 36).
between characters pairs that are already automatically kerned
disables the automatic kerning and uses the value you give to
<strong>BU</strong> or <strong>FU</strong> instead.
<br>
<p>
<!---INLINE_HORIZONTAL_MOM--->
@ -245,17 +287,21 @@ line in order to create special typographic effects.
<p>
<strong>Mom</strong>'s inline escapes for these horizontal movements are
<p>
<table align="left" valign="baseline" summary="inlinehorizontal">
<table align="left" valign="baseline" cellpadding="10" summary="inlinehorizontal">
<tr>
<a name="FWD"></a>
<tr><td width="15"><td width="20%"><strong>\*[FWD #&lt;unit&gt;]
<td>Move forward inline the specified number of
<a href="definitions.html#TERMS_UNITOFMEASURE">units of measure</a>;
decimal fractions are allowed.
<td><pre>\*[FWD n&lt;unit&gt;]</pre></td>
<td width="80%">Move forward inline the specified number of
<a href="definitions.html#TERMS_UNITOFMEASURE">units of measure</a>;
decimal fractions are allowed.</td>
</tr>
<tr>
<a name="BCK"></a>
<tr><td><td><strong>\*[BCK #&lt;unit&gt;]
<td>Move backward inline the specified number of
<a href="definitions.html#TERMS_UNITOFMEASURE">units of measure</a>;
decimal fractions are allowed.
<td><pre>\*[BCK n&lt;unit&gt;]</pre></td>
<td width="80%">Move backward inline the specified number of
<a href="definitions.html#TERMS_UNITOFMEASURE">units of measure</a>;
decimal fractions are allowed.</td>
</tr>
</table>
<p>
For example,
@ -268,9 +314,15 @@ puts 12 points of space between &quot;1.&quot; and
<p>
<strong>NOTE:</strong> For backward compatibility, the forms
<p>
<table valign="baseline" summary="inlinehorizontalold">
<tr><td width="15"><td><strong>\*[BP.25]...\*[BP12.75]</strong><td>Move back .25...12.75 points
<tr><td><td><strong>\*[FP.25]...\*[FP12.75]</strong><td>Move forward .25...12.75 points</td></tr>
<table valign="baseline" cellpadding="10" summary="inlinehorizontalold">
<tr>
<td><pre>\*[BP.25]...\*[BP12.75]</pre></td>
<td>Move back .25...12.75 points</td>
</tr>
<tr>
<td><pre>\*[FP.25]...\*[FP12.75]</pre></td>
<td>Move forward .25...12.75 points</td>
</tr>
</table>
<br>
also exist (i.e. with no space before the digit and points being
@ -278,7 +330,7 @@ the unit of measure, hence no unit of measure required). Both
accept quarter points, so it's possible to do, for example,
<strong>\*[FP.5]</strong> or <strong>\*[BP1.25]</strong> up to a limit
of 12.75 points.
<br>
<p>
<!---INLINE_VERTICAL_MOM--->
@ -289,15 +341,19 @@ of 12.75 points.
If you need to move portions of type up or down on a line,
<strong>mom</strong> provides the following inline escapes:
<p>
<table valign="baseline" summary="inlinevertical">
<table width="80%" valign="baseline" cellpadding="10" summary="inlinevertical">
<tr>
<a name="UP"></a>
<tr><td width="15"><td><strong>\*[UP #&lt;unit&gt;]</strong>
<td>Move up inline the specified number of
<a href="definitions.html#TERMS_UNITOFMEASURE">units of measure</a>
<td><pre>\*[UP n&lt;unit&gt;]</pre></td>
<td>Move up inline the specified number of
<a href="definitions.html#TERMS_UNITOFMEASURE">units of measure</a></td>
</tr>
<tr>
<a name="DOWN"></a>
<tr><td><td><strong>\*[DOWN #&lt;unit&gt;]</strong>
<td>Move down inline the specified number of
<a href="definitions.html#TERMS_UNITOFMEASURE">units of measure</a>
<td><pre>\*[DOWN n&lt;unit&gt;]</pre></td>
<td>Move down inline the specified number of
<a href="definitions.html#TERMS_UNITOFMEASURE">units of measure</a></td>
</tr>
</table>
<br>
For example,
@ -309,20 +365,95 @@ For example,
moves the hyphen in the telephone number up by 1 point, then
moves back down by the same amount.
<p>
<strong>NOTE:</strong> For backward compatibility, the following are
also available:
<strong>NOTE: \*[UP]</strong> and <strong>\*[DOWN]</strong> do not
work with the inline escape,
<a href="#INLINE_RULE_MOM">\*[RULE]</a>.
See
<a href="#RULE_EXCEPTION">here</a>
for details.
<p>
<table valign="baseline" summary="inlinevertical">
<tr><td width="15"><td><strong>\*[ALD.25]...\*[ALD12.75]</strong><td>
Advance lead .25...12.75 points (move downward)
<tr><td><td><strong>\*[RLD.25]...\*[RLD12.75]</strong><td>
Reverse lead .5...12.75 points (move upward)</td></tr>
<strong>ADDITIONAL NOTE:</strong> For backward compatibility, the
following are also available:
<p>
<table valign="baseline" cellpadding="10" summary="inlinevertical">
<tr>
<td><pre>\*[ALD.25]...\*[ALD12.75]</pre>
<td>Advance lead .25...12.75 points (move downward)
</tr>
<tr>
<td><pre>\*[RLD.25]...\*[RLD12.75]</pre></td>
<td>Reverse lead .5...12.75 points (move upward)</td>
</tr>
</table>
<p>
<p>
Both <strong>\*[ALD]</strong> and <strong>\*[RLD]</strong> work in
points, hence you musn't use a unit of measure.
<br>
points, hence you mustn't use a unit of measure.
<p>
<!---INLINE_B_MOM--->
<hr width="66%" align="left">
<a name="B"><h3><u>Terminate a line without advancing on the page</u></h3></a>
<p>
Sometimes, you want <strong>mom</strong> to break a line but not
advance on the page. See
<a href="typesetting.html#EL_EXAMPLE">here</a>
for an example of when you might want to do this.
<p>
In versions of <strong>mom</strong> prior to 1.2-f, this was
accomplished through the use of
<a href="typesetting.html#EL">EL</a>.
As of 1.2-f, you can, if you prefer, accomplish the same thing
by using the inline escape, <strong>\*[B]</strong>. Simply
attach the escape to the end of any line. Using the example
given in the document entry for <strong>EL</strong>, you'd use
<strong>\*[B]</strong> like this:
<p>
<pre>
.LEFT
.LS 12.5
A line of text.\*[B]
.ALD 24p
The next line of text.
</pre>
<strong>\*[B]</strong> works reliably regardless of the current
<a href="definitions.html#TERMS_FILLED">fill mode</a>.
<p>
<!---INLINE_TB+_MOM--->
<hr width="66%" align="left">
<a name="TB+"><h3><u>Call the next sequential tab without advancing on the page</u></h3></a>
<p>
Sometimes, you want <strong>mom</strong> to move to the next tab in
sequence (e.g. from TAB 1 to TAB 2, or TAB 8 to TAB 9) without
<strong>mom</strong> advancing on the page. (See the example in
<a href="typesetting.html#NOTE_TN">here</a>
if you're not clear how <strong>mom</strong> manages tabs and
linebreaks.)
<p>
In versions of <strong>mom</strong> prior to 1.2-f, this was
accomplished through the use of
<a href="typesetting.html#TN">TN</a>.
As of 1.2-f, you can, if you prefer, accomplish the same thing
by using the inline escape, <strong>\*[TB+]</strong>. Simply
attach the escape to the end of any line in a tab, like this:
<p>
<pre>
.TAB 1
Some text\*[TB+] \" This line is in tab 1
Some more text \" This line is in tab 2, on the same baseline as tab 1
</pre>
<strong>\*[TB+]</strong> works reliably regardless of the current
<a href="definitions.html#TERMS_FILLED">fill mode</a>.
<p>
<!---INLINE_RULE_MOM--->
@ -344,10 +475,28 @@ example:
</pre>
The above draws a rule the full measure of the 6-pica line length.
Please note that <strong>\*[$RULE]</strong> should appear on a line by
itself and that it draws the rule to the full measure, hence it
<em>cannot</em> be used to fill the remainder of a partial line with
a rule in this way:
<p>
<strong>\*[RULE]</strong> should appear on a line by itself. In
<a href="definitions.html#TERMS_FILLED">fill modes</a>,
(i.e.
<a href="typesetting.html#QUAD">QUAD</a>
or
<a href="typesetting.html#JUSTIFY">JUSTIFY</a>),
it requires a
<a href="typesetting.html#BR">.BR</a>
on the line immediately before it; otherwise, the rule will be drawn
on the same baseline occupied by any type preceding it. In
<a href="definitions.html#TERMS_NOFILL">nofill modes</a>
(i.e
<a href="typesetting.html#LRC">LEFT</a>,
<a href="typesetting.html#LRC">RIGHT</a>
or
<a href="typesetting.html#LRC">CENTER</a>),
the <strong>.BR</strong> is not required.
<p>
Please note that <strong>\*[RULE]</strong> draws the rule to the
full measure, hence it <em>cannot</em> be used to fill the remainder
of a partial line with a rule in this way:
<p>
<pre>
Signature__________________________________________
@ -358,13 +507,34 @@ If you wish to accomplish this effect, you have to use
<a href="goodies.html#PAD"><strong>PAD</strong></a>
macro and
<a href="typesetting.html#STRING_TABS">string tabs</a>.
(See the example provided with
<a href="goodies.html#PAD_EXAMPLE"><strong>.PAD</strong></a>.
(See the
<a href="goodies.html#PAD_EXAMPLE">example</a>
provided with <strong>PAD</strong>.)
<a name="RULE_EXCEPTION"></a>
<p>
Please also note that the inline escapes
<a href="#UP">\*[UP]</a>
and
<a href="#DOWN">\*[DOWN]</a>
cannot be used in conjunction with <strong>\*[RULE]</strong>. This
doesn't work:
<p>
<pre>
\*[DOWN 2p]\*[RULE]\*[UP 2p]
</pre>
This does:
<p>
<pre>
.ALD 2p
\*[RULE]
.RLD 2p
</pre>
See groff's
<a href="#INLINE_LINEDRAWING_GROFF">Horizontal line drawing function</a>
for more information on drawing horizontal rules.
<br>
<p>
<hr>
<!---INLINE_FONT_GROFF--->
@ -375,33 +545,52 @@ for more information on drawing horizontal rules.
<p>
Groff's basic mechanism for inline font control is the escape
<strong>\f</strong>.
<strong>\f[&lt;</strong>font&gt;<strong>]</strong>.
<p>
<table valign="baseline" summary="inlinefontsgroff">
<tr><td width="15"><td><strong>\fR</strong><td>Change font to roman
<tr><td><td><strong>\fI</strong><td>Change font to italic
<tr><td><td><strong>\fB</strong><td>Change font to bold
<tr><td><td><strong>\f(BI</strong><td>Change font to bold italic
<tr><td><td><strong>\fP</strong><td>Revert to previous font</td></tr>
<table valign="baseline" cellpadding="10" summary="inlinefontsgroff">
<tr>
<td><strong>\f[R]</strong></td>
<td>Change font to medium roman (equivalent to mom's <strong>\*[ROM]</strong>)</td>
</tr>
<tr>
<td><strong>\f[I]</strong></td>
<td>Change font to medium italic (equivalent to mom's <strong>\*[IT]</strong>)</td>
</tr>
<tr>
<td><strong>\f[B]</strong></td>
<td>Change font to bold roman (equivalent to mom's <strong>\*[BD]</strong>)</td>
</tr>
<tr>
<td><strong>\f[BI]</strong></td>
<td>Change font to bold italic (equivalent to mom's <strong>\*[BDI]</strong>)</td>
</tr>
<tr>
<td><strong>\f[P]</strong></td>
<td>Revert to previous font (equivalent to mom's <strong>\*[PREV]</strong>)</td>
</tr>
</table>
<p>
A special instance of <strong>\f</strong> is
<strong>\f[font]</strong>, where &quot;font&quot; can be a
complete legal family/font name combo. This is especially
useful should you need to change both family and font inline.
For example, if your prevailing family and font are Times Roman
and you want a few words in Courier Bold Italic, you could do
this:
<strong>\f[&lt;</strong>font&gt;<strong>]</strong> can be used with
any legal font style registered with groff. (See
<a href="appendices.html#STYLE_EXTENSIONS">here</a>
for a list of pre-registered font styles provided by
<strong>mom</strong>).
<p>
<strong>\f[&lt;</strong>font&gt;<strong>]</strong> can also take a
complete legal family+font name combo. This is especially useful
should you need to change both family and font inline. For example,
if your prevailing family and font are Times Roman and you want a
few words in Courier Bold Italic, you could do this:
<p>
<pre>
.FAM T
.FT R
The command \f[CBI]ls -l\fP gives a &quot;long&quot; directory listing.
The command \f[CBI]ls -l\f[P] gives a &quot;long&quot; directory listing.
</pre>
The Unix command &quot;ls -l&quot; will appear in Courier Bold Italic
in a line that is otherwise in Times Roman.
<br>
<p>
<!---INLINE_HORIZONTAL_GROFF--->
@ -423,7 +612,7 @@ moves you 1.25 inches to the right (forwards) of the horizontal
position on the current
<a href="definitions.html#TERMS_OUTPUTLINE">output line</a>.
<strong>\h'&lt;distance&gt;'</strong> is exactly equivalent to
<a href="#FWD"><strong>\*[FWD #&lt;unit&gt;]</strong></a>.
<a href="#FWD"><strong>\*[FWD n&lt;unit&gt;]</strong></a>.
<p>
<pre>
\h'-1.25i'
@ -431,8 +620,8 @@ position on the current
moves you 1.25 inches to the left (backwards).
<strong>\h'-&lt;distance&gt;'</strong> is exactly equivalent to
<a href="#BCK"><strong>\*[BCK #&lt;unit&gt;]</strong></a>.
<br>
<a href="#BCK"><strong>\*[BCK n&lt;unit&gt;]</strong></a>.
<p>
<!---INLINE_VERTICAL_GROFF--->
@ -456,7 +645,7 @@ moves you (approx.) 2/3 of an
downward on the current
<a href="definitions.html#TERMS_OUTPUTLINE">output line</a>.
<strong>\v'&lt;distance&gt;'</strong> is exactly equivalent to
<a href="#DOWN"><strong>\*[DOWN #&lt;unit&gt;]</strong></a>.
<a href="#DOWN"><strong>\*[DOWN n&lt;unit&gt;]</strong></a>.
<p>
<pre>
\v'-.6m'
@ -464,7 +653,7 @@ downward on the current
moves you (approx.) 2/3 of an em upward.
<strong>\v'&lt;-distance&gt;'</strong> is exactly equivalent to <a
href="#UP"><strong>\*[UP #&lt;unit&gt;]</strong></a>.
href="#UP"><strong>\*[UP n&lt;unit&gt;]</strong></a>.
<p>
<strong>IMPORTANT:</strong> The vertical motion of <strong>\v</strong>
affects ONLY type on the current
@ -479,7 +668,7 @@ you've done what you want to do. Otherwise, the remaining type
will be set too high (if you used <strong>\v</strong> with the
minus sign) or too low (if you used <strong>\v</strong> without
the minus sign).
<br>
<p>
<!---INLINE_STRINGWIDTHL_GROFF--->
@ -507,7 +696,7 @@ argument.</em>
Furthermore, if the string is composed of several words separated
by spaces, you MUST surround the whole escape with double quotes,
as in the example above.
<br>
<p>
<!---INLINE_LINEDRAWING_GROFF--->
@ -543,15 +732,16 @@ a number of other line-drawing escapes, but frankly, using them for
typographically precise drawing is a bit like hammering in a nail
with a screwdriver -- doable, but not recommended.
<p>
Groff comes with a number of &quot;preprocessors&quot; designed to ease
creating rules, boxes, splines, and so on (tbl, pic, and friends), but
I tend not to use them. A firm believer in the &quot;right tool for
the job,&quot; I prefer a vector drawing program (in my case, tgif)
when I need to combine type with graphic elements (say, a complex
ruled form). Inserting the results into a document is easy enough
with <strong>.PSPIC</strong> (consult the <strong>grops</strong>
man page for information on this indispensible and easy-to-use macro).
<br>
Groff comes with a number of &quot;preprocessors&quot; designed
to ease creating rules, boxes, splines, and so on (tbl, pic,
and friends), but I tend not to use them. A firm believer
in the &quot;right tool for the job,&quot; I prefer a vector
drawing program when I need to combine type with graphic elements
(say, a complex ruled form). Inserting the results into a
document is easy enough with <strong>.PSPIC</strong> (consult
the <strong>groff_tmac</strong> man page for information on this
indispensable and easy-to-use macro).
<p>
<!---INLINE_CHARACTERS_GROFF--->
@ -563,11 +753,12 @@ Here follows a short list of commonly-used special characters available
via inline escapes. If you're not sure of the meaning of some of
these characters, consult the
<a href="definitions.html#TERMS">Definitions of Terms</a>.
For a more complete list, consult the section <em>Special
Character Names</em> at the end of the <em>Tutorial Examples</em>
in <strong>cstr54</strong>, available
<a href="http://www.kohala.com/start/troff/">here</a>.
<p>
For a complete list of special characters and glyphs (i.e. just
about anything you'd ever want to appear on the printed page,
including mathematical symbols, accented characters, unusual
ligatures and letters unique to various European languages), consult
<kbd>man groff_char</kbd>.
<p>
<pre>
CHARACTER ESCAPE SEQUENCE
@ -603,7 +794,7 @@ in <strong>cstr54</strong>, available
</pre>
<hr>
<a href="docprocessing.html#TOP">Next</a>&nbsp;&nbsp;
<a href="color.html#TOP">Next</a>&nbsp;&nbsp;
<a href="goodies.html#TOP">Prev</a>&nbsp;&nbsp;
<a href="#TOP">Top</a>&nbsp;&nbsp;
<a href="toc.html">Back to Table of Contents</a>

121
contrib/groff/contrib/mom/momdoc/intro.html
View File

@ -1,3 +1,4 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html>
<head>
<meta http-equiv="content-type" content="text/html;charset=iso-8859-1">
@ -25,6 +26,8 @@
<br>
<a href="#INTRO_DOCUMENTATION">A note on mom's documentation</a>
<br>
<a href="#CANONICAL">Canonical reference materials</a>
<br>
<a href="#MACRO_ARGS">How to read macro arguments</a>
<h2><a name="INTRO_INTRO"><u>Who is mom meant for?</u></a></h2>
@ -50,7 +53,7 @@ She's aimed at three kinds of users:
started.
</ol>
<p>
As might be infered from the above, <strong>mom</strong> is two macro
As might be inferred from the above, <strong>mom</strong> is two macro
packages in one: a set of typesetting macros, and a set of document
processing macros. The typesetting macros govern the physical
aspects of page layout and provide sane, comprehensible control over
@ -61,7 +64,7 @@ typesetting or page layout at all.
Because <strong>mom</strong> provides both typesetting and document
processing macros, it's safe to say she blurs the distinction between
document processing and document design. While her basic document style
comes with pretty spiffy defaults (okay -- change &quot;spiffy&quot;
comes with pretty spiffy defaults (okay--change &quot;spiffy&quot;
to &quot;typographically professional&quot;), you can easily control
how all the various document elements look: titles, page headers and
footers, page numbering, heads, subheads, footnotes and so on can be
@ -72,6 +75,7 @@ read up on groff
<a href="definitions.html#TERMS_PRIMITIVES">primitives</a>
in order to accomplish what you want; the typesetting macros take
care of that.
<p>
<a name="INTRO_TYPESETTING">
<h2><u>Typesetting with mom</u></h2>
@ -101,13 +105,12 @@ want document processing (via the
<a href="docprocessing.html#START">START</a>
macro; see below), every macro is a literal command that remains in
effect until you modify it or turn it off. This means that if you
want to create flyers, document covers, surveys, tabulated forms,
curricula vitae and so on, you may do so in the good old-fashioned
way: one step at a time with complete control over every element on
the page.
want to create flyers, surveys, tabulated forms, curricula vitae and
so on, you may do so in the good old-fashioned way: one step at a
time with complete control over every element on the page.
<p>
Years of reading various mailing lists dealing with computer
typesetting (groff, TeX, and friends) have convinced me that no progam
typesetting (groff, TeX, and friends) have convinced me that no program
can ever replace the human eye and human input when it comes to high
quality typesetting. As of this writing, a thread on the subject of
&quot;micro typography&quot; in groff has been going on for nearly a
@ -117,26 +120,25 @@ rendered flawlessly by any algorithm, no matter how clever. (For
whatever it's worth, a similar problem exists with engraving musical
scores by computer.)
<p>
<strong>Mom</strong> does not try to solve the problems posed by
things like hanging punctuation, left-margin adjustments for those
annoying &quot;space-y&quot; upper case letters like T and W, and
so on. She merely tries to provide tools that allow knowledgeable
typesetters to come up with solutions to these problems
in ways that are somewhat easier and more intuitive than manipulating
groff at the
<a href="definitions.html#TERMS_PRIMITIVES">primtive</a>
<strong>Mom</strong> does not try to solve the problems posed
by things like hanging punctuation, left-margin adjustments for
upper case letters like T and W, and so on. She merely tries to
provide tools that allow knowledgeable typesetters to come up with
solutions to these problems in ways that are easier and more
intuitive than manipulating groff at the
<a href="definitions.html#TERMS_PRIMITIVES">primitive</a>
level. As a professional typesetter of more than two decades, and a
writer, I have encountered few situations that cannot be handled by
<strong>mom</strong>'s typesetting macros.
<p>
<strong>Author's note:</strong> One area where groff itself needs
serious rethinking is in the matter of an algorithm that takes into
account both word AND letter spacing when
account both word and letter spacing when
<a href="definitions.html#TERMS_JUST">justifying</a>
lines. At present, only word spacing is adjusted, requiring what I
consider an unnecessary amount of user intervention whenever
letter spacing is required.
<p>
<a name="INTRO_DOCPROCESSING">
<h2><u>Document processing with mom</u></h2>
</a>
@ -149,7 +151,7 @@ differs is in the degree of control you have over the look and
placement of the various elements of a document. For example, if you
don't want your heads underlined, or you want them bigger/smaller,
or you'd prefer them to be in a different font, or you'd rather they
were flush left instead of centered, you can make the changes easily
were flush left instead of centred, you can make the changes easily
and have them apply to the whole document. Temporary and one-off
changes are easy, too.
<p>
@ -157,13 +159,13 @@ changes are easy, too.
don't provide. For example, you can switch between draft-style and
final-copy output. If you regularly make submissions to publishers
and editors who insist on "typewritten, double-spaced," there's a
special macro --
special macro--
<a href="docprocessing.html#PRINTSTYLE">PRINTSTYLE TYPEWRITE</a>
-- that changes typeset documents into ones that would make your
high-school typing teacher proud. Footnotes, multiple columns,
recto/verso printing and user designable headers and footers are also
part of the fun.
--that changes typeset documents into ones that would make your
high-school typing teacher proud. Footnotes, endnotes, tables of
contents, multiple columns, nested lists, recto/verso printing and
user designable headers and footers are also part of the fun.
<p>
<a name="INTRO_PHILOSOPHY">
<h2><u>Mom's philosophy</u></h2>
</a>
@ -194,8 +196,9 @@ for their special typesetting needs. Not to put too fine a point on
it, groff primitives tend toward the abstruse, and most inline escapes
are about as readable in-line as an encrypted password. This does
not make for happy-camper writers, who either find themselves stuck
with document formatting style they don't really like, or are forced to
learn groff from the ground up -- a daunting task, to say the least.
with a document formatting style they don't really like, or are
forced to learn groff from the ground up--a daunting task, to say
the least.
<p>
<strong>Mom</strong> aims to make creating documents a simple matter,
but with no corresponding loss of user control. The document
@ -220,8 +223,7 @@ produce output that looks good no matter where it's displayed.
She's designed for printed output, although with
<a href="#PRINTSTYLE">PRINTSTYLE TYPEWRITE</a>
she produces acceptable terminal copy. She makes no attempt to be
compatible with older versions of troff. And she remains largely
untested with the groff preprocessors (tbl, pic, eqn, etc.)
compatible with older versions of troff.
<p>
One special feature in <strong>mom</strong>'s design is the attention
she pays to aligning the bottom margins of every page. Nothing screams
@ -233,7 +235,7 @@ bottom of the page without some text underneath it), but in all cases
where hanging bottom margins can be avoided, <strong>mom</strong> does
avoid them, by clever adjustments to leading (&quot;line spacing&quot;)
and the spacing between different elements on the page.
<p>
<a name="INTRO_DOCUMENTATION">
<h2><u>A note on mom's documentation</u></h2>
</a>
@ -249,40 +251,54 @@ that gets tossed.
<strong>Mom</strong>'s documentation assumes users know their way
around GNU/Linux. It further assumes they at least know what groff
is, even if they don't know much about it. Lastly, it assumes that
everyone -- groff newbies and experts alike -- learns faster from
everyone--groff newbies and experts alike--learns faster from
a few well-placed examples than from manpage-style reference docs.
What <strong>mom</strong>'s documentation doesn't assume is that
you know everything -- not about groff, not about typesetting,
you know everything--not about groff, not about typesetting,
not about document processing. Even experts have odd lacunae in
their knowledge base. Therefore, whenever I suspect that a term
or procedure will cause head scratching, I offer an explanation.
And when explanations aren't enough, I offer examples.
<a name="CANONICAL"></a>
<br>
<a name="CANONICAL"><h3><u>Canonical reference materials</u></h3></a>
<p>
The canonical reference materials for groff are <strong>cstr54</strong>
(a downloadable PostScript copy of which is available
The canonical reference materials for groff are
<strong>cstr54</strong> (a downloadable PostScript copy of which is
available
<a href="http://www.kohala.com/start/troff/">here</a>)
and the <strong>troff</strong> and <strong>groff_diff</strong> manpages.
I've tried to avoid reiterating them, however, in a few places, this has
proved impossible. Be forewarned: I have no qualms about sidestepping
excrutiating completeness about groff usage; I'm more concerned with
getting <strong>mom</strong> users up and running. <em>Mea culpa.</em>
and the <strong>troff</strong> and <strong>groff_diff</strong>
manpages. Another excellent source of information (maybe the best)
is the groff <strong>info</strong> pages, available by typing
<p>
<pre>
info groff
</pre>
at the command line (assuming you have <strong>info</strong>
installed on your system). And for inputting special characters,
see <strong>man groff_char.</strong>
<p>
I've tried to avoid reiterating the information contained in these
documents; however, in a few places, this has proved impossible.
But be forewarned: I have no qualms about sidestepping excruciating
completeness concerning groff usage; I'm more interested in getting
<strong>mom</strong> users up and running. <em>Mea culpa.</em>
<p>
<strong>Note:</strong> <strong>Mom</strong>'s macro file
(om.tmac) is heavily commented. Each macro is preceded by a
description of its arguments, function, and usage, which may
description of its arguments, function and usage, which may
give you information in addition to what's contained in this
documentation.
<p>
<a name="MACRO_ARGS">
<h3><u>How to read macro arguments</u></h3>
</a>
<p>
The concise descriptions of macros in this documentation typically
look like this:
<blockquote>
Macro: <strong>NAME</strong> <var>arguments</var>
Macro: <strong>NAME</strong> <nobr>arguments</nobr>
</blockquote>
<var>arguments</var> lists the macro's arguments using conventions that
should be familiar to anyone who has ever read a manpage. Briefly:
@ -299,7 +315,7 @@ should be familiar to anyone who has ever read a manpage. Briefly:
which means &quot;or.&quot;
<li>Arguments that are optional are surrounded by square brackets.
<li>&lt;off&gt; in an argument list means that any argument
turns the macro off.
other than those in the argument list turns the macro off.
</ol>
<a name="TOGGLE_MACRO"><h3><u>Toggle macros</u></h3></a>
@ -313,14 +329,16 @@ it could even be I_LOVE_MOM.
Since these macros toggle things on and off, the argument list
simply reads
<blockquote>
<var>toggle</var>
<nobr>toggle</nobr>
</blockquote>
<br>
<hr>
<h3>Example 1: an argument requiring double-quotes</h3>
<blockquote>
Macro: <strong>TITLE</strong> <var>&quot;&lt;title of document&gt;&quot;</var>
Macro: <strong>TITLE</strong> <nobr>&quot;&lt;title of document&gt;&quot;</nobr>
</blockquote>
<p>
The required argument to <strong>TITLE</strong> is the title of your
document. Since it's surrounded by double-quotes, you must
include them in the argument, like this:
@ -331,8 +349,9 @@ include them in the argument, like this:
<h3>Example 2: a macro with required and optional arguments</h3>
<blockquote>
Macro: <strong>TAB_SET</strong> <var>&lt;tab #&gt; &lt;indent&gt; &lt;length&gt; [ L | R | C | J [ QUAD ] ]</var>
Macro: <strong>TAB_SET</strong> <nobr>&lt;tab #&gt; &lt;indent&gt; &lt;length&gt; [ L | R | C | J [ QUAD ] ]</nobr>
</blockquote>
<p>
The first required argument is a number that identifies the tab (say,
"3"). The second required argument is an indent from the left margin
(say, 6 picas). The third required argument is the length of the tab
@ -355,12 +374,12 @@ you could enter:
.TAB_SET 3 6P 3P L QUAD
</pre>
<a name="TOGGLE_EXAMPLE"><h3>Example 3: a sample toggle macro:</h3></a>
<a name="TOGGLE_EXAMPLE"></a>
<h3>Example 3: a sample toggle macro:</h3>
<blockquote>
Macro: <strong>QUOTE</strong> <var>toggle</var>
Macro: <strong>QUOTE</strong> <nobr>toggle</nobr>
</blockquote>
<p>
<strong>QUOTE</strong> begins a section of quoted text in a document
and doesn't require an argument. When the quote's finished,
you have to tell <strong>mom</strong> it's done.

215
contrib/groff/contrib/mom/momdoc/letters.html
View File

@ -1,3 +1,4 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html>
<head>
<meta http-equiv="content-type" content="text/html;charset=iso-8859-1">
@ -7,9 +8,10 @@
<!====================================================================>
<a href="typemacdoc.html#TOP">Next</a>&nbsp;&nbsp;
<a href="cover.html#TOP">Prev</a>&nbsp;&nbsp;
<a href="macrolist.html#TOP">Next</a>&nbsp;&nbsp;
<a href="refer.html#TOP">Prev</a>&nbsp;&nbsp;
<a href="toc.html">Back to Table of Contents</a>
<p>
<a name="TOP"></a>
<a name="LETTERS">
@ -33,11 +35,11 @@ to design correspondence to your own specifications. However,
flexibility in the matter of letters, which are, after all, simple
communicative documents whose only real style requirements are that
they be neat and professional-looking.
<p>
<a name="TUTORIAL"><h2><u>Tutorial on writing letters</u></h2></a>
<strong>Mom</strong> letters begin, like all <strong>mom</strong>
processed documents, with a
<p>
<strong>Mom</strong> letters begin, like all
<strong>mom</strong>-processed documents, with a
<a href="docprocessing.html#REFERENCE_MACROS">reference macro</a>
(in this case,
<a href="docprocessing.html#AUTHOR">AUTHOR</a>),
@ -46,7 +48,8 @@ a
(<strong>LETTER</strong>, obviously), the essential
<a href="docprocessing.html#PRINTSTYLE">PRINTSTYLE</a>
macro, and
<a href="docprocessing.html#START">START</a>.
<a href="docprocessing.html#START">START</a>,
like this:
<p>
<pre>
.AUTHOR "Yannick P. Guique"
@ -58,30 +61,40 @@ macro, and
<strong>PRINTSTYLE</strong>, above, could also be
<strong>TYPEWRITE</strong>. <strong>Mom</strong> has no objection
to creating letters that look like they were typed on an Underwood
by a shapely secretary with great gams back in the 1940s.
by a shapely secretary with 1940s gams.
<p>
After the <strong>START</strong> macro, you enter data pertinent to
After the <strong>START</strong> macro, you enter headers pertinent to
your letter: the date, the addressee (in business correspondence,
typically both name and address), the addressor (that's you; in
typically both name and address), the addresser (that's you; in
business correspondence, typically both name and address), and a
greeting (in full, e.g. &quot;Dear Mr. Smith,&quot;).
greeting (in full, e.g. &quot;Dear Mr. Smith,&quot; or &quot;Dear
Mr. Smith:&quot;).
<p>
The macros for entering the data are simple (they're not even
<a href="definitions.html#TERMS_TOGGLE">toggles</a>)
and entered in an intuitive order.
<br>
<ol>
<li><code>.DATE</code>
<li><code>.TO</code>
<li><code>.FROM</code>
<li><code>.GREETING</code>
</ol>
The macros for entering the headers are simple (they're not even
<a href="definitions.html#TERMS_TOGGLE">toggles</a>):
<p>
<strong>Mom</strong> ignores any you omit and spaces the letter's
opening according to what you do include.
<pre>
.DATE
.TO
.FROM
.GREETING
</pre>
You may enter them in any order you like, except for
<strong>GREETING</strong>, which must come last.
<strong>Mom</strong> ignores any headers you omit and spaces the
letter's opening according to what you do include. See
<a href="#LETTERS_DEFAULTS">Default for letters</a>
to find out how <strong>mom</strong> formats the headers.
<p>
(In pre 1.1.7-a releases of <strong>mom</strong>, the order
of entry was fixed at the above. This has been changed, although
if you do follow the above order, <strong>mom</strong> will
continue to behave exactly as she did in pre 1.1.7-a.)
<p>
Once you've filled in what you need to get a letter started, simply
type the letter, introducing each and every paragraph with the
type the letter, introducing each and every paragraph, including
the first, with the
<a href="docelement.html#PP">PP</a>
macro.
<p>
@ -132,19 +145,79 @@ here's what the complete letter looks like.
.CLOSING
Sincerely,
</pre>
This produces a letter with headers that follow the North American
standard for business correspondence. If you'd prefer another
style of correspondence, for example, British, you'd set up the
same letter like this:
<p>
<pre>
.AUTHOR "Yannick P. Guique"
.DOCTYPE LETTER
.PRINTSTYLE TYPESET
.START
.FROM
.RIGHT
Y.P. GUIQUE
022 Umask Road
St-Sauveur-en-dehors-de-la-mappe, Québec
.TO
GUILLAUME BARRIÈRES
Minidoux Corporation
5000 Pannes Drive
Redmond, Virginia
.DATE
.RIGHT
August 25, 2004
.GREETING
Dear Mr. Barrières,
</pre>
Notice the use of <strong>.RIGHT</strong> after
<strong>.FROM</strong> and <strong>.DATE</strong> in this example,
used to change the default quad for these macros.
<p>
<hr>
<a name="LETTERS_DEFAULTS">
<h2><u>Defaults for letters</u></h2>
</a>
In letters, <strong>mom</strong> sets:
In letters, if the order of header macros is
<p>
<pre>
.DATE
.TO
.FROM
.GREETING
</pre>
<strong>mom</strong> sets
<br>
<ol>
<li>the date flush right, page right, at the top of page one
<li>the addressee in a block flush left, page left
<li>the addressor in a block flush left, page left
<li>the greeting flush left
<li>the date flush right, page right, at the top of page one,
with a gap of two linespaces underneath
<li>the addressee in a block flush left, page left, with a gap of
one linespace underneath
<li>the addresser in a block flush left, page left, with a gap of
one linespace underneath
<li>the greeting flush left, with a gap of one linespace
underneath
</ol>
<p>
which is the standard for North American business correspondence.
<p>
If you switch the order of <strong>.DATE</strong>,
<strong>.TO</strong> and/or <strong>.FROM</strong>,
<strong>mom</strong> sets all the headers flush left, with a gap of
one linespace underneath each. (The default left quad of any header
can be changed by invoking the <strong>.RIGHT</strong> macro, on
a line by itself, immediately before inputting the text of the
header.)
<p>
Following the headers, <strong>mom</strong> sets
<p>
<ul>
<li>the body of the letter justified
<li>in multi-page letters:
<ul>
@ -152,7 +225,7 @@ In letters, <strong>mom</strong> sets:
<li>the page number at the top of every page after page one
</ul>
<li>the closing/signature line flush left, indented halfway across the page
</ol>
</ul>
<p>
Other important style defaults are listed below, and may be changed
via the
@ -185,7 +258,7 @@ Spaced paragraphs yes no
Footers* yes yes
Footer margin 3 picas 3 picas
Footer gap 3 picas 3 picas
Page numbers top, centered top, centered
Page numbers top, centred top, centred
*Footers contain a &quot;next page&quot; number of the form .../#
</pre>
@ -207,6 +280,7 @@ except <strong>NO_SUITE</strong>.
<li><a href="#CLOSING">CLOSING</a>
<li><a href="#NO_SUITE">NO_SUITE</a> -- &quot;next page&quot; number off
</ul>
<br>
<!---DATE--->
@ -224,6 +298,29 @@ underneath, like this:
October 31, 2002
</pre>
If you wish to change the default quad direction for the date,
enter <kbd>.LEFT</kbd> or <kbd>.RIGHT</kbd>, on a line by itself,
immediately after <kbd>.DATE</kbd>.
<p>
If you wish to insert additional space between the date and any
letter header that comes after it, do so after inputting the date,
not at the top of the next header macro, like this:
<p>
<pre>
.DATE
October 31, 2002
.SPACE \" Or, more simply, .SP
</pre>
If you wish to remove the default space,
<p>
<pre>
.SPACE -1v \" Or, more simply, .SP -1v
</pre>
will do the trick.
<p>
<!---TO--->
<hr width="66%" align="left">
@ -242,6 +339,31 @@ and address of the addressee underneath, like this:
Bramladesh, Ont.
</pre>
If you wish to change the default quad direction for the address,
enter <kbd>.LEFT</kbd> or <kbd>.RIGHT</kbd>, on a line by itself,
immediately after <kbd>.TO</kbd>.
<p>
If you wish to insert additional space between the address and
any letter header that comes after it, do so after inputting the
address, not at the top of the next header macro, like this:
<p>
<pre>
.TO
JOHN SMITH
10 Roberts Crescent
Bramladesh, Ont.
.SPACE \" Or, more simply, .SP
</pre>
If you wish to remove the default space,
<p>
<pre>
.SPACE -1v \" Or, more simply, .SP -1v
</pre>
will do the trick.
<p>
<!---FROM--->
<hr width="66%" align="left">
@ -251,7 +373,7 @@ Macro: <strong>FROM</strong>
<p>
Invoke <strong>FROM</strong> on a line by itself, with the name
and address of the addressor underneath, like this:
and address of the addresser underneath, like this:
<p>
<pre>
.FROM
@ -260,6 +382,31 @@ and address of the addressor underneath, like this:
Ste-Vieille-Andouille, Québec
</pre>
If you wish to change the default quad direction for the address,
enter <kbd>.LEFT</kbd> or <kbd>.RIGHT</kbd>, on a line by itself,
immediately after <kbd>.FROM</kbd>.
<p>
If you wish to insert additional space between the address and
any letter header that comes after it, do so after inputting the
address, not at the top of the next header macro, like this:
<p>
<pre>
.FROM
JOE BLOW
15 Brunette Road
Ste-Vieille-Andouille, Québec
.SPACE \" Or, more simply, .SP
</pre>
If you wish to remove the default space,
<p>
<pre>
.SPACE -1v \" Or, more simply, .SP -1v
</pre>
will do the trick.
<p>
<!---GREETING--->
<hr width="66%" align="left">
@ -308,8 +455,8 @@ page&quot; number at the bottom of multi-page letters, invoke
<p>
<hr>
<a href="typemacdoc.html#TOP">Next</a>&nbsp;&nbsp;
<a href="cover.html#TOP">Prev</a>&nbsp;&nbsp;
<a href="macrolist.html#TOP">Next</a>&nbsp;&nbsp;
<a href="refer.html#TOP">Prev</a>&nbsp;&nbsp;
<a href="#TOP">Top</a>&nbsp;&nbsp;
<a href="toc.html">Back to Table of Contents</a>
</body>

1794
contrib/groff/contrib/mom/momdoc/macrolist.html Normal file
View File

File diff suppressed because it is too large Load Diff

36
contrib/groff/contrib/mom/momdoc/rectoverso.html
View File

@ -1,3 +1,4 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html>
<head>
<meta http-equiv="content-type" content="text/html;charset=iso-8859-1">
@ -10,14 +11,12 @@
<a href="cover.html#TOP">Next</a>&nbsp;&nbsp;
<a href="headfootpage.html#TOP">Prev</a>&nbsp;&nbsp;
<a href="toc.html">Back to Table of Contents</a>
<p>
<a name="TOP"></a>
<a name="INDEX_RECTOVERSO"></a>
<a name="RECTOVERSO">
<h2 align="center"><u>RECTO/VERSO PRINTING and COLLATING</u></h2>
</a>
<a name="INDEX_RECTOVERSO">
<h3><u>Recto/verso and collating</u></h3>
<h1 align="center"><u>RECTO/VERSO PRINTING and COLLATING</u></h1>
</a>
<ul>
@ -57,7 +56,7 @@ of the following aspects of alternating page layout:
if user-defined, single string recto/verso headers
or footers are used in place of the default 3-part
headers or footers
<li>switching the page number position (if page numbers are not centered)
<li>switching the page number position (if page numbers are not centred)
</ul>
<p>
It is beyond the scope of this documentation to cover the different
@ -74,8 +73,7 @@ appropriately, put them back in your printer, and have
work from the command line, check out the man pages for
<strong>pstops</strong> and <strong>psbook</strong>. There are other
programs out there as well to help with two-sided printing.
<br>
<p>
<a name="RECTOVERSO_LIST">
<h3><u>Recto/verso macros list</u></h3>
@ -85,6 +83,7 @@ programs out there as well to help with two-sided printing.
<li><a href="#RECTO_VERSO">RECTO_VERSO</a>
<li><a href="#SWITCH_HDRFTR">SWITCH_HEADERS (also FOOTERS)</a>
</ul>
<p>
<hr>
<!---RECTO_VERSO--->
@ -92,7 +91,6 @@ programs out there as well to help with two-sided printing.
<a name="RECTO_VERSO">
<h3><u>Recto/verso printing</u></h3>
</a>
<br>
Macro: <strong>RECTO_VERSO</strong>
<p>
@ -122,11 +120,11 @@ and
(before or after <strong>START</strong>).
<p>
Equally, recto/verso only switches the page number position if page
numbers aren't centered, which means you have to set the page
numbers aren't centred, which means you have to set the page
number position with
<a href="headfootpage.html#PAGENUM_POS">PAGENUM_POS</a>
(before or after <strong>START</strong>).
<br>
<p>
<!---SWITCH_HDRFTR--->
@ -134,7 +132,6 @@ number position with
<a name="SWITCH_HDRFTR">
<h3><u>Switch header left part/right part</u></h3>
</a>
<br>
Macro: <strong>SWITCH_HEADERS</strong>
<p>
@ -144,7 +141,7 @@ string (by default, the document title). If you don't like
<strong>mom</strong>'s default placement of author and title, use
<strong>SWITCH_HEADERS</strong> to reverse it.
<p>
<strong>SWITCH_HEADERS</strong> can also be useful in conjuction
<strong>SWITCH_HEADERS</strong> can also be useful in conjunction
with
<a href="#RECTO_VERSO">RECTO_VERSO</a>.
The assumption of <strong>RECTO_VERSO</strong> is that the first
@ -160,7 +157,7 @@ respect to headers) will come out as you want.
<p>
<strong>NOTE:</strong> Replace <strong>_HEADERS</strong>, above,
with <strong>_FOOTERS</strong> if your document uses footers.
<br>
<p>
<hr>
<!=====================================================================>
@ -205,15 +202,14 @@ files, chances are the <strong>PRINTSTYLE</strong>'s already there.
<ol>
<li>Do not collate documents of differing
<strong>PRINTSTYLES</strong> (i.e. don't try to
collate a TYPESET document and TYPEWRITE document --
why would you want to do that anyway?)
collate a TYPESET document and TYPEWRITE document).
<li>Use <strong>DOC_FAMILY</strong> instead of
<strong>FAMILY</strong> if, for some reason, you want
to change the family of all the document elements after
<strong>COLLATE</strong>. <strong>FAMILY</strong>, by
itself, will change the family of paragraph text only.
</ol>
<br>
<p>
<!---COLLATE--->
@ -221,7 +217,7 @@ files, chances are the <strong>PRINTSTYLE</strong>'s already there.
<a name="COLLATE">
<h3><u>Collate document files</u></h3>
</a>
<br>
Macro: <strong>COLLATE</strong>
<p>
@ -239,14 +235,14 @@ that require their own titles, looks like this:
<p>
<pre>
.COLLATE
.CHAPTER_STRING "Geek Fatigue: Symptoms and Causes"
.CHAPTER_TITLE "Geek Fatigue: Symptoms and Causes"
.START
</pre>
<strong>NOTE:</strong> See the
<a href="#CAUTION">two words of caution</a>,
above.
<br>
<p>
<hr>
<a href="cover.html#TOP">Next</a>&nbsp;&nbsp;

1482
contrib/groff/contrib/mom/momdoc/refer.html Normal file
View File

File diff suppressed because it is too large Load Diff

2131
contrib/groff/contrib/mom/momdoc/reserved.html
View File

File diff suppressed because it is too large Load Diff

182
contrib/groff/contrib/mom/momdoc/toc.html
View File

@ -1,14 +1,75 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html>
<head>
<meta http-equiv="content-type" content="text/html;charset=iso-8859-1">
<title>Mom -- Table of Contents</title>
<title>Mom, version 1.3-a -- Table of Contents</title>
</head>
<body bgcolor="#dfdfdf">
<!====================================================================>
<h1><u>Table of Contents</u></h1>
<h1 align="center"><u>Table of Contents for mom, version 1.3-a</u></h1>
The table of contents has grown quite large. If you've been using
<strong>mom</strong> for a while, you might prefer the
<a href="macrolist.html#TOP"><strong>Quick Reference Guide</strong></a>.
<p>
If you're new to <strong>mom</strong>, click on any link in the
<a href="#QUICK_TOC"><strong>Quick Table of Contents</strong></a>
to go to the
appropriate section of the <strong>Full Table of Contents</strong>.
<p>
Or click
<a href="#TOC_PROP">here</a>
to go directly to the <strong>Full Table of Contents</strong>.
<p>
<hr>
<a name="QUICK_TOC"><h2>Quick Table of Contents</h2></a>
<a href="#INTRO"><strong>INTRODUCTORY STUFF</strong></a>
<ul>
<li><a href="#WHAT">What is mom?</a>
<li><a href="#DEFS">Definitions of terms used in this manual</a>
<li><a href="#USING">Using mom</a>
</ul>
<a href="#TYPESET"><strong>TYPESETTING WITH MOM</strong></a>
<ul>
<li><a href="#TYPE_INTRO">Intro to typesetting macros</a>
<li><a href="#PAGE">Page setup</a>
<li><a href="#PARAM">Basic typesetting parameters</a>
<li><a href="#JUST">Justifying, quadding, etc.</a>
<li><a href="#REFINE">Refinements</a>
<li><a href="#MOD">Modifying type</a>
<li><a href="#VERT">Vertical movements</a>
<li><a href="#TAB">Tabs</a>
<li><a href="#COL">Multiple columns</a>
<li><a href="#IND">Indents</a>
<li><a href="#GOODIES">Goodies</a>
<li><a href="#ESCAPES">Inline escapes</a>
<li><a href="#COLOR">Coloured text</a>
</ul>
<p>
<a href="#DOCPROC"><strong>DOCUMENT PROCESSING WITH MOM</strong></a>
<ul>
<li><a href="#DOCPROC_INTRO">Introduction to document processing</a>
<li><a href="#PRELIM">Preliminary document setup</a>
<li><a href="#TAGS">The document element tags</a> -- heads, subheads, footnotes, etc.
<li><a href="#HDRFTR">Headers and footers</a>
<li><a href="#PAGINATE">Pagination</a>
<li><a href="#RV">Recto/verso printing and collating</a>
<li><a href="#COVER">Cover pages</a>
<li><a href="#REF">Bibliographies and references</a>
<li><a href="#LETTER">Writing letters</a>
<li><a href="#TYPEMACDOC">Using typesetting macros during document processing</a>
<li><a href="#QUICK">Quick reference guide to mom</a>
<li><a href="#APP">Appendices</a>
</ul>
<br>
<hr>
<a name="TOC_PROP"></a>
<h2>Full Table of Contents</h2>
<a name="INTRO"></a>
<a name="WHAT"></a>
<li><a href="intro.html#INTRO"><strong>1. WHAT IS MOM?</strong></a>
<ul>
<li><a href="intro.html#INTRO_INTRO">1.1 Who is mom meant for?</a>
@ -21,12 +82,14 @@
<li><a href="intro.html#TOGGLE_MACRO">1.5.2 &quot;Toggle&quot; macros</a>
</ul>
</ul>
<a name="DEFS"></a>
<li><a href="definitions.html#TERMS"><strong>2. DEFINITIONS OF TERMS USED IN THIS MANUAL</strong></a>
<ul>
<li><a href="definitions.html#TERMS_TYPESETTING">2.1 Typesetting terms</a>
<li><a href="definitions.html#TERMS_GROFF">2.2 Groff terms</a>
<li><a href="definitions.html#TERMS_MOM">2.3 Mom's document processing terms</a>
</ul>
<a name="USING"></a>
<li><a href="using.html#USING"><strong>3. USING MOM</strong></a>
<ul>
<li><a href="using.html#USING_INTRO">3.1 Introduction</a>
@ -34,34 +97,43 @@
<li><a href="using.html#USING_INVOKING">3.3 Printing -- invoking groff with mom</a>
<li><a href="using.html#USING_PREVIEWING">3.4 How to preview documents</a>
</ul>
<a name="TYPESET"></a>
<li><a href="typesetting.html#MACROS_TYPESETTING"><strong>4. THE TYPESETTING MACROS</strong></a>
<ul>
<a name="TYPE_INTRO"></a>
<li><a href="typesetting.html#INTRO_MACROS_TYPESETTING">4.1 Introduction to the typesetting macros</a>
<br>
<a name="PAGE"></a>
<li><a href="typesetting.html#PAGE_MARGINS"><strong>4.2 Page Setup</strong></a> -- paper size and page margins
<ul>
<li><a href="typesetting.html#INDEX_SETUP">4.2.1 Macro list</a>
</ul>
<li><a href="typesetting.html#BASIC_PARAMS"><strong>4.3 Basic Parameters</strong></a> -- family, font, point size, line space, line length, autolead
<a name="PARAM"></a>
<li><a href="typesetting.html#BASIC_PARAMS"><strong>4.3 Basic Parameters</strong></a> -- family, font, fallback font, point size, line space, line length, autolead
<ul>
<li><a href="typesetting.html#INDEX_BASIC">4.3.1 Macro list</a>
</ul>
<a name="JUST"></a>
<li><a href="typesetting.html#JUST_QUAD_FILL"><strong>4.4 Justifying, Quadding, Filling and Breaking Lines</strong></a>
<ul>
<li><a href="typesetting.html#INDEX_JUST">4.4.1 Macro list</a>
</ul>
<a name="REFINE"></a>
<li><a href="typesetting.html#REFINEMENTS"><strong>4.5 Refinements</strong></a> -- word space, sentence space, letter spacing (track kerning), hyphenation, kerning, ligatures
<ul>
<li><a href="typesetting.html#INDEX_REFINEMENTS">4.5.1 Macro list</a>
</ul>
<a name="MOD"></a>
<li><a href="typesetting.html#MODIFICATIONS"><strong>4.6 Modifying Type</strong></a> -- pseudo-italic, -bold, -condensed, and -extended
<ul>
<li><a href="typesetting.html#INDEX_MODIFICATIONS">4.6.1 Macro list</a>
</ul>
<a name="VERT"></a>
<li><a href="typesetting.html#ALDRLD"><strong>4.7 Vertical Movements</strong></a> -- moving up and down on the page
<ul>
<li><a href="typesetting.html#INDEX_ALDRLD">4.7.1 Macro list</a>
</ul>
<a name="TAB"></a>
<li><a href="typesetting.html#TABS"><strong>4.8 Tabs</strong></a>
<ul>
<li><a href="typesetting.html#TYPESETTING_TABS">4.8.1 Typesetting tabs</a>
@ -74,22 +146,26 @@
</ul>
<li><a href="typesetting.html#INDEX_TABS">4.8.3 Macro list</a>
</ul>
<a name="COL"></a>
<li><a href="typesetting.html#MULTI_COLUMNS"><strong>4.9 Multi-columns</strong></a>
<ul>
<li><a href="typesetting.html#INDEX_MULTI_COLUMNS">4.9.1 Macro list</a>
</ul>
<a name="IND"></a>
<li><a href="typesetting.html#INDENTS"><strong>4.10 Indents</strong></a>
<ul>
<li><a href="typesetting.html#INDENTS_TUT">4.10.1 A brief explanation of how mom handles indents</a>
<li><a href="typesetting.html#INDEX_INDENTS">4.10.2 Macro list</a>
</ul>
<a name="GOODIES"></a>
<li><a href="goodies.html#GOODIES"><strong>4.11 Goodies</strong></a> -- aliases,
transparent lines, smartquotes, caps,
underscoring/underlining, padding lines, leaders, drop
caps, superscripts
caps, superscripts, (nested) lists, user-definable strings
<ul>
<li><a href="goodies.html#INDEX_GOODIES">4.11.1 Macro list</a>
</ul>
<a name="ESCAPES"></a>
<li><a href="inlines.html#INLINE_ESCAPES"><strong>4.12 Inline Escapes</strong></a>
<ul>
<li><a href="inlines.html#INTRO_INLINE_ESCAPES">4.12.1 Introduction to inline escapes</a>
@ -97,14 +173,24 @@
<li><a href="inlines.html#INLINES_GROFF">4.12.3 Groff inlines</a>
<li><a href="inlines.html#INLINE_CHARACTERS_GROFF">4.12.3.1 Inlines for special characters and symbols</a>
</ul>
<a name="COLOR"></a>
<li><a href="color.html#TOP"><strong>4.13 Coloured text</strong></a>
<ul>
<li><a href="color.html#INTRO_COLOR">4.13.1 Introduction to coloured text</a>
<li><a href="color.html#MACROS_COLOR">4.13.2 Macro list</a>
</ul>
</ul>
<a name="DOCPROC"></a>
<a name="DOCPROC_INTRO"></a>
<li><a href="docprocessing.html#DOCPROCESSING"><strong>5. DOCUMENT PROCESSING WITH MOM</strong></a>
<ul>
<li><a href="docprocessing.html#INTRO_MACROS_DOCPROCESSING">5.1 Introduction to document processing</a>
<li><a href="docprocessing.html#DEFAULTS">5.2 Some document defaults</a>
<ul>
<li><a href="docprocessing.html#LEADING_NOTE">IMPORTANT NOTE on leading/spacing and bottom margins</a>
<li><a href="docprocessing.html#LEADING_NOTE">IMPORTANT NOTE on leading/spacing and bottom margins</a>
<li><a href="docprocessing.html#SHIM">The SHIM macro</a> -- to get document leading back on track
</ul>
<a name="PRELIM"></a>
<li><a href="docprocessing.html#SETUP"><strong>5.3 PRELIMINARY DOCUMENT SETUP</strong></a>
<ul>
<li><a href="docprocessing.html#DOCPROCESSING_TUT">5.3.1 Tutorial</a> -- setting up a mom document
@ -112,12 +198,17 @@
<li><a href="docprocessing.html#REFERENCE_MACROS"><strong>5.3.2 The Reference Macros</strong></a>
<ul>
<li><a href="docprocessing.html#TITLE">5.3.2.1 TITLE</a>
<li><a href="docprocessing.html#SUBTITLE">5.3.2.2 SUBTITLE</a>
<li><a href="docprocessing.html#AUTHOR">5.3.2.3 AUTHOR</a>
<li><a href="docprocessing.html#CHAPTER">5.3.2.4 CHAPTER</a>
<li><a href="docprocessing.html#CHAPTER_TITLE">5.3.2.5 CHAPTER_TITLE</a>
<li><a href="docprocessing.html#DRAFT">5.3.2.6 DRAFT</a>
<li><a href="docprocessing.html#REVISION">5.3.2.7 REVISION</a>
<li><a href="docprocessing.html#DOC_TITLE">5.3.2.2 DOCTITLE</a>
<li><a href="docprocessing.html#SUBTITLE">5.3.2.3 SUBTITLE</a>
<li><a href="docprocessing.html#AUTHOR">5.3.2.4 AUTHOR</a>
<li><a href="docprocessing.html#CHAPTER">5.3.2.5 CHAPTER</a>
<li><a href="docprocessing.html#CHAPTER_TITLE">5.3.2.6 CHAPTER_TITLE</a>
<li><a href="docprocessing.html#DRAFT">5.3.2.7 DRAFT</a>
<li><a href="docprocessing.html#REVISION">5.3.2.8 REVISION</a>
<li><a href="docprocessing.html#COPYRIGHT">5.3.2.9 COPYRIGHT</a>
<li><a href="docprocessing.html#MISC">5.3.2.10 MISC</a>
<li><a href="docprocessing.html#COVERTITLE">5.3.2.11 COVER_TITLE</a>
<li><a href="docprocessing.html#COVERTITLE">5.3.2.12 DOC_COVER_TITLE</a>
</ul>
<li><a href="docprocessing.html#DOCSTYLE_MACROS"><strong>5.3.3 The Docstyle Macros</strong></a>
<ul>
@ -127,9 +218,15 @@
</ul>
<li><a href="docprocessing.html#STYLE_BEFORE_START"><strong>5.3.4 Changing Type and Style Parameters <em>before</em> START</strong></a>
<ul>
<li><a href="docprocessing.html#TYPE_BEFORE_START">5.3.4.1 Typesetting macros</a> -- usage
<li><a href="docprocessing.html#DOC_LEAD_ADJUST">5.3.4.2 DOC_LEAD_ADJUST</a> -- adjust document leading to fill pages
<li><a href="docprocessing.html#DOCHEADER">5.3.4.3 DOCHEADER</a> -- managing the docheader
<li><a href="docprocessing.html#TYPE_BEFORE_START">5.3.4.1 Typesetting macros before START</a> -- usage
<ul>
<li><a href="docprocessing.html#COLOR">Colour</a>
</ul>
<li><a href="docprocessing.html#DOC_LEAD_ADJUST">5.3.4.2 DOC_LEAD_ADJUST</a> -- adjusting the document
<a href="definitions.html#TERMS_LEADING">leading</a> (line spacing) to fill pages
<li><a href="docprocessing.html#DOCHEADER">5.3.4.3 DOCHEADER</a> -- managing the
<a href="definitions.html#TERMS_DOCHEADER">document header</a>
<li><a href="docprocessing.html#COLUMNS_INTRO">5.3.4.4 COLUMNS</a> -- setting documents in columns
</ul>
<li><a href="docprocessing.html#START_MACRO"><strong>5.3.5 ***START***</strong></a> -- the macro to initiate document processing
@ -138,7 +235,10 @@
<ul>
<li><a href="docprocessing.html#INDEX_DOC_PARAM">5.3.6.1 Macro list</a>
</ul>
<a name="TYPEMACDOC"></a>
<li><a href="typemacdoc.html#TYPESETTING"><strong>5.3.7 Using typesetting macros during document processing</strong></A>
</ul>
<a name="TAGS"></a>
<li><a href="docelement.html#DOCELEMENT"><strong>5.4 THE DOCUMENT ELEMENT TAGS</strong></a>
<ul>
<li><a href="docelement.html#DOCELEMENT_INTRO">5.4.1 Introduction to the document element tags</a>
@ -151,13 +251,19 @@
<li><a href="docelement.html#HEAD_INTRO">5.4.4 Main heads</a>
<li><a href="docelement.html#SUBHEAD_INTRO">5.4.5 Subheads</a>
<li><a href="docelement.html#PARAHEAD_INTRO">5.4.6 Paragraph heads</a>
<li><a href="docelement.html#LINEBREAK_INTRO">5.4.7 Linebreaks</a> -- author linebreaks
<li><a href="docelement.html#QUOTE_INTRO">5.4.8 Quotes</a> -- line for line poetic quotes
<li><a href="docelement.html#LINEBREAK_INTRO">5.4.7 Linebreaks</a> -- author linebreaks (section breaks)
<li><a href="docelement.html#QUOTE_INTRO">5.4.8 Quotes</a> -- line for line poetic quotes or unformatted, verbatim text (e.g. code snippets)
<li><a href="docelement.html#BLOCKQUOTE_INTRO">5.4.9 Blockquotes</a> -- cited material
<li><a href="docelement.html#FOOTNOTE_INTRO">5.4.10 Footnotes</a>
<li><a href="docelement.html#ENDNOTE_INTRO">5.4.11 Endnotes</a>
<li><a href="docelement.html#FINIS_INTRO">5.4.12 Document termination</a> -- FINIS
<li><a href="docelement.html#LIST_INTRO">5.4.10 Lists</a> -- (nested) lists
<li><a href="docelement.html#NUMBER_LINES_INTRO">5.4.11 Line numbering</a>
<li><a href="docelement.html#FOOTNOTE_INTRO">5.4.12 Footnotes</a>
<li><a href="docelement.html#ENDNOTE_INTRO">5.4.13 Endnotes</a>
<li><a href="docelement.html#MARGIN_NOTES_INTRO">5.4.14 Margin notes</a>
<li><a href="docelement.html#BLANK_PAGE_TITLE">5.4.15 Blank pages</a>
<li><a href="docelement.html#TOC_INTRO">5.4.16 Table of contents</a>
<li><a href="docelement.html#FINIS_INTRO">5.4.17 Document termination</a> -- FINIS
</ul>
<a name="HDRFTR"></a>
<li><a href="headfootpage.html#HEADFOOTPAGE"><strong>5.5 DOCUMENT HEADERS AND FOOTERS</strong></a>
<ul>
<li><a href="headfootpage.html#HEADFOOTPAGE_INTRO">5.5.1 Introduction</a>
@ -170,11 +276,13 @@
</ul>
<li><a href="headfootpage.html#HEADFOOT_CONTROL">5.5.6 Control macros for headers/footers</a>
</ul>
<a name="PAGINATE"></a>
<li><a href="headfootpage.html#PAGINATION"><strong>5.6 PAGINATION</strong></a>
<ul>
<li><a href="headfootpage.html#PAGINATION">Introduction</a>
<li><a href="headfootpage.html#INDEX_PAGINATION">Pagination macros list</a>
</ul>
<a name="RV"></a>
<li><a href="rectoverso.html#RECTOVERSO"><strong>5.7 RECTO/VERSO PRINTING AND COLLATING</strong></a>
<ul>
<li><a href="rectoverso.html#RECTOVERSO_INTRO">5.7.1 Introduction to recto/verso</a>
@ -186,23 +294,35 @@
<li><a href="rectoverso.html#COLLATE">5.7.2.1 The COLLATE macro</a>
</ul>
</ul>
<li><a href="cover.html#RECTOVERSO"><strong>5.8 CREATING A COVER PAGE</strong></a>
<a name="COVER"></a>
<li><a href="cover.html#COVER_TOP"><strong>5.8 CREATING COVER PAGES</strong></a>
<br>
<li><a href="letters.html#LETTERS"><strong>5.9 WRITING LETTERS</strong></a>
<a name="REF"></a>
<li><a href="refer.html#REF_TOP"><strong>5.9 BIBLIOGRAPHIES AND REFERENCES</strong></a>
<br>
<a name="LETTER"></a>
<li><a href="letters.html#LETTERS"><strong>5.10 WRITING LETTERS</strong></a>
<ul>
<li><a href="letters.html#LETTERS_INTRO">5.9.1 Introduction to writing letters</a>
<li><a href="letters.html#TUTORIAL">5.9.2 Tutorial on writing letters</a>
<li><a href="letters.html#LETTERS_DEFAULTS">5.9.3 Default style for letters</a>
<li><a href="letters.html#LETTERS_MACROS">5.9.4 The letter macros</a>
<li><a href="letters.html#LETTERS_INTRO">5.10.1 Introduction to writing letters</a>
<li><a href="letters.html#TUTORIAL">5.10.2 Tutorial on writing letters</a>
<li><a href="letters.html#LETTERS_DEFAULTS">5.10.3 Default style for letters</a>
<li><a href="letters.html#LETTERS_MACROS">5.10.4 The letter macros</a>
</ul>
<li><a href="typemacdoc.html#TYPESETTING"><strong>5.10 USING TYPESETTING MACROS DURING DOCUMENT PROCESSING</strong></a>
</ul>
<li><a href="appendices.html#APPENDICES"><strong>6. APPENDICES</strong></a>
<a name="QUICK"></a>
<li><a href="macrolist.html#QUICK"><strong>6. QUICK REFERENCE GUIDE TO MOM</strong></a>
<p>
<a name="APP"></a>
<li><a href="appendices.html#APPENDICES"><strong>7. APPENDICES</strong></a>
<ul>
<li><a href="appendices.html#MOREDOC">6.1 Further notes on this documentation</a>
<li><a href="appendices.html#CODENOTES">6.2 Some reflections on mom</a>
<li><a href="reserved.html#RESERVED">6.3 List of reserved words</a>
<li><a href="appendices.html#CONTACT">6.4 Contact the author</a>
<li><a href="appendices.html#MOREDOC">7.1 Further notes on this documentation</a>
<li><a href="appendices.html#FONTS">7.2 Adding PostScript fonts to groff</a>
<ul>
<li><a href="appendices.html#HOWTO">7.2.1 How to create a PostScript font for use with groff</a>
</ul>
<li><a href="appendices.html#CODENOTES">7.2 Some reflections on mom</a>
<li><a href="reserved.html#RESERVED">7.3 List of reserved words</a>
<li><a href="appendices.html#CONTACT">7.4 Contact the author</a>
</ul>
</ul>
</body>

106
contrib/groff/contrib/mom/momdoc/typemacdoc.html
View File

@ -1,3 +1,4 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html>
<head>
<meta http-equiv="content-type" content="text/html;charset=iso-8859-1">
@ -7,9 +8,10 @@
<!====================================================================>
<a href="appendices.html#TOP">Next</a>&nbsp;&nbsp;
<a href="letters.html#TOP">Prev</a>&nbsp;&nbsp;
<a href="docelement.html#TOP">Next</a>&nbsp;&nbsp;
<a href="docprocessing.html#TOP">Prev</a>&nbsp;&nbsp;
<a href="toc.html">Back to Table of Contents</a>
<p>
<a name="TOP"></a>
<a name="TYPESETTING">
@ -29,24 +31,27 @@ alone. (To indent footnotes, see the full explanation of the
<a href="docelement.html#FOOTNOTE">FOOTNOTE</a>
macro.)
<p>
There are, however, some typesetting macros that, used during document
<strong>Mom</strong>'s tabs
(both
<a href="typesetting.html#TYPESETTING_TABS">typesetting tabs</a>
and
<a href="typesetting.html#STRING_TABS">string tabs</a>)
behave as expected in running text during document processing. Tab
structures that do not exceed the line length of running text are
preserved sensibly from page to page, and, if
<a href="docprocessing.html#COLUMNS">COLUMNS</a>
are enabled, from column to column.
<p>
Some typesetting macros, however, when used during document
processing, behave in special ways. These are the macros that deal
with the basic parameters of type style: horizontal and vertical margins,
line length,
with the basic parameters of type style: horizontal and vertical
margins, line length,
<a href="definitions.html#TERMS_FAMILY">family</a>,
<a href="definitions.html#TERMS_FONT">font</a>,
point size,
<a href="definitions.html#TERMS_PS">point size</a>,
<a href="definitions.html#TERMS_LEADING">leading</a>,
and
<a href="definitions.html#TERMS_QUAD">quad</a>.
<p>
<strong>NOTE:</strong> See the section on
<a href="#TB_MARGINS">Top and bottom margins in document processing</a>
for information on how <strong>mom</strong> interprets
<a href="typesetting.html#T_MARGIN">T_MARGIN</a>
and
<a href="typesetting.html#B_MARGIN">B_MARGIN</a>
in document processing.
<p>
<strong>Mom</strong> assumes that any changes to these parameters
@ -58,7 +63,17 @@ middle of a document.
<p>
The following lists those typesetting macros whose behaviour during
document processing requires some explanation.
<p>
(Please refer to
<a href="#TB_MARGINS">Top and bottom margins in document processing</a>
for information on how <strong>mom</strong> interprets
<a href="typesetting.html#T_MARGIN">T_MARGIN</a>
and
<a href="typesetting.html#B_MARGIN">B_MARGIN</a>
in document processing. Additionally, see
<a href="#ADD_SPACE">ADD_SPACE</a>
if you encounter the problem of trying to get <strong>mom</strong>
to put space at the tops of pages after the first.)
<pre>
MACRO EFFECT DURING DOCUMENT PROCESSING
----- ---------------------------------
@ -115,9 +130,14 @@ LS *Changes line space for the duration of the
current tag only. As soon as another document
element tag is entered, the line space reverts to
the current document default for the new
tag. Highly NOT recommended, since changes to
a document's leading interfere with mom's
ability to balance bottom margins.
tag.
Using LS to temporarily change leading within a
document will almost certainly result in a bottom
margin that doesn't align with the bottom margin
of subsequent pages. You'll need to use the SHIM
macro to get mom back on track when you're ready
to return to the document's default leading.
QUAD *Changes quad for the duration of the
current tag only. As soon as another document
@ -159,10 +179,56 @@ running text, but have no effect on the placement of
<a href="definitions.html#TERMS_FOOTER">footers</a>,
or page numbers.
<a name="ADD_SPACE">
<h2><u>ADD_SPACE</u></h2>
</a>
<p>
Occasionally, you may want to insert space before the start of
<a href="definitions.html#TERMS_RUNNING">running text</a>
on pages after the first.
<p>
You might have tried using
<a href="typesetting.html#ALD">ALD</a>
or
<a href="typesetting.html#SPACE">SPACE</a>
and found it did nothing. This is because <strong>mom</strong>
normally inhibits any extra space before the start of running text
on pages after the first.
<p>
If you need the space, you must use the macro,
<strong>ADD_SPACE</strong>, in conjuction with
<a href="typesetting.html#NEWPAGE">NEWPAGE</a>.
<strong>ADD_SPACE</strong> takes as its single argument the
distance you want <strong>mom</strong> to advance from the normal
baseline position at the top of the page. A
<a href="definitions.html#TERMS_UNITOFMEASURE">unit of measure</a>
is required.
<p>
For example, say you wanted to insert 2 inches of space before the
start of running text on a page other than the first. You'd
accomplish it with
<p>
<pre>
.NEWPAGE
.ADD_SPACE 2i
</pre>
which would terminate your current page, break to a new page,
print the header (assuming headers are on) and insert 2 inches of
space before the start of running text.
<p>
Since adding space in this way is almost sure to disrupt
<strong>mom</strong>'s ability to guarantee perfectly flush bottom
margins, I highly recommend using the
<a href="docprocessing.html#SHIM">SHIM</a>
macro immediately after <strong>ADD_SPACE</strong>.
<p>
<hr>
<a href="appendices.html#TOP">Next</a>&nbsp;&nbsp;
<a href="letters.html#TOP">Prev</a>&nbsp;&nbsp;
<a href="docelement.html#TOP">Next</a>&nbsp;&nbsp;
<a href="docprocessing.html#TOP">Prev</a>&nbsp;&nbsp;
<a href="#TOP">Top</a>&nbsp;&nbsp;
<a href="toc.html">Back to Table of Contents</a>
</body>

1048
contrib/groff/contrib/mom/momdoc/typesetting.html
View File

File diff suppressed because it is too large Load Diff

57
contrib/groff/contrib/mom/momdoc/using.html
View File

@ -1,3 +1,4 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html>
<head>
<meta http-equiv="content-type" content="text/html;charset=iso-8859-1">
@ -10,7 +11,7 @@
<a href="typesetting.html#TOP">Next</a>&nbsp;&nbsp;
<a href="definitions.html#TOP">Prev</a>&nbsp;&nbsp;
<a href="toc.html">Back to Table of Contents</a>
<p>
<a name="TOP"></a>
<a name="USING">
<h1 align="center"><u>USING MOM</u></h1>
@ -23,7 +24,7 @@
<a href="#USING_INVOKING">Invoking groff</a>
<br>
<a href="#USING_PREVIEWING">Previewing documents</a>
<br>
<p>
<hr>
<h2><a name="USING_INTRO"><u>Introduction</u></a></h2>
@ -46,11 +47,11 @@ macro, explained below. After <strong>START</strong>,
<strong>mom</strong> determines the appearance of text following
the markup tags automatically, although you, the user, can easily
change how <strong>mom</strong> interprets the tags. This gives you
nearly complete control over the look and feel of your documents.
In addition, the typesetting macros, in combination with document
processing, let you meet all sorts of typesetting needs that just
can't be covered by &quot;one macro fits all&quot; markup tags.
nearly complete control over document design. In addition, the
typesetting macros, in combination with document processing, let you
meet all sorts of typesetting needs that just can't be covered by
&quot;one macro fits all&quot; markup tags.
<p>
<a name="USING_MACROS">
<h2><u>How to input mom's macros</u></h2>
</a>
@ -67,9 +68,9 @@ following apply.
rules for <strong>mom</strong>'s macros and
<a href="definitions.html#TERMS_INLINES">inline escapes</a>.
I use the vi clone called elvis, and find it a pure
joy in this regard. Simply colorizing macros and
joy in this regard. Simply colourizing macros and
inlines to half-intensity can be enough to make text stand
out clearly from formattting commands.
out clearly from formatting commands.
<li>All <strong>mom</strong>'s macros begin with a period
(dot) and must be entered in upper case (capital)
letters.
@ -120,12 +121,12 @@ Consider the following, which is a template for starting the
chapter of a book.
<p>
<pre>
.TITLE "My Pulizter Novel"
.TITLE "My Pulitzer Novel"
.AUTHOR "Joe Blow"
.CHAPTER 1
\#
.DOCTYPE CHAPTER
.PRINTSTYPE TYPESET
.PRINTSTYLE TYPESET
\#
.FAM P
.PT_SIZE 10
@ -171,7 +172,7 @@ option along with the other options you require. Theoretically, you
only need <code>-U</code> with <code>.open, .opena, .pso, .sy,</code>
and <code>.pi</code>, however reality seems, at times, to dictate
otherwise.
<p>
<a name="USING_PREVIEWING">
<h2><u>How to preview documents</u></h2>
</a>
@ -184,7 +185,7 @@ Groff itself comes with a quick and dirty previewer called
gxditview. Invoke it with
<p>
<pre>
groff -X -mom &lt;filename&gt;
groff -X -mom filename
</pre>
It's not particularly pretty, doesn't have many navigation
@ -200,18 +201,24 @@ doesn't gobble up system resources.
<p>
A surer way to preview documents is with <strong>gv</strong>
(ghostview). This involves processing documents with groff,
directing the output to a temporary (PostScript) file, then opening
the temporary file in <strong>gv</strong>. While that may sound
like a lot of work, I've set up my editor (elvis) to do it for me.
Whenever I'm working on a document that needs previewing/checking,
I fire up <strong>gv</strong> with the &quot;Watch File&quot;
option turned on. To look at the file, I tell elvis to process
it (with groff) and send it to a temporary file (<kbd>groff
-mom filename &gt; filename.ps</kbd>), then open the file inside
<strong>gv</strong>. Ever after, when I want to look at any changes
I make, I simply tell elvis to work his magic again. The Watch File
option in <strong>gv</strong> registers that the file has changed,
and automatically loads the new version. Voilà! -- instant previewing.
and directing the output to a PostScript file, like this,
<p>
<pre>
groff -mom filename &gt; filename.ps
</pre>
then opening .ps file in <strong>gv</strong>.
<p>
While that may sound like a lot of work, I've set up my editor
(elvis) to do it for me. Whenever I'm working on a document that
needs previewing/checking, I fire up <strong>gv</strong> with the
&quot;Watch File&quot; option turned on. To look at the file, I
tell elvis to process it (with groff) and send it to a temporary
file (<kbd>groff -mom filename &gt; filename.ps</kbd>), then open
the file inside <strong>gv</strong>. Ever after, when I want to
look at any changes I make, I simply tell elvis to work his magic
again. The Watch File option in <strong>gv</strong> registers that
the file has changed, and automatically loads the new version.
Voilà! --instant previewing.
<p>
<hr>

11400
contrib/groff/contrib/mom/om.tmac
View File

File diff suppressed because it is too large Load Diff

137
contrib/groff/contrib/pdfmark/ChangeLog Normal file
View File

@ -0,0 +1,137 @@
2005-06-22 Keith Marshall <keith.d.marshall@ntlworld.com>
pdfroff.sh portability enhancement.
* pdfroff.sh: (ARGLIST): Variable removed.
(GROFF_STYLE): Use it for all groff invocations.
(INPUT_FILES): Pass to all groff invocations, instead of ARGLIST.
(CS_MACRO, CE_MACRO): Initialize independently.
(CS_FILTER): Simplify quoting; it used to confuse some shells.
(Source): CVS keyword removed; replaced by...
(RCSfile, Revision): these.
2005-06-17 Keith Marshall <keith.d.marshall@ntlworld.com>
* pdfroff.sh: (MATCH): Correct quoting.
(Source): Add terminating `$' on CVS keyword.
2005-06-17 Zvezdan Petkovic <zpetkovic@acm.org>
* Makefile.sub: (RM): Define as `rm -f', for `make' programs
which don't predefine it.
2005-06-16 Bernd Warken
* pdfroff.sh: (NULLDEV): Correct misspelled instance of NULDEV.
2005-05-28 Werner LEMBERG <wl@gnu.org>
* Makefile.sub (.ms.pdf): Use `--stylesheet', not `--style'.
2005-05-17 Keith Marshall <keith.d.marshall@ntlworld.com>
Improve portability of `pdfroff' shell script.
* pdfroff.sh: Add space in shebang, conforming to portability
guidelines in `autoconf' docs.
(searchpath): New shell function; use it instead of `type' command
to locate prerequisite helper programs.
* pdfroff.man: Document influence of `OSTYPE' and `PATH_SEPARATOR'
environment variables.
* Makefile.sub: (pdfroff): Make it depend on SH_DEPS_SED_SCRIPT,
from arch/misc/shdeps.sh; use it to customize PATH_SEPARATOR
initialization code for `searchpath' function in pdfroff.sh.
2005-05-16 Keith Marshall <keith.d.marshall@ntlworld.com>
Interim documentation update.
* pdfmark.ms: (GROFF-WEBSITE): New string; use it in references and
examples.
(Section 2.5): Add definitions of D and Z operators, for use with
pdfhref macro.
(Section 2.5.4): Complete description of pdfhref macro usage for
`Linking to Internet Resources'; provide examples.
2005-05-14 Nick Stoughton <nick@usenix.org>
* pdfmark.tmac (LB): Renamed to ...
(PDFLB): This to avoid conflicts with mm's LB macro.
2005-05-02 Keith Marshall <keith.d.marshall@ntlworld.com>
Handle parsing anomalies in Cygwin's `ash', and similar, shells.
* pdfroff.sh: ($CAT, $GREP, $SED, $GROFF, $DIFF): Avoid interpreting
misdirected error messages, which `type' sends to `stdout' in some
shells, as a successful program file match.
($AWK, $GS): Likewise; also ensure that multiple choice match
prototypes are eval'ed as such, in case token splitting occurs
before variable expansion.
2005-04-24 Keith Marshall <keith.d.marshall@ntlworld.com>
Add support for folded outlines in PDF documents.
* pdfmark.tmac (PDFOUTLINE.FOLDLEVEL): New register.
(pdf:bm.emit): Use it.
* pdfmark.ms: Document it.
2005-03-25 Werner LEMBERG <wl@gnu.org>
* Makefile.in: Removed.
2005-03-24 Werner LEMBERG <wl@gnu.org>
* Makefile: Renamed to...
* Makefile.in: This.
2005-03-22 Keith Marshall <keith.d.marshall@ntlworld.com>
* pdfroff.sh: Eliminate invalid program reference to $AWK, when
invoked with `--no-reference-dictionary' option.
2005-03-02 Keith Marshall <keith.d.marshall@ntlworld.com>
* contrib/pdfmark/Makefile.sub (install_data): Use $(INSTALL_SCRIPT)
to install `pdfroff'.
* contrib/pdfmark/pdfroff.man (opte): New macro.
Use it to remove spurious equal signs from SYNOPSIS.
2005-02-28 Keith Marshall <keith.d.marshall@ntlworld.com>
Provide `pdfroff' shell script, and manpage to document it;
runs multiple groff passes, to format PDF documents.
* pdfroff.sh: New shell script template;
* pdfroff.man: New man page to document it.
Integrate `pdfmark' into normal groff build system;
install macro `pdfmark' packages, build and install `pdfroff',
and PDF format documentation.
* Makefile.sub: Rewritten.
* pdfmark.tmac: Modified.
(pdfhref): New macro operators, `D' and `Z'.
(pdf*href-D, pdf*href-Z): New macros: implement them.
(pdf*href.mark.resolve, pdf*href.mark.emit, pdf*href.mark.flush):
Modified macro algorithm, to eliminate inconsistencies between
`grohtml' representations of `opminy' from differing groff versions.
(pdf*href.mark, pdf*href.mark.release, pdf*href.mark.close):
deleted (redundant macros).
(PDFHREF.LEADING): Default value changed (was 2.5p; now -1.0p).
Global comment updates.
* TODO: Updated.
2004-12-10 Werner LEMBERG <wl@gnu.org>
* TODO: Updated.
2004-12-08 Keith Marshall <keith.d.marshall@ntlworld.com>
First import of pdfmark files.

114
contrib/groff/contrib/pdfmark/Makefile.sub Normal file
View File

@ -0,0 +1,114 @@
# Copyright (C) 2005, Free Software Foundation, Inc.
# Written by Keith Marshall (keith.d.marshall@ntlworld.com)
#
# This file is part of groff.
#
# groff is free software; you can redistribute it and/or modify it under
# the terms of the GNU General Public License as published by the Free
# Software Foundation; either version 2, or (at your option) any later
# version.
#
# groff is distributed in the hope that it will be useful, but WITHOUT ANY
# WARRANTY; without even the implied warranty of MERCHANTABILITY or
# FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
# for more details.
#
# You should have received a copy of the GNU General Public License along
# with groff; see the file COPYING. If not, write to the Free Software
# Foundation, 51 Franklin St - Fifth Floor, Boston, MA 02110-1301, USA.
MAN1=\
pdfroff.n
CMDFILES=\
pdfroff
TMACFILES=\
pdfmark.tmac \
spdf.tmac
PDFDOCFILES=\
pdfmark.pdf
CLEANADD=\
gnu.eps \
$(PDFDOCFILES) \
$(CMDFILES)
# Some `makes' don't predefine RM...
RM=rm -f
GROFF_BIN_DIR=$(top_builddir)/src/roff/groff
GROFF_OTHER_BIN_DIRS=\
$(top_builddir)/src/roff/troff \
$(top_builddir)/src/devices/grops
GROFF_BIN_DIRS=$(GROFF_BIN_DIR) $(GROFF_OTHER_BIN_DIRS)
GROFF_BIN_PATH=`echo $(GROFF_BIN_DIRS) | sed -e 's| *|$(SH_SEP)|g'`
FFLAG=-F$(top_builddir)/font -F$(top_srcdir)/font
MFLAG=-M$(srcdir) -M$(top_builddir)/tmac -M$(top_srcdir)/tmac
PFLAG=-dpaper=$(PAGE) -P-p$(PAGE)
PDFROFF=\
export GROFF_COMMAND_PREFIX; GROFF_COMMAND_PREFIX=''; \
export GROFF_BIN_DIR; GROFF_BIN_DIR=$(GROFF_BIN_DIR); \
export GROFF_BIN_PATH; GROFF_BIN_PATH=$(GROFF_BIN_PATH); \
./pdfroff $(FFLAG) $(MFLAG) $(PFLAG)
.SUFFIXES: .ms .pdf
.ms.pdf:
$(RM) $@
$(PDFROFF) -mspdf --stylesheet=$(srcdir)/cover.ms $< >$@
all: pdfroff $(make_pdfdoc)
pdfdoc: gnu.eps $(PDFDOCFILES)
gnu.eps:
if test -f $(top_srcdir)/doc/gnu.eps; then \
cp $(top_srcdir)/doc/gnu.eps . ; \
elif test -f $(top_builddir)/doc/gnu.eps; then \
cp $(top_builddir)/doc/gnu.eps . ; \
else \
xpmtoppm $(top_srcdir)/doc/gnu.xpm | pnmdepth 15 | \
$(pnmtops_nosetpage) -noturn -rle >$@ ; \
fi
pdfroff: pdfroff.sh $(SH_DEPS_SED_SCRIPT)
$(RM) $@
sed -f $(SH_DEPS_SED_SCRIPT) \
-e "s|@VERSION@|$(version)$(revision)|" \
-e "s|@GROFF_AWK_INTERPRETERS@|$(ALT_AWK_PROGS)|" \
-e "s|@GROFF_GHOSTSCRIPT_INTERPRETERS@|$(ALT_GHOSTSCRIPT_PROGS)|" \
-e "s|@GROFF_BIN_DIR@|$(bindir)|" $(srcdir)/pdfroff.sh >$@
chmod +x $@
install_data: $(make_install_pdfdoc)
-test -d $(bindir) || $(mkinstalldirs) $(bindir)
for f in $(CMDFILES); do \
$(RM) $(bindir)/$$f; \
$(INSTALL_SCRIPT) $$f $(bindir)/$$f; \
done
-test -d $(tmacdir) || $(mkinstalldirs) $(tmacdir)
for f in $(TMACFILES); do \
$(RM) $(tmacdir)/$$f; \
$(INSTALL_DATA) $(srcdir)/$$f $(tmacdir)/$$f; \
done
install_pdfdoc:
-test -d $(pdfdocdir) || $(mkinstalldirs) $(pdfdocdir)
for f in $(PDFDOCFILES); do \
$(RM) $(pdfdocdir)/$$f; \
$(INSTALL_DATA) $$f $(pdfdocdir)/$$f; \
done
uninstall_sub:
for f in $(CMDFILES); do \
$(RM) $(bindir)/$$f; \
done
for f in $(TMACFILES); do \
$(RM) $(tmacdir)/$$f; \
done
for f in $(PDFDOCFILES); do \
$(RM) $(pdfdocdir)/$$f; \
done

25
contrib/groff/contrib/pdfmark/PROBLEMS Normal file
View File

@ -0,0 +1,25 @@
Known PROBLEMS in pdfmark.tmac
==============================
Bounding boxes for link hot-spots which straddle a page break
are not computed correctly.
*** Resolved: 06-Dec-2004 (KDM): pdfmark.tmac.patch-20041206 ***
--------
Documents including a large number of cross references may fail,
with an 'input stack limit exceeded' error.
*** Resolved: 27-Sep-2004 (KDM): pdfmark.tmac.patch-20040927 ***
--------
Links placed in diversions, such as footnotes or floating keeps,
resolve to the wrong destinations; (mapping order becomes confused
between links in diversion, and links in running text following
the diversion).
--------
Annotations placed by .pdfnote cannot exceed about 200 chars.

50
contrib/groff/contrib/pdfmark/README Normal file
View File

@ -0,0 +1,50 @@
README for pdfmark.tmac
=======================
Copyright (C) 2004, Free Software Foundation Inc.
Contributed by Keith Marshall (keith.d.marshall@ntlworld.com)
This is free software. See file COPYING, for copying permissions,
and warranty disclaimer.
This is a preview release of a proposed pdfmark.tmac macro package,
for use with GNU troff (groff). It is not yet complete, and should
be considered as an alpha release; there are a few problems to be
resolved (see file PROBLEMS).
Partial documentation is provided, in groff-ms format. To convert
this to PDF format, you will require a working groff installation,
a working ghostscript installation, with the gs command in your PATH,
and a GNU-compatible make. The tarball should be unpacked in the
top directory of your groff source tree, then:
cd <groff-current>/contrib/pdfmark
make pdfmark
where <groff-current> is the top directory of your current groff
source tree.
Included in this package, are:
pdfmark.tmac -- the core pdfmark macro set
spdf.tmac -- a rudimentary set of bindings for ms macros
pdfmark.ms -- preliminary documentation
cover.ms -- a template for the documentation cover sheet
gnu.eps -- the groff logo, copied from the groff distribution
Makefile -- makefile, for formatting the documentation
README -- this file
PROBLEMS -- a list of known problems
TODO -- a list of planned features, not yet implemented
To make the pdfmark macros generally usable, copy pdfmark.tmac to the
'site-tmac' directory appropriate to your groff installation; (ms users
may also wish to copy spdf.tmac). The macros may then be accessed, by
including the '-mpdfmark' option on the groff command line; (for ms
users, '-mspdf' is equivalent to '-ms -mpdfmark', with some extra
macros 'thrown in').
Comments, and bug reports are welcomed. Please post to the groff
mailing list, groff@gnu.org; (you must be subscribed to this list to
post mails). To subscribe, visit
http://lists.gnu.org/mailman/listinfo/groff

53
contrib/groff/contrib/pdfmark/TODO Normal file
View File

@ -0,0 +1,53 @@
TODO items for pdfmark.tmac
===========================
Add copyright information to PDF documentation.
--------
Add acknowledgements and trade mark ownership notifications
to PDF documentation.
--------
Provide documentation in man page and texinfo formats.
--------
Add comments in spdf.tmac, to clarify its operation.
Also add commentary in pdfmark.tmac, to clarify operation of
recent changes.
--------
Make Makefile generic, so 'configure' can resolve target
system dependencies.
* Comment added 2005-02-26 by Keith Marshall <keith.d.marshall@ntlworld.com>
If this refers to contrib/pdfmark/Makefile, then it is addressed by the new
`pdfroff' script; the original Makefile may be considered redundant. Local
system dependencies are resolved by `configure', and applied to `pdfroff',
when it is generated from `pdfroff.sh'.
--------
Improve Makefile.sub, to integrate pdfmark.tmac installation
into a regular groff build. Add it to groff's Makefile.in.
* Comment added 2005-02-26 by Keith Marshall <keith.d.marshall@ntlworld.com>
Completed.
--------
Provide a `pdfmark' script (or call it `groff2pdf'?) which
actually converts a groff input file to pdf, and which
takes care of the necessary intermediate steps to handle
PDF marks.
* Comment added 2005-02-26 by Keith Marshall <keith.d.marshall@ntlworld.com>
This facility now provided by `pdfroff' script; documented in `pdfroff.man'.
Man page still requires an additional section, to describe use of `stylesheet'
feature. Script also requires documentation in PDF and texinfo formats.

57
contrib/groff/contrib/pdfmark/cover.ms Normal file
View File

@ -0,0 +1,57 @@
.de CS
.if !rCO .nr CO 0
.if !rTL .nr TL 0
.\".nr PO*SAVED \\n[PO]
.nr LL*SAVED \\n[LL]
.nr HM*SAVED \\n[HM]
.nr HM 0
.nr PO (2.1c+\\n[CO]u)
.nr LL 17.1c
\&
.nr PS*SAVED \\n[PS]
.nr VS*SAVED \\n[VS]
.nr PS 24
.nr VS 30
.CD
.fam T
.sp |(5.9c+\\n[TL]u)
.als AU au@first
..
.de au@first
.sp 1.5v
.als AU au@next
.AU \\$@
..
.de au@next
.DE
.nr PS 18
.nr VS 18
.CD
.sp 0.5v
\\$*
..
.de AI
\H'-4z'\\$*\H'0'
..
.de CE
.DE
.sp |17.5c
.PSPIC gnu.eps
.nr PS 19
.CD
.fam H
.tkf HR 10z 2p 20z 4p
\H'-4z'A GNU MANUAL\H'0'
.DE
.\".nr PO \\n[PO*SAVED]
.nr LL \\n[LL*SAVED]
.nr PS \\n[PS*SAVED]
.nr VS \\n[VS*SAVED]
.nr HM \\n[HM*SAVED]
.\".rr PO*SAVED
.rr LL*SAVED
.rr PS*SAVED
.rr VS*SAVED
.rr HM*SAVED
.fam
..

2531
contrib/groff/contrib/pdfmark/pdfmark.ms Normal file
View File

File diff suppressed because it is too large Load Diff

1562
contrib/groff/contrib/pdfmark/pdfmark.tmac Normal file
View File

File diff suppressed because it is too large Load Diff

Some files were not shown because too many files have changed in this diff Show More