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 15:24:33 -0500 Message-ID: References: Mime-Version: 1.0 Content-Type: multipart/alternative; boundary=bcaec50162994358ad04d69254cc Return-path: Received: from eggs.gnu.org ([208.118.235.92]:50401) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1UA4bF-00013l-43 for emacs-orgmode@gnu.org; Mon, 25 Feb 2013 15:24:42 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1UA4bC-0006TF-Tp for emacs-orgmode@gnu.org; Mon, 25 Feb 2013 15:24:36 -0500 Received: from mail-ve0-f173.google.com ([209.85.128.173]:56683) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1UA4bC-0006T9-OL for emacs-orgmode@gnu.org; Mon, 25 Feb 2013 15:24:34 -0500 Received: by mail-ve0-f173.google.com with SMTP id oz10so2593857veb.4 for ; Mon, 25 Feb 2013 12:24:34 -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 --bcaec50162994358ad04d69254cc Content-Type: text/plain; charset=UTF-8 Hello, On 25 February 2013 14:01, Subhan Tindall 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 [...] --bcaec50162994358ad04d69254cc Content-Type: text/html; charset=UTF-8 Content-Transfer-Encoding: quoted-printable 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}). =C2=A0will compile just fine.
(@ref{my_node_name}). will not. =C2=A0

Both work perfe= ctly fine for me.
makeinfo (GNU texinfo) 5.0
=C2=A0
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, et= c.

Although the differences are subtle, they really are not equivalent
and should not be treated as such.
=C2=A0
Wi= th a slight amount of work on the user's part, they can be made
func= tionally 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
appropria= te See/see added in the text) and disregarding filename
differences (sin= ce 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.tex= i
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" w= hile the
equivalent "See @ref{}" becomes "See *note"= with @pxref{}->*note vs
see @ref{} -> see *note.

However o= nce they are viewed within the *info* buffer (C-u C-h i
good-ref.info/ref-only.info<= /a>) the lines in question are visually
identical since *Note becomes &q= uot;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
abo= ve locations by simply replacing:

@xref{}=C2=A0 -> "See @ref= {}"
@pxref{} -> "see @ref{}"

I had to compare these possibl= e outcomes when working on the texinfo
exporter.=C2=A0 Since links are p= arsed 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
inte= nded by a link in Org.=C2=A0 Restricting it to @ref{} in all cases,
even= if it added a slight burden to the user (4 additional characters
to typ= e in Org) if they wanted to emulate @xref or @pxref was in my
opinion the best choice.

Regards,

--
Jon

[...]
<= /div>

--bcaec50162994358ad04d69254cc--