gbergman@ucbtopaz.CC.Berkeley.ARPA (08/27/84)
I will try to be complete, even though this means mentioning
things other people have said.
The intended way of commenting troff code is with the sequence
\" --whenever this sequence occurs, it and the remainder of the
line containing it are ignored. (In everything I say here, I
assume you have left the escape and control characters as \ . and '
If you have changed them using .ec, .cc or .c2 what I say applies
mutatis mutandis. If you have macros that change them dynamically,
you're on your own!) In particular, a line beginning with \" is
equivalent to an empty line, and an empty line is equivalent to
the space command .sp, so you do not want to begin your comment-lines
with this sequence. Rather, use lines beginning .\", which are
equivalent to lines consisting of . alone, in other words, the vacuous
command.
.\" so a block
.\" comment should
.\" look like this.
You can also use ' instead of ., and/or put space after the
first character:
' \"this is
' \"also ok.
Another completely safe method is to put comments after the
command .ex, which terminates troffing (equivalent to ^D). Though
this does not allow one to put comments near what is commented,
it allows one to have completely arbitrary lines; I use it for
editor commands that I will want to execute, e.g.
/\\f[^123P]|"to search for typos in font commands.
1,/^.ex/w !spell
1,/^.ex/w !nroff|col|more
etc.
.nx filename should work as well as .ex, though I have seldom
used it.
All other ways of inserting material not to be processed have one
common drawback, which, though obscure, can cause trouble: The comment
is ``processed'' at least to the extent of expanding strings and
number registers. Hence, if your ``comment'' mentions an
auto-incrementing number register \n+(xx \n-(xx etc., or mentions a
string \*(yy whose expansion contains such a register, or even
contains a sequence \*(zz where .zz is a macro which uses such
a register, the indicated incrementation or decrementation will take
effect, and the numbering system in which this register is used will
be upset. With this in mind, let me list some of the many almost-safe
ways of inserting comments.
The way I thought was best until recently was the .ig command:
.ig
material to be ignored
..
or
.ig xx
material to be ignored
.xx
Here if .xx is undefined, it simply serves to terminate the
``comment''; if it is a meaningful command or macro, it will
be the first item executed after the comment. (Actually, if
you define .., e.g.
.de .
.tm urp!
..
then even this will be executed when it occurs as a delimiter
to .ig, .de, etc.)
However, a few weeks ago when I .ig'ed out a couple of lines
in a footnote, I got some thoroughly weird behavior on the rest
of the file. One of the consultants at the Computing Center here,
ucbvax!opal.cc!edmoy, was able to figure it out
From edmoy@ucbopal.CC Fri Aug 3 09:37:00 1984
Yes, you've discovered a bug. .ig uses a similar mechanism to
.de .di and .ds. Unfortunately, .ig clobbers a global variable
without saving it and restoring it later, while the others
handle it correctly. I've tested the fix and it seems to
work. I don't know when the fix will be put in because of our
policy of testing things before installing them in the standard
places.
Ed (edmoy)
The Nroff/Troff User's Manual describes .ig as ``exactly like de
except that the input is discarded.'' So until the fix comes out, you
might instead use
.de ##
comments
..
or
.de ## xx
comments
.xx
and never call the macro .##; though of course this means a bit of
file-space is used in storing your comment whenever the file is troffed.
Something I use with material that I want to include on
some runs of the file but not on the current run is
.if 0 \{.
material
.\}
and then I simply change 0 to 1 when I want to include it.
(Warning: If you use
.if condition \{...
material\}
and if material ends with a terminal message: .tm blah\}, then
the message sent to your terminal will include the internal
troff code for \}. In the old troff this is ^^, which interpreted
as a cursor homing command by an adm3a or a tvi -- it took me a long
time to figure out why my terminal messages were messing up my
screen! -- in ditroff it is ^Q. Anyway, beware all the special
escape sequences, \}, \{, \e, \^, \| etc. in .tm's. To investigate
them for yourself try
% troff -z|& cat -v -u
.tm \e (or whatever)
Anyway, this is one reason to use .\} on a separate line rather
than \} on the last line of the material.)
Another way to hide things is to use \c, which continues
text without a break. An example of its intended use is
.ie \n(dy%2 pro-\c
.el anti-\c
soviet
which gives ``pro-soviet'' on odd days and ``anti-soviet'' on
even. Since everything after the \c is ignored you could comment
the first line
.ie \n(dy%2 pro-\c this is a silly example.
Finally, since macros which have not been defined, or whose
definitions include no arguments, ignore any arguments, you could
use
.xx comment
or
.. comment
I was surprized to see that the news item that
originated this discussion claimed that this messed up the output;
I'd be interested to see an example. (That item is already off
this machine, and I don't remember the writer's name.) It has no such
effect in tries I've made. One bizarre bug here, though: If
.xx and .yy are macros, you should not begin a line with
.xx \*(yy
even if .xx uses no arguments. The above input generally makes troff
grind to a halt. I have no idea why.
Anyway, generally for comments \" and .\" are best!
George Bergman
Math, UC Berkeley 94720 USA
...!ucbvax!ucbcartan!gbergman