bugGNU roff - Bugs: bug #53547, [PATCH] tmac/groff_ms.7.man:...

 
 

bug #53547: [PATCH] tmac/groff_ms.7.man: Change bold '[' and ']' to roman and other tidying

Submitter:  Bjarni Ingi Gislason <bjarniig>
Submitted:  Mon 02 Apr 2018 04:56:21 PM UTC
   
 
Category:  Macro ms Severity:  2 - Minor
Item Group:  Documentation Status:  Fixed
Privacy:  Public Assigned to:  gbranden
Open/Closed:  Closed Planned Release:  1.22.4
* Mandatory Fields

Add a New Comment Rich Markup
   

Jump to the original submission

Sat 01 Apr 2023 02:58:19 PM UTC, comment #8: 


commit dbfa0b757b920eb6c44a2fd319180f525b138a28
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
Date:   Sun Apr 22 02:38:52 2018 -0400

    groff_ms(7): Make style fixes.

    * Escape hyphens used as minus signs or embedded in macro parameters
      (see SN-STYLE, SN-DOT, and SN-NO-DOT).
    * Render option brackets in roman, not bold, in macro descriptions.
    * Use paired directional double quotes to clarify use-versus-mention
      scenarios.
    * Remove spurious \- from the name of the ms macros (they're not the
      "-ms" macros).
    * Fix subject/verb agreement.  Two things do not "denotes" something.
    * Stop captializing a sentence following a colon.
    * Use the Oxford comma.
    * Remove unnecessary commas from dependent clauses.
    * Make minor tweaks to phrasing.
    * Wrap one long line.

    Based on changes suggested by Bjarni Ingli Gislason.

    Fixes bug https://savannah.gnu.org/bugs/index.php?53547.

    Signed-off-by: G. Branden Robinson <g.branden.robinson@gmail.com>


G. Branden Robinson <gbranden>
Group administrator
Mon 23 Apr 2018 11:38:49 PM UTC, comment #7: 

  I used ".it" in the my macros (I and B), not ".itc".
I have changed that "back".

  mandoc has only a issue with the transparent indicator line.

Bjarni Ingi Gislason <bjarniig>
Sun 22 Apr 2018 06:42:27 AM UTC, comment #6: 

I did not find any need for this:


\# The next argument must be longer than the indent from .TP (8n)


or the spaces they refer to, nor for the transparent line indicators.  Things seem to be rendering fine both to the utf8 and PDF output devices.  (The underlying changes involving the font style used for option brackets and similar, are legitimate.)

Is mandoc doing something differently?

G. Branden Robinson <gbranden>
Group administrator
Sun 22 Apr 2018 12:12:36 AM UTC, comment #5: 

The lack of sufficient context in the diff got me.  The situation is simpler; it's not a "de-dent", but a normal hanging indent for which we have a standard English term in typography.  The nonce word is still useful as a mnemonic for the macro.  I have the following change pending.


@@ -426,7 +426,8 @@ or
 .PP
 The
 .B XP
