Re: [groff] Creating a numbered list without macros

[Ingo Schwarze]

Hi Ralph,

Ralph Corderoy wrote on Mon, Aug 13, 2018 at 09:33:12AM +0100:
> Ingo Schwarze wrote:
>> Yves Cloutier wrote:

>>> The short answer is that those macros are too level even for me.

>> I don't understand what "too level" means.

> `too (high|low) level'?

Maybe, but both are still very unclear statements.

>> Roff is both a typesetting system and a programming language.  So the
>> way to do what you want to do with roff is by writing the program you
>> are trying to write - in roff.  In other words, write a macro set.

> We're not entirely sure what he wants.  He may not know himself at this
> early stage of MVP and experimentation.  Perhaps troff syntax, even with
> mainly light-noise macros, would be off-putting to his users and so he's
> wanting a pre-processor that produces troff.  The input language could
> be largely based on indentation, for example.

That has been tried, with very poor results:

  https://undeadly.org/cgi?action=article&sid=20170304230520

I have come to conclude that most of shortcomings are shortcomings
of the concept, not of the particular attempt.  Attempting to invent
syntax without being willing to design syntax just doesn't work,
unsurprisingly.  The idea that people can learn a language without
having to learn a language is wishful thinking (and quite absurd)
and none of the simple markup languages (HTML, roff, LaTeX) present
any real learning barrier.  You cannot make it simpler.  If you
try, it merely gets messier, and actually *harder* as soon as the
task at hand becomes even mildly non-trivial.

I think this is a very important lesson.  Do not take people seriously
who say they cannot learn HTML or roff (the macro markup language
part, *not* the programming language, of course, which is quite
hard even for a programming language) or any similar markup language.
They are merely too lazy to spend half an hour once that would
subsequently save them full hours on each of many later days.  Saying
"HTML or roff macros is too hard for me" is *much* more absurd than
it would be to say "learning to read and write a natural language
is too hard for me, i'm content with oral communication" because
learning to read and write a natural language is many orders of
magnitudes harder than something as simple as HTML or roff macros.
Being able to handle something as simple as HTML or roff macros
must be considered part of basic literacy (as opposed to programming,
which is a completely different matter).

>> In general, generating code in one programming language by a program
>> in a different language is often a second-best approach, to put my
>> opinion mildly.

> All programs that generate troff are written in a different language
> AFAICS - all those preprocessors - with macros being the only exception,
> and then they're normally accompanied by prologue that sets up the
> environment rather than being self-contained.

True, but even the best one, pod2man(2), is not pretty - neither
if you look at the pod2man source code nor if you look at the
generated man(7) code.

That's why i say that even the most casual and inexperienced user
*really* wants to have an easy roff macro language, like groff_mom(7).
Just give them a small cheat sheet of the handful of mom macros
they want to use and be done with it.  :)

>> Besides, whith a macro set, advanced users can use roff(7) requests
>> between the macros when the need arises.  With your approach, even
>> mildly adanced users will soon hit walls where your stuff is not good
>> enough - and they can't complement it by directly resorting to
>> low-level roff(7) where needed either.

> Yves should consider an `escape' such that troff can be poked through.

That sounds deceivingly easy, but is actually quite hard to design
correctly.  Embedding fragments of one language into another can
cause no end of trouble, in particular if implemented naively and
in a rush.  Typical issues relate to nesting and escaping but are
not limited to that.  See the article about markdown above, which
attempts to allow embedding of HTML, but fails spectacularly.

Yours,
  Ingo