Re: How to print a literal '.' as the first character in a line?

[Ralph Corderoy]

Hi Branden,

> I could just as well say:
>
> "Many people have found their way to a better life through the gospels."

Yes, I expect they have.

> ...see how condescending that is?

No, it doesn't come across like that to me.

You seem to write many words when fewer would do, whether in emails
or documentation.  Unix has a history of succinct and high quality man
pages and papers which were key in its spread given many of us had nothing
else to study.  I find groff's documentation becoming increasingly chatty
and waffly in tone.

I'll re-introduce the example you cut:

 1  We have now encountered almost all of the syntax there is in the
    'roff' language, with an exception already noted in passing.  

 2  A "request" is an instruction to the formatter that occurs after a
    control character.  

 3  A "control character" must occur at the beginning of an input line
    to be recognized.(1)  (*note Requests and Macros-Footnote-1::)

 4  The regular control character has a counterpart, the "no-break
    control character", which suppresses the break that is implied by
    some requests.  

 5  The default control characters are the dot ('.') and the neutral
    apostrophe ('''), the latter being the no-break control character.  

 6  These characters were chosen because it is uncommon for lines of
    text in natural languages to begin them.  

 7  If you require a formatted period or apostrophe (closing single
    quotation mark) where GNU 'troff' is expecting a control character,
    prefix the dot or neutral apostrophe with the non-printing input
    break escape sequence, '\&'.

- 1 refers to ‘an exception already noted in passing’ but what is it?
  Do I need to recall at this point to understand what follows or is it
  an aside which doesn't need mentioning?
- 2 refers to a control character which isn't defined until 3.
- 3 points out the control character must start a line and refers to an
  input line; why not start with input consisting of text lines and
  control lines?  We've gone request→control character→line which is
  middle→low→high rather than HML or LMH.  Given text files are thought
  of as HML, I think that's the best order.
- 4 talks of a regular control character but I've still no idea what it
  looks like.  I do know from general knowledge, that a control
  character is below ASCII space.  Is the ‘no-break control character’
  the irregular partner to the regular or a third?  Is the break it
  suppresses left unsuppressed by the regular control character?  And
  what is a break anyway?
- 5 now shows something concrete for the control characters but doesn't
  say the dot is the regular one mentioned earlier and has to refer
  backwards with ‘latter’ for the quote character.  ‘Neutral apostrophe’
  is a wordy phrase when something simpler would suffice given it is
  shown.
- 6 doesn't need saying.
- 7 is too specific at this stage.  It introduces ‘escape sequence’ and
  mentions an ‘input break’.

For contrast, here is the start of §1.1 of CSTR 54.

    1.1. Form of input.

    Input consists of text lines, which are destined to be printed,
    interspersed with control lines, which set parameters or otherwise
    control subsequent processing.

    Control lines begin with a control character -- normally . (period)
    or ' (single quote) -- followed by a one or two character name that
    specifies a basic request or the substitution of a user-defined
    macro in place of the control line.

    The control character ' suppresses the break function -- the forced
    output of a partially filled line -- caused by certain requests.

    The control character may be separated from the request/macro name
    by white space (spaces and/or tabs) for aesthetic reasons.

    Names should be followed by either space or newline.

    Control lines with unrecognized names are ignored.

If I look at the source for the sentences 1-7 above, I see the next
paragraph introduces control and text lines, but can't help adding a
footnote.  So many footnotes¹.
https://git.savannah.gnu.org/cgit/groff.git/tree/doc/groff.texi#n5069

A couple of paragraphs later is:

    Of key importance are the requests that define macros.

    Macros are invoked like requests, enabling the request repertoire to be
    extended or overridden.

    @footnote{Argument handling in macros is more flexible but also more
    complex.  @xref{Request and Macro Arguments}.}

‘Of key importance’, ‘request repertoire’, ...  It reads to me as
self-important and puffy.


1.  As Noel Coward is said to have complained: ‘Having to read footnotes
resembles having to go downstairs to answer the door while in the midst
of making love’.

-- 
Cheers, Ralph.