Re: Warn on mid-input line sentence endings

[G. Branden Robinson]

We're re-covering some familiar ground here.

I have a few points I'd like to make.

1.  "Semantic newlines" is a terrible term.  We should abandon it at
once.  The detection of sentence boundaries is not restricted to
newlines, and you *don't* want to warn on _those_, but on the ones
that appear in the _midst_ of an input line.

https://lists.gnu.org/archive/html/groff/2022-07/msg00074.html

2.  Bjarni's comment '"groff" is not the right tool for such things, but
"grep" is.' is thoroughly wrong-headed and Ingo was right to reject
it with great force.  Here a few reasons why.  I don't think any of
B through D are relevant to mandoc(1) since it doesn't support the
features in question (as far as I know).

A.  The formatter decides where sentence boundaries are based on its
input.

B.  Use of the `cflags' request can change the characters that have
sentence-ending semantics.  grep(1) cannot know this.

C.  Sentence-ending characters are subject to character translation
(the `tr` request).  grep(1) cannot know this.

D.  The user/document could define a special character that is a
sentence-ending character (with `char` and `cflags`).  grep(1)
cannot know this.

3.  The artificial intelligence detecting sentence boundaries is already
in the formatter; no one needs to add it.  Moreover, it was already
present in AT&T troff.

https://lists.gnu.org/archive/html/groff/2022-07/msg00080.html
https://lists.gnu.org/archive/html/groff/2022-07/msg00084.html

Since this subject is a recurring trash fire, I should note one
development since last summer's discussion.  I would prefer now to lump
this feature into a new warning category called "style" because I have
thought of another couple of things to put in it.  I still mean to leave
this warning category disabled by default.  I will opt in to it in my
personal working environment.  Others might choose to follow.

https://savannah.gnu.org/bugs/?62776

Regards,
Branden


signature.asc
Description: PGP signature

Re: Warn on mid-input line sentence endings

[G. Branden Robinson]

I should clarify a couple of points here since I was feeling grumpy when
I wrote the following, and that made me forget things.

At 2023-04-27T09:45:40-0500, G. Branden Robinson wrote:
> We're re-covering some familiar ground here.
> 
> I have a few points I'd like to make.
> 
> 1.  "Semantic newlines" is a terrible term.

I should have said "_Warn on_ semantic newlines" is a terrible
instruction/summary.

They are what we _don't_ want to warn about upon encountering them.

If man-pages(7) or other people continue to call the practice of
breaking *roff input lines after sentence-ending punctuation "semantic
newlines", I have no complaint.  It could also be called "Kernighan
breaking", in honor of an early popularizer of the practice.

> 2.  Bjarni's comment '"groff" is not the right tool for such things,
> but "grep" is.' is thoroughly wrong-headed and Ingo was right to
> reject it with great force.  Here a few reasons why.  I don't
> think any of B through D are relevant to mandoc(1) since it
> doesn't support the features in question (as far as I know).
> 
> A.  The formatter decides where sentence boundaries are based on
> its input.
> 
> B.  Use of the `cflags' request can change the characters that
> have sentence-ending semantics.  grep(1) cannot know this.
> 
> C.  Sentence-ending characters are subject to character
> translation (the `tr` request).  grep(1) cannot know this.
> 
> D.  The user/document could define a special character that is a
> sentence-ending character (with `char` and `cflags`).  grep(1)
> cannot know this.

  E.  Because '.', '?', and '!' are valid characters in *roff
  identifiers, grep(1) can be fooled by special character, register,
  or string interpolations in the input if their identifiers use
  those characters.

Example:

I can't believe \*(I.  ate the whole thing.

It is only valid to detect the end of a sentence here if the (recursive)
_expansion_ of the `I.` string ends with a sentence-ending punctuation
character.

Further, since string interpolations can result in further string
interpolations, a finite-state automaton will not suffice to analyze
this input.  You need a stack machine.  (IIRC, a stack machine
recognizes "recursively enumerable" languages.)

