bug-texinfo
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: Unadorned cross-references


From: Gavin Smith
Subject: Re: Unadorned cross-references
Date: Mon, 31 May 2021 20:17:33 +0100

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.

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



reply via email to

[Prev in Thread] Current Thread [Next in Thread]