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

[Ingo Schwarze]

Hi Steffen,

Steffen Nurpmeso wrote on Mon, Sep 15, 2014 at 01:53:29PM +0200:

> So next week (hopefully) i will sit down and write a patch against
> current -mdoc that implements an .Ix stub and documents it, adding
> an entry to the bug tracker.

Take all i'm saying below with a grain of salt; i didn't spend the
time to really think it through yet, so i may be overlooking important
constraints or requirements.  I'm not even sure .Ix is the right
approach, it's just a candidate.  Having a prototype may be useful,
though, to play with it and help completing the design.

I have a hunch jmc@ won't like .Ix and might call it too complicated,
too much work to maintain, and not providing enough value.  Quite
likely, we will have to both simplify the concept further and make
it more powerful before it stands a real-world chance.

For a real-world chance, we might have to start without *any* new
macro or syntax and without any need to change anything in
existing manuals, demonstrate that the concept can provide considerable
real-world value, develop it as far as possible without causing any
new maintenance effort, and only then introduce new syntax to
handle those (hopefully few) cases that can't be autodetected.

> I think .Ix should at least support referencing of Dv, Ev, Fn, Ic,
> Va, printing an error message for other uses.  Does this sound
> right / sufficient / acceptable to mandoc(1)?

Looking at "Macro Keys" in apropos(1), i see some more:

Important: Fl Cm Ar Fa

Maybe:  Pa (would usually point to a FILES entry)
        Er (would usually point to an ERRORS entry)

Fo must act like Fn in this respect.

If any of these cause trouble, they can of course be left out
at first.  The implementation ought to be mostly macro-agnostic,
though.  So if adding another macro to the list causes any
significant work, it's probably badly implemented.

> Since the improved referencing / indexing capabilities will refer
> to new or actively updated manuals only i think it is acceptable
> to require that one of the first commands be an ".Ix 1" to
> indicate that the document makes use of the extensions --

I still don't see the point at all.  It's just a useless knob.
Either it works and can be enabled by default, or it doesn't
work, then it should be deleted.  I don't want options.

Besides, .Ix 1 is terrible syntax.  To follow mdoc(7) standards,
it would have to be something like .Ix -enable (compare to
.An -nosplit).  But such feature switches creating state are not
the best part of the mdoc(7) language and i don't want more of
them.  The language should have as little global state as possible.

> this
> would affect the -mandoc mode of mandoc(1) as that currently
> doesn't detect the right macro set when .Ix comes first (instead
> of .Dd, .Dt and ...), yet i think placing it first would be a
> logical decision from a manual writers point of view.

If at all, it definitely has to be after the preample (i.e. after
.Os), maybe even after .Nd.  Even if you need it at all, you
certainly don't need it before the start fo the content of the
first non-NAME section.

> (Unfortunately mdoc doesn't define a request that indicates a
> documents' version or required feature set (like e.g. perl(1)s
> $^UNICODE) which could be used / added to for that.  And from my
> point of view adding one now is complete overkill.)

I consider specifying the language version in documents VERY harmful.
It just encourages the parsers to develop bloat in the form of
excessive backward compatibility, and it unduly encourages incompatible
language extensions.  I'm thankful we don't have it, and if we had,
it would be one of the first things i would call out for deletion.

Not having that kind of bloat-provoking crutch is the right way to
make sure the language is developed responsibly.

> I think any non-".Ix 1" that occurs without having seen the
> unlocking ".Ix 1" first should print an error message, too.
> 
> So consensus on the above is of course a prerequisite.
> 
> I'd also look into less(1) and write a proof-of-concept patch.
> (Again, the idea is to have a simple command shortcut, say, ^X,
> read in a decimal number, expand that to a backspace sequence and
> start a simple search.)

Where is the user supposed to get that decimal number from?

Integration with less(1) is very tricky because it doesn't have
any notion of a "current cursor position".  Integration with
view(1) would be much easier, but that doesn't handle input
piped into it.  I have no idea yet how to handle this pager
business.

> Later on, hopefully this year, i'll adjust the -- then usable --
> S-roff TTY mode

What do you mean by TTY mode?

> to support the two pass model that is necessary to
> be able to track all references -- one cannot assume that all .Dv,

Actually, .Dv is one of the macros cooperating less willingly with .Ix.
For example, .Dv NULL cannot reasonably link anywhere.  Other uses,
like .Dv O_CREAT, will point to a place in the same page, though.

In general, i consider .Ix a tool purely for navigating *inside*
one manual page.  When it comes to *external* references, .Xr
must be used, anyway.

> .Ev

In a properly written manual, every variable appearing in .Ev
will have an entry below ENVIRONMENT, as a rule.

> etc. that are used throughout a manual are actually defined in
> the same manual, right?  I assume mandoc(1) can simply traverse
> it's tree...

Not sure what you are trying to say here.  You mean when invoking
a hyperlink which has no target in the same page, less(1) should
transparently invoke apropos(1) to search for it in other manuals?
That idea seems bold and interesting, but quite difficult to
implement, even more difficult than complete .Ix support.

The steps would be:

 1. Local .Ix, that is, .Ix for linking within one page.
    (Which includes all we have discussed so far.)
 2. Let apropos(1) support .Ix, that is, allow searching
    for macro keys having the .Ix property.
 3. Let step 2 be used from within a manual viewer.

Are you jumping to step 3 here?  That would be a jump very far into
the future, before even the foundations have been laid.

[...]
> P.S.: what about a ".To [number]" request that embeds an
> automatically created table of contents for all .Sh and .Ss of
> a document?  That would also be a real win, but this time
> _especially_ for HTML and PDF output..

That's useless for almost all manuals because .Sh headers are
standardized, some every manual would have almost literally the
same table of contents, .Ss are used very little (and rightly so),
and most manuals are too short for a table of contents to be useful.

For the very small number of manuals that might profit from such a
feature, introducing a new macro isn't warranted, in particular
since you can already trivially do this:

  $ man ksh | grep '^...[^ ]'

Yours,
  Ingo