Re: [Groff] More referenceability for -mdoc would be an improvement!?

[Ingo Schwarze]

Hi Steffen,

Steffen Nurpmeso wrote on Thu, Sep 11, 2014 at 04:22:22PM +0200:

> despite the fact that grohtml produces faulty output for it
> anyway, i really think that -mdoc would need a few more commands
> so that it would be possible to create "better" documents with it,
> where "better" refers to usability and user experience.

If we keep groff_mdoc(7) and mandoc(1) in sync, i'm not necessarily
opposed to very sparingly adding functionality, if it adds very
considerable value.

> E.g., even mandoc(1) -Tx?html doesn't create anchors and
> references for variables etc., just because... it cannot.  Where
> should there be an anchor.  So this is the one killer argument for
> this terrible info system, that it is capable to offer the links
> that make the better usability.

You slightly overstate the case:  Most manual pages are short, so
finding something in them is rarely difficult.  Besides, all modern
pagers have integrated search functionality.

Still, i think you are making a valid point.  Large manuals like
sh(1) and perlfunc(1) do exist, even if they are the exception
rather than the rule, and at least those would considerably profit
from such additional functionality.

> Imho there should be additional commands to create anchors, e.g.,
> .Vx as an alias for .Va except that it actually defines an anchor
> too, or why not .Xv (variable), .Xf (function)... in equal spirit
> to .Xr.  Or a new .Z* series for this sole purpose.

Yuck.

Such a project needs a very careful design.

Some requirements:

 * Minimum backward compatibility.
   Formatting a document using the new functionality with an
   old formatter should not produce completely broken output.

 * Scalability.
   Though i don't follow his conclusion about the overall worth of
   the mdoc(7) language, Eric's criticism of the language is largely
   valid.  One of the problems of mdoc(7) is redundance and some
   lack of consistency, and the number of macros is already rather
   high.  For example, .Oo ... .Oc is the same as .Op Xo ... .Xc
   (redundance), but some macros have only implicit scope forms
   (.It, .Ql) while for some of the explicit scope forms the
   corresponding implicit scope forms are blocks (.Bd -> .D1) while
   for others they are in-line (.Bf -> .Em/Li/Sy).
   I'm certainly not going to add to that mess by adding yet more
   redundance or inconsistency, and we are not going to double
   each and every bloody macro.

I'm not at all sure what the right design would be.  No problem
because i'm not in a hurry quite yet...

Anyway, here are a few possible ideas:

  .Ix [macro] [key]

Example:

  .Ix Ev USER

That would add an index entry for the string USER to the index
of environment variables.  Arguments would default to the next
content macro occurring in the input stream.  So

  .Ix
  .Ix Ar
  .It Fl o Ar outfile

would be equivalent to

  .Ix Fl o
  .Ix Ar outfile
  .It Fl o Ar outfile

In either case, earlier or later .Fl o and .Ar outfile would
automatically imply a hyperlink to this place.

Given a plain text line like

  The options are as follows:

the above approach includes an normal index for plain-text words
by simply doing this:

  The
  .Ix
  .No option Ns s
  are as follows:

Or, as a matter of taste, equivalently:

  The
  .Ix No option
  options are as follows:

An alternative scheme would be to use escape sequences instead
of macros.

  .It \A'Fl:o'\A'Ar:outfile' Fl o Ar outfile

is already possible now, but quite clumsy.  Or if we use

  .It Fl o\R'Ix +1' Ar outfile\R'Ix +1'

we get numbering for free.  Minimal syntax would be

  .It Fl o\*(Ix Ar outfile\*(Ix

never ever defining the string so it doesn't change output,
only using its presence as a clue to generate an index entry.

There are many interesting possibilities.  The repercussions
are not easy to fathom, the design needs to be carefully chosen.

Besides, who will plow through the 4000 existing manuals in the
OpenBSD base system (and similarly elsewehere) and add the
required markup?

> ..some more.  The tty output device could learn a new switch and
> embed new x^Hy^H sequences, say {no} and [no], then pagers could
> go and implement something like the keypad_mode=LINKS_ARE_NUMBERED
> that lynx(1) supports and could even jump to the corresponding
> anchor.  And of course X?HTML output devices could create anchors
> and regulary references to them, too.

These are difficult problems.  The info(1) debacle demonstrates
that writing your own pager is a bad idea.  Requiring pagers to
implement anything specifically for manuals violates the principle
of having each tool do one small thing well.  Not sure yet how to
solve that dilemma, but your dream raises valid questions.

> Of course these new commands are ~20 years overdue, but for Unix
> manuals to become a better experience (regardless of the actual
> form, wether tty, html or pdf) they would be a first step, the
> necessary framework for things to come.

Yes, 24 years specifically, 4.3BSD-Reno was released in 1990.

Yours,
  Ingo