From mboxrd@z Thu Jan 1 00:00:00 1970 From: Jonathan Leech-Pepin Subject: Re: pxref in texinfo export Date: Mon, 25 Feb 2013 17:01:25 -0500 Message-ID: References: Mime-Version: 1.0 Content-Type: multipart/alternative; boundary=bcaec5016299a4ed1804d693ae93 Return-path: Received: from eggs.gnu.org ([208.118.235.92]:38607) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1UA66y-0007gj-Ii for emacs-orgmode@gnu.org; Mon, 25 Feb 2013 17:01:30 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1UA66w-0002dJ-5l for emacs-orgmode@gnu.org; Mon, 25 Feb 2013 17:01:28 -0500 Received: from mail-ve0-f169.google.com ([209.85.128.169]:48808) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1UA66v-0002dF-Va for emacs-orgmode@gnu.org; Mon, 25 Feb 2013 17:01:26 -0500 Received: by mail-ve0-f169.google.com with SMTP id 15so2740661vea.28 for ; Mon, 25 Feb 2013 14:01:25 -0800 (PST) In-Reply-To: List-Id: "General discussions about Org-mode." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org Sender: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org To: Subhan Tindall Cc: Org-mode --bcaec5016299a4ed1804d693ae93 Content-Type: text/plain; charset=UTF-8 Hello On 25 February 2013 16:34, Subhan Tindall 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::][description] or [[info:#][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 > wrote: > > (Here are the attached files, forgot to add them) > > > > > > On 25 February 2013 15:24, Jonathan Leech-Pepin > > wrote: > >> > >> Hello, > >> > >> On 25 February 2013 14:01, Subhan Tindall < > subhan.tindall@rentrakmail.com> > >> 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 > | smt@rentrakmail.com > RENTRAK | www.rentrak.com | NASDAQ: RENT > --bcaec5016299a4ed1804d693ae93 Content-Type: text/html; charset=UTF-8 Content-Transfer-Encoding: quoted-printable Hello

On 25 February 2013 16:34, Subhan T= indall <subhan.tindall@rentrakmail.com> wrote:<= br>
I noticed you left out @inforef, was that by design? =C2=A0It 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.
=C2=A0INFOREF *note Arg2: (Arg3)Lore I= psum Arg4, Arg5

I omitted @inforef, @uref, = @url @email by design because they are
external links in an org f= ile and can be processed differently. =C2=A0=C2=A0
=C2=A0
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>:&= lt;node>][description] or
[[info:<info-file>#<node>][description]] so can provide th= e 3 arguments
by splitting between file and node.

<= /div>
Regards


On Mon, Feb 25, 2013 at 12:29 PM, Jonathan Leech-Pepin
<jonathan.leechpepin@gm= ail.com> wrote:
> (Here are the attached files, forgot to add them)
>
>
> On 25 February 2013 15:24, Jonathan Leech-Pepin
> <jonathan.leechpep= in@gmail.com> wrote:
>>
>> Hello,
>>
>> On 25 February 2013 14:01, Subhan Tindall <subhan.tindall@rentrakmail.com>
>> wrote:
>>>
>>> The point being that compiling .texinfo source into an Info fi= le
>>> treats references differently. For example:
>>> (@pxref{my_node_name}). =C2=A0will 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 t= ype
>>> depending on target output of file (info, DVI, HTML,...). For = example,
>>> @pxref generates different punctuation for typeset v. info fil= es, @ref
>>> does not generate a 'See ' in printed material while @= xref does, etc.
>>>
>>> Although the differences are subtle, they really are not equiv= alent
>>> and should not be treated as such.
>>
>>
>> With a slight amount of work on the user's part, they can be m= ade
>> 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/px= ref
>> 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 "*Not= e" while the
>> equivalent "See @ref{}" becomes "See *note" wi= th @pxref{}->*note vs
>> see @ref{} -> see *note.
>>
>> However once they are viewed within the *info* buffer (C-u C-h i >> g= ood-ref.info/ref-only.info) the lines in question are visually
>> identical since *Note becomes "See" and *note becomes &q= uot;see" if there
>> is not already "see" present.
>>
>> I will not disagree that @ref, @pxref and @xref are subtly differe= nt,
>> however with slight user intervention @ref can be used in the same=
>> above locations by simply replacing:
>>
>> @xref{} =C2=A0-> "See @ref{}"
>> @pxref{} -> "see @ref{}"
>>
>> I had to compare these possible outcomes when working on the texin= fo
>> exporter. =C2=A0Since links are parsed before being included in th= eir
>> paragraphs, I did not have a way to obtain context and therefore >> attempt to guess (and be successful) at which type of reference wa= s
>> intended by a link in Org. =C2=A0Restricting it to @ref{} in all c= ases,
>> even if it added a slight burden to the user (4 additional charact= ers
>> to type in Org) if they wanted to emulate @xref or @pxref was in m= y
>> opinion the best choice.
>>
>> Regards,
>>
>> --
>> Jon
>>
>> [...]
>>
>



--
Subhan Michael Tindall | Software Developer
| smt@rentrakmail.com
RENTRAK | www.rentrak.= com | NASDAQ: RENT

--bcaec5016299a4ed1804d693ae93--