Re: [Groff] .if !dTS - GNU extension?

[Ingo Schwarze]

Hi James,

James K. Lowden wrote on Fri, Apr 29, 2016 at 03:43:03PM -0400:
> On Fri, 29 Apr 2016 17:50:52 +0200, Ingo Schwarze wrote:
>> James K. Lowden wrote:

>>> I'm pretty sure my man invokes mandoc as "mandoc".
>>>  Would that be a problem?  

>> That cannot work.  If man(1) invokes an external mandoc(1) via fork
>> and exec, there is no :t support.  You need a version of mandoc
>> where /usr/bin/man and /usr/bin/mandoc are hard links to one and
>> the same executable file.  Otherwise, man cannot know the name of
>> the temporary ctags file that mandoc created, so it cannot pass it
>> on to less.

> If I may say so, that's an unfortunate, unnecessary limitation.
> Instead of replacing /usr/bin/man, why not support a command-line
> option to specify the name of a ctags file, and supply that name to
> less?

This feature isn't the main reason for replacing man(1).  See pages
6 to 12, in particular page 8 of my BSDCan 2015 presentation:

 - Unified user interfaces:
   man can use: -W -T -O -I from mandoc(1)
   apropos can use: -w -h -a from man(1)
   man -Tlint crypt_checkpass     # check an installed manual
   man -Thtml lynx | lynx -stdin  # pager overkill
   man -Tps gv | gv -             # even more pager overkill
 - Allow much simpler man.conf(5) format -> next slides
 - database priority now overrides section priority
 - Use additional names from .Dt/.TH and NAME .Nm
   (250 new entries in OpenBSD, compared to 10200 existing ones)
 - One less userland program to maintain
   (that had rather old code)
 - Possibility to get rid of multiple ln(1) links to the same manual
   [done in April 2016 in OpenBSD, reduced the base install by
   thousands of directory entries]
 - Possibility to implement an interactive chooser (-i)
   [not done yet]

For more context,
http://www.openbsd.org/papers/eurobsdcon2015-mandoc.pdf

Besides, your idea causes an unreasonable amount of work and bloat.
It doesn't just add a command line option to mandoc(1), which i
consider almost prohibite bloat all by itself, but requires changing
*all* the man(1) programs, and basically, each system has its own
of these.

Well, once any of the various third-party man(1) implementations
implements :t support, i would probably consider adding such a
command line option to mandoc(1), but as long as that doesn't
happen, the very question is moot.  For the time being, if you
want that feature, your only choice is to pick a man(1)
implementation that supports it - short of writing patches for
your favourite man(1) implementation and getting them integrated
upstream.

> NetBSD's man uses /etc/man.conf, and the existing syntax could
> enable that behavior.  

The man.conf(5) format is very non-portable.  Each and every system
has its own format, and the traditional 4.4BSD one is among the
worst.  So i removed all the bloat and designed a new, very simple
format from scratch, see pages 10-12 of the above presentation.
After a year, there is still no noticeable demand for any of the
deleted or newly proposed not-yet-implemnted features, so simplifying
this was definitely the right move.

> I don't want to replace the man utility, or groff as manpage formatter
> for everything.  (groff.7 and groff_ms.7 are two examples of files
> mandoc can't render.)

The best way to deal with that is to make your packaging system
install manual pages that use some of the more arcane groff extensions
not supported by mandoc, or some gory low-level roff(7) not supported
by mandoc, as preformatted files rather than as source code.  That
issue affects about 5% of manuals, and all of them are
man(7)-roff(7)-mixtures, none mdoc(7), so they won't get indexing
anyway.  For a longer discussion, see pages 27 to 29 of the above
presentation.

> Have you experimented with a single index for all man pages?

No.

> I wonder how useful that would be,

Not useful at all.  First, it cannot be done because you don't
know the user's terminal width at database build time, so you
don't know output line numbers.  Besides, even if that could
be overcome, the growth of the database size is likely to be
prohibitive.  And even if that could be managed, it isn't
needed in practice.  If apropos(1) tells you which page to
look at, and then :t lets you jump to the right place inside
once you have opened it (either by apropos(1) -a directly or
manually with man(1)), you can do all you need, right?

> or how it might be subdivided.  An index that
> spanned pages would be helpful for sets of routines covered by
> different man pages.  (groff.7 and groff_char.7 come to mind.)  

Bad examples.  These can't be indexed in the first place, they
use the non-semantic man(7) format.

Yours,
  Ingo