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

[Steve Izma]

On Wed, Apr 25, 2018 at 10:49:25PM +0100, Ralph Corderoy wrote:
> Subject: Re: [groff] groff as the basis for comprehensive documentation?
> 
> > When I write, I only want to think about the words on the screen and
> > the structure of my argument
> 
> And when you've finished writing, do you not look at an output and spot
> problems due to concentrating on the content?  It's also troff input,
> e.g. `.\&', and although that shouldn't interrupt your flow when
> writing, it does need to be considered in some pass.

I see what you mean. I didn't clarify that I write using a simple
markup scheme (much simpler than markdown-style systems), so I'm
not using troff in the source (except for more complicated, short
items like posters and theatre or music programmes, in which I'll
enter troff requests directly). For longer pieces using only the
structural elements I mentioned, I need very little in markings
(e.g., blank lines for paragraphs, dashes around subheads). I
have simple awk scripts (sometimes a more complicated python
script, depending on the output) to run the finished text through
groff and to PS or PDF or XML, etc.

I'm not sure why you consider `.\&' important: is that for
end-of-sentence recognition? I would never start a text line with
a character that needs '\&' for escaping, although I'll use it
often in my conversion scripts. I very often write at least my
first drafts with each sentence beginning a new line, if I want
sentence-ending recognition in vim or groff. I've never used double
spaces for sentences, but I recognize there are good arguments in
favour of it.

> > I should not need to make significant changes to the source text in
> > order for it to read properly in these different formats.
> 
> Only if you've no errors in the first place, errors that might not show
> up if you don't check a formatted output, or check only one.

For *content* errors, one should be able to use a text editor
that makes the source readable enough to do this (until you reach
the author-self-proofing problem I mentioned earlier; then it's
up to others to read a cleanly formatted output).

For *typesetting* or *style* errors, of course there's going to
be back and forth. But I don't reach that point until I'm
satisfied with the textual content. After that point and to
adjust the typeset output, I work in either the troff or XML
source file to add processing instructions (mostly things like
kerning and extra spacing, which are really just last-resort
fixes to formatting when the troff macro can't handle all
possible situations), but since I'm no longer editing the content
all this extra markup isn't interfering with reading the text.

        -- 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>