groff
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: [groff] groff as the basis for comprehensive documentation?


From: Ingo Schwarze
Subject: Re: [groff] groff as the basis for comprehensive documentation?
Date: Sun, 22 Apr 2018 17:11:41 +0200
User-agent: Mutt/1.8.0 (2017-02-23)

Hi Nate,

Nate Bargmann wrote on Sat, Apr 21, 2018 at 12:59:16PM -0500:

> But why do we focus on presentation when authoring a document?
> I think that in large part we have trained ourselves to do so
> using the various desktop word processing/publishing programs
> that came down the pike.
> I've done plenty of documents where the content was subservient to the
> presentation (newsletters and such).  A word processor forces a
> presentation first mindset because its only real output is the printed
> page.  It's not a GUI thing, I was spending as much time tweaking the
> presentation in the codes editor in Word Perfect 5.1 on MS-DOS in 1990
> as I was writing lab reports.

I think it depends on where you come from.  Not counting pure-ASCII
text editing for fixed-width line printers that couldn't do *any*
kind of formatting at all in the early 80ies, i grew up with LaTeX
as *the* one and only text processor for serious work (not counting
the occasional Word document for quickly preparing a leaflet to
distribute on Campus, which we didn't really take seriously in the
sense of "text processing").  And when i typeset formulae for
theoretical high enery phsics, i used to not only make sure that
the content of the formulae was correct and that the printed output
was easy to read and pretty, but also that the source code was
easily human-readable and conveyed the structure of the formulae
that were often several lines long.  That applied even when i had
to design new glyphs for specialized symbols, typically by grouping
existing component glyphs, or to code new environments for specialized
function-like notations.

> Working in the presentation mindset for so long makes it difficult to
> think in terms of semantic markup.  I'm not sure I really understand it
> fully.  Even working with the man macros, I still spend some amount of
> time checking the presentation on the terminal and with PDF and HTML
> output.

I work on mdoc(7) manual pages a lot, and i almost never look at
any kind of output to see whether the final formatting comes out
in the desired visual form.  While writing, i exclusively think
about the logical structure of the text and the semantic function
of each word and symbol.  (I do periodically check the rendered
console output, though - but only because finding typos is easier
in the rendered form than in the source code.)  I certainly
never look at HTML or PDF/PostScript output to see whether it
comes out right.  I just *know* it will - or if it won't then
that's a bug in the formatter which i have to fix.

This anecdotal evidence still confirms your observation, though.
The chief maintainer of the OpenBSD manuals, Jason McIntyre, trained
himself for many years by editing mdoc(7) manual pages with an
ancient, now long obsolete version of groff, groff-1.15, which was
much more quirky than the current, much cleaner groff after Werner's
major work that led up to groff-1.17.  I know definitely that Jason
is still in the habit of checking that every change renders in the
way he desires.  During those years, he got so used to work around
quirks in the parsers and formatters by tweaking the source that
for some years, i found more bugs in mandoc by inspecting his
workaround commits than by explicit bug reports - even though he
did report many bugs.  He *expected* the formatter to be quirky and
thoroughly trained himself to "tweak for effect" by using quirky
software for a long time.

That effect does exist, but is is not unavoidable, and i think
it is even reversible, though of course unlearning is always
harder than learning.

Yours,
  Ingo



reply via email to

[Prev in Thread] Current Thread [Next in Thread]