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

[Steffen Nurpmeso]

Once again hallo Ingo, list,

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

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

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

So i really like your .Ix multiplexer idea.  I think it is still
better to write the above than to end up doing hard to decode
things like

 .It Fl \*(Ixo Ar \*(Ixoutfile

even though the latter mandoc(1) v1.13.1 likes more:

  address@hidden src]$ mandoc -Tlint x.1
  mandoc: x.1:44:22: WARNING: undefined string, using "": Ix
  mandoc: x.1:44:9: WARNING: undefined string, using "": Ix
  mandoc: x.1:48:2: ERROR: skipping unknown macro: .Ix Ev dummy

The visual output of mandoc and groff -Tutf8 is the same either
way.

For mandoc with its parsed tree of nodes implementing such a
usability improvement may even be a completely straightforward
thing to do, for X-roff, on the other side, it will be much
harder.  So, and why i'm writing this, i think that, for X-roff,
it won't be accepted if this mode of operation would be made the
default.

It will require a "complete rewrite" of the TTY device, for
example, which is yet sequential but then has to wait until EOF
just to lookout wether any .Ix anchor occurred.  Of course a new
\X'' has to pass additional info through etc.  Etc. etc.  (Symbol
table etc.)

Short: i think a second command / string / number register has to
be defined that turns on the new functionality.  If set, mdoc (+)
will emit \X'' sequences and the driver would take appropriate
steps for the two-pass mode.  Etc. etc.  Then also allowing .Sx
etc. to do what they are supposed to do.  (Just as mandoc(1)
already does today.  Thanks.)

mandoc(1) could simply ignore this request as such i presume.  But
i think such a toggle would be crucial for X-roff.  To be easy,
how about using a string \*(Ix which must be defined for this to
work?  Thus, the .Ix multiplexer defines anchor / index entries,
the existence of the \*(Ix string represents the users desire to
have an improved interactive experience?  And i think, and that
is one of my declared long-term goals for S-roff, it should be
possible for documents to be self-contained, so just like
mandoc(1)s -mandoc inspects the first non-comment command, if the
document defines ".ds Ix" first, this mode should be enabled
automatically.

I mean, not that time presses..
And..
Have a nice weekend, Ciao!

--steffen