On 14.03.25 13:45, G. Branden Robinson wrote:
> At 2025-03-14T09:00:50+0000, dvalin--- via GNU roff typesetting system
> discussion wrote:
...
> > Yes, at "4.6.5.3 Paragraphs" I read "Alternatively, a blank input line
> > breaks the output line and vertically spaces by one vee." There was no
> > hint that a space in a text line could do the same. As it modifies
> > paragraph wrapping, I submit that it is functionally a paragraph
> > attribute, highly worthy of an additional clause in the "blank line"
> > sentence.
>
> Yes, this might be worth noting in a tutorial introduction to ms. The
> handling of blank lines and leading spaces on text lines is a property
> of *roff itself, not of macro packages. (Albeit in GNU troff, one can
> override the default behavior of each.)
I'll attach the succinct user-oriented groff bootstrap notes I'm starting,
as a first groff effort. It offers the *commented* groff itself to provide
elucidating syntax examples - enough for initial take-off.
The footnote there describes a further winkle on the leading-blanks
magic - it fails if there's a trailing backslash on the preceding line.
(That's doubtless deliberate, but the whole combination has trouble
conforming to POLA when documented only with near-infinite entropy, by
mention only in deeply buried, widely dispersed, leaf nodes of a massive
doco tree.) I've documented the two ways of escaping the escape, that
I've experimentally discovered. The commented groff reveals just how
many backslashes it takes to print an escaped backslash in the notes.
(A *nix neophyte probably needs a few more hints than one merely new to
groff. Anyway, example beats explanation every time, I figure.)
It looks like I might use psbooks for A5 on A4 multipage, rather than
psnup, assuming I figure out how to drive it. Might have to install
"info" first, as the psbook manpage is only a placeholder.
...
> I'm attaching a recent rendered version of the groff ms manual from our
> Git repository. Nearly every word of it applies equally well to the
> groff 1.22.4 (December 2018) packages you're apparently using.
...
> Let me know if this helps, or doesn't.
That *very* helpfully collects a lot of useful start-up information
otherwise widely dispersed. The tables are particularly helpful as a
quickly accessible reference for those basic configs needed to whip an
initial effort into shape.
However, rather than reveal the crucial neophyte's hint on how to set
stuff with .nr & .ds unobtrusively in-line under a "scaling unit"
subordinate issue, I'd move it to just above the "3. Document control
settings" table, as the parameter syntax there is only for
"interpolation" (parameter expansion), AIUI - providing no local
information on actually achieving "Document control settings".
In programming, it is optimal to maximise Cohesion, while minmising
Coupling. In documentation, cohesive information modules are also better
than links to scattered locations for half of it, and infinitely better
when even the links are missing.
Groff is like *nix, it isn't hard, it's just a lot, I'm finding.
Reducing the distance between elucidation and syntax examples greatly
improves the ability to understand the How of the What - and that's
precisely what the beginner needs.
...
> > I'll read that now, and add the worst gotchas to the nascent groff
> > section of my 460 pages of *nix & embedded systems software
> > development notes, long essential for survival despite manpages.
>
> Agreed. I maintain an "answers" text file and a shell function "qa"
> that uses lkbib(1) to essentially perform a keyword search on it and
> return relevant entries.
That's a bit more sophisticated than a single 31,011 line file which Vim
folding presents a single TOC-like page of top level folds, including:
TEXT / OFFICE TOOLS & PRINTING 66 P
which opens to:
TEXT / OFFICE TOOLS & PRINTING {{{
GAWK:------------------------------------------------------------- 6 P
GREP: --------------------------------------------------------LOOK 1 P
GROFF:--------------------------- NROFF ---------------------TROFF 3 P
FILTERS / TRANSLATORS:--------------- FILTER: -------------------- 2 P
GNUPLOT:---------------------------------------------------------- 20 L
and GROFF: now opens to:
GROFF:---------------------- NROFF --------------------------TROFF {{{
https://www.gnu.org/software/groff/manual/groff.html.node/index.html
groff -Tps -dpaper=a4l -P-pa4 -P-l -ms foo.ms > foo.ps
| | \ \
| | Pass to postprocessor
Postscript Landscape
Book Printing: PSBOOK: 15 L
Output Formats: 20 L
Paper Size: 18 L
Fonts: 4 L
Formatting macros: 4 L
My only keyword lookup is a Vim search for the word capitalised
(a reference) or with trailing ':' (section on that subject). It's a bit
simple, but serves well for just answering "How do I do X?"
Many thanks for your advice.
Erik
