bugGNU roff - Bugs: bug #59251, fix an example in groff_tmac(5)

 
 

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

Submitter:  ivan tkachenko <ratijas>
Submitted:  Mon 12 Oct 2020 10:12:29 AM UTC
   
 
Category:  Macro - others/general Severity:  2 - Minor
Item Group:  Documentation Status:  Fixed
Privacy:  Public Assigned to:  schwarze
Open/Closed:  Closed Planned Release:  1.23.0
* Mandatory Fields

Add a New Comment Rich Markup
   

Wed 18 Jan 2023 04:38:43 AM UTC, comment #5: 


commit db2bbd805439fcdf9a80addd331b3ef281150629
Author: Ingo Schwarze <schwarze@openbsd.org>
Date:   Mon Oct 12 16:03:51 2020 +0200

    adjust the text around the example changed in the previous commit

commit d5042f97eb2923bce6e4f9c5d127772d5cbc1c81
Author: ivan tkachenko <me@ratijas.tk>
Date:   Mon Oct 12 15:29:04 2020 +0300

    groff_tmac(5): Remove .tm prefix from example

    .tm request sends anything to stderr. I found it confusing to be used
    in these examples because:
     1. it further complicates things by introducing extra entity;
     2. it doesn't even work, since stderr won't be formatted with \f[I].

    This solution sacrifices line break before the arguments list. I found
    that single dot (.) line does not work without leading spaces in
    surrounding lines; and introducing .br request would be like swapping
    one extra complexity for another. After all, the implied-but-missing
    line break is not as noticable as the missing \f* formatting.

    Via: https://savannah.gnu.org/bugs/index.php?59251


G. Branden Robinson <gbranden>
Group administrator
Mon 12 Oct 2020 10:05:43 PM UTC, comment #4: 

I pulled master branch -- and there it is, already in the upstream. Impressive. And you even managed to preserve my authorship while adding links to commit messages! Never thought it would be so easy.

> 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?). Looks like every other editor and syntax highlighter has more or less rudimentary support at least for the basic language constructs.

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

I never knew that in roff-talk 'terminal' means stderr. 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.  For a newbie I sure learn things the hard way.

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

ivan tkachenko <ratijas>
Mon 12 Oct 2020 02:18:29 PM UTC, comment #3: 

Fixed in db2bbd805439fcdf9a80addd331b3ef281150629.

Applying the second patch required adjusting the surrounding text, too, which was still talking about stderr.  While there, i reduced the verbosity slightly.

The text is still very verbose and quite awkwardly worded with lots of following ... following ... following ...

Also, there is arguably another minor imprecision below "Draft mode": the two versions of the example are not equivalent.  In the first version, later changes to the midpart make no difference, while in the second version, if midpart is changed before calling print_args a second time, the changes take effect for the later invocation.  I don't know how to fix that right now without adding even more confusing verbosity.

I guess eventually Branden will come round to this page...  :-)

Ingo Schwarze <schwarze>
Group Member
Mon 12 Oct 2020 01:00:16 PM UTC, comment #2: 

So, I just run git format-patch -2, and then forget about signed commits, and... here goes nothing...

Patch 1 is a must. Patch 2 is a little opinionated, so you might wanna think twice about it.

(file #49965, file #49966)

ivan tkachenko <ratijas>
Mon 12 Oct 2020 10:24:32 AM UTC, comment #1: 

Just attach your patch to this ticket.
We obviously can't push a patch that you do not submit.

Subscribing to mailinglists is not required.
PGP keys are completely irrelevant.

Ingo Schwarze <schwarze>
Group Member
Mon 12 Oct 2020 10:12:29 AM UTC, original submission:  

Hi. I'm new to groff and GNU Savannah, and I have a tiny little patch to contribute.

As a GitHub-born millennial, I am terribly confused by the lack of any Pull Request functionality. All the information I've found so far on GNU website wasn't of a big help either: e.g. Mission Statement is actually quite off-topic to the question "How do I contribute?", and an "Additional contributions can be found here[1]" link at groff front page[2] leads to a domain with an expired certificate.

I suppose, patches are sent to a mailing list, but my experience with those concepts is quite limited. Once I managed to get my Zsh patch[3] to their upstream, but I've since long forgotten how I did that.

So, I found a little bug in the groff documentation. And if I were to tell you the line number, I'm sure someone with push access would just fix it right away. But if I may, I'd really want to do it myself, to see how things work out here at GNU.

I suppose, my first step would be to subscribe to -email is unavailable- mailing list?

And what about PGP signature? I have my pubkey uploaded somewhere like keys.gnupg.net[4], I believe, but it's not signed by anyone just yet.

 Best regards,
 Ivan a.k.a. @ratijas
 https://ratijas.tk

[1] http://groff.ffii.org/groff/contrib/
[2] https://www.gnu.org/software/groff/groff.html
[3] https://www.zsh.org/mla/workers/2018/msg01626.html
[4] http://keys.gnupg.net/pks/lookup?search=ratijas&fingerprint=on&op=index

ivan tkachenko <ratijas>

 

(Note: upload size limit is set to 16384 kB, after insertion of the required escape characters.)

Attach Files:
   
   
Comment:
   

 

Depends on the following items: None found

Items that depend on this one: None found

 

Carbon-Copy List
  • -email is unavailable- added by gbranden (Posted a comment)
  • -email is unavailable- added by schwarze (Posted a comment)
  • -email is unavailable- added by ratijas (Submitted the item)
  • -email is unavailable- added by ratijas
  •  

    There are 0 votes so far. Votes easily highlight which items people would like to see resolved in priority, independently of the priority of the item set by tracker managers.

    Only logged-in users can vote.

     

    Follow 10 latest changes.

    Date Changed by Updated Field Previous Value => Replaced by
    2020-10-12 schwarze StatusNeed Info Fixed
        Assigned toNone schwarze
        Open/ClosedOpen Closed
        Planned ReleaseNone 1.23.0
        SummarySo anyways, how do I contribute? fix an example in groff_tmac(5)
    2020-10-12 ratijas Attached File- Added 0001-groff_tmac-5-Fix-examples-for-Writing-Macros.patch, #49965
        Attached File- Added 0002-groff_tmac-5-Remove-.tm-prefix-from-examples.patch, #49966
    2020-10-12 schwarze Severity3 - Normal 2 - Minor
        StatusNone Need Info
    2020-10-12 ratijas Carbon-Copy- Added -email is unavailable-

    Back to the top

    Powered by Savane 3.13-d3ae.
    Corresponding source code