Re: [bug #59251] fix an example in groff_tmac(5)

[Ingo Schwarze]

Hi,

i'm no longer posting to the bugtracker because this is no longer
relevant to the ticket.

ivan tkachenko wrote on Mon, Oct 12, 2020 at 06:05:43PM -0400:

> Follow-up Comment #4, bug #59251 (project groff):
> I pulled master branch -- and there it is, already in the upstream.

Well, admittedly, in free software projects with few developers
like groff, it does sometimes happen that bug reports end up delayed
or even forgotten.  But when there is an obviously correct and
useful patch together with a convincing explanation which problem
it is aiming to fix, why not push it right away and without making
a fuss of it?

> Impressive. And you even managed to preserve my authorship while
> adding links to commit messages!

Well, some people passionately hate Github and consider it totally
unusable with an atrocious user interface (for example myself),
but that doesn't mean i don't know how to use git(1).  :-)
Really, what's wrong with a bit of "git am"
and "git commit -a --amend"?  Much easier than wading through a
pull request anyway.

> Never thought it would be so easy.

Indeed, i do think handling patches is easier without a web GUI.

>> the two versions of the example are not equivalent.

> I'm not qualified to comment on this one, but I guess you might be right.
> 
> In fact, I just started diving into this thing few days ago, because
> I wanted to develop some quality plugin to support Roff (& friends)
> in Sublime Text (whops, are we even allowed to spell that proprietary
> name here?).

Sure.  Many GNU projects go to great lengths supporting proprietary
software as well as free software:

  schwarze@isnote $ grep -RFi windows groff/* | wc -l
    2345

That said, personally i don't know what Sublime Text is and don't care
much given that it seems to be non-free software.  But that doesn't
mean people mentioning it should be shunned, or groff bug reports
should be ignored if they arise in the context of using it.

> Looks like every other editor and syntax highlighter has more or less
> rudimentary support at least for the basic language constructs.

No idea because i never use syntax highlighting.  But your finding
doesn't surprise me given that roff has been a dominant typesetting
system for half a century.  Plenty of time to notice its existence...

>> db2bbd805439fcdf9a80addd331b3ef281150629
>> -the following text is printed to the terminal:
>> +the following text is printed:

> I never knew that in roff-talk 'terminal' means stderr.

Admittedly, that's an imprecise expression because stderr is not
necessarily connected to a terminal, and also because, *if* a program
runs interactively, usually both stdout and stderr are connected
to the terminal, so the wording doesn't make it clear which file
descriptor is used.

Talking about stderr as "printing to the terminal" isn't necessarily
roff jargon though.  You are likely to find that sloppy wording in
other contexts, too.

> I spent two days learning the language and getting back to that
> example over and over again, until I figured to look up *.tm*
> request definition.  Actually, *groff*(7) -- the document with
> a reference for requests -- was one of the last things I've
> looked into, mainly because it is so much shadowed by *groff*(1)
> with the same name.

Yes, understanding how to use man(1) is important.

> For a newbie I sure learn things the hard way.

But given that you submitted a useful patch, it is obvious that
you do learn, and quickly enough given that you only started
looking at these things some days ago.

> Well, that's all I've got so far. Thanks for the help!

Have fun, and let us know about other errors or misleading
statements that hold you back.  Feedback from new but quickly
learning users often help a lot to improve documentation.
By contrast, people who already know the subject matter by heart
often overlook gaps in the documentation.

Yours,
  Ingo