RE: [Groff] troff syntax and useability

[Ted Harding]

Hi Rob,
A good question, and even the founding fathers agree
with you:

  The great strength of troff is the flexibility of
  the basic language and its programmability --- it
  can be made to do almost any formatting task. But
  the flexibility comes at a high price --- troff is
  often astonishingly hard to use. It is fair to say
  that almost all of the UNIX document preparation
  software is designed to  cover up some part of
  naked troff.

                    "The UNIX Programming Environment"
                    Brian W. Kernighan & Rob Pyke (1984)

The terseness you refer to undoubtedly originated (like
much UNIX terseness) in a desire to avoid pressing more
keys than necessary --- especially on teletypes, where
correcting typos was a nightmare since "erase and overtype"
was not an option: instead, it looked like tj/j/his ...

However, the terseness itself can be avoided with groff,
since "long names" are admissible, and you can use the
".als" directive (or request), also new in groff, to set
up a long-name alias for a 2-character name. For instance,
for the page-offset directive ".po" you could initially do

  .als page-offset po

after which

  .page-offset 0.75i

becomes very transparent. However, I bet you would soon
revert to ".po" once you got used to it; but the editors
etc. that you refer to might be better pleased! You could
in fact write your private macro package which renamed
everything you needed to something more readable. It would
not prevent you from using the terse forms since ".po" is
still there after it have been given the alias ".page-offset".

However, I think the real difficulty in using troff is not
the terseness. I think it lies in the necessity to understand
the internals, at least to some degree, so that you know what
really goes on when a request or other formatting directive
is executed. Also, there are a number of subtle (and often
not well documented) interactions between directives, and
side-effects which the naive user might not expect (e.g. the
fact that input sent to a diversion is stored formatted
according to the environment which applies to the diversion,
and is no longer "raw" input). There are also aspects of
the way troff was designed that make certain things very
hard indeed to achieve straightforwardly -- e.g. it is far
from trivial to switch on "continuous underlining", something
which is commonplace in standard word-processors.

All this can at times add up to real obscurity in the
interpretation of troff commands, and can indeed lead to
"outsiders" not wanting to get involved.

These, I think, are among the reasons why "troff is often
astonishingly hard to use". However, doing anything about
that would involve a re-design which would be a huge effort.

Nevertheless, your reasons for wanting to use groff are the
same reasons we all share: we like what it does, and value
the almost total control it gives over layout. All of us
who have really got to know g|troff well have had to learn
it the hard way, but we kept going because of those reasons.

Note that troff's difficulties are not unique to troff:
similar difficulties are encountered with any typesetting
software which amounts to a "markup language": TeX is another,
and no-one would say that raw TeX is easy to get to know
(and easier variants such as LaTeX are mainly macro-based
interfaces to "naked TeX"). SGML, XML and so on also pose
learning difficulties to the user: the basic reason why
this happens is that the user has to know what the tags
really mean.

Best wishes,
Ted.

On 27-Aug-02 Rob Scovell wrote:
> I am going to ask a radical question here. This is not because
> I want to stir a fight between purists and pragmatists. It is a
> genuine question.
> I also do not want to denigrate what you guys are doing.
> 
> troff syntax is horribly terse. The macros are better, but not
> that much better, IMHO. I am not a regular troff user but I like
> what it does and would like to use it more than I do for the
> almost total control it gives you over layout.
> 
> I am assuming the syntax is as terse as it is because it was initially 
> developed in the days when disk space was precious. Why can't it be
> made easier or more obvious? I am no stranger to terse code -- just
> peek at some of my perl code. I am also confident with postscript code.
> However, if I pick up troff, use it for something, then put it down
> again, when I come back to use it the next time I find I have to
> re-learn a lot of stuff.
>   This does not happen with other languages.
> 
> If my aim is to produce postscript, why should I have to start with 
> something that is more difficult than postscript?
> 
> Debugging is hellish.
> 
> Admittedly, the requests and macros make sense *after* you've learned
> them -- but not before and the appearance on the page of terse,
> two-letter 'commands' makes learning troff too much of a memory test.
> 
> I would prefer to spend more time and risk more RSI typing out
> meaningful requests and macros that would make the debugging task
> easier.
> 
> Another consideration is that a human editor or author wouldn't
> want to go anywhere near troff code as it stands. They would be
> less reluctant if it were clear what the typesetting code meant,
> even if they were under strict instructions not to monkey with it,
> as the codes would give them clear visual cues when editing the text.
> 
> I want to use troff to typeset -- not for the intellectual challenge
> of learning troff nor for the sake of Unix ritual purity.
> 
> But the worst problem is this -- it's not much *fun*.
> 
> Rob

--------------------------------------------------------------------
E-Mail: (Ted Harding) <address@hidden>
Fax-to-email: +44 (0)870 167 1972
Date: 27-Aug-02                                       Time: 15:35:36
------------------------------ XFMail ------------------------------