pxref in texinfo export

pxref in texinfo export

[Thomas S. Dye]

Aloha all,

IIUC, there is currently no support for @pxref{} in the texinfo
exporter.  This is a texinfo @-command that does one thing in the info
output and another in the LaTeX output.  

My idea is to create a custom link type, something like this:

(org-add-link-type
   "pxref" nil
   (lambda (path desc format)
     (cond
      ((eq format 'html)
       (format "<span class=\"pxref\">%s</span>" path))
      ((eq format 'latex)
       (format "\\ref{%s}" path))
      ((eq format 'texinfo)
       (format "@pxref{%s,%s}" path desc)))))

I haven't tested this, but it should export approximately correctly and
I'm confident I can get the export part working.

What I can't figure out is how to have Org recognize that a link like
this:

[[pxref:Internal link]]

is really an internal link, rather than an external link.  I'd like to
be able to click on this and end up at <<Internal link>> in the Org
buffer. 

Is this possible?  If so, can you point me to a solution?

All the best,
Tom

-- 
T.S. Dye & Colleagues, Archaeologists
735 Bishop St, Suite 315, Honolulu, HI 96813
Tel: 808-529-0866, Fax: 808-529-0884
http://www.tsdye.com

Re: pxref in texinfo export

[Jonathan Leech-Pepin]

[-- Attachment #1: Type: text/plain, Size: 2543 bytes --]

Hello Tom,

On 25 February 2013 12:52, Thomas S. Dye <tsd@tsdye.com> wrote:

> Aloha all,
>
> IIUC, there is currently no support for @pxref{} in the texinfo
> exporter.  This is a texinfo @-command that does one thing in the info
> output and another in the LaTeX output.
>

Ultimately there is actually no real difference between "see @ref{}"
and "@pxref{}".  I just checked using the first @pxref{} in org.texi
(Under Activation).

In org.texi it is shown as (@pxref{Conflicts}), in org.html it
becomes: (see <a href="#Conflicts">Conflicts</a>) while in the info
file (org) it is shown as (*note Conflicts::).

Opening the info file in Info (C-u C-h i <path to info file>), *node
Conflicts:: becomes "see Conflicts".  Adding "see" manually
before *note does not change the output.  The same is the case for
@xref{}.  @xref{} adds "See" before the link in html/LaTeX, and
uses *Note in the info document; "See [[link]]" produces the same See in
html/LaTeX, and creates "See *note" in the info file (which is
inserted as "See <link>" in Emacs Info.

Yes the output is different if looking at the info file directly,
however when viewing it withing Emacs the text is consistent.

I didn't implement support for @xref{} or @pxref{} in the texinfo
exporter, because I could not find a way to reliably determine the
context so as to use the right type of link in the texi file.

Using occur there were already 47 cases in org.texi where "[Ss]ee
@ref" was used rather than the stylistically appropriate @pxref/@xref.

Regards,

Jon


> My idea is to create a custom link type, something like this:
>
> (org-add-link-type
>    "pxref" nil
>    (lambda (path desc format)
>      (cond
>       ((eq format 'html)
>        (format "<span class=\"pxref\">%s</span>" path))
>       ((eq format 'latex)
>        (format "\\ref{%s}" path))
>       ((eq format 'texinfo)
>        (format "@pxref{%s,%s}" path desc)))))
>
> I haven't tested this, but it should export approximately correctly and
> I'm confident I can get the export part working.
>
> What I can't figure out is how to have Org recognize that a link like
> this:
>
> [[pxref:Internal link]]
>
> is really an internal link, rather than an external link.  I'd like to
> be able to click on this and end up at <<Internal link>> in the Org
> buffer.
>
> Is this possible?  If so, can you point me to a solution?
>

All the best,
> Tom
>
> --
> T.S. Dye & Colleagues, Archaeologists
> 735 Bishop St, Suite 315, Honolulu, HI 96813
> Tel: 808-529-0866, Fax: 808-529-0884
> http://www.tsdye.com
>
>

[-- Attachment #2: Type: text/html, Size: 3745 bytes --]

Re: pxref in texinfo export

[Subhan Tindall]

There are 4 different ref commands, all with slightly syntactic
requirements and outputs when compiled using makeinfo.  I for one use
@pxref{} a lot, and it has different requirements for placement than
@ref or @xref (namely those two MUST have a . or , following the end
of the ref)
8.1 Different Cross Reference Commands
There are four different cross reference commands:
@xref Used to start a sentence in the printed manual saying ‘See . . .
’ or an Info
         cross-reference saying ‘*Note name : node.’.
@ref Used within or, more often, at the end of a sentence; same as
@xref for Info;
    produces just the reference in the printed manual without a preceding ‘See’.
@pxref Used within parentheses to make a reference that suits both an
Info file and a
        printed book. Starts with a lower case ‘see’ within the
printed manual. (‘p’ is
               for ‘parenthesis’.)
@inforef Used to make a reference to an Info file for which there is
no printed manual.

(from the Texinfo manual)

On Mon, Feb 25, 2013 at 10:32 AM, Jonathan Leech-Pepin
<jonathan.leechpepin@gmail.com> wrote:
> Hello Tom,
>
> On 25 February 2013 12:52, Thomas S. Dye <tsd@tsdye.com> wrote:
>>
>> Aloha all,
>>
>> IIUC, there is currently no support for @pxref{} in the texinfo
>> exporter.  This is a texinfo @-command that does one thing in the info
>> output and another in the LaTeX output.
>
>
> Ultimately there is actually no real difference between "see @ref{}"
> and "@pxref{}".  I just checked using the first @pxref{} in org.texi
> (Under Activation).
>
> In org.texi it is shown as (@pxref{Conflicts}), in org.html it
> becomes: (see <a href="#Conflicts">Conflicts</a>) while in the info
> file (org) it is shown as (*note Conflicts::).
>
> Opening the info file in Info (C-u C-h i <path to info file>), *node
> Conflicts:: becomes "see Conflicts".  Adding "see" manually
> before *note does not change the output.  The same is the case for
> @xref{}.  @xref{} adds "See" before the link in html/LaTeX, and
> uses *Note in the info document; "See [[link]]" produces the same See in
> html/LaTeX, and creates "See *note" in the info file (which is
> inserted as "See <link>" in Emacs Info.
>
> Yes the output is different if looking at the info file directly,
> however when viewing it withing Emacs the text is consistent.
>
> I didn't implement support for @xref{} or @pxref{} in the texinfo
> exporter, because I could not find a way to reliably determine the
> context so as to use the right type of link in the texi file.
>
> Using occur there were already 47 cases in org.texi where "[Ss]ee
> @ref" was used rather than the stylistically appropriate @pxref/@xref.
>
> Regards,
>
> Jon
>
>>
>> My idea is to create a custom link type, something like this:
>>
>> (org-add-link-type
>>    "pxref" nil
>>    (lambda (path desc format)
>>      (cond
>>       ((eq format 'html)
>>        (format "<span class=\"pxref\">%s</span>" path))
>>       ((eq format 'latex)
>>        (format "\\ref{%s}" path))
>>       ((eq format 'texinfo)
>>        (format "@pxref{%s,%s}" path desc)))))
>>
>> I haven't tested this, but it should export approximately correctly and
>> I'm confident I can get the export part working.
>>
>> What I can't figure out is how to have Org recognize that a link like
>> this:
>>
>> [[pxref:Internal link]]
>>
>> is really an internal link, rather than an external link.  I'd like to
>> be able to click on this and end up at <<Internal link>> in the Org
>> buffer.
>>
>> Is this possible?  If so, can you point me to a solution?
>>
>>
>> All the best,
>> Tom
>>
>> --
>> T.S. Dye & Colleagues, Archaeologists
>> 735 Bishop St, Suite 315, Honolulu, HI 96813
>> Tel: 808-529-0866, Fax: 808-529-0884
>> http://www.tsdye.com
>>
>



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

Re: pxref in texinfo export

[Jonathan Leech-Pepin]

[-- Attachment #1: Type: text/plain, Size: 4755 bytes --]

Hello,

On 25 February 2013 13:40, Subhan Tindall <subhan.tindall@rentrakmail.com>wrote:

> There are 4 different ref commands, all with slightly syntactic
> requirements and outputs when compiled using makeinfo.  I for one use
> @pxref{} a lot, and it has different requirements for placement than
> @ref or @xref (namely those two MUST have a . or , following the end
> of the ref)
>

Not entirely true, @ref{} will add a period after the end of the reference
in the info output
if no period or comma present, @xref{} needs a comma or period.  @pxref{}
can be
followed by a period, comma or right parenthesis, otherwise the info output
will include
a period as well.

So all three must have some sort of punctuation (or paren) following them
to ensure that
the references are clearly delimited.

Regards,


> 8.1 Different Cross Reference Commands
> There are four different cross reference commands:
> @xref Used to start a sentence in the printed manual saying ‘See . . .
> ’ or an Info
>          cross-reference saying ‘*Note name : node.’.
> @ref Used within or, more often, at the end of a sentence; same as
> @xref for Info;
>     produces just the reference in the printed manual without a preceding
> ‘See’.
> @pxref Used within parentheses to make a reference that suits both an
> Info file and a
>         printed book. Starts with a lower case ‘see’ within the
> printed manual. (‘p’ is
>                for ‘parenthesis’.)
> @inforef Used to make a reference to an Info file for which there is
> no printed manual.
>
> (from the Texinfo manual)
>
> On Mon, Feb 25, 2013 at 10:32 AM, Jonathan Leech-Pepin
> <jonathan.leechpepin@gmail.com> wrote:
> > Hello Tom,
> >
> > On 25 February 2013 12:52, Thomas S. Dye <tsd@tsdye.com> wrote:
> >>
> >> Aloha all,
> >>
> >> IIUC, there is currently no support for @pxref{} in the texinfo
> >> exporter.  This is a texinfo @-command that does one thing in the info
> >> output and another in the LaTeX output.
> >
> >
> > Ultimately there is actually no real difference between "see @ref{}"
> > and "@pxref{}".  I just checked using the first @pxref{} in org.texi
> > (Under Activation).
> >
> > In org.texi it is shown as (@pxref{Conflicts}), in org.html it
> > becomes: (see <a href="#Conflicts">Conflicts</a>) while in the info
> > file (org) it is shown as (*note Conflicts::).
> >
> > Opening the info file in Info (C-u C-h i <path to info file>), *node
> > Conflicts:: becomes "see Conflicts".  Adding "see" manually
> > before *note does not change the output.  The same is the case for
> > @xref{}.  @xref{} adds "See" before the link in html/LaTeX, and
> > uses *Note in the info document; "See [[link]]" produces the same See in
> > html/LaTeX, and creates "See *note" in the info file (which is
> > inserted as "See <link>" in Emacs Info.
> >
> > Yes the output is different if looking at the info file directly,
> > however when viewing it withing Emacs the text is consistent.
> >
> > I didn't implement support for @xref{} or @pxref{} in the texinfo
> > exporter, because I could not find a way to reliably determine the
> > context so as to use the right type of link in the texi file.
> >
> > Using occur there were already 47 cases in org.texi where "[Ss]ee
> > @ref" was used rather than the stylistically appropriate @pxref/@xref.
> >
> > Regards,
> >
> > Jon
> >
> >>
> >> My idea is to create a custom link type, something like this:
> >>
> >> (org-add-link-type
> >>    "pxref" nil
> >>    (lambda (path desc format)
> >>      (cond
> >>       ((eq format 'html)
> >>        (format "<span class=\"pxref\">%s</span>" path))
> >>       ((eq format 'latex)
> >>        (format "\\ref{%s}" path))
> >>       ((eq format 'texinfo)
> >>        (format "@pxref{%s,%s}" path desc)))))
> >>
> >> I haven't tested this, but it should export approximately correctly and
> >> I'm confident I can get the export part working.
> >>
> >> What I can't figure out is how to have Org recognize that a link like
> >> this:
> >>
> >> [[pxref:Internal link]]
> >>
> >> is really an internal link, rather than an external link.  I'd like to
> >> be able to click on this and end up at <<Internal link>> in the Org
> >> buffer.
> >>
> >> Is this possible?  If so, can you point me to a solution?
> >>
> >>
> >> All the best,
> >> Tom
> >>
> >> --
> >> T.S. Dye & Colleagues, Archaeologists
> >> 735 Bishop St, Suite 315, Honolulu, HI 96813
> >> Tel: 808-529-0866, Fax: 808-529-0884
> >> http://www.tsdye.com
> >>
> >
>
>
>
> --
> Subhan Michael Tindall | Software Developer
> | smt@rentrakmail.com
> RENTRAK | www.rentrak.com | NASDAQ: RENT
>

[-- Attachment #2: Type: text/html, Size: 6489 bytes --]

Re: pxref in texinfo export

[Subhan Tindall]

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

On Mon, Feb 25, 2013 at 10:48 AM, Jonathan Leech-Pepin
<jonathan.leechpepin@gmail.com> wrote:
> Hello,
>
> On 25 February 2013 13:40, Subhan Tindall <subhan.tindall@rentrakmail.com>
> wrote:
>>
>> There are 4 different ref commands, all with slightly syntactic
>> requirements and outputs when compiled using makeinfo.  I for one use
>> @pxref{} a lot, and it has different requirements for placement than
>> @ref or @xref (namely those two MUST have a . or , following the end
>> of the ref)
>
>
> Not entirely true, @ref{} will add a period after the end of the reference
> in the info output
> if no period or comma present, @xref{} needs a comma or period.  @pxref{}
> can be
> followed by a period, comma or right parenthesis, otherwise the info output
> will include
> a period as well.
>
> So all three must have some sort of punctuation (or paren) following them to
> ensure that
> the references are clearly delimited.
>
> Regards,
>
>>
>> 8.1 Different Cross Reference Commands
>> There are four different cross reference commands:
>> @xref Used to start a sentence in the printed manual saying ‘See . . .
>> ’ or an Info
>>          cross-reference saying ‘*Note name : node.’.
>> @ref Used within or, more often, at the end of a sentence; same as
>> @xref for Info;
>>     produces just the reference in the printed manual without a preceding
>> ‘See’.
>> @pxref Used within parentheses to make a reference that suits both an
>> Info file and a
>>         printed book. Starts with a lower case ‘see’ within the
>> printed manual. (‘p’ is
>>                for ‘parenthesis’.)
>> @inforef Used to make a reference to an Info file for which there is
>> no printed manual.
>>
>> (from the Texinfo manual)
>>
>> On Mon, Feb 25, 2013 at 10:32 AM, Jonathan Leech-Pepin
>> <jonathan.leechpepin@gmail.com> wrote:
>> > Hello Tom,
>> >
>> > On 25 February 2013 12:52, Thomas S. Dye <tsd@tsdye.com> wrote:
>> >>
>> >> Aloha all,
>> >>
>> >> IIUC, there is currently no support for @pxref{} in the texinfo
>> >> exporter.  This is a texinfo @-command that does one thing in the info
>> >> output and another in the LaTeX output.
>> >
>> >
>> > Ultimately there is actually no real difference between "see @ref{}"
>> > and "@pxref{}".  I just checked using the first @pxref{} in org.texi
>> > (Under Activation).
>> >
>> > In org.texi it is shown as (@pxref{Conflicts}), in org.html it
>> > becomes: (see <a href="#Conflicts">Conflicts</a>) while in the info
>> > file (org) it is shown as (*note Conflicts::).
>> >
>> > Opening the info file in Info (C-u C-h i <path to info file>), *node
>> > Conflicts:: becomes "see Conflicts".  Adding "see" manually
>> > before *note does not change the output.  The same is the case for
>> > @xref{}.  @xref{} adds "See" before the link in html/LaTeX, and
>> > uses *Note in the info document; "See [[link]]" produces the same See in
>> > html/LaTeX, and creates "See *note" in the info file (which is
>> > inserted as "See <link>" in Emacs Info.
>> >
>> > Yes the output is different if looking at the info file directly,
>> > however when viewing it withing Emacs the text is consistent.
>> >
>> > I didn't implement support for @xref{} or @pxref{} in the texinfo
>> > exporter, because I could not find a way to reliably determine the
>> > context so as to use the right type of link in the texi file.
>> >
>> > Using occur there were already 47 cases in org.texi where "[Ss]ee
>> > @ref" was used rather than the stylistically appropriate @pxref/@xref.
>> >
>> > Regards,
>> >
>> > Jon
>> >
>> >>
>> >> My idea is to create a custom link type, something like this:
>> >>
>> >> (org-add-link-type
>> >>    "pxref" nil
>> >>    (lambda (path desc format)
>> >>      (cond
>> >>       ((eq format 'html)
>> >>        (format "<span class=\"pxref\">%s</span>" path))
>> >>       ((eq format 'latex)
>> >>        (format "\\ref{%s}" path))
>> >>       ((eq format 'texinfo)
>> >>        (format "@pxref{%s,%s}" path desc)))))
>> >>
>> >> I haven't tested this, but it should export approximately correctly and
>> >> I'm confident I can get the export part working.
>> >>
>> >> What I can't figure out is how to have Org recognize that a link like
>> >> this:
>> >>
>> >> [[pxref:Internal link]]
>> >>
>> >> is really an internal link, rather than an external link.  I'd like to
>> >> be able to click on this and end up at <<Internal link>> in the Org
>> >> buffer.
>> >>
>> >> Is this possible?  If so, can you point me to a solution?
>> >>
>> >>
>> >> All the best,
>> >> Tom
>> >>
>> >> --
>> >> T.S. Dye & Colleagues, Archaeologists
>> >> 735 Bishop St, Suite 315, Honolulu, HI 96813
>> >> Tel: 808-529-0866, Fax: 808-529-0884
>> >> http://www.tsdye.com
>> >>
>> >
>>
>>
>>
>> --
>> Subhan Michael Tindall | Software Developer
>> | smt@rentrakmail.com
>> RENTRAK | www.rentrak.com | NASDAQ: RENT
>
>



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

Re: pxref in texinfo export

[Jonathan Leech-Pepin]

[-- Attachment #1: Type: text/plain, Size: 2745 bytes --]

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

[...]

[-- Attachment #2: Type: text/html, Size: 3560 bytes --]

Re: pxref in texinfo export

[Jonathan Leech-Pepin]

[-- Attachment #1.1: Type: text/plain, Size: 3013 bytes --]

(Here are the attached files, forgot to add them)

On 25 February 2013 15:24, Jonathan Leech-Pepin <
jonathan.leechpepin@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 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
>
> [...]
>
>

[-- Attachment #1.2: Type: text/html, Size: 4039 bytes --]

[-- Attachment #2: good-ref.texi --]
[-- Type: application/x-texinfo, Size: 2908 bytes --]

[-- Attachment #3: ref.texi --]
[-- Type: application/x-texinfo, Size: 2911 bytes --]

Re: pxref in texinfo export

[Subhan Tindall]

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




On Mon, Feb 25, 2013 at 12:29 PM, Jonathan Leech-Pepin
<jonathan.leechpepin@gmail.com> wrote:
> (Here are the attached files, forgot to add them)
>
>
> On 25 February 2013 15:24, Jonathan Leech-Pepin
> <jonathan.leechpepin@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 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

Re: pxref in texinfo export

[Nicolas Goaziou]

Hello,

Jonathan Leech-Pepin <jonathan.leechpepin@gmail.com> writes:

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

What kind of context would you need to know? The string that will be
exported just before the current ref link?


Regards,

-- 
Nicolas Goaziou

Re: pxref in texinfo export

[Subhan Tindall]

I don't think there is a specific context that can clearly separate
them. The differences are largely semantic, not syntactic. What is
needed is some sort of marker on the tag in the original file telling
it what kind of link is to be used.



On Mon, Feb 25, 2013 at 1:38 PM, Nicolas Goaziou <n.goaziou@gmail.com> wrote:
> Hello,
>
> Jonathan Leech-Pepin <jonathan.leechpepin@gmail.com> writes:
>
>> 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.
>
> What kind of context would you need to know? The string that will be
> exported just before the current ref link?
>
>
> Regards,
>
> --
> Nicolas Goaziou



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

Re: pxref in texinfo export

[Jonathan Leech-Pepin]

[-- Attachment #1: Type: text/plain, Size: 4377 bytes --]

Hello

On 25 February 2013 16:34, Subhan Tindall <subhan.tindall@rentrakmail.com>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
> <jonathan.leechpepin@gmail.com> wrote:
> > (Here are the attached files, forgot to add them)
> >
> >
> > On 25 February 2013 15:24, Jonathan Leech-Pepin
> > <jonathan.leechpepin@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 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
>

[-- Attachment #2: Type: text/html, Size: 6343 bytes --]

Re: pxref in texinfo export

[Jonathan Leech-Pepin]

[-- Attachment #1: Type: text/plain, Size: 1826 bytes --]

Hello

On 25 February 2013 16:48, Subhan Tindall <subhan.tindall@rentrakmail.com>wrote:

> I don't think there is a specific context that can clearly separate
> them. The differences are largely semantic, not syntactic. What is
> needed is some sort of marker on the tag in the original file telling
>  it what kind of link is to be used.
>

Agreed, although there is a semi-syntactic method potentially.


>
> On Mon, Feb 25, 2013 at 1:38 PM, Nicolas Goaziou <n.goaziou@gmail.com>
> wrote:
> > Hello,
> >
> > Jonathan Leech-Pepin <jonathan.leechpepin@gmail.com> writes:
> >
> >> 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.
> >
> > What kind of context would you need to know? The string that will be
> > exported just before the current ref link?
> >


 For @xref{} I would need to know if it was at the start of a sentence and
followed
by a comma or period.
For @pxref{} I would need to determine if it was at end of sentence,
mid sentence followed by a comma or within parentheses, and not preceeded by
"see" or "see".  Although even this would not suffice, since there are
contexts where
@ref{} is the better choice.

Allowing for attributes on the links would allow for differentiating,
however the
alternative (which is the current behaviour) is just to create them all as
@ref{} and
then include the semantic context (See, see or nil) as appropriate for
export.

Regards,

Jon


> > Regards,
> >
> > --
> > Nicolas Goaziou
>
>
>
> --
> Subhan Michael Tindall | Software Developer
> | smt@rentrakmail.com
> RENTRAK | www.rentrak.com | NASDAQ: RENT
>

[-- Attachment #2: Type: text/html, Size: 2957 bytes --]

Re: pxref in texinfo export

[Nicolas Goaziou]

Jonathan Leech-Pepin <jonathan.leechpepin@gmail.com> writes:

>  For @xref{} I would need to know if it was at the start of a sentence and
> followed
> by a comma or period.
> For @pxref{} I would need to determine if it was at end of sentence,
> mid sentence followed by a comma or within parentheses, and not preceeded by
> "see" or "see".  Although even this would not suffice, since there are
> contexts where
> @ref{} is the better choice.

FWIW, from `org-texinfo-link',

  (org-export-data (org-export-get-previous-element link info t) info)

will give you the exported string so far in the container element and 

  (org-export-data (org-export-get-next-element link info t) info)

will return the string that will follow your link.

You need to upgrade Org for the first snippet, as order for `o-e-g-p-e'
return value has changed.


Regards,

-- 
Nicolas Goaziou