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

[G. Branden Robinson]

Update of bug #53547 (project groff):

 Planned Release:None => 1.22.4 

___

Follow-up Comment #8:


commit dbfa0b757b920eb6c44a2fd319180f525b138a28
Author: G. Branden Robinson 
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 




___

Reply to this item at:

  

___
Message sent via Savannah
https://savannah.gnu.org/

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

[Bjarni Ingi Gislason]

Follow-up Comment #7, bug #53547 (project groff):

  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.

___

Reply to this item at:

  

___
  Message sent via/by Savannah
  http://savannah.gnu.org/


___
bug-groff mailing list
bug-groff@gnu.org
https://lists.gnu.org/mailman/listinfo/bug-groff

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

[Ingo Schwarze]

Hi Branden,

G. Branden Robinson wrote on Sun, Apr 22, 2018 at 02:42:27AM -0400:

> Follow-up Comment #6, bug #53547 (project groff):
> 
> 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.

I don't have the slightest idea what Bjarni thought when
proposing this change:

@@ -276,7 +276,10 @@
 in the order shown.
 .
 .TP
-.B .RP [no]
+\#.B .RP [no]
+\!.B .RP \c
+\# The next argument must be longer than the indent from .TP (8n)
+.RB [ no ]\ \ \ \ \ \"
 Specifies the report format for your document.
 .
 The report format creates a separate cover page.

It looks totally bogus to me on more than one level.  You most
certainly do not want any of "\#", "\!", "\ \ \ " in a manual
page and you also most certainly do not want

  .B anything \c
  .RB anything

> 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?

The rendering of

  .TP
  .BR ".RP " [ no ]
  Specifies the report format for your document.

in the context of groff_ms(7) is identical in groff and mandoc.
(Otherwise, it would be a bug in mandoc.  :)


Only the SYNOPSIS differs; groff renders:

   groff -ms [option ...] [input-file ...]

   groff -m ms [option ...] [input-file ...]

Mandoc renders:

   [option ...] [input-file ...] [option ...] [input-file ...]

because it does not implement the .SY macro.  That macro is exceedingly
rare in practice.  I scanned all ten thousand third-party software
packages in the OpenBSD ports tree and could not find a single use
outside groff itself.

I think the macro should be deleted, first from the few groff manual
pages using it, then from man-ext.tmac.  It is a half-hearted attempt
at sneaking semantic markup into a purely presentational language
that (forunately) never got traction anywhere.

Yours,
  Ingo

___
bug-groff mailing list
bug-groff@gnu.org
https://lists.gnu.org/mailman/listinfo/bug-groff

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

[G. Branden Robinson]

Update of bug #53547 (project groff):

 Open/Closed:Open => Closed 


___

Reply to this item at:

  

___
  Message sent via/by Savannah
  http://savannah.gnu.org/


___
bug-groff mailing list
bug-groff@gnu.org
https://lists.gnu.org/mailman/listinfo/bug-groff

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

[G. Branden Robinson]

Update of bug #53547 (project groff):

  Status: In Progress => Fixed  


___

Reply to this item at:

  

___
  Message sent via/by Savannah
  http://savannah.gnu.org/


___
bug-groff mailing list
bug-groff@gnu.org
https://lists.gnu.org/mailman/listinfo/bug-groff

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

[G. Branden Robinson]

Follow-up Comment #6, bug #53547 (project groff):

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?


___

Reply to this item at:

  

___
  Message sent via/by Savannah
  http://savannah.gnu.org/


___
bug-groff mailing list
bug-groff@gnu.org
https://lists.gnu.org/mailman/listinfo/bug-groff

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

[G. Branden Robinson]

Update of bug #53547 (project groff):

Severity:1 - Wish => 2 - Minor  


___

Reply to this item at:

  

___
  Message sent via/by Savannah
  http://savannah.gnu.org/


___
bug-groff mailing list
bug-groff@gnu.org
https://lists.gnu.org/mailman/listinfo/bug-groff

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

[G. Branden Robinson]

