Re: .ss paragraph-style-footnote example, then and now

[G. Branden Robinson]

Hi, Dave!

At 2021-04-03T04:23:22-0500, Dave Kemper wrote:
> Hi Branden,
> 
> I too need to amend misstatements in my original post.  Unfortunately,
> unlike you, I spotted them after you replied, so I've muddied the
> discussion with them.
> 
> Here's what I should have said about the original example:
> 
>   - It shows how to use .ss to insert extra (discardable) horizontal
>   space without overriding its normal use to also separate words and
>   sentences.  That is, in the original example, one of the footnotes
>   could have consisted of more than one sentence, and groff would use
>   its usual spaces to separate words and sentences while still putting
>   the extra-wide space between footnotes.
> 
>   - It shows that .ss will take effect multiple times on the same
>   output line.
> 
> So I got the details wrong, but with the above finessing I think my
> main points stand.

Yes, I agree that those are both desirable points to illustrate.

> On 3/25/21, G. Branden Robinson <g.branden.robinson@gmail.com> wrote:
> > The _main_ thing I wanted to illustrate was the use of the _second_
> > argument to .ss.
> 
> A valid point, though I still suspect that's a straightforward enough
> application of the basic .ss description that it might not warrant an
> example illustrating only that.

I can buy that.

> > the original example _does not illustrate the use of
> > the second argument to .ss_, which I think is a flaw given the
> > context.  In fact, the _only_ groff feature it uses is the .nop
> > request.
> 
> Therein lies a worthy philosophical question: should the Texinfo
> examples strive to illustrate groff-specific features, or general
> language features?  The manual overall seems to presume no existing
> roff knowledge, so arguably the examples should be illustrating the
> roff language as a whole.

The '"roff language as a whole" as implemented by groff' is how I would
put it, yes.  As I think I have mentioned before (but which I should
document in some kind of introduction to our Texinfo manual), my model
reader for the manual is a person with basic competence in the Unix
shell and in natural language (English) composition, but no knowledge of
typography or programming languages.  In principle, such a model reader
could start from that position and acquire sufficient knowledge from the
manual in toto to be able to write a full-service macro package for
oneself.  In practice, our typical reader is neither that ignorant nor
that ambitious, but each one will have different gaps in requisite
knowledge.

> > By changing the .nop request into a pair of spaces you can, perhaps,
> > achieve the same result with only CSTR #54 features.  (I say
> > "perhaps" because V7 Unix troff didn't honor the .ss request for
> > nroff devices at all, and Heirloom doesn't seem to either).  I'll
> > call this "Example 3".
> >
> > .ll 4.5i
> > 1.\ This is the first footnote.\c
> > .ss 48
> >   \" 2 spaces
> > .ss 12
> > 2.\ This is the second footnote.
> >
> > The above works on groff equivalently to the old original example.
> 
> Good point.  (Incidentally, two spaces aren't necessary; one is
> sufficient.)

Right.  The second space is only necessary if the effect of the _second_
newline in the input text is suppressed with \c.

> But I think which is better is a judgment call.

Since there is a redundancy in the above, I would replace it with one of
the following.

.ll 4.5i
1.\ This is the first footnote.\c
.ss 48
 \" 1 space
.ss 12
2.\ This is the second footnote.

.ll 4.5i
1.\ This is the first footnote.\c
.ss 48
 \c \" 2 spaces
.ss 12
2.\ This is the second footnote.

The first is more economical, but the second is much more illustrative
of end of sentence detection and what, precisely, \c does.  Maybe it
will suffice to have the latter only in the mailing list archives.

> Were I using this technique in production code, I'd probably use the
> .nop formulation because I find it cleaner than a line containing only
> space (or alternatively, as above, space followed by a comment).  The
> .nop might still warrant a comment to explain what it's doing, but the
> comment at least wouldn't need to point out the .nop's very existence.
> 
> But in a short example illustrating a novel .ss usage, keeping the
> focus on that and not bringing in more other requests than necessary
> has its advantages too.

I have a bias against .nop at present because I don't know how to
explain it convincingly to people.  "It's syntactic sugar for '.if 1'!"
feels feeble to me.

> Whittling your Example 3 down to only CSTR #54 features further drives
> home that the implementation matters: This snippet does what you want
> in groff, and does not in Heirloom troff, regardless of what extension
> level you specify.  Whether this is a functional change that warrants
> an explicit mention in the manual, I'm not sure.  This might be an
> unintentional limitation (or a bug) in the original code; I don't
> think anything in CSTR #54 indicates that this *shouldn't* work.
> Thus, while groff seems to depart from historical behavior here, it's
> not clear that it departs from historical *intent*.

I agree with that.  At least I think I do.  I believe you're referring
to the following statement of mine.

> > In fact, after having tested with Heirloom troff and dpost, Heirloom
> > seems to require a break before it will apply a change to .ss at
> > all.

As comprehensive at it is, there is much that is undocumented in CSTR
#54.  The following were all true of Unix V7 troff.

(1) .ss was honored only for typesetter output, i.e. "troff mode";
(2) .ss defined only "minimum inter-word spacing" as we term it;
(3) additional inter-sentence spacing was copied from the foregoing; and
(4) the \h escape was supported.

Given the above, I conjecture that V7 .ss was used only in extremis, to
fix bad justification (to both margins) on a per-output-line basis.  It
wasn't _useful_ for tweaking inter-sentence spacing, but applied to
every inter-word space on a line and therefore there would be no
_reason_ to change it within an output line.

.\" Example
So you might have some input like this,
.ss 18
and for some reason the incorrigible formatter badly justifies the
output line in which these words appear.
.ss
But the rest of the document looks nice so we apply the ss request for
spot-tweaking;
the extra half-space between the words on that one line makes everything
copasetic.

Nobody cared about how pretty the output was on a TTY (that was just for
drafts or internal reference anyway), even had they been capable of
horizontal half-spacing.

Regards,
Branden

signature.asc
Description: PGP signature