Re: A Roadmap for TexInfo without Info

[Eli Zaretskii]

> From: Assaf Gordon <address@hidden>
> Date: Fri, 25 Nov 2016 10:40:14 -0500
> Cc: Texinfo <address@hidden>
> 
> > On Nov 25, 2016, at 04:00, Gavin Smith <address@hidden> wrote:
> > 
> > On 24 November 2016 at 19:55, Assaf Gordon <address@hidden> wrote:
> >> one minor annoyance that stems from the "info" format: the references 
> >> (@ref/@xref/@pxref).
> > 
> > As Eli said, the main problem with the above is the printed output,
> [...]
> 
> Perhaps I should rephrase: the problem is in the "texinfo/info" eco-system, 
> where, if I want to adhere to the best-practices, these kind of references 
> are discouraged (by the official manual).

They are not discouraged.  Instead, you are _encouraged_ to think
about how your cross-reference will look in all the various output
formats, and write your Texinfo accordingly.

> IMHO, the distinction between "print" and "online" should be refined, as both 
> HTML and PDF can be used for printing and for online viewing. The distinction 
> should be between formats/displays/interfaces that support embedded linking, 
> and those that don't.

I agree, but that doesn't help to solve the issue in any way.  The
media that can express the fact that a certain text is a hyper-link,
and the media that cannot, have different requirements.  If anything,
this (correct, IMO) distinction you propose _adds_ a problem: the PDF
format can be both read on-line where it supports clickable
hyper-links, but it can also be printed (and is produced by Texinfo
tools that assume it _will_ be printed), where those hyper-links
cannot be acted upon, and are usually simply invisible.

> Additionally, with modern HTML capabilities we can also know if it being 
> viewed on screen or being printed. 

Again, how does this help to resolve the issue?  Are you suggesting
that whatever prints the manual changes its text as part of preparing
it for printing?  That's not something modern browsers and PDF readers
can do.  Usually, a page that should look differently in print has a
link labeled something like "Printed version", which leads you to
another page, formatted specifically for printing.  That would
translate in our case to 2 variants of PDF/HTML produced from the same
source, one for on-line, the other for printing.  Which then gets us
back to square one, which is how to produce a hyper-link text suitable
for both an on-line and a printed version of the manual.

> I'd like to be able to do the following. Perhaps it's already possible, I'm 
> not sure how.
> 
> I want to be able to write something like:
> 
>     The @option{-E} option turns on @linkref{extended regular expression} mode
>     @printref(extended regular expression}.
> 
> Where "@linkref" would generate an embedded link, with the text being 
> "extended regular expression" and look natural as part of the sentence. It 
> should work in HTML, PDF when viewed on screen, and all other interactive 
> formats.
> 
> When printed, it should just be the text "extended regular expression" 
> without additional text (e.g. no "see" or pages) - effectively looking like 
> normal text and losing its cross-ref attributes.
> 
> And "@printref" is something that generates a stand-alone expression, with 
> parenthesis, suitable for inclusion in printed material (such as PDF, or HTML 
> with special media=print tags), and it should be something like "(see 
> Extended Regular Expressions, Section X, Page Y)".

You can have this today, by writing a suitable, quite simple, Texinfo
macro.

The problem with your suggestion is that it only works in the simple
use case you described.  But in real life, cross-references are used
in Texinfo manuals in many different kinds of context.  There's

  @xref{Some node, some aspect}, for the details of how Something is done.

and

  For details of Something, see @ref{Some node}.

and

  You can do Something by invoking Something-Else (@pxref{Elsewhere}).

and

  Something is described in its own manual, @pxref{Top, Something,
  Something's manual, something.info, The Manual Of Something}.

And many other variants, with some of the arguments omitted.  There
are even (perverse, IMO) use cases where cross-references are embedded
in Texinfo menus, something that's very difficult to express in print,
because menus end up omitted there.

The challenge is to implement a single cross-reference command that
will produce correct English text for each one of these situations.  I
encourage you or someone else to work on that, but I'm quite sure that
when the dust settles and all the bugs in it are fixed, we will
discover that the author still needs to think about the possible
outputs when she writes the surrounding text.  Why? because the
results are simply too different for us to be able to reconcile them.

IMO, it would be better to have a Texinfo cross-reference directive
which would explicitly allow me to write the two variants of the
produced text, thus uncoupling them, and letting me think about each
one separately, without having to come up with a single text that
suits both.  We kinda have this today already: there are @inforef and
@url that can be used for on-line versions; there are also @ifhtml,
@ifnothtml, etc.  But maybe we could come up with a better glue, which
would not require the use of too many different variants and
conditionals for the same text.

> This is just a rough idea, I'm sure there are edge-cases I haven't considered.

The problem is, those "edge cases" are actually most of the use cases.

> But my point is - I want to take advantage of convenient cross-referencing 
> with media that allows it,
> and not be limited by having to consider the lowest-common-denominator of 
> "how it will look in info".

See above: you are already not limited, you just need to use the tools
that are available.  But your dream about a single link directive is
IMO just a dream.

> > The Info output may be suboptimal, but you are free to ignore it, as I said.
> 
> I suspect others (Eli for example) would not agree that "I'm free to ignore 
> it"...

Indeed.  There's no replacement for the efficiency of an Info manual
as of today.  Until someone comes up with a comparably efficient way
of using the HTML-formatted manuals, I'm sticking with Info, because I
actually use it all the time, and it must work efficiently for me.
For example, when I wrote the above, I had to look up the variants of
@xref in the Texinfo manual; with an Info reader that was possible
with just half a dozen keystrokes, knowing just the name of the manual
and the name of the directive @xref I was looking for.