Follow-up Comment #5, bug #53547 (project groff):

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,


___

Reply to this item at:

  

___
  Message sent via/by Savannah
  http://savannah.gnu.org/


___
bug-groff mailing list
bug-groff@gnu.org
https://lists.gnu.org/mailman/listinfo/bug-groff

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

[G. Branden Robinson]

Follow-up Comment #4, bug #53547 (project groff):

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

___

Reply to this item at:

  

___
  Message sent via/by Savannah
  http://savannah.gnu.org/


___
bug-groff mailing list
bug-groff@gnu.org
https://lists.gnu.org/mailman/listinfo/bug-groff

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

[Werner LEMBERG]

Follow-up Comment #3, bug #53547 (project groff):

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'.

___

Reply to this item at:

  

___
  Message sent via/by Savannah
  http://savannah.gnu.org/


___
bug-groff mailing list
bug-groff@gnu.org
https://lists.gnu.org/mailman/listinfo/bug-groff

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

[G. Branden Robinson]

Follow-up Comment #2, bug #53547 (project groff):


-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.

___

Reply to this item at:

  

___
  Message sent via/by Savannah
  http://savannah.gnu.org/


___
bug-groff mailing list
bug-groff@gnu.org
https://lists.gnu.org/mailman/listinfo/bug-groff

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

[G. Branden Robinson]

Update of bug #53547 (project groff):

  Status:None => In Progress

___

Follow-up 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.]

___

Reply to this item at:

  

___
  Message sent via/by Savannah
  http://savannah.gnu.org/


___
bug-groff mailing list
bug-groff@gnu.org
https://lists.gnu.org/mailman/listinfo/bug-groff

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

[Ingo Schwarze]

Update of bug #53547 (project groff):

Category:None => Macro - ms 
Severity:  3 - Normal => 1 - Wish   
 Assigned to:None => gbranden   


___

Reply to this item at:

  

___
  Message sent via/by Savannah
  http://savannah.gnu.org/


___
bug-groff mailing list
bug-groff@gnu.org
https://lists.gnu.org/mailman/listinfo/bug-groff

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

[G. Branden Robinson]

Caveat: I haven't made a commit in a few months, so apply due weight to
my opinion.

At 2018-04-15T04:08:28+0200, Ingo Schwarze wrote:
> Bjarni,
> 
> i don't have the time to read your long-winded rants, and i doubt
> that others have.

Personally I appreciate the amount of spit and polish Bjarni is willing
to apply to the groff man pages.  True, there are things he could do to
package his concerns more palatably, like not using the structured output of 
what I
assume is a personal style checker as the primary body of his report,
and by not having far and away the groff development community's longest
.signature file.

The former is best recast for reading by mere English-speaking humans
who communicate through conversation, since we do not have an AI agent
to process the bug backlog.  The latter I regard as a personal
idiosyncrasy.

> Please go away.
> 
> The point of my reply to this ticket was that wading through such
> tickets to find whether anything of value is hidden in them is not
> worth the time and effort it requires.  Quite obviously, that implies
> that explaining in detail why the aspects of the ticket that are
> bogus, unimportant, and wrong are so is even less worth the time
> it would require.  Explaining it is also useless because it's obvious
> to anyone with sufficient experience.

Ingo, maybe you could skip over all reports from bjarnig when you're
going over the bug list in Savannah?  When I draw my "git push" sword
again I will be willing to triage the reports he files.  On balance, I
find his reports a benefit to the project, even if things don't always
turn out his way (or mine).

-- 
Regards,
Branden


signature.asc
Description: PGP signature
___
bug-groff mailing list
bug-groff@gnu.org
https://lists.gnu.org/mailman/listinfo/bug-groff

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

[Ingo Schwarze]

Bjarni,

i don't have the time to read your long-winded rants, and i doubt
that others have.

Please go away.

