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

[Steve Izma]

On Wed, Apr 25, 2018 at 05:00:01PM +0100, Ralph Corderoy wrote:
> Subject: Re: [groff] groff as the basis for comprehensive documentation?
> 
> > 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.
> 
> ... I find looking at the PostScript/PDF valuable
> precisely because it's a different rendering and thus shows problems
> hidden by the rendering used when writing.

I completely agree with Ingo's approach because it demonstrates
the whole point of differentiating between content and format.
When I write, I only want to think about the words on the screen
and the structure of my argument, which is my interpretation of
semantic structure -- paragraph breaks (corresponding to the
notion of a paragraph presenting a single coherent part of the
overall argument), sub-heads to flag a shift in the discussion,
blockquotes to distinguish other people's thoughts, etc. Maybe
also lists, but not much else structually speaking.

This, of course, is a statement about writing in general, not
specifically about writing man pages, but I think the logic
holds.

I also usually assume that I will end up rendering the text in
various ways, e.g., typeset on paper, plain text in an e-mail,
similarly structured input for a wiki. And the typeset output
is not necessarily fixed either: sometimes I'll want it in two
columns on a letter-sized page, sometimes a single column on a
book page. I should not need to make significant changes to the
source text in order for it to read properly in these different
formats. We all know that's the job of the tmac package.

In respect to proofreading, I don't have problems writing and
editing within a text editor. But, over the decades I've worked
in publishing, I've come to see it as a rule that authors
fairly quickly get so familiar with their text that they see what
they want to see, rather than what's actually on the page, so
proofreading is never complete until someone else does it. That
often means an additional way of formatting the text for others
to correct it (e.g., additional line spacing, wider margins for
notes).

        -- Steve

-- 
Steve Izma
-
Home: 35 Locust St., Kitchener, Ontario, Canada  N2H 1W6
E-mail: address@hidden  phone: 519-745-1313  cell: 519-998-2684

A: Because it messes up the order in which people normally read text.
Q: Why is top-posting such a bad thing?
A: Top-posting.
Q: What is the most annoying thing in e-mail?
<http://en.wikipedia.org/wiki/Posting_style>