This is categorically not what regular expressions can cope with,
formally.  My vague understanding of modern regex implementations is
that they are not finite state automata; the drive for extra features
has caused them to add limited support for recursively enumerable
languages.  (If memory and comprehension serve, "backreferences" in
matches, like "grep 'foo\(bar\)baz\1qux'" were the camel's nose
admitting unbounded memory usage to the regex interpreters of the land.
Perl added many more.[2])

But even knowing that modern regex engines aren't (more precisely: don't
construct) strict finite state machines doesn't save you; they still
understand only their own grammar, not *roff's, so they have no way of
knowing how a *roff string will ultimately expand.

And, to put a bow on that observation, by the time a grep(1) is looking
at the line above, it has already discarded all of the input that set up
the string definitions it would need to know.

So that's yet another reason why, if mid-input line sentence endings are
to be warned about, they must be detected in the formatter, or an
interpreter for so much of the formatter's grammar that one might as
well write a formatter.

I think this is one reason all of the deroff(1) projects in the world
have died.  Eventually they will all fail given a sufficiently complex
input.  I don't have a theorem/proof to back this up, but my hunch is
that since *roff is a Turing-complete language, then deciding what a
*roff formatter will output with "all of the formatting stripped away"
is equivalent to solving the halting problem.

It occurs to me that the right way to attack the problem of extracting
the text from a *roff document is to scrape it out of the device-
independent output format.  Only a handful of commands in that language
produce text glyphs, and they are easy to parse.  This _still_ isn't a
100% solution; access to the current font's glyphs by their index values
can still conceal text.[3][4]  But it strikes me as a far more reliable
approach to several nines of efficacy in this task than any other I've
seen.

But as far as I know no one has ever done this.  I admit that I'm
baffled why not.

Regards,
Branden

[1] I get the impression that Jeffrey Friedl quit updating his O'Reilly
book on regular expressions because he kept getting punked on the
Internet by (pseudo?)academics over the distinction between
"regexes" (Unixy stuff that supports backreferences and all kinds of
other un-Kleene extensions) and regular expressions "proper".  While
the distinction is useful--especially if you're a programmer and
have decided to bite off the task of writing a regex matcher for
yours

Re: Warn on mid-input line sentence endings

[Alejandro Colomar]

Hi Branden,

On 4/30/23 02:05, G. Branden Robinson wrote:
> I should clarify a couple of points here since I was feeling grumpy when
> I wrote the following, and that made me forget things.
> 
> At 2023-04-27T09:45:40-0500, G. Branden Robinson wrote:
>> We're re-covering some familiar ground here.
>>
>> I have a few points I'd like to make.
>>
>> 1.  "Semantic newlines" is a terrible term.
> 
> I should have said "_Warn on_ semantic newlines" is a terrible
> instruction/summary.

That's why I used the phrase (at least I tried to do it consistently
recently) "warn on S. N. violations".

> 
> They are what we _don't_ want to warn about upon encountering them.
> 
> If man-pages(7) or other people continue to call the practice of
> breaking *roff input lines after sentence-ending punctuation "semantic
> newlines", I have no complaint.  It could also be called "Kernighan
> breaking", in honor of an early popularizer of the practice.

You could use it for the warning name ;).

