bugGNU roff - Bugs: bug #52444, Half the man pages save and...

 
 

bug #52444: Half the man pages save and restore compatibility mode like macro packages

Submitter:  G. Branden Robinson <gbranden>
Submitted:  Sun 19 Nov 2017 05:37:28 AM UTC
   
 
Category:  General 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

Mon 18 Jun 2018 07:38:37 AM UTC, comment #6: 

Fixed in 518577df68d021335f49e227f8866f4b98e947ca.


    man pages: Comment compatibility-mode switching.

    The '.do' and '.cp' requests (both groffisms) are some of the more
    obscure features of groff's own man page corpus.  Consequently, they get
    cargo-culted around, within and outside groff.  Thanks to Werner Lemberg
    for the discussion, which revealed (to me) that groff ships with
    compatibility mode on by default on Solaris 10 and 11.


G. Branden Robinson <gbranden>
Group administrator
Tue 21 Nov 2017 05:55:04 AM UTC, comment #5: 

Okay, I've fixed the 2 pages that were compatibility-mode broken, and enhanced my ugly local regression-testing script to check compatibility mode.

To address this bug, I now propose to do the following:

1) See if any of the pages currently saving and restoring compatibility mode can get along without it, since it is a down-in-the-weeds kind of thing as Ingo noted.  By this I simply mean seeing if any pages as currently written are doing a .cp 0 when they don't need to.

2) Add a boilerplate comment to this procedure in all of the man pages that do do it.  So that readers understand and with luck no one will file a bug like this nor break compatibility mode in pages in the future.

As Steffan noted, I will probably do (2) with a sed script.  :)

Any objections?

G. Branden Robinson <gbranden>
Group administrator
Mon 20 Nov 2017 09:41:27 AM UTC, comment #4: 

Compatibility mode on is the default if groff gets built on Solaris.  Otherwise zillions of man pages are not correctly formatted – at least that is the situation with Solaris 10 and 11.

Werner LEMBERG <wl>
Group administrator
Mon 20 Nov 2017 09:00:55 AM UTC, comment #3: 

Okay, Werner's hint to cast git blame led me to the answer.

https://savannah.gnu.org/bugs/index.php?44708

I don't understand how or why the original bug submitter had compatibility mode on by default, but that may not matter.

If I "git log 8ac03ed2a5e1672754749df87c1742e7d161e32c" I see a major effort by Werner to make all the man pages work in compatibility mode.  Rather than rewrite them all in a portable subset, this trick was done.

A quick check reveals that a couple of pages have problems.  One I introduced on 2 November, and I'll commit a fix for it after I've done some tests.

The other one was around even back then.  What's the best way to fix it?


$ for M in $(find -name "*man"); do ./test-groff -C -t -p -mandoc $M >/dev/null; done
./src/preproc/soelim/soelim.1.man:2: warning: macro 'ms' not defined
$ git blame ./src/preproc/soelim/soelim.1.man |head
d12c7ba3c src/preproc/soelim/soelim.man   (Werner LEMBERG      2004-08-07 04:52:54 +0000   1) '\" p
c1886fcaa src/preproc/soelim/soelim.man   (Bernd Warken        2014-09-18 01:41:01 +0200   2) .mso pic.tmac
c1886fcaa src/preproc/soelim/soelim.man   (Bernd Warken        2014-09-18 01:41:01 +0200   3) .TH @G@SOELIM @MAN1EXT@ "@MDATE@" "Groff Version @VERSION@"
c1886fcaa src/preproc/soelim/soelim.man   (Bernd Warken        2014-09-18 01:41:01 +0200   4) .SH NAME
c1886fcaa src/preproc/soelim/soelim.man   (Bernd Warken        2014-09-18 01:41:01 +0200   5) @g@soelim \- interpret .so requests in groff input
c1886fcaa src/preproc/soelim/soelim.man   (Bernd Warken        2014-09-18 01:41:01 +0200   6) .
c1886fcaa src/preproc/soelim/soelim.man   (Bernd Warken        2014-09-18 01:41:01 +0200   7) .
8ac03ed2a src/preproc/soelim/soelim.man   (Werner Lemberg      2015-04-03 16:55:03 +0200   8) .do nr groff_C \n[.C]
8ac03ed2a src/preproc/soelim/soelim.man   (Werner Lemberg      2015-04-03 16:55:03 +0200   9) .cp 0
8ac03ed2a src/preproc/soelim/soelim.man   (Werner Lemberg      2015-04-03 16:55:03 +0200  10) .


