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

[G. Branden Robinson]

At 2018-04-21T18:21:28-0400, James K. Lowden wrote:
> On Sat, 21 Apr 2018 12:59:16 -0500
> Nate Bargmann <address@hidden> wrote:
> 
> > But why do we focus on presentation when authoring a document?  
> 
> Because the document we see is what we're creating.  The only purpose
> of the document is to be read, and appearance matters to the reader.
> The reader assuredly doesn't care about semantic markup.  
> 
> Semantic markup is an abstraction that assists the author.  It can
> ensure that semantically similar things -- section headers, quotations,
> etc. -- are rendered consistently.  It can help -- somewhat -- in
> rendering the same input text pleasantly in different output formats.
> It can help indexing programs and such knit together different
> documents in ways that are useful to the user (and thus to the
> author).  
> 
> There's no Higher Good honored by using semantic markup.  It's a tool
> to use if it gets you where you want to go.  Ultimately, though, you
> want your text to be read, and it is altogether fitting and proper that
> you be concerned with its appearance.  

This is true for literature, like poetry or a novel.

For nonfiction, there are additional objectives--full-text searchability
and cross-referencing.  For technical documentation of software systems,
we can further add templating.

By "templating" I mean the little markup-convention languages we use to
distinguish literal text from variable text, and punctuation symbols
like brackes, braces, bars, and ellipses we draft into service to
communicate the regularity (in the formal sense) of the underlying
expressions.

-- 
Regards,
Branden

signature.asc
Description: PGP signature