From: Subhan Tindall <subhan.tindall@rentrakmail.com>
To: Jonathan Leech-Pepin <jonathan.leechpepin@gmail.com>
Cc: Org-mode <emacs-orgmode@gnu.org>, "Thomas S. Dye" <tsd@tsdye.com>
Subject: Re: pxref in texinfo export
Date: Mon, 25 Feb 2013 11:01:38 -0800 [thread overview]
Message-ID: <CAKKEbDt-+1NCFSpNperv=5aPpqECMGOMp89AUsknJuLQKW3VKQ@mail.gmail.com> (raw)
In-Reply-To: <CAEWDx5eqSEh1_5U7ZHVCoLkAdmVSzoi_BaD=zs-xU-8GnQKU=A@mail.gmail.com>
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
next prev parent reply other threads:[~2013-02-25 19:02 UTC|newest]
Thread overview: 13+ messages / expand[flat|nested] mbox.gz Atom feed top
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 [this message]
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
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://www.orgmode.org/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to='CAKKEbDt-+1NCFSpNperv=5aPpqECMGOMp89AUsknJuLQKW3VKQ@mail.gmail.com' \
--to=subhan.tindall@rentrakmail.com \
--cc=emacs-orgmode@gnu.org \
--cc=jonathan.leechpepin@gmail.com \
--cc=tsd@tsdye.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
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).