* pxref in texinfo export
@ 2013-02-25 17:52 Thomas S. Dye
2013-02-25 18:32 ` Jonathan Leech-Pepin
0 siblings, 1 reply; 13+ messages in thread
From: Thomas S. Dye @ 2013-02-25 17:52 UTC (permalink / raw)
To: Org-mode
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
^ permalink raw reply [flat|nested] 13+ messages in thread* Re: pxref in texinfo export 2013-02-25 17:52 pxref in texinfo export Thomas S. Dye @ 2013-02-25 18:32 ` Jonathan Leech-Pepin 2013-02-25 18:40 ` Subhan Tindall 0 siblings, 1 reply; 13+ messages in thread From: Jonathan Leech-Pepin @ 2013-02-25 18:32 UTC (permalink / raw) To: Thomas S. Dye; +Cc: Org-mode [-- 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 --] ^ permalink raw reply [flat|nested] 13+ messages in thread
* Re: pxref in texinfo export 2013-02-25 18:32 ` Jonathan Leech-Pepin @ 2013-02-25 18:40 ` Subhan Tindall 2013-02-25 18:48 ` Jonathan Leech-Pepin 0 siblings, 1 reply; 13+ messages in thread From: Subhan Tindall @ 2013-02-25 18:40 UTC (permalink / raw) To: Jonathan Leech-Pepin; +Cc: Org-mode, Thomas S. Dye 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 ^ permalink raw reply [flat|nested] 13+ messages in thread
* Re: pxref in texinfo export 2013-02-25 18:40 ` Subhan Tindall @ 2013-02-25 18:48 ` Jonathan Leech-Pepin 2013-02-25 19:01 ` Subhan Tindall 0 siblings, 1 reply; 13+ messages in thread From: Jonathan Leech-Pepin @ 2013-02-25 18:48 UTC (permalink / raw) To: Subhan Tindall; +Cc: Org-mode, Thomas S. Dye [-- 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 --] ^ permalink raw reply [flat|nested] 13+ messages in thread
* Re: pxref in texinfo export 2013-02-25 18:48 ` Jonathan Leech-Pepin @ 2013-02-25 19:01 ` Subhan Tindall 2013-02-25 20:24 ` Jonathan Leech-Pepin 0 siblings, 1 reply; 13+ messages in thread From: Subhan Tindall @ 2013-02-25 19:01 UTC (permalink / raw) To: Jonathan Leech-Pepin; +Cc: Org-mode, Thomas S. Dye 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 ^ permalink raw reply [flat|nested] 13+ messages in thread
* Re: pxref in texinfo export 2013-02-25 19:01 ` Subhan Tindall @ 2013-02-25 20:24 ` Jonathan Leech-Pepin 2013-02-25 20:29 ` Jonathan Leech-Pepin 2013-02-25 21:38 ` Nicolas Goaziou 0 siblings, 2 replies; 13+ messages in thread From: Jonathan Leech-Pepin @ 2013-02-25 20:24 UTC (permalink / raw) To: Subhan Tindall; +Cc: Org-mode [-- 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 --] ^ permalink raw reply [flat|nested] 13+ messages in thread
* Re: pxref in texinfo export 2013-02-25 20:24 ` Jonathan Leech-Pepin @ 2013-02-25 20:29 ` Jonathan Leech-Pepin 2013-02-25 21:34 ` Subhan Tindall 2013-02-25 21:38 ` Nicolas Goaziou 1 sibling, 1 reply; 13+ messages in thread From: Jonathan Leech-Pepin @ 2013-02-25 20:29 UTC (permalink / raw) To: Subhan Tindall; +Cc: Org-mode [-- 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 --] ^ permalink raw reply [flat|nested] 13+ messages in thread
* Re: pxref in texinfo export 2013-02-25 20:29 ` Jonathan Leech-Pepin @ 2013-02-25 21:34 ` Subhan Tindall 2013-02-25 22:01 ` Jonathan Leech-Pepin 0 siblings, 1 reply; 13+ messages in thread From: Subhan Tindall @ 2013-02-25 21:34 UTC (permalink / raw) To: Jonathan Leech-Pepin; +Cc: Org-mode 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 ^ permalink raw reply [flat|nested] 13+ messages in thread
* Re: pxref in texinfo export 2013-02-25 21:34 ` Subhan Tindall @ 2013-02-25 22:01 ` Jonathan Leech-Pepin 0 siblings, 0 replies; 13+ messages in thread From: Jonathan Leech-Pepin @ 2013-02-25 22:01 UTC (permalink / raw) To: Subhan Tindall; +Cc: Org-mode [-- 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 --] ^ permalink raw reply [flat|nested] 13+ messages in thread
* Re: pxref in texinfo export 2013-02-25 20:24 ` Jonathan Leech-Pepin 2013-02-25 20:29 ` Jonathan Leech-Pepin @ 2013-02-25 21:38 ` Nicolas Goaziou 2013-02-25 21:48 ` Subhan Tindall 1 sibling, 1 reply; 13+ messages in thread From: Nicolas Goaziou @ 2013-02-25 21:38 UTC (permalink / raw) To: Jonathan Leech-Pepin; +Cc: Org-mode, Subhan Tindall 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 ^ permalink raw reply [flat|nested] 13+ messages in thread
* Re: pxref in texinfo export 2013-02-25 21:38 ` Nicolas Goaziou @ 2013-02-25 21:48 ` Subhan Tindall 2013-02-25 22:06 ` Jonathan Leech-Pepin 0 siblings, 1 reply; 13+ messages in thread From: Subhan Tindall @ 2013-02-25 21:48 UTC (permalink / raw) To: Nicolas Goaziou; +Cc: Org-mode, Jonathan Leech-Pepin 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 ^ permalink raw reply [flat|nested] 13+ messages in thread
* Re: pxref in texinfo export 2013-02-25 21:48 ` Subhan Tindall @ 2013-02-25 22:06 ` Jonathan Leech-Pepin 2013-02-25 22:23 ` Nicolas Goaziou 0 siblings, 1 reply; 13+ messages in thread From: Jonathan Leech-Pepin @ 2013-02-25 22:06 UTC (permalink / raw) To: Subhan Tindall; +Cc: Org-mode, Nicolas Goaziou [-- 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 --] ^ permalink raw reply [flat|nested] 13+ messages in thread
* Re: pxref in texinfo export 2013-02-25 22:06 ` Jonathan Leech-Pepin @ 2013-02-25 22:23 ` Nicolas Goaziou 0 siblings, 0 replies; 13+ messages in thread From: Nicolas Goaziou @ 2013-02-25 22:23 UTC (permalink / raw) To: Jonathan Leech-Pepin; +Cc: Org-mode, Subhan Tindall 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 ^ permalink raw reply [flat|nested] 13+ messages in thread
end of thread, other threads:[~2013-02-25 22:23 UTC | newest] Thread overview: 13+ messages (download: mbox.gz / follow: Atom feed) -- links below jump to the message on this page -- 2013-02-25 17:52 pxref in texinfo export Thomas S. Dye 2013-02-25 18:32 ` Jonathan Leech-Pepin 2013-02-25 18:40 ` Subhan Tindall 2013-02-25 18:48 ` Jonathan Leech-Pepin 2013-02-25 19:01 ` Subhan Tindall 2013-02-25 20:24 ` Jonathan Leech-Pepin 2013-02-25 20:29 ` Jonathan Leech-Pepin 2013-02-25 21:34 ` Subhan Tindall 2013-02-25 22:01 ` Jonathan Leech-Pepin 2013-02-25 21:38 ` Nicolas Goaziou 2013-02-25 21:48 ` Subhan Tindall 2013-02-25 22:06 ` Jonathan Leech-Pepin 2013-02-25 22:23 ` Nicolas Goaziou
Code repositories for project(s) associated with this public inbox https://git.savannah.gnu.org/cgit/emacs/org-mode.git This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).