> 
>> 2.  Bjarni's comment '"groff" is not the right tool for such things,
>> but "grep" is.' is thoroughly wrong-headed and Ingo was right to
>> reject it with great force.  Here a few reasons why.  I don't
>> think any of B through D are relevant to mandoc(1) since it
>> doesn't support the features in question (as far as I know).
>>
>> A.  The formatter decides where sentence boundaries are based on
>> its input.
>>
>> B.  Use of the `cflags' request can change the characters that
>> have sentence-ending semantics.  grep(1) cannot know this.
>>
>> C.  Sentence-ending characters are subject to character
>> translation (the `tr` request).  grep(1) cannot know this.
>>
>> D.  The user/document could define a special character that is a
>> sentence-ending character (with `char` and `cflags`).  grep(1)
>> cannot know this.
> 
>   E.  Because '.', '?', and '!' are valid characters in *roff
>   identifiers, grep(1) can be fooled by special character, register,
>   or string interpolations in the input if their identifiers use
>   those characters.
> 
> Example:
> 
> I can't believe \*(I.  ate the whole thing.
> 
> It is only valid to detect the end of a sentence here if the (recursive)
> _expansion_ of the `I.` string ends with a sentence-ending punctuation
> character.
> 
> Further, since string interpolations can result in further string
> interpolations, a finite-state automaton will not suffice to analyze
> this input.  You need a stack machine.  (IIRC, a stack machine
> recognizes "recursively enumerable" languages.)
> 
> This is categorically not what regular expressions can cope with,
> formally.

Well, formally yes.  And a regex can't find C function definitions in a
source tree; at least if you try to fool it by writing the most horrible
code in the universe.  But I wrote a relatively small script[1] that
finds a lot of C code with pcre2grep(1), and works most of the time.  It
has limitations; some of which can be fixed by improving the regexes
(read: making them even more unreadable); some others are likely
impossible to fix with a regex.  The biggest limitation I think I've met
is K&R-style functions: I don't think a regex can cope with them.

I believe a regex-based script can be good enough for some purposes,
even if it's not perfect.

Cheers,
Alex

[1]:  

-- 

GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5


OpenPGP_signature
Description: OpenPGP digital signature

Re: Warn on mid-input line sentence endings

[G. Branden Robinson]

At 2023-04-30T03:04:27+0200, Alejandro Colomar wrote:
> On 4/30/23 02:05, G. Branden Robinson wrote:
> > I should have said "_Warn on_ semantic newlines" is a terrible
> > instruction/summary.
> 
> That's why I used the phrase (at least I tried to do it consistently
> recently) "warn on S. N. violations".

Alas, it got lost in the most recent thread subject line on this topic
to the groff list...

https://lists.gnu.org/archive/html/groff/2023-04/msg00334.html

Hmm, I see that was Bjarni's doing.  Being from Iceland, he perhaps has
more of the spirit of Loki than most...

> > They are what we _don't_ want to warn about upon encountering them.
> > 
> > If man-pages(7) or other people continue to call the practice of
> > breaking *roff input lines after sentence-ending punctuation
> > "semantic newlines", I have no complaint.  It could also be called
> > "Kernighan breaking", in honor of an early popularizer of the
> > practice.
> 
> You could use it for the warning name ;).

Not a chance.  :P

As I noted, I want this under the "style" penumbra now, along with some
other bits of weirdness.

https://savannah.gnu.org/bugs/?62776

> > This is categorically not what regular expressions can cope with,
> > formally.
> 
> Well, formally yes.  And a regex can't find C function definitions in
> a source tree; at least if you try to fool it by writing the most
> horrible code in the universe.  But I wrote a relatively small
> script[1] that finds a lot of C code with pcre2grep(1), and works most
> of the time.  It has limitations; some of which can be fixed by
> improving the regexes (read: making them even more unreadable); some
> others are likely impossible to fix with a regex.  The biggest
> limitation I think I've met is K&R-style functions: I don't think a
> regex can cope with them.

I don't know if you have to cope with "the lexer hack", but you might.

https://en.wikipedia.org/wiki/Lexer_hack

How much grief might have been saved if objects in C had been prefixed
with a sigil like $, or if types had been prefixed with %?

In my imagination, Thompson vetoed this, but when I consider it more
seriously, I reckon the truth is more complicated, and arises from C's
origins in the wholly untyped B language.  The dialect of C we see in
Version 6 Unix (q.v. the Lions book) is shockingly loosely typed to
modern eyes.  I once ground the productivity of my workplace to a halt
for an entire afternoon by presenting my colleagues with the attached
exhibit of "legal C".  (It remained legal in AT&T USG Unix for many,
many years.)

> I believe a regex-based script can be good enough for some purposes,
> even if it's not perfect.

All of this is true, and I like programming languages that are dead
simple to lexically analyze.  (But I spend next to no time working in
them.)

I'm strident on this point because I'm opposed to putting a diagnostic
into the formatter that throws false positives.  That would disserve
users.

Regards,
Branden


signature.asc
Description: PGP signature

Re: Warn on mid-input line sentence endings

[Ingo Schwarze]

Hi Branden,

G. Branden Robinson wrote on Sun, Apr 30, 2023 at 07:34:57AM -0500:

> Hmm, I see that was Bjarni's doing.  Being from Iceland, he perhaps has
> more of the spirit of Loki than most...

Please do not jump to conclusions.  I know at least one Icelander
personally and he is a very pleasant and intelligent guy.

The problem with Bjarni causing confusing and wasting our time over
and over again lies with Bjarni personally and Bjarni alone, not
in any way with Icelanders.

I realize that you likely intended the above statement as a joke,
and fair enough in that case.  As a German, and i can live with
being labeled as not readily understanding British humour.  ;-)

But i think we should be crystal clear about such matters in public
in order to not cause misleading impressions on casual bystanders.


Regarding the naming bikeshed this arose from, i still like
the wording "new sentence, new line" that mandoc(1) adopted
because Jason McTntyre keeps saying that.  It is concise, simple,
and instructive.  But i don't feel strongly about how the warning
is called.  The simpler, the better.

[...]
> I'm strident on this point because I'm opposed to putting a diagnostic
> into the formatter that throws false positives.  That would disserve
> users.

That is very laudable: avoiding false positives as far as possible is
a very good idea, even though it's not usually possible to bring the
rate of false positives down to strictly zero, and there is almost
always a tradeoff between accepting a small number of false positives
or not having a useful warning at all.

For error messages, false positives are quite bad and should be
avoided almost completely if possible.  For style messages, a small
number of false positives are often unavoidable, but minimizing them
is still worthwhile.  "New sentence, new line" is an excellent example
of a style warning where a good perser can do a good job to keep the
rate of false positives low, whereas an ad-hoc partial parser in some
scripting language will almost certainly cause more noise.  All the
same, this is also an excellent example of a warning where even a
very good parser will hardly bring the rate down to zero, and where
accepting the very small residual rate makes sense in order to have
such a quite useful warning.

Yours,
  Ingo

Re: Warn on mid-input line sentence endings

[Alejandro Colomar]

Hi Branden,

On 4/30/23 14:34, G. Branden Robinson wrote:
>> Well, formally yes.  And a regex can't find C function definitions in
>> a source tree; at least if you try to fool it by writing the most
>> horrible code in the universe.  But I wrote a relatively small
>> script[1] that finds a lot of C code with pcre2grep(1), and works most
>> of the time.  It has limitations; some of which can be fixed by
>> improving the regexes (read: making them even more unreadable); some
>> others are likely impossible to fix with a regex.  The biggest
>> limitation I think I've met is K&R-style functions: I don't think a
>> regex can cope with them.
> 
> I don't know if you have to cope with "the lexer hack", but you might.
> 
> https://en.wikipedia.org/wiki/Lexer_hack

No, I didn't.  The script is by design very dumb.  It doesn't have a
database or index; it doesn't involve any compiler either.  It is able
to work very fast on any source tree, without having to perform any
operations on it (e.g., I can clone a repository, and immediately after
I can run the program to search for a function).

It's literally just a wrapper around pcre2grep(1), which is just grep(1)
on steroids.  I find it more usable than existing tools like ctags(1).

You could try it (but C++ will only work as long as it resembles C; and
you need to specify the file suffix).

> 
> How much grief might have been saved if objects in C had been prefixed
> with a sigil like $, or if types had been prefixed with %?

With sane coding styles, my script works well.  Of course, if you
take code from an obfuscation code contest, it will find garbage, but
I'm writing a small tool that is useful for finding code in useful code,
not a compiler that needs to be able to actually compile the weirdest
stuff that one can think of.

> 
> In my imagination, Thompson vetoed this, but when I consider it more
> seriously, I reckon the truth is more complicated, and arises from C's
> origins in the wholly untyped B language.  The dialect of C we see in
> Version 6 Unix (q.v. the Lions book) is shockingly loosely typed to
> modern eyes.  I once ground the productivity of my workplace to a halt
> for an entire afternoon by presenting my colleagues with the attached
> exhibit of "legal C".  (It remained legal in AT&T USG Unix for many,
> many years.)
> 
>> I believe a regex-based script can be good enough for some purposes,
>> even if it's not perfect.
> 
> All of this is true, and I like programming languages that are dead
> simple to lexically analyze.  (But I spend next to no time working in
> them.)
> 
> I'm strident on this point because I'm opposed to putting a diagnostic
> into the formatter that throws false positives.

Bjarni didn't propose adding such a thing to groff.  He was rather
suggesting me to call such a script from my Makefile where I want the
diagnostics.  I think that would be fair (assuming I can get a readable
thing out of that script); especially, since I already have other
scripts for similar purposes (like the one suggested by Ralph, for the
80-column margin, which I find very useful).

Cheers,
Alex

>  That would disserve
> users.
> 
> Regards,
> Branden

-- 

GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5


OpenPGP_signature
Description: OpenPGP digital signature

Re: Warn on mid-input line sentence endings

[G. Branden Robinson]

Hi Alex,

At 2023-05-01T00:15:55+0200, Alejandro Colomar wrote:
> You could try it (but C++ will only work as long as it resembles C;
> and you need to specify the file suffix).

I prefer C to C++ when I have a choice.  groff doesn't give me one.  ;-)

But I'm also accustomed to ctags(1) and cscope(1).  I'm not exactly in
love with cscope's interface, though.

> Bjarni didn't propose adding such a thing to groff.

Oh, I know--he strongly declared that it _shouldn't_ be added, and that
grep was adequate to tackle the problem.  Hence my five-point rebuttal
as to why it was not.

> He was rather suggesting me to call such a script from my Makefile
> where I want the diagnostics.

If that works adequately for you, great!  For well-behaved man
documents, I can't think of a case where any of my five caveats would
apply.

But I interpreted his words as an objection to the proposed enterprise
of Savannah #62776.[1]

Maybe I misunderstood, and _I'm_ the Loki in this discussion... :-O

> I think that would be fair (assuming I can get a readable thing out of
> that script); especially, since I already have other scripts for
> similar purposes (like the one suggested by Ralph, for the 80-column
> margin, which I find very useful).

I'm a big fan of defense in depth.  Give my programming language a
strong type checker _and_ my machine a tagged memory architecture!  :D

Regards,
Branden

[1] https://savannah.gnu.org/bugs/?62776


signature.asc
Description: PGP signature

Re: Warn on mid-input line sentence endings

[josh]

Hi, I'm here with a quick tangent.

It turns out that there is a lot of discourse out there about "semantic
newlines", under a few different names. So far the names I've seen are:

- One Sentence Per Line (OSPL)
- Semantic Line Breaks (SemBr)
- Semantic Linefeeds
- Ventilated Prose
- Semantic newlines (just on this list)

Reading through the pages below was helpful in getting a better idea of
what language people use to discuss this. They're mostly historical
retrospectives or arguments for the merit of semantic newlines.

https://rhodesmill.org/brandon/2012/one-sentence-per-line
https://ramshankar.org/blog/posts/2019/semantic-line-breaks
https://vanemden.wordpress.com/2009/01/01/ventilated-prose
https://discuss.python.org/t/semantic-line-breaks/13874
https://discuss.python.org/t/one-sentence-per-line-for-peps-and-more/13920
https://sembr.org
https://asciidoctor.org/docs/asciidoc-recommended-practices/#one-sentence-per-line

(Actually I think one-sentence-per-line denotes something slightly different
from semantic-line-breaks, not that I know what that difference is).

Hope this is interesting,
Josh

Re: Warn on mid-input line sentence endings

[Alejandro Colomar]

On 5/2/23 00:21, josh wrote:
> Hi, I'm here with a quick tangent.

Hi Josh,

> 
> It turns out that there is a lot of discourse out there about "semantic
> newlines", under a few different names. So far the names I've seen are:
> 
> - One Sentence Per Line (OSPL)

This forgets about clauses and phrases (see below).

> - Semantic Line Breaks (SemBr)

I like this one.

> - Semantic Linefeeds

Since we call ASCII LF the newline character (\n), I think newlines
would be a more common term under Unix.  Linefeed is a term I rarely
see; and only in non-Unix contexts (e.g., IETF RFCs).

> - Ventilated Prose

What is ventilated in the context of prose?  Not too clear to me just by
reading dict(1).

> - Semantic newlines (just on this list)

This one is in use in man-pages(7).

> 
> Reading through the pages below was helpful in getting a better idea of
> what language people use to discuss this. They're mostly historical
> retrospectives or arguments for the merit of semantic newlines.
> 
> https://rhodesmill.org/brandon/2012/one-sentence-per-line
> https://ramshankar.org/blog/posts/2019/semantic-line-breaks
> https://vanemden.wordpress.com/2009/01/01/ventilated-prose
> https://discuss.python.org/t/semantic-line-breaks/13874
> https://discuss.python.org/t/one-sentence-per-line-for-peps-and-more/13920
> https://sembr.org
> https://asciidoctor.org/docs/asciidoc-recommended-practices/#one-sentence-per-line

You can also read man-pages(7):

```
   Use semantic newlines
   In the source of a manual page, new sentences should be started
   on  new  lines,  long  sentences  should be split into lines at
   clause breaks (commas, semicolons, colons, and so on), and long
   clauses should be split at phrase boundaries.  This convention,
   sometimes known as "semantic newlines", makes it easier to  see
   the  effect of patches, which often operate at the level of in‐
   dividual sentences, clauses, or phrases.