The point of my reply to this ticket was that wading through such
tickets to find whether anything of value is hidden in them is not
worth the time and effort it requires.  Quite obviously, that implies
that explaining in detail why the aspects of the ticket that are
bogus, unimportant, and wrong are so is even less worth the time
it would require.  Explaining it is also useless because it's obvious
to anyone with sufficient experience.

  *
  I'm hereby asking for the OK of another project member to close
  this ticket as "Closed/Invalid".
  *

I'm including the relevant part of my original mail for easier
reference:

  The "Details:" section of your report is inscrutable gibberish,
  some of the content - as far as it can be guessed what it is
  supposed to mean - is obvious bogus advice, some of it is of
  very little importance (like the Oxford comma), and the patch
  is obviously not fit for committing.

Ingo

___
bug-groff mailing list
bug-groff@gnu.org
https://lists.gnu.org/mailman/listinfo/bug-groff

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

[Bjarni Ingi Gislason]

On Mon, Apr 02, 2018 at 07:42:31PM +0200, Ingo Schwarze wrote:
> Please stop clobbering the bugtracker with low-quality reports of
> this kind.

  What is this low-quality?  Explain.

  What is "this kind"?

  I am not doing this (clobbering).
Direct your complaint to the right addresses,
namely your fellow maintainers,
who keep and maintain the bug tracker in the same state.

>The "Details:" section of your report is inscrutable
> gibberish, some of the content - as far as it can be guessed what
> it is supposed to mean - is obvious bogus advice, some of it is of
> very little importance (like the Oxford comma), and the patch is
> obviously not fit for committing.
> 

  This only means to me that you do not understand, even that you are
not willing to understand.

  I use a "higher" level language, that you can't comprehend?

  What is this bogus advise?

  Why may, shall, must reports only be about "important" issues?

  What is this "importance"?

  What is not "important" but valid?

  Who and what decides what is what?

  According to what rules?

  Where is all that documented, demanded, explained?

  Why is the patch not "fit" for committing?
  Then you simply do not know how to do (adjust) it.

  Why can't you do anything about it (except complaining without any
clear, concrete information).

  I there anything in the report that is more likely false than true?

  What information is missing in the report?

  What do you think is the purpose of bug reports?

  What is is not?

##

  The patch is totally OK.  You have not demonstrated that it is not!

> Such reports are not helpful at all.  Triaging them causes more
> work than it is worth, and we simply don't have the time to do such
> triage work.

  The may not help you with a mission.  What is this mission?

  There is no need for any "triaging".  Why is that needed?

  The reasons are all in the report.
Some are not "hand written", but anyone with a common sense can infer
the meaning.
And it is allowed to assume that maintainers have a basic knowledge to
understand the report and be able to find their lacking knowledge on its
own (or ask questions if it is not clear).

>  In fact, the most severe problem the bug tracker
> currently has, limiting its usefulness, is that it is hard to find
> the relevant tickets among lots of noise.
> 

  Your problem is that you do not know what relevant is, and why it
should, must, has to be needed.

  Why do you not find the "relevant" (to whom?) tickets?

  Obviously the needed information is not there, and that is because the
maintainers have not added that information to the bug tracker.

  So this is not my doing, but of your fellow maintainers.

  Why do you not ask them, blame them?

  So your attitude forbids you to commit patches if they do not follow
some demands of your own.

  SO YOU ARE A (BIG) PART OF YOUR PROBLEM!

> I feel tempted to close this ticket without even looking at the details.
> 

That simply shows me that you are unfit for the job.

> Please only open a ticket in the future if you:
> 
>  (1) Provide a very concise and clear hand written description.
>  (2) Focus on one problem at a time.
>  (3) The problem is really important.
> 

  These rules are for CODE (except the "hand written" and "important"
part), not necessarily for text!

1) The descriptions are all there, may not be exactly in the form you
(seem to) demand.

  "Hand written" is never a necessity, even if you don't understand
output from a programme.

  File a bug against the programme.  And do not forget to comply to all
your own demands, what a bug report has to, shall, must, contain.

2)  Applies to code, not necessarily to text

  If there is one report for every "problem", then that will "clobber"
