emacs-orgmode
[Top][All Lists]
Advanced

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

Re: [O] pxref in texinfo export


From: Jonathan Leech-Pepin
Subject: Re: [O] pxref in texinfo export
Date: Mon, 25 Feb 2013 17:01:25 -0500

Hello

On 25 February 2013 16:34, Subhan Tindall <address@hidden> wrote:
I noticed you left out @inforef, was that by design?  It actually does
behave quite differently than other members of the @*ref family, and
the more arguments it gets the more different it looks IE Here's an
example with a full 5 arguments:
REF *note Arg2: (Arg4)Lore Ipsum.
 INFOREF *note Arg2: (Arg3)Lore Ipsum Arg4, Arg5

I omitted @inforef, @uref, @url @email by design because they are
external links in an org file and can be processed differently.   
 
Org Links only have 2 arguments at most (destination and description)
so the additional arguments are skipped as well.

Info links are format: [[info:<info-file>:<node>][description] or
[[info:<info-file>#<node>][description]] so can provide the 3 arguments
by splitting between file and node.

Regards


On Mon, Feb 25, 2013 at 12:29 PM, Jonathan Leech-Pepin
<address@hidden> wrote:
> (Here are the attached files, forgot to add them)
>
>
> On 25 February 2013 15:24, Jonathan Leech-Pepin
> <address@hidden> wrote:
>>
>> Hello,
>>
>> On 25 February 2013 14:01, Subhan Tindall <address@hidden>
>> wrote:
>>>
>>> The point being that compiling .texinfo source into an Info file
>>> treats references differently. For example:
>>> (@pxref{my_node_name}).  will compile just fine.
>>> (@ref{my_node_name}). will not.
>>
>>
>> Both work perfectly fine for me.
>> makeinfo (GNU texinfo) 5.0
>>
>>>
>>> There are also differences in case
>>> (see v. See, note v. Note), and differences in output by ref type
>>> depending on target output of file (info, DVI, HTML,...). For example,
>>> @pxref generates different punctuation for typeset v. info files, @ref
>>> does not generate a 'See ' in printed material while @xref does, etc.
>>>
>>> Although the differences are subtle, they really are not equivalent
>>> and should not be treated as such.
>>
>>
>> With a slight amount of work on the user's part, they can be made
>> functionally equivalent on export.
>>
>> Using the two attached minimal .texi files (good-ref.texi is using
>> @xref/@pxref as is preferred while ref.texi is using @ref with
>> appropriate See/see added in the text) and disregarding filename
>> differences (since they are noted in the info output) I get the
>> following differences:
>>
>> > makeinfo --html --no-split good-ref.texi ref.texi
>> 0 Diffs
>>
>> > makeinfo --docbook --no-split good-ref.texi ref.texi
>> Filename ID appears in diff
>>
>> > makeinfo --xml --no-split good-ref.texi ref.texi
>> Filename difference.
>>
>> Links are different since TexinfoML does still distinguish xref/pxref
>> and ref in how they create the links.
>>
>> > makeinfo --no-split good-ref.texi ref.texi
>>
>> The info file does show the expected differences between the two
>> documents, notably that the "@xref{}" becomes "*Note" while the
>> equivalent "See @ref{}" becomes "See *note" with @pxref{}->*note vs
>> see @ref{} -> see *note.
>>
>> However once they are viewed within the *info* buffer (C-u C-h i
>> good-ref.info/ref-only.info) the lines in question are visually
>> identical since *Note becomes "See" and *note becomes "see" if there
>> is not already "see" present.
>>
>> I will not disagree that @ref, @pxref and @xref are subtly different,
>> however with slight user intervention @ref can be used in the same
>> above locations by simply replacing:
>>
>> @xref{}  -> "See @ref{}"
>> @pxref{} -> "see @ref{}"
>>
>> I had to compare these possible outcomes when working on the texinfo
>> exporter.  Since links are parsed before being included in their
>> paragraphs, I did not have a way to obtain context and therefore
>> attempt to guess (and be successful) at which type of reference was
>> intended by a link in Org.  Restricting it to @ref{} in all cases,
>> even if it added a slight burden to the user (4 additional characters
>> to type in Org) if they wanted to emulate @xref or @pxref was in my
>> opinion the best choice.
>>
>> Regards,
>>
>> --
>> Jon
>>
>> [...]
>>
>



--
Subhan Michael Tindall | Software Developer
| address@hidden
RENTRAK | www.rentrak.com | NASDAQ: RENT


reply via email to

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