```



> 
> (Actually I think one-sentence-per-line denotes something slightly different
> from semantic-line-breaks, not that I know what that difference is).

Yeah, one-sentence-per-line only requires breaking at sentence
boundaries, while with semantic newlines, the intent is that all
newlines are well tought.  Places for placing semantic newlines can be
(apart from sentence boundaries, of course) clause boundaries or phrase
boundaries (in the latter case, there's controversy in this list
regarding how strict one should be).  I tend to be on the strictest
side, as it helps me considerably when reading patches.

Cheers,
Alex

> 
> Hope this is interesting,
> Josh

-- 

GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5


OpenPGP_signature
Description: OpenPGP digital signature

Re: Warn on mid-input line sentence endings

[josh]

Hey Alex,

Thanks a lot for the clarifications, I agree with your reasoning.

On Mon, May 1, 2023 at 8:30 PM Alejandro Colomar  wrote:
> What is ventilated in the context of prose?  Not too clear to me just by
> reading dict(1).

Regarding "Ventilated Prose", it's more of an endearing figure of speech than a
technical categorization. Think of a hot stuffy room, and the transformation
that occurs when you open the window and let in a cool breeze -- the room
becomes well ventilated. So too with a stuffy paragraph.

Here's a relevant passage about the origin of the phrase from
https://vanemden.wordpress.com/2009/01/01/ventilated-prose,

> In the 1930s Buckminster Fuller (he of the domes, but also of many other
> things) was doing research for the Phelps Dodge Corporation. His boss could
> not read Fuller’s reports, but found them perfectly intelligible when read
> aloud by the author.
>
> For Fuller's own account, see below.
>
> [...]
>
> Though the [...] presentation had been developed under the close observation 
> of
> the corporation’s Director of Research, my final written presentation of it
> was declared by the Director to be incomprehensible. Disgruntled, I re-read
> it carefully and returned to the Director saying, "Please listen to this,"
> and proceeded to read in spontaneously metered "doses" from my manuscript.
> As I read I also watched for expressions of comprehension on the Director’s
> face. The Director pondered each verbal dose, and when his face signalled
> "that is clear" I would intuitively measure out the next portion. Finally,
> the Director said, "Why don’t you write it that way?" I said, "I am
> reading directly and without skipping from my original text"; so the
> Director said, "It just doesn’t read that way." The explanation was that
> the intuitive doses did not correspond to conventional syntax.
>
> When the re-written report was submitted, the Director said, "This is lucid,
> but it is poetry, and I cannot possibly hand it to the President of the
> Corporation for submission to the Board of Directors." I insisted that it
> was obviously not poetry, since both he and I knew how I had chopped up a
> conventional prose report. The Director said, "I am having two poets for
> dinner tonight and I will take this to them and see what they say." He
> returned the next day and said, "It’s too bad — it’s poetry."

Sorry to drone on about it, I just think it's very amusing :).

Josh

Re: Warn on mid-input line sentence endings

[Alejandro Colomar]

Hey Josh,

On 5/2/23 05:59, josh wrote:
[...]

> Here's a relevant passage about the origin of the phrase from
> https://vanemden.wordpress.com/2009/01/01/ventilated-prose,
> 
>> In the 1930s Buckminster Fuller (he of the domes, but also of many other
>> things) was doing research for the Phelps Dodge Corporation. His boss could
>> not read Fuller’s reports, but found them perfectly intelligible when read
>> aloud by the author.
>>
>> For Fuller's own account, see below.
>>

[...]

>> The Director said, "I am having two poets for
>> dinner tonight and I will take this to them and see what they say." He
>> returned the next day and said, "It’s too bad — it’s poetry."

:-)

Heh!
Branden wasn't enthusiastic my emails when I wrote poetry in them, though :/
Any chance we can warn users that they should write poems, not prose?

$ cat poem.mdoc 
.Dd May 3, 2023
.Dt POEM 7
.Os
.Sh NAME
.Nm poem
.Nd not really
.Sh DESCRIPTION
Am I really writing a poem?  No, I'm not.  Or am I?
$ mandoc -mdoc -Tlint poem.mdoc 
mandoc: poem.mdoc:8:44: WARNING: new sentence, new line
$ my_mandoc -mdoc -Tlint poem.mdoc 
mandoc: poem.mdoc:8:44: WARNING: write poems, not prose

Just kidding, but technically, it's probably more accurate, and more fun.

Cheers,
Alex

> 
> Sorry to drone on about it, I just think it's very amusing :).
> 
> Josh

-- 

GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5


OpenPGP_signature
Description: OpenPGP digital signature

Re: Warn on mid-input line sentence endings

[Ingo Schwarze]

Hi,

Alejandro Colomar wrote on Wed, May 03, 2023 at 02:35:41AM +0200:

> Heh!
> Branden wasn't enthusiastic my emails when I wrote poetry in them, though :/
> Any chance we can warn users that they should write poems, not prose?
[...]
> Just kidding, but technically, it's probably more accurate, and more fun.

For demonstration purposes, i present a short poem, hoping you like it:

  Pesky poets badly
  Breakit.  Poems permit! 

My point is that excessively smart ideas like "write poems, not prose"
make nothing clear, the times when poetry followed strict rules lie
thousands of years in the past.  When designing technical terms for
use in technical documentation, aim for clarity and simplicity and
refrain from trying to seem witty or funny.

Sure, making the documentation pleasant to read is fine as a secondary
goal as long at that doesn't harm the primary goals - correctness,
clarity, completeness, conciseness, and systematic organization.

Even the occasional joke, applied sparingly, has its place:

   $ man strftime | grep -A 1 ^B   
  BUGS
 There is no conversion specification for the phase of the moon.

But such is indeed the place: near the bottom of the page, where
it doesn't get in the way of the many people who need to quickly
find the relevant information while focussing on something else,
namely on coding or on using some program in a complicated way.
We should certainly refrain from joking while defining technical terms.

Yours,
  Ingo