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

[Steffen Nurpmeso]

Hallo Ingo,

Ingo Schwarze <address@hidden> wrote:
 |Steffen Nurpmeso wrote on Thu, Sep 11, 2014 at 04:22:22PM +0200:
 |> 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.

cool that you responded and are interested in this topic!

 |> 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.

Absolutely.  On the long run such extensions could also result in
less fragmented manuals, which can be a pain to use.
And also in better global indeces, key word apropos(1).

..I'm reordering a bit..

 |> ..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.

So the idea is however that the TTY driver writes just another
backspace escaped sequence that should end up invisible in the
pager (that is x^Hx^H.., not x^Hx.., but such stacked sequences
are already used today (for lists)) -- or is instead displayed as,
say, "[NUMBER]".  The anchor will always be invisible, and all the
pager really has to do is to offer a command-shortcut that expands
a user-given NUMBER to the full backspace escape sequence that
makes up the anchor, which then can be found through the normal
searching capabilities of the pager.  So for pagers which already
support searching the necessary changes should be pretty small
(less wraparound search, possibly), and i'd be willing to dig into
less(1) for a proof-of-concept should this thread have a countable
outcome.

No, i think the complication is rather exclusively on the TTY
driver side, which i'm afraid has to use a two-pass algorithm,
shall these optional new features be enabled...

 |> 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.

Absolutely.

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

So then completely new requests could not be used at all?
In respect to "simply replace on old '.It Va myvar' with '.It Vax
myvar' and end up right", at least.
And you don't like three-letter commdands, .Dvx, .Evx, .Flx (?),
.Fnx (trailing "word" <> "funcname"), .Fox, .Vax (trailing
"word"), whatever.  What a pity.

 | * 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

..oh well, it is terrible to look at the sources.. _terrible_..

 |   valid.  One of the problems of mdoc(7) is redundance and some

 |   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

Oh yes!

 |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

But that in turn looks somewhat error prone to me, especially when
crossing multiple entries; this is the downside of not being able
to simply say

  .It Flx o Arx outfile

But even more i'm afraid that a general purpose pipeline like
non-mandoc :) will not be able to deal with your idea...
Unfortunately!  I guess all that X-roff could do is to adjust the
macros and emit special \X'' sequences for the backend...

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

Yes, two-pass i think cannot be avoided with this.

 [.]
 |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?

It may take another 24 years..
(Luckily many manuals follow a common style so that even large
ones could be transformed via search+replace, possibly even
completely automatic.)

 |Yes, 24 years specifically, 4.3BSD-Reno was released in 1990.
 
Indeed it seems it is older than the 4.4BSD mdoc.7 note in mandoc
v1.13.1 [1]?  But you are the expert in this topic!

  [1] 
<http://minnie.tuhs.org/cgi-bin/utree.pl?file=4.3BSD-Reno/share/tmac/tmac.doc>

--steffen