Unadorned cross-references

[Christopher Dimech]

> Sent: Tuesday, June 01, 2021 at 7:17 AM
> From: "Gavin Smith" <gavinsmith0123@gmail.com>
> To: "Augusto Stoffel" <arstoffel@gmail.com>
> Cc: "Texinfo" <bug-texinfo@gnu.org>
> Subject: Re: Unadorned cross-references
>
> This question comes up again and again and the following was added to
> the manual to address this. I hope it explains the issue.
>
> Why do I have 'see' appearing in front of all of my links?
>
>      By default, Emacs Info mode either changes the marker '*note' for
>      cross-references to 'see', or hides it completely.  Unfortunately,
>      there is no way to do this reliably, as both the '@pxref' and
>      '@ref' commands in Texinfo output this marker in the Info output,
>      and the 'see' text is only appropriate for '@pxref'.
>
> Yes, but how do I get a plain link, with no extra markup?
>
>      You can't.  Info is a plain text format that is displayed mostly
>      as-is in the viewers, and without the '*note' text there would be
>      nothing to mark text as a link.  Additionally, in printed output
>      there is no such thing as a plain link, as the page number of the
>      target would have to be printed somewhere.

This has been a debatable argument for a long time.  You provide an explanation,
but have no doubt that people have valid reasons not to want to do that.  The 
fact
that they can't creates a lot of bother.  Unless there are technical reasons 
making
a change impossible, it should be done.  A problematic situation I encountered 
was
when you have a list of links and do not want "see" or "page numbers" on all of 
them.
Still, the possibility should not simply be implemented globally for the entire 
file,
because one would generally want to toggle between showing them and not showing 
them.


>      If you really want a plain link in HTML output without affecting
>      other output formats, you could create a macro with conditional
>      definitions for each output format.
>
> Why do lines containing links appear mysteriously short?
>
>      This due to Emacs (or 'info' with 'hide-note-references' set to
>      'On') hiding '*note' strings, as mentioned above.
>
> Can the Info format be extended to support fonts, colors or reflowable text?
>
>      Any extension would be incompatible with existing Info-viewing
>      programs.  Extra markup added to Info files would be displayed to
>      the user, making files ugly and unreadable.
>
>      When Texinfo files are processed into Info files, information about
>      which Texinfo commands were used to markup text is lost.  Moreover,
>      it is not possible to reliably detect whether text can be reflowed
>      (e.g. a paragraph of prose), or whether line breaks should be kept
>      (e.g. a code sample, or poem).
>
>      Info's core purpose is to display documentation on text terminals.
>      If you want more, you are recommended to use the HTML output from
>      'texi2any' instead.
>
> On Mon, May 31, 2021 at 3:06 PM Augusto Stoffel <arstoffel@gmail.com> wrote:
> >
> > I would like to suggest adding a command to Texinfo, as well as some
> > markup in the .info file format, to create unadorned cross-references,
> > that is, without the assumption that the cross reference fits in a
> > phrase like "see such and such".
> >
> > Currently, it seems to be more or less impossible to create info
> > documentation from manuals that were not specifically written in
> > Texinfo, since other markup languages don't make a similar grammatical
> > assumption on internal hyperlinks.
> >
> > For instance, I recently tried to do this with the Python manual
> > (converting rst files to texi with Sphinx, and then running makeinfo
> > to generate info files).  The result looks like this in Emacs:
> >
> >     1.8.9.17 popen
> >     ..............
> >
> >     The see os.popen(). and see subprocess.Popen(). functions
> >     now support see with. statements for auto-closing of the file
> >     descriptors.
> >
> > The expected result would be "The os.open() and subprocess.Popen()
> > functions...", with hyperlinks on "os.open()" and "subprocess.Popen()".
> >
> > The .info file itself looks like this:
> >
> >     1.8.9.17 popen
> >     ..............
> >
> >     The *note os.popen(): 3b5. and *note subprocess.Popen(): 3c5. functions
> >     now support *note with: 7b7. statements for auto-closing of the file
> >     descriptors.
> >
> > I'm not very familiar with Texinfo, but one idea on how to implement
> > this suggestion on the .info side would be to extend the
> >     *note <topic>: <location><punctuation>
> > markup so that, say,
> >     *note <topic>: <location>#
> > signifies an unadorned internal link.
> >
> > Finally, let me remark that the Python source code already includes a
> > Makefile target to build the documentation in info format, even though
> > their website doesn't offer this for download.  I can well imagine
> > that they would like to provide info manuals, and just don't do it
> > because they look a little wrong.
> >
>
>