bugGNU roff - Bugs: bug #44707, [grog] much too strict about file...

 
 

bug #44707: [grog] much too strict about file name extensions for man pages

Submitter:  None
Submitted:  Fri 03 Apr 2015 12:56:26 AM UTC
   
 
Category:  Utilities Severity:  3 - Normal
Item Group:  Incorrect behaviour Status:  Fixed
Privacy:  Public Assigned to:  gbranden
Open/Closed:  Closed Planned Release:  1.23.0
* Mandatory Fields

Add a New Comment Rich Markup
   

Mon 28 Jun 2021 04:46:37 AM UTC, comment #3: 


commit 2ba599980081fb700e09c10abcc136657ae93070
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
Date:   Mon Jun 28 14:28:32 2021 +1000

    [grog]: Heavily refactor.

    * src/utils/grog/grog.pl:
      - Drop import of unused module `Data::Dumper`.
      - Drop unused scalars `Sp` and `correct_tmac`.
      - Simplify determination of version number.  Drop hash `at_at` which
        only stored one key, `GROFF_VERSION`.  Initialize scalar
        `groff_version` to "DEVELOPMENT".  Rename scalar `before_make` to
        `in_source_tree` and initialize to zero.  Update `groff_version`
        with Automake-determined version variable if it is defined (i.e.,
        grog is not running in an unbuilt source tree).
      - Drop unused `Mparams` list.  Replace it with new list
        `requested_package`, which stores the arguments to any grog `-m`
        options specified by the user.
      - Rename many objects so that I, and others, can better comprehend
        their purpose, and for consistent letter casing.
        . @Command -> @command
        . @devices -> @device
        . $Prog -> $program_name
        . %macros -> %user_macro
        . $have_any_valid_args -> $have_any_valid_arguments
        . &handle_args -> &process_arguments
        . &handle_whole_files -> &process_input
        . @preprograms -> @preprocessor
        . &make_groff_device -> &infer_device
        . &make_groff_preproc -> &infer_preprocessors
        . &make_groff_tmac_man_ms -> &infer_man_or_ms_package
        . &make_groff_line_rest -> &construct_command
      - Drop many unused keys in `Groff` hash.
      - Add new lists, `macro_ms`, `macro_man`, and `macro_man_or_ms` to
        support new scoring technique to disambiguate input documents
        between these two packages.
      - Append the foregoing 3 lists to new list `standard_macro`, and add
        these as keys to the `Groff` hash.
      - Add new list `main_package` to keep track of full-service package
        names.
      - Add new scalars `man_score`, `ms_score`, and `inside_tbl_table` to
        aid disambiguation of .TH macro calls and the many macro names
        shared between man(7) and ms(7).

      (process_arguments): Strip '-m' off of argument before storing the
      remainder in `@requested_package`.

      (do_line): Detect .TH macro call even if white space occurs between
      the control character and the macro name.

      (do_line): Inflate `$man_score` by 100 if .TH is the first macro call
      seen in a document.

      (do_line): Fix bug; clear `$before_first_command` in correct
      scope--after any macro call, not just if we saw a .TH as the first
      macro call.

      (do_line): Set `$inside_tbl_table` when we see a .TS call.

      (do_line): Clear `$inside_tbl_table` when we see a .TE call.  Also
      increment `$Groff{'tbl')' again, increasing the "score" of tbl(1)
      usage evidence.

      (do_line): Drop a lot of code that manually increments %Groff keys
      corresponding to man and ms macros.  This is now done differently and
      elsewhere.

      (do_line): Drop "P" from list of characteristic mm(7) macros.

      (do_line): Simplify matching of mom(7) macros (match $command, not
      $line).  Extend list of characteristic mom(7) macros.

      (do_line): Increment $Groff{$key} if $key is in @standard_macro.

      (infer_man_or_ms_package): Rewrite.  Compute a score for each package
      by counting occurrences of their characteristic macros.  If both have
      a score of zero, assume that the input is a raw roff document.  If the
      scores are equal (doc/webpage.ms, startlingly, comes within 1 point of
      a tied score), infer ms(7) if 'TH' was never called, and if it was,
      issue a diagnostic advising user to supply a disambiguating `-m`
      option.  Otherwise, the scores are unequal, and infer the package of
      the winner.  Set scalar `inferred_main_package` instead of pushing
      `-m` options onto `@m`.

      (infer_macro_packages): Set scalar `inferred_main_package` instead of
      pushing `-m` options onto `@m`.  Explicitly return 0 if we fall off
      the end of the function.

      (construct_command): Rewrite handling of -m options.  Add new list
      `msupp` to store supplementary (non-main) macro package arguments.  If
      a full-service package was explicitly requested, it had better not
      clash with what we inferred.  If it does, explicitly unset
      $inferred_main_package so that the -m arguments are placed in the same
      order that the user gave them; caveat dictator.  If `--run` option was
      given, just print the command; don't preface it with __FILE__ and
      __LINE__ noise.

      - Remove comments documenting shared variables used by subroutines.
        These are far from useless but too tedious to keep up to date while
        the code is in flux.
      - Note several places for further code review or refactoring with
        "XXX" comments.
      - Add Vim modeline.

    grog now passes all its tests and correctly infers arguments for all
    in-tree groff documents (except for a known, and already documented in
    grog(1), false positive detection of soelim in soelim(1)).  This
    refactor also obviates or resolves several outstanding Savannah tickets.

    Fixes <https://savannah.gnu.org/bugs/?44707> by obviating it; grog no
    longer cares about file name extensions on man pages (or any other
    input).

    Fixes <https://savannah.gnu.org/bugs/?55302>; same.  The quality of
    diagnostic messages has been improved as well.

    Fixes <https://savannah.gnu.org/bugs/?59753>; same.

    Fixes <https://savannah.gnu.org/bugs/?59664>.  The attached patch was a
    less aggressive refactor of &do_line and %Groff.  Its author made the
    following claim for it: "With this patch, all 'man', 'me', 'mom, and
    'ms' files in the repository are correctly identified.  The only example
    of a 'mm'-file is "letter.mm", which is not recognized correctly."  As
    noted above, the present refactor achieves correct recognition of all of
    the files including letter.mm.


G. Branden Robinson <gbranden>
Group administrator
Mon 07 Jun 2021 09:49:15 PM UTC, comment #2: 

Categorizing grog bugs as Utilities, per discussion.

Dave <barx>
Group Member
Sun 06 Jun 2021 04:49:13 PM UTC, comment #1: 

I'm looking into this.  I don't understand why grog(1) is trying to police the name space of man page suffixes by refusing to run its heuristics on ones it doesn't recognize.

The more of Bernd's code I see, the fewer things I find myself capable of saying diplomatically.

G. Branden Robinson <gbranden>
Group administrator
Fri 03 Apr 2015 12:56:26 AM UTC, original submission:  

Greetings,

I'm using groff-1.22.3 on a Solaris 10 (X86_64) system and noticed
that grog(1) reports ".../grog/subs.pl 397: Unknown file name
extension ..." in some cases.

For the record, I thought I would document these cases.

From /usr/share/man, 144 cases like the following:

  Unknown file name extension /usr/share/man/man5/abort.5sql

Given that Solaris 10 has 106 separate man<sect> directories, it
probably a bug that .5sql pages (from the Sun delivered postgres) are
not in the man5sql subdirectory (but a postgres local build does
exactly the same thing).  And given no complaints for all the other
system manual pages, I'm guessing this mismatch in section names is
the cause of the warning.

Locally we compile Free, Libre, and Open Source Software with a unique
prefix for each product instance
(e.g. /pkgs/64-bit/release/<product>-<version>)

I was beginning to think while reviewing the grog(1) output for FLOSS
packages, that the warning was generated when man<sect>/<name>.<sect>
had mismatching <sect> components.

But then the following paths also report the same issue:

  /pkgs/64-bit/release/smartmontools-X.Y/man/man1m/smartctl.1m
  /pkgs/64-bit/release/smartmontools-X.Y/man/man1m/smartd.1m
  /pkgs/64-bit/release/sudo-X.Y/man/man1m/sudo.1m
  /pkgs/64-bit/release/sudo-X.Y/man/man1m/sudoedit.1m
  /pkgs/64-bit/release/sudo-X.Y/man/man1m/visudo.1m

But all the system (/usr/share/man) section 1m pages don't give this
message. So I'm unsure why I'm getting this message.

Looking at the code, handle_file_ext() seems to about issuing warnings
and making assignments to $tmac_ext. But the list of valid manual
pages extensions in the code is incredibly small.

On Solaris 10 & 11, /usr/share/man/man.cf lists the manual page
extensions presumably in search preference order. See the example
contents of this file at the end of this message, each MANSECTS= entry
is a single line comma separated value list.

I'm happy to get this message for files in the manual page trees that
are not valid manual pages, and in the FLOSS tree there are few
mistakes. But I'm at a loss as to why, for example, otherwise
seemingly valid manual pages generate this warning. Enlightenment
appreciated

Regards,
Peter Bray
Sydney, Australia

On Solaris 10 Update 11, /usr/share/man/man.cf's MANSECT contains 110 entries:

MANSECTS=1,1m,1s,1as,2,3,3c,3malloc,3nsl,3socket,3ldap,3nisdb,3resolv,3rpc,3sip,3slp,3proc,3rt,3c_db,3elf,3kvm,3kstat,3m,3mp,3mvec,3pam,3papi,3aio,3bsm,3tsol,3contract,3cpc,3sec,3secdb,3smartcard,3cfgadm,3crypt,3devid,3door,3devinfo,3lib,3libucb,3head,3nvpair,3rsm,7,7d,7fs,7i,7ipp,7m,7p,9,9e,9f,9p,9s,4,5,4b,3fm,3gen,3exacct,3sysevent,3uuid,3wsreg,3dmi,3snmp,3tnf,3volmgt,3mail,3layout,3ext,3picl,3picltree,3pool,3project,3perl,3lgrp,3sasl,3scf,3dat,3hbaapi,3tecla,3mpapi,3commputil,1b,1c,1f,3ucb,3xnet,3curses,3plot,3xcurses,3dlpi,3gss,6,3tiff,3fontconfig,3xtsol,3mlib,3c++,3cc4,3f,3p,3pi,3rtc,8,l,n

On Solaris 11 Update 2, /usr/share/man/man.cf's MANSECT contains 145 entries:

MANSECTS=1,1m,1s,1as,1t,2,3,3c,3malloc,3nsl,3socket,3ldap,3nisdb,3resolv,3rpc,3sip,3slp,3proc,3c_db,3elf,3kvm,3kstat,3m,3mp,3mvec,3pam,3papi,3tsol,3contract,3cpc,3sec,3cfgadm,3crypt,3devid,3devinfo,3lib,3head,3nvpair,7,7d,7fs,7i,7ipp,7m,7p,9,9e,9f,9p,9s,4,5,4b,3gen,3exacct,3stmf,3iscsit,3sysevent,3uuid,3reparse,3dmi,3snmp,3volmgt,3mail,3layout,3ext,3fm,3fstyp,3picl,3picltree,3pool,3project,3perl,3lgrp,3sasl,3scf,3srpt,3dat,3hbaapi,3tecla,3mpapi,3fcoe,1b,1c,3xnet,3curses,3plot,3xcurses,3dlpi,3dns_sd,3gss,6,3tiff,3fontconfig,3tcl,3tk,3xtsol,3zonestat,3mlib,3c++,3cc4,3f,3p,3pi,3rtc,3rad,8,1erl,1oldap,3commputil,3libmemcached,3oldap,3pcap,3erl,4erl,1openssl,3openssl,5oldap,5openssl,6erl,7openssl,8oldap,3x11,3xres,3xau,3xaw,3xcomposite,3xcursor,3xevie,3xext,3xi,3xinerama,3xmu,3xp,3xrandr,3xss,3xt,3xtst,3xv,3xxf86misc,3xxf86vm,Cg,CgFX,l,n


Anonymous

 

(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 gbranden (Posted a comment)
  •  

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

    Date Changed by Updated Field Previous Value => Replaced by
    2021-06-28 gbranden StatusIn Progress Fixed
        Open/ClosedOpen Closed
        Planned ReleaseNone 1.23.0
    2021-06-28 gbranden StatusNone In Progress
    2021-06-07 barx Carbon-CopyRemoved 93119 -
    2021-06-07 barx CategoryNone Utilities
    2021-06-06 gbranden CategoryPreprocessor - others/general None
        Assigned toNone gbranden
        Summarygrog(1) (1.22.3 - Solaris 10 X86_64) reports &quot;.../grog/subs.pl 397: Unknown file name extension ...&quot; [grog] much too strict about file name extensions for man pages
    2021-05-14 barx Carbon-CopyRemoved 93119 -
    2021-05-14 barx CategoryNone Preprocessor - others/general

    Back to the top

    Powered by Savane 3.13-3230.
    Corresponding source code