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

[G. Branden Robinson]

At 2021-03-23T19:41:58-0500, Dave Kemper wrote:
[...]
> The example itself originally read:
> 
>     .ll 4.5i
>     1.\ This is the first footnote.\c
>     .ss 48
>     .nop
>     .ss 12
>     2.\ This is the second footnote.
> 
>     RESULT:
> 
>     1. This is the first footnote.        2. This
>     is the second footnote.
> 
> The new version of this example is:
> 
>     .ie n .ll 50n
>     .el   .ll 2.75i
>     .ss 12 48
>     1. J. Fict. Ch. Soc. 6 (2020), 3\[en]14.
>     2. Better known for other work.
> 
>     RESULT:
> 
>     1. J. Fict. Ch. Soc. 6 (2020), 3-14.     2. Better
>     known for other work.
> 
> The new example really only demonstrates that you can set the
> sentence-space parameter of .ss to a large value to create a large
> space between sentences.  I don;t think this is particularly
> illuminating; one could easily deduce that from the description of
> .ss.  Its one bit of value-add is that it shows a use case --
> separating footnotes -- that a user might not have otherwise thought
> of.

Sometimes it's not clear to me when we want an example to illustrate one
thing, or several things.  I found the \c and .nop distracting at the
time I rewrote the example.  The _main_ thing I wanted to illustrate was
the use of the _second_ argument to .ss.  I'll return to this point.

> However, the original example shows this as well, but also has
> additional attributes that the new example lacks:
> 
>   - It shows how to use .ss to insert extra (discardable) horizontal
>   space without overriding its normal use to also separate sentences.
>   That is, in the original example, one of the footnotes could have
>   consisted of more than one sentence, and groff would use normal
>   sentence spaces between sentences and extra-wide ones between
>   footnotes.

I don't think that's quite what's happening here.  In the original
example, minimal inter-word spacing is being increased to 48 twelfths
of a space width _just_ for the word break between the two footnotes.
Your interpretation only seems plausible because the \c is suppressing
end-of-sentence detection (which is re-detected thanks to the .nop
request, which puts a newline on the input stream).  If you were correct
on this point, the following would work just as well.

.ll 4.5i
.ss 48
1.\ This is the first footnote.
2.\ This is the second footnote.

...but it does not.

>   (Arguably, the example could be expanded to demonstrate this
>   explicitly, but I think it's fairly deducible from the example as
>   written.)  The modified example does not have this property; any
>   sentence breaks within a footnote would be given footnote-separating
>   space.
> 
>   - It shows a use of the .nop request, whose description otherwise
>   leaves users wondering what utility it has.

I think it largely still does... :-/  I find .nop to be poorly-named
since it's not a "no operation" or even like Python's "pass".  It is its
own beast and if I understood all of the use cases that motivated it I'd
be happy to add them to our manual.

>   - It shows that the second .ss parameter will take effect multiple
>   times on the same output line.

The _original_ example doesn't do this because it doesn't _use_ the
second parameter to .ss.  No second argument is given.

>   This may not seem particularly noteworthy, but it turns out to not
>   be true of all roff implementations:
>   http://github.com/n-t-roff/heirloom-doctools/issues/103

I agree that it's a point worth illustrating.

> The footnote text in the retooled example does look like real
> footnotes, but this improvement could be easily retained while
> restoring the functionality of the original.  In fact, the new
> footnote text could easily use sentence space within the footnotes,
> allowing the example to demonstrate word spaces, sentence space, and
> nonce footnote spaces within its two lines of output.
> 
> What do you think?

I agree that that could be done, and might be desirable.  I would
reiterate 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.  By changing
the .nop request into another unbreakable space escape, 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 perhaps Heirloom doesn't 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.

At 2021-03-24T17:03:16-0400, M Douglas McIlroy wrote:
> As the example came through in my mail reader--in a different,
> proportionally spaced font, the effect of .ll in the examples was hard
> to figure out. Which of the two line lengths in the new case is
> actually operative? Why are the inch lengths in the old and new
> examples so different?

As the one who must wear the blame for the new example, I'll attempt to
answer these.  I set different line lengths for nroff and troff because
I thought I needed to; I am now nearly convinced that I don't need to.

Which of the two line lengths is operative depends on the output driver
selected by the user to execute the example.  Our examples in out
Texinfo manual generally do not include this information.

The length of the inch is, blissfully, not redefined in the new example;
they do however use different units, and that is down to my preference
for not using traditional measurements when composing for nroff, where
I, and I suspect many others, tend to compose with character-cell widths
in mind instead of inches.  I'm a whipper-snapper who grew up on glass,
not paper.

> The new example is ticklish, since it depends on the peculiar AI that
> identifies sentence endings. Suppose reference 1 is naively broken
> after "Soc."

This assertion, I differ with; groff detects the ends of sentences as
AT&T troff does by default.  (groff's idea of which input characters are
word-constituent, word-breaking, or "transparent" for the purpose of
end-of-sentence detection can be changed with its .cflags request.)

Reference 1 will not be broken after "Soc." because it is followed by
one space and then a digit.  For the end of a sentence to be detected,
the dot would have to be followed by (1) two spaces or (2) zero or more
spaces and a newline, and then either of these would have to followed by
further word-constituent characters, and not something that would cause
a break.

> I prefer the old example because it's clean to read, isn't mixed up
> with AI, and incidentally illustrates a nontrivial use for .nop.

I think these are subjective merits that are harder to evaluate than the
question which motivated me: are we trying to illustrate idiomatic usage
of the second argument to .ss, or not?

On another point, I did also get rid of the non-breaking, non-adjustable
em-space escapes after the footnote numbers.  Upon reflection I think it
would be good style to restore them for an example illustrating this
footnoting style, but as \~, letting them adjust but not break.  This
would not be necessary for footnote styles where every new note begins a
paragraph.

Regards,
Branden

signature.asc
Description: PGP signature