And here's my patch for the other problem:


diff --git a/contrib/gperl/gperl.1.man b/contrib/gperl/gperl.1.man
index f6f341a2..818e4cd1 100644
--- a/contrib/gperl/gperl.1.man
+++ b/contrib/gperl/gperl.1.man
@@ -267,7 +267,7 @@ generates a
 storage line
 .RS
 .EX
-\fB.ds \fIvar_name content
+.BI .ds " var_name content"
 .EE
 .RE
 .
@@ -276,7 +276,7 @@ In
 the following groff command is generated
 .RS
 .EX
-\fB.nr \fIvar_name content
+.BI .nr " var_name content"
 .EE
 .RE
 .






G. Branden Robinson <gbranden>
Group administrator
Sun 19 Nov 2017 05:24:04 PM UTC, comment #2: 

Even if there used to be some reason in the past, the two snippets look like providing a bad example, and it seems desirable to get rid of them.  Manual pages ought to avoid fooling around with low-level internals.

Ingo Schwarze <schwarze>
Group Member
Sun 19 Nov 2017 06:02:10 AM UTC, comment #1: 

I no longer remember, sorry – maybe `git blame' brings some more info...

Werner LEMBERG <wl>
Group administrator
Sun 19 Nov 2017 05:37:28 AM UTC, original submission:  

About half (29 of 62) in-tree man pages do some tomfoolery like this:


$ grep -n -C 1 -F .cp ./src/utils/hpftodit/hpftodit.1.man
7-.do nr groff_C \n[.C]
8:.cp 0
9-.
--
372-.
373:.cp \n[groff_C]
374-.


What is the point of doing this in a man page?  That's a "terminal" document, not something that's going to get sourced by another document.

Is this something cargo-culted in?  Or is there a good reason for it, and the other 33 man pages should be following suit?


$ grep -lF .cp $(find -name "*.man")
./src/utils/hpftodit/hpftodit.1.man
./src/roff/groff/groff.1.man
./src/devices/grodvi/grodvi.1.man
./src/devices/grops/grops.1.man
./src/devices/grotty/grotty.1.man
./src/devices/gropdf/gropdf.1.man
./src/preproc/preconv/preconv.1.man
./src/preproc/tbl/tbl.1.man
./src/preproc/soelim/soelim.1.man
./src/preproc/eqn/eqn.1.man
./src/preproc/pic/pic.1.man
./src/preproc/grn/grn.1.man
./contrib/hdtbl/groff_hdtbl.7.man
./contrib/mm/groff_mm.7.man
./contrib/mm/groff_mmse.7.man
./contrib/pdfmark/pdfroff.1.man
./contrib/mom/groff_mom.7.man
./contrib/chem/chem.1.man
./man/groff_tmac.5.man
./man/groff_out.5.man
./man/groff_diff.7.man
./man/groff_char.7.man
./man/groff.7.man
./man/roff.7.man
./man/groff_font.5.man
./tmac/groff_trace.7.man
./tmac/groff_ms.7.man
./tmac/groff_man.7.man
./tmac/groff_www.7.man


G. Branden Robinson <gbranden>
Group administrator

 

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

Attach Files:
   
   
Comment:
   

No files currently attached

 

Depends on the following items: None found

Items that depend on this one: None found

 

Carbon-Copy List
  • -email is unavailable- added by schwarze (Posted a comment)
  • -email is unavailable- added by wl (Posted a comment)
  • -email is unavailable- added by gbranden (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 7 latest changes.

    Date Changed by Updated Field Previous Value => Replaced by
    2022-06-15 gbranden CategoryNone General
    2018-06-18 gbranden Open/ClosedOpen Closed
    2018-06-18 gbranden Planned ReleaseNone 1.22.4
    2017-12-14 gbranden Severity3 - Normal 2 - Minor
        StatusNeed Info Fixed
    2017-11-20 gbranden StatusNone Need Info
        Assigned toNone gbranden

    Back to the top

    Powered by Savane 3.13-4448.
    Corresponding source code