bugGNU troff - Bugs: bug #59920, [PATCH] [me] documentation...

 
 

bug #59920: [PATCH] [me] documentation terminology cleanup

Submitted by:  Dave <barx>
Submitted on:  Thu 21 Jan 2021 03:57:34 AM UTC  
 
Category:  Macro - me Severity:  2 - Minor
Item Group:  Documentation Status:  Need Info
Privacy:  Public Assigned to:  G. Branden Robinson <gbranden>
Open/Closed:  Open Planned Release:  None

Add a New Comment (Rich Markup)
   

You are not logged in

Please log in, so followups can be emailed to you.

 

( Jump to the original submission)

Thu 18 Mar 2021 11:36:40 PM UTC, comment #6: 

I asked a French-speaking friend about the changes I proposed in comment #3, and she concurred with them, so I've put them into the attached 59920.fr.minimal.patch.

Besides the changes needed to synchronize with the updated English document, she also suggested a minor change in some nearby text.  As I know nothing of French, I cannot comment on this additional change.  I've put this into a second patch, 59920.fr.alternate.patch, which whoever commits this can decide to apply or ignore as they see fit.  (The second patch includes the changes of the first, so only one or the other should be applied.)

(file #51089)

Dave <barx>
Project Member
Fri 05 Mar 2021 02:57:17 AM UTC, comment #5: 

comment #4:

> Not sure why this was marked "Fixed" and "1.23.0".


My bad, I reopened it but didn't update those fields.

Dave <barx>
Project Member
Thu 04 Mar 2021 12:02:55 AM UTC, comment #4: 

Not sure why this was marked "Fixed" and "1.23.0".

We need a French speaker to supply or confirm correct French wording for this item.  It's small and easy, n'est ce pas&nbsp;?

G. Branden Robinson <gbranden>
Project AdministratorIn charge of this item.
Thu 11 Feb 2021 02:35:53 AM UTC, comment #3: 

The first change to doc/meintro_fr.me will be in the chunk of text added in commit 7ad6964d.  Specifically, the lines

utilisez la macro
.b .bl

should refer to .bl as a request rather than a macro (assuming the rest of the French translation follows the original's convention of calling all -me macros "requests").  The paragraph begins in English "This request" and in French "Cette requête," which implies to me that "requête" is the word to substitute for "macro."  Elsewhere, the document uses the article "la" before "requête," so this would probably remain unchanged, but that is guesswork.

The second change will be in the passage

Cela peut être réalisé
en utilisant les commandes
.b .(q
et
.b .)q
entourant la citation.

Here the English patch changes "commands" to "requests," which suggests to me "les commandes" should become "les requêtes" (again using the plural article appearing elsewhere in the text before "requêtes").

My ignorance of French is nearly complete, so I could be overlooking any number of language subtleties.

Dave <barx>
Project Member
Wed 10 Feb 2021 05:13:31 PM UTC, comment #2: 

Ugh, I forgot meintro.me has a French translation.  The two wording changes will need to be made there also.  I could try to figure out the changes needed based on the English version, but I might end up butchering the French, so it's probably better that someone with at least a passing familiarity with the language look at it.

Dave <barx>
Project Member
Wed 10 Feb 2021 06:55:27 AM UTC, comment #1: 

commit 84d8a288b0a685fa1447dc706e567be798ac2058
Author:     Dave Kemper <saint.snit@gmail.com>
AuthorDate: Thu Jan 21 03:57:34 2021 +0000
Commit:     G. Branden Robinson <g.branden.robinson@gmail.com>
CommitDate: Thu Feb 4 14:08:57 2021 +1100

    doc/me{intro,ref}.me: Use consistent terminology.

    Historical and modern *roff documentation is careful to exclusively use
    the term "request" for what coders more conventionally call a "command."

    doc/meref.me largely follows this practice, but slips up in a couple
    places, using "command" for *roff requests.  This patch fixes those.

    While it's at it, it fixes a few places where "request" or "command"
    erroneously refers to a macro.

    The situation in doc/meintro.me is trickier.  This document pervasively
    calls macros defined by the -me package "requests," and reserves the
    term "macro" for macros the user defines in his own -me document.  While
    not strictly accurate, this slight muddying is consistent and probably
    fine for the intended (novice) audience of this document.

    The sole exception to this consistency is text I wrote that was added in
    commit 7a83f7f50, which calls .bl a macro--technically accurate but
    inconsistent with the rest of the document's usage.  Thus this patch
    changes this word to "request."

    The one use of "command" in meintro.me is also changed to "request"
    following similar logic.

G. Branden Robinson <gbranden>
Project AdministratorIn charge of this item.
Thu 21 Jan 2021 03:57:34 AM UTC, original submission:  

Historical and modern *roff documentation is careful to exclusively use the term "request" for what coders more conventionally call a "command."

doc/meref.me largely follows this practice, but slips up in a couple places, using "command" for *roff requests.  This patch fixes those.

While it's at it, it fixes a few places where "request" or "command" erroneously refers to a macro.

The situation in doc/meintro.me is trickier.  This document pervasively calls macros defined by the -me package "requests," and reserves the term "macro" for macros the user defines in his own -me document.  While not strictly accurate, this slight muddying is consistent and probably fine for the intended (novice) audience of this document.

The sole exception to this consistency is text I wrote that was added in commit 7a83f7f50, which calls .bl a macro--technically accurate but inconsistent with the rest of the document's usage.  Thus this patch changes this word to "request."

The one use of "command" in meintro.me is also changed to "request" following similar logic.

Dave <barx>
Project Member

 

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

Attach Files:
   
   
Comment:
   

Attached Files
file #51090:  59920.fr.alternate.patch added by barx (822B - text/x-patch - Changes to sync meintro_fr.me translation with meintro.me original, plus additional minor edits)
file #51089:  59920.fr.minimal.patch added by barx (713B - text/x-patch - Changes to sync meintro_fr.me translation with meintro.me original)

 

Depends on the following items: None found

Items that depend on this one: None found

 

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

    Do you think this task is very important?
    If so, you can add your encouragement to it.
    This task has 0 encouragements so far.

    Only logged-in users can vote.

     

     

     

    Follow 12 latest changes.

    Date Changed by Updated Field Previous Value => Replaced by
    2021-06-04 barx Summary[PATCH] -me documentation terminology cleanup => [PATCH] [me] documentation terminology cleanup
    2021-03-18 barx Attached File- => Added 59920.fr.alternate.patch, #51090
    2021-03-18 barx Attached File- => Added 59920.fr.minimal.patch, #51089
    2021-03-04 gbranden StatusFixed => Need Info
        Planned Release1.23.0 => None
    2021-02-10 barx Open/ClosedClosed => Open
    2021-02-10 gbranden StatusIn Progress => Fixed
        Open/ClosedOpen => Closed
        Planned ReleaseNone => 1.23.0
    2021-02-04 gbranden StatusNone => In Progress
        Assigned toNone => gbranden
    2021-01-21 barx Attached File- => Added me_terminology_cleanup.patch, #50759

    Back to the top


    Powered by Savane 3.6