* doc/Makefile: Added texput.log to the `clean' target.

* doc/groff.texinfo: Added info about delimiters for escapes.

4 files changed, 213 insertions, 42 deletions

diff --git a/ChangeLog b/ChangeLog
index 3ab86b7b..102cecbf 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,8 @@
+2000-03-08  Werner LEMBERG  <wl@gnu.org>
+
+	* doc/Makefile: Added texput.log to the `clean' target.
+	* doc/groff.texinfo: Added info about delimiters for escapes.
+
 2000-03-08  Bernd Warken  <bwarken@mayn.de>
 
 	* src/preproc/pic/pic.man: Add info on conversion of pic images to
diff --git a/doc/Makefile b/doc/Makefile
index c8e1dced..8e70de0a 100755
--- a/doc/Makefile
+++ b/doc/Makefile
@@ -67,7 +67,8 @@ install:
 clean:
 	-rm -f *.ps *.html *.ascii *.png *.gif *.dit core
 	-rm -f *.aux *.cp *.cps *.cv *.cn *.dvi *.fn *.fns *.ky *.kys \
-               *.log *.op *.pg *.pgs *.ps *.toc *.tp *.tps *.tr *.vr *.vrs
+               *.log *.op *.pg *.pgs *.ps *.toc *.tp *.tps *.tr *.vr *.vrs \
+               texput.log
 
 distclean: clean
 
diff --git a/doc/groff.texinfo b/doc/groff.texinfo
index 52ed4ec4..7b4b61b7 100644
--- a/doc/groff.texinfo
+++ b/doc/groff.texinfo
@@ -538,11 +538,12 @@ necessary.  Here is a sample; alter the names:
 
 @smallexample
 @group
-Yoyodyne, Inc., hereby disclaims all copyright interest in the program
-`Gnomovision' (which makes passes at compilers) written by James
-Hacker.
+Yoyodyne, Inc., hereby disclaims all copyright interest
+in the program `Gnomovision' (which makes passes at compilers)
+written by James Hacker.
 
-@var{signature of Ty Coon}, 1 April 1989 Ty Coon, President of Vice
+@var{signature of Ty Coon}, 1 April 1989
+Ty Coon, President of Vice
 @end group
 @end smallexample
 
@@ -1653,7 +1654,7 @@ as many of them together on one output line as it can.  This is known as
 @dfn{filling}.
 
 Once @code{gtroff} has a @dfn{filled} line it will try to @dfn{adjust}
