[Groff] Better locale macro file handling?

[Colin Watson]

I'm trying to figure out how to make use of the new localisation macro
files in man-db. The documentation is simple: just add -mfr (or -msv
etc.).

I really don't want man-db to have to keep track of what locales groff
supports, though. From my point of view that's an implementation detail
of groff, not to mention that generally speaking man has no terribly
accurate idea of what version of groff is installed never mind what
macros it has available. I would prefer to just tell groff to source the
appropriate macro for the current language, and for that to be ignored
in case groff doesn't support that locale. Unfortunately, -mnonexistent
is a fatal error, and '.mso nonexistent.tmac', while not fatal, still
produces an error message on stderr. I want something a bit more
graceful than that.

What's the best fix for this? I can think of several possibilities:

  * Have groff check the locale and source the appropriate macro file
    automatically.

    + Requires no changes in calling code.
    - Awkward if the document isn't for the current primary language
      (e.g. with LANG=ja_JP.UTF-8 LANGUAGE=ja:de set in the environment,
      man might fall back to a German manual page if it can't find a
      Japanese one).

  * Introduce a new option to source a macro file if it exists, but
    otherwise be silent.

    + Allows the caller to control which locale is in use.
    + General, so potentially useful elsewhere.
    - Uses up another option letter.
    - Invalid options are a fatal error, so using this would mean that
      man-db would have a hard requirement of a newer version of groff.
      I'd rather not have to do this.

  * Introduce a new request which acts like .mso but is silent if the
    file does not exist.

    + Allows the caller to control which locale is in use, provided that
      it can feed extra commands into the input stream (man-db can do
      this with relative ease).
    + General, so potentially useful elsewhere.
    + Can be used without breaking backward compatibility (using
      something like '.if d qmso .qmso fr.tmac').
    - Perhaps not as general as it should be since it wouldn't apply to
      .so.

On balance, I think the last option is the best I can think of. How does
the following patch look?

2009-02-17  Colin Watson  <address@hidden>

        Implement a `qmso' variant of the `mso' request which does not
        emit error messages if the macro file is not found.

        * src/roff/troff/input.cpp (macro_source): Renamed to...
        (do_macro_source): This.
        Introduce a quiet parameter.
        (macro_source, quiet_macro_source): New functions.
        (init_input_requests): Register `qmso'.

        * NEWS, man/groff_diff.man, man/groff.man, doc/groff.texinfo
        (Macro Directories, Ultrix-specific man macros, I/O): Document
        new request.

=== modified file 'NEWS'
--- NEWS        2009-02-14 17:21:35 +0000
+++ NEWS        2009-02-17 03:51:32 +0000
@@ -20,6 +20,11 @@ o The new `lsm' request specifies a macr
   registers `lsn' and `lss' hold the number of removed leading spaces and
   the corresponding horizontal space, respectively.
 
+o The new `qmso' request is the same as `mso' except that it does not emit
+  an error message when the macro file does not exist.  This may be useful
+  for loading localization macros without having to keep track of which ones
+  groff currently supports.
+
 
 VERSION 1.20.1
 ==============

=== modified file 'doc/groff.texinfo'
--- doc/groff.texinfo   2009-02-14 17:21:35 +0000
+++ doc/groff.texinfo   2009-02-17 03:42:38 +0000
@@ -1365,9 +1365,9 @@ above.
 
 All macro file names must be named @address@hidden or
 @address@hidden to make the @address@hidden command line
-option work.  The @code{mso} request doesn't have this restriction; any
-file name can be used, and @code{gtroff} won't try to append or prepend
-the @samp{tmac} string.
+option work.  The @code{mso} and @code{qmso} requests don't have this
+restriction; any file name can be used, and @code{gtroff} won't try to
+append or prepend the @samp{tmac} string.
 
 @cindex tmac, directory
 @cindex directory, for tmac files
@@ -2620,7 +2620,8 @@ default is @address@hidden
 The @code{groff} source distribution includes a file named
 @file{man.ultrix}, containing macros compatible with the Ultrix variant
 of @code{man}.  Copy this file into @file{man.local} (or use the
address@hidden request to load it) to enable the following macros.
address@hidden or @code{qmso} request to load it) to enable the following
+macros.
 
 @Defmac {CT, @Var{key}, man}
 Print @samp{<CTRL/@var{key}>}.
@@ -13124,6 +13125,11 @@ included has the form @address@hidden
 @code{mso} tries to include @address@hidden and vice versa.
 @endDefreq
 
address@hidden {qmso, file}
+Identical to the @code{mso} request except that @code{gtroff} does not emit
+an error message if the specified @var{file} does not exist.
address@hidden
+
 @DefreqList {trf, file}
 @DefreqListEnd {cf, file}
 @cindex transparent output (@code{cf}, @code{trf})

=== modified file 'man/groff.man'
--- man/groff.man       2009-02-14 17:21:35 +0000
+++ man/groff.man       2009-02-17 03:50:06 +0000
@@ -2137,6 +2137,14 @@ Change post-vertical line spacing accord
 .scaleindicator p ).
 .
 .TPx
+.REQ .qmso "file"
+The same as
+.request .mso
+except that an error message is not emitted if
+.I file
+does not exist.
+.
+.TPx
 .REQ .rchar "c1 c2 .\|.\|.\&"
 Remove the definitions of entities
 .IR c1 ,

=== modified file 'man/groff_diff.man'
--- man/groff_diff.man  2009-02-14 17:21:35 +0000
+++ man/groff_diff.man  2009-02-17 03:48:55 +0000
@@ -1919,6 +1919,14 @@ and
 with a positive value which are applied after the line is output.
 .
 .TP
+.BI .qmso\  file
+The same as the
+.B mso
+request except that an error message is not emitted if the specified
+.I file
+does not exist.
+.
+.TP
 .BI .rchar\  c1\ c2\|.\|.\|.\&
 Remove the definitions of glyphs
 .IR c1 ,

=== modified file 'src/roff/troff/input.cpp'
--- src/roff/troff/input.cpp    2009-02-14 17:21:35 +0000
+++ src/roff/troff/input.cpp    2009-02-17 03:36:59 +0000
@@ -7329,7 +7329,7 @@ static void process_startup_file(const c
   mac_path = orig_mac_path;
 }
 
-void macro_source()
+static void do_macro_source(int quiet)
 {
   symbol nm = get_long_name(1);
   if (nm.is_null())
@@ -7366,12 +7366,22 @@ void macro_source()
       input_stack::push(new file_iterator(fp, symbol(path).contents()));
       a_delete path;
     }
-    else
+    else if (!quiet)
       error("can't find macro file `%1'", nm.contents());
     tok.next();
   }
 }
 
+void macro_source()
+{
+  do_macro_source(0);
+}
+
+void quiet_macro_source()
+{
+  do_macro_source(1);
+}
+
 static void process_input_file(const char *name)
 {
   FILE *fp;
@@ -7844,6 +7854,7 @@ void init_input_requests()
 #ifndef POPEN_MISSING
   init_request("pso", pipe_source);
 #endif /* not POPEN_MISSING */
+  init_request("qmso", quiet_macro_source);
   init_request("rchar", remove_character);
   init_request("rd", read_request);
   init_request("return", return_macro_request);

Thanks,

-- 
Colin Watson                                       address@hidden