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

[Ingo Schwarze]

Hi Steffen,

Steffen Nurpmeso wrote on Sat, Sep 13, 2014 at 05:07:27PM +0200:

> So i really like your .Ix multiplexer idea.

Not really a multiplexer, it's just giving one single name to one
single, logically self-contained piece of functionality.

> 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

That doesn't really matter.

I didn't say old tools should be able to process manuals using
new features without warnings and error messages.  I only meant
they should still produce usable output, if possible.

Actually it's good if they warn.  That tells the user that the
document uses features the tools don't support.  From the mandoc(1)
perspective, ERROR is better here than WARNING because there is a
risk of significant information loss (even though what remains is
probably still about as good as old documents not using the
functionality in the first place).  But seeing just a warning would
not really be a problem, either.

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

True.

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

I don't think any mode switches will be acceptable in this context.
It should just work.  People don't want to twist knobs all day,
they merely want to read documentation.

> It will require a "complete rewrite" of the TTY device, for
> example,

I'm not yet convinced anything meaningful can be done for terminal
output.  I guess in the first step, groff will merely parse it
without complaint, in the second, it will be mostly for HTML,
in the third step for PDF, and *maybe* someday for ASCII.  We
certainly shouldn't start with ASCII.

> which is yet sequential but then has to wait until EOF
> just to lookout wether any .Ix anchor occurred.

Encoding the link destinations (anchors) in ASCII at all is
already a huge problem, the problem of forward references is
minor compared to that and allows several different solutions.

> Of course a new \X'' has to pass additional info through etc.
> Etc. etc.  (Symbol table etc.)

Right now, doc.tmac doesn't do more than plain Sy and Em font
instructions even for .Lk.  Not sure we have to aim higher than
that for the first version.

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

I'm not even convinced two-pass is needed.  Certainly not at the
beginning, and maybe never.  Forward references will be the
exception rather than the rule.  So one obvious shortcut is to
simply ignore forward references if they cause trouble and only
handle backward ones.  Another might be to simply handle all newly
occurring, non-anchored content macros as forward references; as
everything ought to be handled *somewhere*, that's likely to just
work.  One could also allow forward declarations, allowing authors
to state "this is a forward reference".  Lots of ways, not at all
sure which one will turn out to be the best.

Yours,
  Ingo