[bug #44784] groff-git_2015-04-04: Compatibility Mode rendering of groff manual pages

[Peter Bray]

Follow-up Comment #10, bug #44784 (project groff):

Greetings,

The FSF file-copy copyright assignment form has been sent to Werner, I
included the following PS, which I thought should go in the bug history:

PS: You may wish to note in the release notes, that groff manual pages require
groff manual page ('an') macros to render correctly. Thus those platforms with
non-GNU vendor provided 'an' macros, who do not choose the new
--with-compatibility-mode=manual, may find that the groff manual pages do not
render as the author intended, due to missing macro definitions.

Additionally, I have the following thoughts:

 - the work done to support compatibility mode,
    https://savannah.gnu.org/bugs/?44708
that is, shortening all the macro names to two characters, could possibly be
reversed (this is definitely not my call, I don't have any knowledge of macro
compatibility, but the longer names definitely are easier to read)

  - I recall, without actually revisiting the manual pages themselves, that
some groff manual pages redefined macros that were in the groff-provided 'an'
macro set, BUT ONLY SOME, so on systems not using groff-provided 'an' macros
the rendering of groff man pages will be hit and miss. I recall the macros
have to do with command options, a critical set of macros for getting the
correct SYNOPSIS rendering.

  - The last point does bring up a 'lint' type issue, maybe these (repeated)
macro definitions should be removed from the manual pages they have been coded
into, so that only a single definition of the macro exists within the project
(for 'an' / 'andoc' macro sets, obviously other macro sets can reuse macro
names). Maybe a tool exists to do this 'lint' style work, I have not
investigated this. But the following is a starting point:

% find . -type f -name *.man | xargs egrep -h '^. *de[^ ]* ' | sort | uniq -c
| sort -n | tail
   2 .    de C\$1
   2 .  de make-C-macro
   2 .de FONT
   2 .de LI
   3 .de FT
   6 .de TQ
   9 .de OP
  17 .de Tp
  31 .de au
  57 .de co

See the original post in the bug report regarding .SY/.OP/.YS and related
macro definitions (partly reproduced below). But please remember that I am not
familiar with *roff macro definitions, so the above may be perfectly fine
(such as unique author definitions), but at least simplistically that seems
like some repeated code.

Following on from that, it would seem better to have groff specific manual
page macros defined in a single location and expanded into the actual manual
pages at build time. I believe that could be done with soelim(1) as part of
the build process.

Just the thoughts of a casual observer without *roff knowledge,

Peter

Repeated Content from the original posting:

Looking at the raw source again, I discovered that the .SY/.OP/.YS macros used
by the first synopsis line where not being rendered. In the groff manual
pages, there are 34 files that use (*1) .OP (for example), while only 9 files
that define (*2) the OP macro. I then looked at the two renderings (-man and
-mgan) in a postscript viewer for "missing content" on the grog(1) manual page
and also noticed that email addresses in the author section were missing,
which the source suggested was the rendering of the .MT macro. The stats for
.MT are 33 files that use and 0 files that define. The command (*3) shows
inconsistencies in the arguments provided to the .MT macro, including
occasional quoting of '-' as in '-' and occasional use of ':' after an '@' as
in '@:', I wondered if the later were from texinfo source documentation where
'@' is special. Finally I noticed that examples in '-mgan' used a typewriter
style font (Courier?), but that is was absent from the '-man' output, seems to
be related to .EX or maybe .IP or .RS (not investigated further).

*1: find .../share/man/man -type f | xargs grep -l '^.OP' | wc -l
*2: find .../share/man/man -type f | xargs grep -l '^.de.*OP' | wc -l
*3: find .../share/man/man -type f | xargs grep -h '^.MT' | sort | uniq -c



    _______________________________________________________

Reply to this item at:

  <http://savannah.gnu.org/bugs/?44784>

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