bugGNU roff - Bugs: bug #65967, [docs] Say "input"...

 
 

bug #65967: [docs] Say "input" instead of "input file" where appropriate

Submitter:  Dave <barx>
Submitted:  Tue 09 Jul 2024 06:37:50 AM UTC
   
 
Category:  General Severity:  2 - Minor
Item Group:  Documentation Status:  Need Info
Privacy:  Public Assigned to:  barx
Open/Closed:  Open Planned Release:  None
* Mandatory Fields

Post a Comment

Add a New Comment Rich Markup
   

Discussion

Jump to the original submission

Mon 13 Jan 2025 11:58:29 AM UTC, comment #11: 

Right, it's just text about the .nx request.  But the points raised in comment #3 and comment #7 show that accurate wording that reflects all possible cases is not entirely straightforward, and I need to test some edge cases to see how they even behave, and none of this has been a priority for me.

Dave <barx>
Group Member
Sun 12 Jan 2025 09:34:01 PM UTC, comment #10: 

It looks like not much remains!

G. Branden Robinson <gbranden>
Group administrator
Sun 12 Jan 2025 08:15:21 PM UTC, comment #9: 

Below are the parts of the patch I originally submitted that were rejected for the reasons cited in comment #2.  This is purely for my own record-keeping; these parts still need to be reworked per comment #3.

diff --git a/doc/groff.texi.in b/doc/groff.texi.in
index 95adfc67f..384dc1649 100644
--- a/doc/groff.texi.in
+++ b/doc/groff.texi.in
@@ -16514,7 +16514,7 @@ from becoming part of the diversion (@pxref{Diversions}).
 @cindex read next file (@code{nx})
 @cindex file, next, read (@code{nx})
 @cindex next file, read (@code{nx})
-Stop processing the input file.  If @var{file} is specified, read it;
+Stop processing the input.  If @var{file} is specified, read it;
 otherwise, read the next pending input file, if any.

 GNU @command{troff} strips a leading neutral double quote from the
diff --git a/man/groff.7.man b/man/groff.7.man
index 7724486d0..2c4addd0b 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -3969,7 +3969,7 @@ if any.
 .
 .TPx
 .REQ .nx file
-Stop processing the input file and read
+Stop processing the input and read
 .IR file .
 .
 .TPx


Dave <barx>
Group Member
Sun 14 Jul 2024 11:50:58 PM UTC, comment #8: 

Editing Summary: I don't currently have a patch for the remaining issues.

Dave <barx>
Group Member
Thu 11 Jul 2024 02:23:14 PM UTC, comment #7: 


comment #6:

> To address the issue raised in comment #3, I can reopen this, or open a new ticket, per your preference.


Okay.  I'm reopening; feel free to take another crack at the wording.

Recall that `nx` might cause a transition from reading from a file to reading from the standard input stream, as when `troff -i` is used.

G. Branden Robinson <gbranden>
Group administrator
Thu 11 Jul 2024 02:19:54 PM UTC, comment #6: 

To address the issue raised in comment #3, I can reopen this, or open a new ticket, per your preference.

Dave <barx>
Group Member
Wed 10 Jul 2024 07:08:04 AM UTC, comment #5: 


commit e6f9a7a9aac0d1f78b6b7bf3de51b9ee18a58b9b
Author: Dave Kemper <saint.snit@gmail.com>
Date:   Tue Jul 9 06:37:50 2024 +0000

    [docs]: Revise "input file" usage.

    Change the term "input file" to "input" in groff documentation in cases
    where the referenced input need not come from a file.

    Fixes <https://savannah.gnu.org/bugs/?65967>.

    [Follow-ups:

    1. Update the description of groff at its GNU home page to match the
       language now in ANNOUNCE/groff.texi.in/groff.1.man.

    2. Sync meintro_fr.me.in.  Drop a "fichier"?

    3. Change some instances of "input" to "the input" where that sounds
       better.

    --GBR]


G. Branden Robinson <gbranden>
Group administrator
Wed 10 Jul 2024 06:28:21 AM UTC, comment #4: 

