From mboxrd@z Thu Jan 1 00:00:00 1970 From: Subhan Tindall Subject: Re: pxref in texinfo export Date: Mon, 25 Feb 2013 11:01:38 -0800 Message-ID: References: Mime-Version: 1.0 Content-Type: text/plain; charset=windows-1252 Content-Transfer-Encoding: quoted-printable Return-path: Received: from eggs.gnu.org ([208.118.235.92]:37952) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1UA3JF-0003DW-GG for emacs-orgmode@gnu.org; Mon, 25 Feb 2013 14:02:01 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1UA3Iz-0004S6-8V for emacs-orgmode@gnu.org; Mon, 25 Feb 2013 14:01:55 -0500 Received: from mail-la0-x229.google.com ([2a00:1450:4010:c03::229]:41447) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1UA3Iy-0004Re-Rq for emacs-orgmode@gnu.org; Mon, 25 Feb 2013 14:01:41 -0500 Received: by mail-la0-f41.google.com with SMTP id fo12so3052499lab.14 for ; Mon, 25 Feb 2013 11:01:38 -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: 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 wrote: > Hello, > > On 25 February 2013 13:40, Subhan Tindall > 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 referenc= e > 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 outp= ut > 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 =91See . . . >> =92 or an Info >> cross-reference saying =91*Note name : node.=92. >> @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 precedin= g >> =91See=92. >> @pxref Used within parentheses to make a reference that suits both an >> Info file and a >> printed book. Starts with a lower case =91see=92 within the >> printed manual. (=91p=92 is >> for =91parenthesis=92.) >> @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 >> wrote: >> > Hello Tom, >> > >> > On 25 February 2013 12:52, Thomas S. Dye 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 inf= o >> >> 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 Conflicts) while in the info >> > file (org) it is shown as (*note Conflicts::). >> > >> > Opening the info file in Info (C-u C-h i ), *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 " 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 "%s" 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 a= nd >> >> 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 t= o >> >> be able to click on this and end up at <> 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 > > --=20 Subhan Michael Tindall | Software Developer | smt@rentrakmail.com RENTRAK | www.rentrak.com | NASDAQ: RENT