-it.  which means it will widen the spacing between words until the text
+it.  Which means it will widen the spacing between words until the text
 reaches the right margin (in the default adjustment mode).  Extra spaces
 between words are preserved, but spaces at the end of lines are ignored.
 Spaces at the front of a line will cause a @dfn{break} (breaks will be
@@ -2014,8 +2015,10 @@ expressions, unless the entire expression is surrounded by parentheses.
 Like any other language, @code{gtroff} has rules for properly formed
 @dfn{identifiers}.  In @code{gtroff} an identifier can be made up of
 almost any printable character.  The only exception are characters which
-are interpreted by @code{gtroff} (backslash, square brackets, and
-@samp{?}).  So, for example, any of the following is valid.
+are interpreted by @code{gtroff} (backslash, square brackets, @dots{}).
+So, for example, any of the following is valid.
+
+@c XXX which characters exactly?
 
 @example
 br
@@ -2025,13 +2028,20 @@ end-list
 @@_
 @end example
 
-@findex \A
-You can test whether an identifier is valid in @code{gtroff} with the
-@code{\A} escape.  It expands to@w{ }1 or@w{ }0 according to whether its
-argument (given in quotes) is or is not acceptable as the name of a
-string, macro, diversion, number register, environment, or font.  It
-will return@w{ }0 if no argument is given.  This is useful if you want
-to look up user input in some sort of associative table.
+@deffn Escape \A ident
+You can test whether an identifier @var{ident} is valid in @code{gtroff}
+with the @code{\A} escape.  It expands to the character@w{ }1 or@w{ }0
+according to whether its argument (given in quotes) is or is not
+acceptable as the name of a string, macro, diversion, number register,
+environment, or font.  It will return@w{ }0 if no argument is given.
+This is useful if you want to look up user input in some sort of
+associative table.
+
+@example
+\A'end-list'
+    @result{} 1
+@end example
+@end deffn
 
 @c XXX add xrefs above
 
@@ -2098,9 +2108,12 @@ A request line begins with a control character, which is either a single
 quote (@samp{'}) or a period (@samp{.}).  These can be changed;
 @xref{Character Translations}, for details.  After this there may be
 optional tabs or spaces followed by an identifier which is the name of
-the request.  This may be followed by any number of space separated
+the request.  This may be followed by any number of space-separated
 arguments.
 
+@cindex zero width space character
+@cindex character, zero width space
+@cindex space character, zero width
 @findex \&
 If you want to begin a line with a control character without it being
 interpreted, precede it with @code{\&}.  This represents a zero width
@@ -2124,8 +2137,6 @@ The line is split into arguments according to spaces.  An argument which
 is intended to contain spaces can either be enclosed in quotes (single
 or double), or have the spaces @dfn{escaped} with backslashes.
 
-So, for example:
-
 @example
 .uh The Mouse Problem
 .uh "The Mouse Problem"
@@ -2138,9 +2149,9 @@ The first line is the @code{uh} macro being called with 3 arguments,
 same effect or calling the @code{uh} macro with one argument @samp{The
 Mouse Problem}.
 
+@findex ds
 Note, however, that the @code{ds} request works differently.
-
-@xref{Strings}.
+@xref{Strings}, for more details.
 
 @node Macros, Escapes, Requests, Embedded Commands
 @subsection Macros
@@ -2156,23 +2167,31 @@ requests---arguments also may be passed in the same manner.
 @subsection Escapes
 @cindex escapes
 
-@findex \e
-@findex \\
 Escapes may occur anywhere in the input to @code{gtroff}.  They begin
-with a backslash and are followed by a single character which indicates
-the function to be performed.  If you want to have a backslash appear in
-your document, you should use the escape sequence @code{\e}.  Merely
-escaping the backslash with another backslash will work in @emph{some}
-circumstances.
+with a backslash usually and are followed by a single character which
+indicates the function to be performed.  The escape character can be
+changed; @xref{Character Translations}.
+
+@findex (
+@findex [
+@findex ]
+Escape sequences which require an identifier as a parameter accept three
+possibilities of syntax.
 
-Many escapes have no parameters; those that do, do so in one of two
-ways.  For escapes which require an identifier there must be a way for
-@code{gtroff} to tell where the identifier ends and the text begins.  It
-assumes that the next single character is the identifier, but if that
-character is an opening parenthesis, it takes the next two characters as
-the identifier; and if the next character is an opening bracket, all
-characters until a closing bracket are taken as the identifier.  Note
-that in the second case there is no closing parenthesis.  For example:
+@itemize @bullet
+@item
+The next single character is the identifier.
+@item
+If this single character is an opening parenthesis, take the following
+two characters as the identifier.  Note that there is no closing
+parenthesis after the identifier.
+@item
+If this single character is an opening bracket, take all characters
+until a closing bracket as the identifier.
+@end itemize
+
+@noindent
+Examples:
 
 @example
 \fB
@@ -2181,15 +2200,147 @@ that in the second case there is no closing parenthesis.  For example:
 @end example
 
 @findex '
+@cindex argument delimiting characters
+@cindex characters, argument delimiting
+@cindex delimiting characters for arguments
 Other escapes may require several arguments and/or some special format.
-In these cases the @dfn{argument} is enclosed in single quotes
-@c XXX (not required??)
-and the enclosing text is decoded according to what that escape expects.
+In such cases the argument is traditionally enclosed in single quotes
+(and quotes are always used in this manual for the definitions of the
+escape sequences).  The enclosed text is then processed according to
+what that escape expects.  Example:
 
 @example
 \l'1.5i\(bu'
 @end example
 
+@findex \o
+@findex \b
+@findex \X
+Note that the quote character can be replaced with any other character
+which does not occur in the argument (even a newline or a space
+character) in the following escapes: @samp{\o}, @samp{\b}, and
+@samp{\X}.  This makes e.g.
+
+@example
+A caf
+\o
+e\'
+
+
+in Paris
+  @result{} A caf@'e in Paris
+@end example
+
+@noindent
+possible, but it is better to avoid this feature to avoid confusion.
+
+@findex \%
+@findex \ 
+@findex \|
+@findex \^
+@findex \@{
+@findex \@}
+@findex \'
+@findex \`
+@findex \-
+@findex \_
+@findex \!
+@findex \?
+@findex \@@
+@findex \)
+@findex \/
+@findex \,
+@findex \&
+@findex \~
+@findex \0
+@findex \a
+@findex \c
+@findex \d
+@findex \e
+@findex \E
+@findex \p
+@findex \r
+@findex \t
+@findex \u
+The following escapes sequences (which are handled similar to characters
+since they don't take a parameter) are also allowed as delimiters:
+@samp{\%}, @samp{\ }, @samp{\|}, @samp{\^}, @samp{\@{}, @samp{\@}},
+@samp{\'}, @samp{\`}, @samp{\-}, @samp{\_}, @samp{\!}, @samp{\?},
+@samp{\@@}, @samp{\)}, @samp{\/}, @samp{\,}, @samp{\&}, @samp{\~},
+@samp{\0}, @samp{\a}, @samp{\c}, @samp{\d}, @samp{\e}, @samp{\E},
+@samp{\p}, @samp{\r}, @samp{\t}, and @samp{\u}.  Again, don't use these
+if possible.
+
+@findex \A
+@findex \Z
+@findex \C
+@findex \w
+No newline characters as delimiters are allowed in the following
+escapes: @samp{\A}, @samp{\Z}, @samp{\C}, and @samp{\w}.
+
+@findex \D
+@findex \h
+@findex \H
+@findex \l
+@findex \L
+@findex \N
+@findex \R
+@findex \s
+@findex \S
+@findex \v
+@findex \x
+Finally, the escapes @samp{\D}, @samp{\h}, @samp{\H}, @samp{\l},
+@samp{\L}, @samp{\N}, @samp{\R}, @samp{\s}, @samp{\S}, @samp{\v}, and
+@samp{\x} can't use the following characters as delimiters:
+
+@itemize @bullet
+@cindex numbers
+@cindex digits
+@item
+The digits @samp{0}-@samp{9}.
+@cindex operators
+@findex +
+@findex -
+@findex /
+@findex *
+@findex %
+@findex <
+@findex >
+@findex =
+@findex &
+@findex :
+@findex (
+@findex )
+@findex .
+@item
+The operators @samp{+-/*%<>=&:().}.
+@item
+@cindex space character
+@cindex character, space
+@cindex tab character
+@cindex character, tab
+@cindex newline character
+@cindex character, newline
+The space, tab, and newline characters.
+@findex \%
+@findex \@{
+@findex \@}
+@findex \'
+@findex \`
+@findex \-
+@findex \_
+@findex \!
+@findex \@@
+@findex \/
+@findex \c
+@findex \e
+@findex \p
+@item
+All escape sequences except @samp{\%}, @samp{\@{}, @samp{\@}},
+@samp{\'}, @samp{\`}, @samp{\-}, @samp{\_}, @samp{\!}, @samp{\@@},
+@samp{\/}, @samp{\c}, @samp{\e}, and @samp{\p}.
+@end itemize
+
 @findex \\
 @findex \e
 @findex \E
@@ -3494,6 +3645,8 @@ description file after the charset command.  It is possible to include
 unnamed characters in the font description file by using a name of
 @samp{---}; the @code{\N} escape sequence is the only way to use these.
 
+@c XXX should be `glyph', not `character'
+
 @findex cflags
 @cindex character properties
 @cindex properties of characters
@@ -3639,6 +3792,9 @@ What is kerning?
 
 @c XXX more info
 
+@cindex zero width space character
+@cindex character, zero width space
+@cindex space character, zero width
 If the font description file contains pairwise kerning information,
 characters from that font will be kerned.  Kerning between two
 characters can be inhibited by placing @code{\&} between them.
@@ -4110,6 +4266,9 @@ The preceding example produces:
 1, 2, 3, 4, 5, 6, 7, 8, 9, 10
 @end example
 
+@cindex zero width space character
+@cindex character, zero width space
+@cindex space character, zero width
 @findex \&
 @noindent
 Note the usage of the @code{\&} escape to avoid a control character at
@@ -4262,7 +4421,7 @@ name.
 This would be called as
 
 @example
-.vl $Id: groff.texinfo,v 1.16 2000/03/07 08:26:47 wlemb Exp $
+.vl $Id: groff.texinfo,v 1.17 2000/03/08 11:02:08 wlemb Exp $
 @end example
 
 @xref{Request Arguments}.
@@ -4340,6 +4499,9 @@ a 1/6th em space.
 a 1/12th em space.
 @item \0
 a space the size of a digit.
+@cindex zero width space character
+@cindex character, zero width space
+@cindex space character, zero width
 @item \&
 A zero width space.
 @item \)
@@ -4458,6 +4620,9 @@ The optional second parameter @var{c} is a character to draw the line
 with.  If this second argument is not specified, troff will use the
 underscore character.
 
+@cindex zero width space character
+@cindex character, zero width space
+@cindex space character, zero width
 @findex \&
 If you need to separate the two arguments (to prevent troff from
 interpreting a drawing character as a scaling indicator), you can
@@ -5484,8 +5649,8 @@ GNU @code{troff} does not allow the use of the escape sequences
 @code{\@key{SP}}, @code{\'}, @code{\`}, @code{\-}, @code{\_}, @code{\!},
 @code{\%}, and @code{\c} in names of strings, macros, diversions, number
 registers, fonts or environments; @sc{Unix} @code{troff} does.  The
-@code{\A} escape sequence may be helpful in avoiding use of these escape
-sequences in names.
+@code{\A} escape sequence (@pxref{Identifiers}) may be helpful in
+avoiding use of these escape sequences in names.
 
 @cindex fractional point sizes
 @cindex point sizes, fractional
diff --git a/src/preproc/pic/pic.man b/src/preproc/pic/pic.man
index 2b09fe78..311a04e6 100644
--- a/src/preproc/pic/pic.man
+++ b/src/preproc/pic/pic.man
@@ -1,5 +1,5 @@
 .ig \"-*- nroff -*-
-Copyright (C) 1989-1999 Free Software Foundation, Inc.
+Copyright (C) 1989-2000 Free Software Foundation, Inc.
 
 Permission is granted to make and distribute verbatim copies of
 this manual provided the copyright notice and this permission notice