It's perhaps a little clearer the way it's presented (post-patch) in groff(7):

  .nx        Stop processing the input file and read the next, if any.
  .nx file   Stop processing the input and read file.

But even here I fudged a bit, because the no-argument version does stop processing regardless of whether input is coming from a file or not.  It occurs to me now this aspect might be clearer by moving one word: "Stop processing the input and read the next file, if any."

Dave <barx>
Group Member
Wed 10 Jul 2024 06:17:34 AM UTC, comment #3: 

True, this might require a deeper rewording to clarify.  But the point I'm trying to make here is that .nx can interrupt any input, not just an input file.

$ cat interruption
No going back!
$ printf "You'll see me.\n.nx interruption\nYou won't see me.\n" | nroff | cat -s
You'll see me.  No going back!

Without an argument, and if there's no next file (such as if there's no file at all), then yes, it's basically an .ex call.

Dave <barx>
Group Member
Wed 10 Jul 2024 05:48:36 AM UTC, comment #2: 


@@ -16315,7 +16315,7 @@ @node I/O
 @cindex read next file (@code{nx})
 @cindex file, next, read (@code{nx})
 @cindex next file, read (@code{nx})
-Stop processing the input file.  If @var{file} is specified, read it;
+Stop processing the input.  If @var{file} is specified, read it;
 otherwise, read the next pending input file, if any.
 @endDefreq


This one makes more sense as it was because the point of `nx` is to proceed to the next input file, and to exit only if there is none.

As you have recast it, it is harder to perceive the difference between the `nx` and `ex` requests.

G. Branden Robinson <gbranden>
Group administrator
Tue 09 Jul 2024 03:35:01 PM UTC, comment #1: 

Mom documentation appears to be clean in this regard.  "Input file" refers in all cases to source files.

Peter Schaffter <PTPi>
Group Member
Tue 09 Jul 2024 06:37:50 AM UTC, original submission:  

The attached patch changes the term "input file" to "input" in groff documentation in cases where the referenced input need not come from a file. 

I excluded all -mom documentation, as that has a dedicated maintainer.  I've cc:ed that maintainer here, should he want to audit -mom's documentation for similar loose usage.

I also excluded the user-facing NEWS file (and doc/webpage.ms, derived from it) and the developer-facing ChangeLog files and source-code comments.

Dave <barx>
Group Member

 

Attached Files

Attached Files
file #56238:  65967.patch added by barx (12KiB - text/x-diff)

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

Attach Files:
   
   
Comment:
   

 

Dependencies

This item does not depend on any other items.

No items depend on this one.

 

Mail Notification Carbon-Copy List

Carbon-Copy List
  • -email is unavailable- added by gbranden (Updated the item)
  • -email is unavailable- added by PTPi (Posted a comment)
  • -email is unavailable- added by barx (Submitted the item)
  •  

    Votes

    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.

     

    Please enter the title of George Orwell's famous dystopian book (it's a date):

    History

    Follow 14 latest changes.

    Date Changed by Updated Field Previous Value => Replaced by
    2024-08-03 gbranden Planned Release1.24.0 None
    2024-07-14 barx Carbon-CopyRemoved ptpi -
    2024-07-14 barx Summary[PATCH] [docs] Say &quot;input&quot; instead of &quot;input file&quot; where appropriate [docs] Say "input" instead of "input file" where appropriate
    2024-07-12 gbranden StatusIn Progress Need Info
    2024-07-11 gbranden StatusFixed In Progress
        Assigned togbranden barx
        Open/ClosedClosed Open
    2024-07-10 gbranden StatusIn Progress Fixed
        Open/ClosedOpen Closed
        Planned ReleaseNone 1.24.0
    2024-07-10 gbranden StatusNone In Progress
        Assigned toNone gbranden
    2024-07-09 barx Attached File- Added 65967.patch, #56238
        Carbon-Copy- Added ptpi

    Back to the top

    Powered by Savane 3.16-a7ba.
    Corresponding source code