the bug tracker.
So fulfilling both of your demands is a CATCH-22.

  I am not aware of any rule, that only allows some kind of reports to
be sent.  Where are those rules?

> Others who are better at reporting may slightly stretch these rules
> and still be helpful, but you have amply demonstrated in the past
> that you *must* follow these rules very strictly, or what you do
> is more of a nuisance than of any help.
> 

  I must not.
That is in your imagination.
You just demonstrate, that you want to be spoon-fed, do not want to
think, do not want to learn, do not want to understand, do not want
"groff" getting improved (by "others").


  Why are valid bug reports a nuisance to you (and other maintainers)?

  What are bug reports supposed to help you (plural) with?

  This simply shows me that you want control, need control over what
others do, are allowed to do.

  Groff is free software, not a slaved one, or you want it to be your
servant.
  Groff is part of the GNU operation system, which is a free
software --- that is, it respects users' freedom.

  You (singular) and other maintainers DO ACTIVELY NOT RESPECT THAT.

  You have at least an opportunity to explain your behaviour truly and
honestly.

  You (plural) show me, 

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

[Ingo Schwarze]

Please stop clobbering the bugtracker with low-quality reports of
this kind.  The "Details:" section of your report is inscrutable
gibberish, some of the content - as far as it can be guessed what
it is supposed to mean - is obvious bogus advice, some of it is of
very little importance (like the Oxford comma), and the patch is
obviously not fit for committing.

Such reports are not helpful at all.  Triaging them causes more
work than it is worth, and we simply don't have the time to do such
triage work.  In fact, the most severe problem the bug tracker
currently has, limiting its usefulness, is that it is hard to find
the relevant tickets among lots of noise.

I feel tempted to close this ticket without even looking at the details.

Please only open a ticket in the future if you:

 (1) Provide a very concise and clear hand written description.
 (2) Focus on one problem at a time.
 (3) The problem is really important.

Others who are better at reporting may slightly stretch these rules
and still be helpful, but you have amply demonstrated in the past
that you *must* follow these rules very strictly, or what you do
is more of a nuisance than of any help.


Bjarni Ingi Gislason wrote on Mon, Apr 02, 2018 at 12:56:23PM -0400:

> URL:
>   
> 
>  Summary: [PATCH] tmac/groff_ms.7.man: Change bold '[' and ']'
> to roman and other tidying
>  Project: GNU troff
> Submitted by: bjarniig
> Submitted on: Mon 02 Apr 2018 04:56:21 PM UTC
> Category: None
> Severity: 3 - Normal
>   Item Group: Documentation
>   Status: None
>  Privacy: Public
>  Assigned to: None
>  Open/Closed: Open
>  Discussion Lock: Any
>  Planned Release: None

___
bug-groff mailing list
bug-groff@gnu.org
https://lists.gnu.org/mailman/listinfo/bug-groff

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

[Bjarni Ingi Gislason]

URL:
  

 Summary: [PATCH] tmac/groff_ms.7.man: Change bold '[' and ']'
to roman and other tidying
 Project: GNU troff
Submitted by: bjarniig
Submitted on: Mon 02 Apr 2018 04:56:21 PM UTC
Category: None
Severity: 3 - Normal
  Item Group: Documentation
  Status: None
 Privacy: Public
 Assigned to: None
 Open/Closed: Open
 Discussion Lock: Any
 Planned Release: None

___

Details:

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.




___

File Attachments:


---
Date: Mon 02 Apr 2018 04:56:21 PM UTC  Name:
0001-tmac-groff_ms.7.man-Change-bold-and-to-roman-and-other.txt  Size: 9KiB  
By: bjarniig
[PATCH] tmac/groff_ms.7.man: Change bold '[' and ']' to roman and other
tidying


___

Reply to this item at:

  

___
  Message sent via/by Savannah
  http://savannah.gnu.org/


___
bug-groff mailing list
bug-groff@gnu.org
https://lists.gnu.org/mailman/listinfo/bug-groff