-macro produces an exdented paragraph.
+macro produces an \(lqexdented\(rq paragraph; that is, one with a
+hanging indent.
 .
 The first line of the paragraph begins at
 the left margin,


G. Branden Robinson <gbranden>
Group administrator
Sat 21 Apr 2018 10:10:40 PM UTC, comment #4: 

It makes sense that where English has 0 standard words for a concept, German would have two.

G. Branden Robinson <gbranden>
Group administrator
Sat 21 Apr 2018 02:23:47 PM UTC, comment #3: 

In German, there are actually two words for that: `einrücken' und `ausrücken'. :-)

I suggest to add an explanation in parentheses in case native English speakers don't understand `exdent'.

Werner LEMBERG <wl>
Group administrator
Sat 21 Apr 2018 11:51:05 AM UTC, comment #2: 


-macro produces an exdented paragraph.
+macro produces an extended paragraph.


The above change is spurious.  "Exdented" is a nonce word indicating a negative indent, or left indent.  Some people use the term "dedented" for this.  As far as I know there is no standard term.

G. Branden Robinson <gbranden>
Group administrator
Sat 21 Apr 2018 11:32:47 AM UTC, comment #1: 

I concur with the following classes of change:

1. Change - to \- if it means a minus sign.

2. Use a macro to change to the italic font, instead of \fI [1], if possible.  The macros have the italic corrections, but "\c" removes them or add the italic corrections.

3. Add a comma before "and", "or", or "nor" if a series contains three or more words. [In other words, use the Oxford comma.]

4. Change '[' and ']' from bold to roman. [In command synopses, yes--only literals should be rendered in bold.]

I do not concur with the following class of change:

5. Surround a block of comments with the macros ".ig" and "..".  [In my opinion, the groff man pages should become exemplars of good man page style, and while .ig and .. are not much harder to understand than "#if 0" and a corresponding "#endif", that little bit makes a difference.  Comment leaders are nearly universal in programming languages, and require only a finite automaton to parse, instead of a pushdown automaton or worse.  I've taught my Vim installation how to recognize *roff comments, so even reflowing text is no longer a problem for me.]

Changes I'm still evaluating:

6. Arguments to the macro ".TP" (uses '.itc') [We went back and forth a whole lot in this, didn't we?]

7. Use '\!' and '\c' to use two input lines as a one line of arguments. [I need to brush up on \# vs. \! and the interaction each has with \c.]

G. Branden Robinson <gbranden>
Group administrator
Mon 02 Apr 2018 04:56:21 PM UTC, original submission:  

tmac/groff_ms.7.man: Change bold '[' and ']' to roman and other tidying

Input file is groff_ms.7.man

mandoc: groff_ms.7.man:1181:2: WARNING: skipping paragraph macro: LP empty

#######

Test nr. 17:

Change - to \- if it means a minus sign.

247:FPS Point size next footnote \[rs]n[PS]-2

#####

Test nr. 20:

Use a macro to change to the italic font, instead of \fI [1], if
possible.
The macros have the italic corrections, but "\c" removes them
  or
add the italic corrections.
[1] man-pages(7)

945:\&.DS I [\fIindent\fP] \&.ID T{

#####

Test nr. 30:

Surround a block of comments with the macros ".ig" and "..".
The .\" (\#) at the beginning of each line is then not needed.
Makes it easier to add and remove text and adjust length of lines.

NO PATCH

10:.\" ====================================================================
11:.\" Legal Terms
12:.\" ====================================================================
13:.\"
14:.\" Copyright (C) 1989-2014 Free Software Foundation, Inc.
15:.\"
16:.\" Permission is granted to make and distribute verbatim copies of this
17:.\" manual provided the copyright notice and this permission notice are
18:.\" preserved on all copies.
19:.\"
20:.\" Permission is granted to copy and distribute modified versions of
21:.\" this manual under the conditions for verbatim copying, provided that
22:.\" the entire resulting derived work is distributed under the terms of
23:.\" a permission notice identical to this one.
24:.\"
25:.\" Permission is granted to copy and distribute translations of this
26:.\" manual into another language, under the above conditions for
27:.\" modified versions, except that this permission notice may be
28:.\" included in translations approved by the Free Software Foundation
29:.\" instead of in the original English.
1804:.\" Local Variables:
1805:.\" mode: nroff
1806:.\" End:
1807:.\" vim: set filetype=groff:

#####

Test nr. 40:

Add a comma before "and", "or", or "nor" if a series contains three or
more words

1708:The following conventions are used for names of macros, strings and

#####

  Extra changes

  Arguments to the macro ".TP" (uses '.itc'):

  Change '[' and ']' from bold to roman.

  Use '\!' and '\c' to use two input lines as a one line of arguments.

Bjarni Ingi Gislason <bjarniig>

 

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

Attach Files:
   
   
Comment:
   

Attached Files
file #43771:  0001-tmac-groff_ms.7.man-Change-bold-and-to-roman-and-other.txt added by bjarniig (9KiB - text/plain - [PATCH] tmac/groff_ms.7.man: Change bold '[' and ']' to roman and other tidying)

 

Depends on the following items: None found

Items that depend on this one: None found

 

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

    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 9 latest changes.

    Date Changed by Updated Field Previous Value => Replaced by
    2023-04-01 gbranden Planned ReleaseNone 1.22.4
    2018-04-22 gbranden Open/ClosedOpen Closed
    2018-04-22 gbranden StatusIn Progress Fixed
    2018-04-22 gbranden Severity1 - Wish 2 - Minor
    2018-04-21 gbranden StatusNone In Progress
    2018-04-15 schwarze CategoryNone Macro ms
        Severity3 - Normal 1 - Wish
        Assigned toNone gbranden
    2018-04-02 bjarniig Attached File- Added 0001-tmac-groff_ms.7.man-Change-bold-and-to-roman-and-other.txt, #43771

    Back to the top

    Powered by Savane 3.13-02a9.
    Corresponding source code