Re: [O] [dev] Implement ref link types
On the Org side, when a link like [[something]] or [[something][text]] is encountered in a buffer, the search would go on like this: 1. Search any something or #+target: something[1]. 1. A link to an invisible target will be replaced with _nothing_ (that's the point of being invisible). What led you to come up with this interpretation? [3]. A target *reference* will *always* export and create a clickable link irrespective how the target is *defined*. Read on... [1] This is the replacement for invisible targets, since they cannot live in comments anymore. I think there is an element of confusion about what invisible target is. After some digging, I realize that they were originally called as invisible anchors. The manual [1] has the following note: , |* Matt Lundin has proposed last-row references for table formulas | and named invisible anchors. ` The original post [2] from Matt says , | # radiotarget | | should become | | a name=radiotarget/a ` Now the question is what is invisible? The description in a ... /a becomes invisible. Why was the term invisible chosen in the first place. For this one has to look at the the default behaviour for targets which is to export with *both* the anchor name and anchor description. So, I think a correction is in order. Footnotes: [1] (info (org) History and Acknowledgments) [2] http://lists.gnu.org/archive/html/emacs-orgmode/2008-11/msg00327.html [3] If I export the following unit test snippet, the produced output from LaTeX/PDF has *just* Paragraph and nothing else. , | Paragraph. | #+TARGET: Test | [[Test]] ` --
Re: [O] [dev] Implement ref link types
Hello, Here is a new version of the patch built on top of master, along with test cases. If there is no objection, I'll push it to master in a couple of days. I really think that's a great feature to have in Org. Regards, -- Nicolas Goaziou From 2fdde87bb7f1241f3d24dbd8ae030a300fe8f0fc Mon Sep 17 00:00:00 2001 From: Nicolas Goaziou n.goaz...@gmail.com Date: Mon, 20 Feb 2012 22:24:38 +0100 Subject: [PATCH] Implement numbered cross-references * lisp/org.el (org-link-search): Search for #+name affiliated keywords and invisible targets. * contrib/lisp/org-element.el (org-element-link-parser): Remove ref links relative part. (org-element-target-parser): Move property name from `:raw-value' to `:value'. (org-element-recursive-objects): Remove targets from tables. Cells are not parsed unless explicitely asked by back-end developer, too late. A target wouldn't be noticed in time. One solution could be to parse every table, but that's time consumming. (org-element-object-restrictions): Target are not recursive anymore. * contrib/lisp/org-export.el (org-export-resolve-fuzzy-link): Find elements with a matching #+name: path affiliated keyword. (org-export-get-ordinal): Make special cases for headlines, items, footnotes definitions and references. (org-export-resolve-ref-link): Removed function. * EXPERIMENTAL/org-e-latex.el (org-e-latex-link): Handle cross-reference numbers. (org-e-latex-target): Targets have no contents. * EXPERIMENTAL/org-e-ascii.el (org-e-ascii--describe-links): Ignore fuzzy links in link description at the end of the section. (org-e-ascii-link): Handle cross-reference numbers. * testing/contrib/lisp/test-org-export.el: Add tests. * testing/lisp/test-org.el: Add tests. --- EXPERIMENTAL/org-e-ascii.el | 80 -- EXPERIMENTAL/org-e-latex.el | 50 +-- contrib/lisp/org-element.el | 20 ++--- contrib/lisp/org-export.el | 141 --- lisp/org.el | 16 testing/contrib/lisp/test-org-export.el | 91 testing/lisp/test-org.el| 41 + 7 files changed, 299 insertions(+), 140 deletions(-) diff --git a/EXPERIMENTAL/org-e-ascii.el b/EXPERIMENTAL/org-e-ascii.el index 0eb547b..c9cca4a 100644 --- a/EXPERIMENTAL/org-e-ascii.el +++ b/EXPERIMENTAL/org-e-ascii.el @@ -825,28 +825,24 @@ channel. (if (not desc) (org-element-property :raw-link link) (org-export-secondary-string desc 'e-ascii info) (cond - ;; Coderefs, radio links and ref links are ignored. - ((member type '(coderef radio ref)) nil) - ;; Id, custom-id and fuzzy links (with the exception of - ;; targets): Headlines refer to their numbering. - ((member type '(custom-id fuzzy id)) - (let ((destination (if (string= type fuzzy) -(org-export-resolve-fuzzy-link link info) - (org-export-resolve-id-link link info - (unless (eq (org-element-type destination) 'target) - (concat - (org-e-ascii--fill-string - (format - [%s] %s - anchor - (if (not destination) - (org-e-ascii--translate Unknown reference info) - (format - (org-e-ascii--translate See section %s info) - (mapconcat 'number-to-string - (org-export-get-headline-number destination info) - . - width info) \n\n + ;; Coderefs, radio links and fuzzy links are ignored. + ((member type '(coderef radio fuzzy)) nil) + ;; Id and custom-id links: Headlines refer to their numbering. + ((member type '(custom-id id)) + (let ((destination (org-export-resolve-id-link link info))) + (concat + (org-e-ascii--fill-string + (format + [%s] %s + anchor + (if (not destination) + (org-e-ascii--translate Unknown reference info) + (format + (org-e-ascii--translate See section %s info) + (mapconcat 'number-to-string + (org-export-get-headline-number destination info) + . + width info) \n\n))) ;; Do not add a link that cannot be resolved and doesn't have ;; any description: destination is already visible in the ;; paragraph. @@ -1390,29 +1386,23 @@ INFO is a plist holding contextual information. (org-element-property :path link) (cdr (assq 'radio-target org-element-object-restrictions))) 'e-ascii info)) - ;; Ref link: If there's no description (DESC, return link's - ;; destination sequence number among elements of same - ;; type. Otherwise, use DESC. - ((string= type ref) - (if (org-string-nw-p desc) desc - (format %d - (org-export-get-ordinal - (org-export-resolve-ref-link link info) - info nil nil - (lambda (el) (or (org-element-property :caption el) - (org-element-property :name el))) ;; Do not apply a special syntax on fuzzy links pointing to ;; targets. - ((and (string= type fuzzy) - (let ((path (org-element-property :path link))) - (loop for target in (plist-get info
Re: [O] [dev] Implement ref link types
At Tue, 21 Feb 2012 10:18:00 +0100, Nicolas Goaziou wrote: Hello, David Maus dm...@ictsoc.de writes: I don't see why we should drop the link type in fuzzy links. After all they /are/ are special type of link. There is no link type in fuzzy links : [[something]] matches something in master. Without the link type we will run into trouble, won't we?. In the example file: , | We end the list at item [[itm:last]]. ` So, itm:last is a fuzzy link but it could as well be a regular link of type itm with a path component of last and no description. I realize my examples are confusing. I shouldn't have used colons. In fact, the output will be the same if the target is itm-last, table-last or even foo. In other words, the itm: part wasn't meant as a link type, but as a cosmetic part of the name. So the list example could as well be: Thanks for the clarification. Best, -- David -- OpenPGP... 0x99ADB83B5A4478E6 Jabber dmj...@jabber.org Email. dm...@ictsoc.de pgpSeuw3JODk6.pgp Description: PGP signature
Re: [O] [dev] Implement ref link types
Hello,
David Maus dm...@ictsoc.de writes:
I don't see why we should drop the link type in fuzzy links. After all
they /are/ are special type of link.
There is no link type in fuzzy links : [[something]] matches
something in master.
Without the link type we will run into trouble, won't we?.
In the example file:
,
| We end the list at item [[itm:last]].
`
So, itm:last is a fuzzy link but it could as well be a regular link
of type itm with a path component of last and no description.
I realize my examples are confusing. I shouldn't have used colons. In
fact, the output will be the same if the target is itm-last,
table-last or even foo.
In other words, the itm: part wasn't meant as a link type, but as
a cosmetic part of the name. So the list example could as well be:
#+begin_src org
1. A first item in a list.
2. Another item
1. With three subparts. This one.
2. Another one.
3. last And the last subpart.
We end the list at item [[last]].
#+end_src
If we say that we use itm:last as a fuzzy link iff there is no
registered link type itm we might put people into trouble if in some
point in the future Org mode introduces a link of type itm and the
fuzzy links stop working.
Certainly. I should have used another name for my examples.
The point is that a fuzzy link [[foo]] will detect the context of its
matching target (foo) or element (#+name: foo) and return an
appropriate sequence number.
The main difference with the current behaviour is that the target part
is ignored. At the moment, in LaTeX, path becomes
\label{path}path. It will be only \label{path} with the patch. This
allows for more flexibility (note that other types of targets, like
radio targets are unchanged).
Or is there any technical reason to use [[itm:last]] instead of
[[ref:itm:last]]?
I won't answer this question, since it came out from a mistake of
mine. Though, I'd answer another one: Why do I prefer [[something]]
over [[ref:something]]?.
Thank you for asking this... Well, that's because Org also recognizes
plain links, i.e. http//orgmode.org. And, for an internal link, I'd
rather enforce the use of square brackets, as it is done actually.
Also, we don't require extra syntax, unless we don't want to change
behaviour of targets.
Regards,
--
Nicolas Goaziou
Re: [O] [dev] Implement ref link types
Hello, Carsten Dominik carsten.domi...@gmail.com writes: On Feb 20, 2012, at 1:51 AM, Nicolas Goaziou wrote: There are still a few limitations. For example, you cannot reference a precise list item since items do not accept affiliated keywords. Ah, yes, this is right. Thinking about it, there may exist a better alternative to [[ref:name]] links: fuzzy links. In other words, #+name: something could be made an alternate of something, with a lower priority. On the Org side, when a link like [[something]] or [[something][text]] is encountered in a buffer, the search would go on like this: 1. Search any something or #+target: something[1]. 2. If none is found, search any #+name: something. 3. If it fails, try to find the headline * something. 4. Eventually offer to create such headline. This step doesn't apply during export. On the export side, it depends on the description part of the link: - If there's a description (i.e. [[something][description]]), display it and link to target if possible, whatever that target is. - If there's no description: 1. A link to an invisible target will be replaced with _nothing_ (that's the point of being invisible). 2. A link to a target (i.e. something) will be replaced with the sequence number of the closest item or headline[2]. Examples: #+begin_src org - item one - item two - here item two dot one #+end_src Any link like [[here]] will be replaced with 2.1 during export. #+begin_src org * Headline one * Headline two * Headline two dot one Some paragraph. Another paragraph warning. #+end_src Here [[warning]] will also be replaced with 2.1 during export. Note that [[Headline two dot one]] would also be replaced with 2.1. 3. An link to an element (i.e. #+name: something) would return the sequence number of that element among elements of the same type with a caption, a name affiliated keyword, or both. Example: #+begin_src org #+name: letters #+caption: I know my alphabet. |a|b|c| |foo|bar| #+name: numbers |1|2|3| #+end_src Here, a [[numbers]] link would be replaced with 2, since middle table has no name nor caption. To sum it up, at a quick glance, I can see the following: - Pros :: + No new syntax, + Possibly number every element, including items. - Cons :: + Fuzzy links are a bit overloaded, but, on the other hand, linking to headlines is not very useful since custom-id and id implementation. + There is more documentation to write. Again, what do you think? Regards, [1] This is the replacement for invisible targets, since they cannot live in comments anymore. [2] If headlines are not numbered (i.e. num:nil), replace link with headline's title instead. -- Nicolas Goaziou
Re: [O] [dev] Implement ref link types
Completing myself, here is a patch implementing the previous suggestion,
along with example output obtained with it. You may need to
(fmakunbound 'org-e-ascii-target) to avoid an error, since this patch
removes the function.
First, the test buffer.
#+begin_src org
#+TITLE: Cross-references
#+LANGUAGE: en
* First headline.
Here we demonstrate cross-references to items.
1. A first item in a list.
2. Another item
1. With three subparts. This one.
2. Another one.
3. itm:last And the last subpart.
We end the list at item [[itm:last]].
Before we continue, here is a rather trivial equation, assuming base
isn't too low[fn:1].
#+name: eq:trivial
\begin{equation}
1 + 1 = 2
\end{equation}
We can verify it with the following code:
#+name: oneplusone
#+caption: Shortly after the beginning of arithmetic.
#+BEGIN_SRC emacs-lisp :exports code
(+ 1 1)
#+END_SRC
** Sub-topic
Here we demonstrate cross-references to tables.sec:tables
#+name: tab:numbers
#+caption: Test
| one | 1 |
| two | 2 |
#+name: tab:letters
#+caption: Letters
| a | aille |
| b | bi|
In table [[tab:numbers]] we can only see two numbers. Yet, in
[[tab:numbers][the very
same table]], we can already tell the radix used isn't too low
(remember footnote [[fn:basetwo]]?). On the other hand, table
[[tab:letters]] shows letters, but that's clearly uninteresting.
#+name: eq:euler
\begin{equation}
e^{i\pi} + 1 = 0
\end{equation}
Equation [[eq:euler]], also known as Euler's equation, is remarkable
unlike to the equation [[eq:trivial]], which is boring (except the
elisp part, in listing [[oneplusone]]).
#+target: end
This is the end of section [[sec:tables]]. [[end][Invisible link to line
above]]
* Footnotes
[fn:1] fn:basetwo That is strictly greater than two.
#+end_src
Then the ASCII output.
#+begin_src text
1 First headline.
=
Here we demonstrate cross-references to items.
1. A first item in a list.
2. Another item
1. With three subparts. This one.
2. Another one.
3. And the last subpart.
We end the list at item 2.3.
Before we continue, here is a rather trivial equation, assuming base
isn't too low[1].
\begin{equation}
1 + 1 = 2
\end{equation}
We can verify it with the following code:
,
| (+ 1 1)
`
Listing 1: Shortly after the beginning of arithmetic.
1.1 Sub-topic
~
Here we demonstrate cross-references to tables.
one 1
two 2
Table 1: Test
a aille
b bi
Table 2: Letters
In table 1 we can only see two numbers. Yet, in the very same table,
we can already tell the radix used isn't too low (remember footnote
1?). On the other hand, table 2 shows letters, but that's clearly
uninteresting.
\begin{equation}
e^{i\pi} + 1 = 0
\end{equation}
Equation 2, also known as Euler's equation, is remarkable unlike to
the equation 1, which is boring (except the elisp part, in listing 1).
This is the end of section 1.1.
#+end_src
And with LaTeX.
#+begin_src latex
\section{First headline.}
\label{sec-1}
Here we demonstrate cross-references to items.
\begin{enumerate}
\item A first item in a list.
\item Another item
\begin{enumerate}
\item With three subparts. This one.
\item Another one.
\item \label{itm:last} And the last subpart.
\end{enumerate}
\end{enumerate}
We end the list at item \ref{itm:last}.
Before we continue, here is a rather trivial equation, assuming base
isn't too low\footnote{\label{fn:basetwo} That is strictly greater than two.}.
\begin{equation}
\label{eq:trivial}
1 + 1 = 2
\end{equation}
We can verify it with the following code:
\begin{figure}[H]
\caption{\label{oneplusone}Shortly after the beginning of arithmetic.}
\begin{verbatim}
(+ 1 1)
\end{verbatim}
\end{figure}
\subsection{Sub-topic}
\label{sec-1-1}
Here we demonstrate cross-references to tables.\label{sec:tables}
\begin{table}[htb]
\caption{\label{tab:numbers}Test}
\begin{center}
\begin{tabular}{lr}
one 1 \\
two 2 \\
\end{tabular}
\end{center}
\end{table}
\begin{table}[htb]
\caption{\label{tab:letters}Letters}
\begin{center}
\begin{tabular}{ll}
a aille \\
b bi \\
\end{tabular}
\end{center}
\end{table}
In table \ref{tab:numbers} we can only see two numbers. Yet, in
\hyperref[tab:numbers]{the very
same table}, we can already tell the radix used isn't too low
(remember footnote \ref{fn:basetwo}?). On the other hand, table
\ref{tab:letters} shows letters, but that's clearly uninteresting.
\begin{equation}
\label{eq:euler}
e^{i\pi} + 1 = 0
\end{equation}
Equation \ref{eq:euler}, also known as Euler's equation, is remarkable
unlike to the equation \ref{eq:trivial}, which is boring (except the
elisp part, in listing \ref{oneplusone}).
This is the end of section \ref{sec:tables}.
#+end_src
Regards,
--
Nicolas Goaziou
From dcae2d1015f958dcb1ed3c92349ad0c2e18a1219 Mon Sep 17 00:00:00
Re: [O] [dev] Implement ref link types
Nice!
Nicolas Goaziou n.goaz...@gmail.com writes:
Completing myself, here is a patch implementing the previous suggestion,
along with example output obtained with it. You may need to
(fmakunbound 'org-e-ascii-target) to avoid an error, since this patch
removes the function.
First, the test buffer.
#+begin_src org
#+TITLE: Cross-references
#+LANGUAGE: en
* First headline.
Here we demonstrate cross-references to items.
1. A first item in a list.
2. Another item
1. With three subparts. This one.
2. Another one.
3. itm:last And the last subpart.
We end the list at item [[itm:last]].
Before we continue, here is a rather trivial equation, assuming base
isn't too low[fn:1].
#+name: eq:trivial
\begin{equation}
1 + 1 = 2
\end{equation}
We can verify it with the following code:
#+name: oneplusone
#+caption: Shortly after the beginning of arithmetic.
#+BEGIN_SRC emacs-lisp :exports code
(+ 1 1)
#+END_SRC
** Sub-topic
Here we demonstrate cross-references to tables.sec:tables
#+name: tab:numbers
#+caption: Test
| one | 1 |
| two | 2 |
#+name: tab:letters
#+caption: Letters
| a | aille |
| b | bi|
In table [[tab:numbers]] we can only see two numbers. Yet, in
[[tab:numbers][the very
same table]], we can already tell the radix used isn't too low
(remember footnote [[fn:basetwo]]?). On the other hand, table
[[tab:letters]] shows letters, but that's clearly uninteresting.
#+name: eq:euler
\begin{equation}
e^{i\pi} + 1 = 0
\end{equation}
Equation [[eq:euler]], also known as Euler's equation, is remarkable
unlike to the equation [[eq:trivial]], which is boring (except the
elisp part, in listing [[oneplusone]]).
#+target: end
This is the end of section [[sec:tables]]. [[end][Invisible link to line
above]]
* Footnotes
[fn:1] fn:basetwo That is strictly greater than two.
#+end_src
Then the ASCII output.
#+begin_src text
1 First headline.
=
Here we demonstrate cross-references to items.
1. A first item in a list.
2. Another item
1. With three subparts. This one.
2. Another one.
3. And the last subpart.
We end the list at item 2.3.
Before we continue, here is a rather trivial equation, assuming base
isn't too low[1].
\begin{equation}
1 + 1 = 2
\end{equation}
We can verify it with the following code:
,
| (+ 1 1)
`
Listing 1: Shortly after the beginning of arithmetic.
1.1 Sub-topic
~
Here we demonstrate cross-references to tables.
one 1
two 2
Table 1: Test
a aille
b bi
Table 2: Letters
In table 1 we can only see two numbers. Yet, in the very same table,
we can already tell the radix used isn't too low (remember footnote
1?). On the other hand, table 2 shows letters, but that's clearly
uninteresting.
\begin{equation}
e^{i\pi} + 1 = 0
\end{equation}
Equation 2, also known as Euler's equation, is remarkable unlike to
the equation 1, which is boring (except the elisp part, in listing 1).
This is the end of section 1.1.
#+end_src
And with LaTeX.
#+begin_src latex
\section{First headline.}
\label{sec-1}
Here we demonstrate cross-references to items.
\begin{enumerate}
\item A first item in a list.
\item Another item
\begin{enumerate}
\item With three subparts. This one.
\item Another one.
\item \label{itm:last} And the last subpart.
\end{enumerate}
\end{enumerate}
We end the list at item \ref{itm:last}.
Before we continue, here is a rather trivial equation, assuming base
isn't too low\footnote{\label{fn:basetwo} That is strictly greater than two.}.
\begin{equation}
\label{eq:trivial}
1 + 1 = 2
\end{equation}
We can verify it with the following code:
\begin{figure}[H]
\caption{\label{oneplusone}Shortly after the beginning of arithmetic.}
\begin{verbatim}
(+ 1 1)
\end{verbatim}
\end{figure}
\subsection{Sub-topic}
\label{sec-1-1}
Here we demonstrate cross-references to tables.\label{sec:tables}
\begin{table}[htb]
\caption{\label{tab:numbers}Test}
\begin{center}
\begin{tabular}{lr}
one 1 \\
two 2 \\
\end{tabular}
\end{center}
\end{table}
\begin{table}[htb]
\caption{\label{tab:letters}Letters}
\begin{center}
\begin{tabular}{ll}
a aille \\
b bi \\
\end{tabular}
\end{center}
\end{table}
In table \ref{tab:numbers} we can only see two numbers. Yet, in
\hyperref[tab:numbers]{the very
same table}, we can already tell the radix used isn't too low
(remember footnote \ref{fn:basetwo}?). On the other hand, table
\ref{tab:letters} shows letters, but that's clearly uninteresting.
\begin{equation}
\label{eq:euler}
e^{i\pi} + 1 = 0
\end{equation}
Equation \ref{eq:euler}, also known as Euler's equation, is remarkable
unlike to the equation \ref{eq:trivial}, which is
Re: [O] [dev] Implement ref link types
At Mon, 20 Feb 2012 23:06:32 +0100, Nicolas Goaziou wrote: Completing myself, here is a patch implementing the previous suggestion, along with example output obtained with it. You may need to (fmakunbound 'org-e-ascii-target) to avoid an error, since this patch removes the function. I don't see why we should drop the link type in fuzzy links. After all they /are/ are special type of link. Without the link type we will run into trouble, won't we?. In the example file: , | We end the list at item [[itm:last]]. ` So, itm:last is a fuzzy link but it could as well be a regular link of type itm with a path component of last and no description. If we say that we use itm:last as a fuzzy link iff there is no registered link type itm we might put people into trouble if in some point in the future Org mode introduces a link of type itm and the fuzzy links stop working. Or is there any technical reason to use [[itm:last]] instead of [[ref:itm:last]]? Best, -- David -- OpenPGP... 0x99ADB83B5A4478E6 Jabber dmj...@jabber.org Email. dm...@ictsoc.de pgpDlDRSOzYXk.pgp Description: PGP signature
[O] [dev] Implement ref link types
Hello,
I'd like to introduce a new type of internal links, namely ref links.
Since any element can now have a #+name: something affiliated keyword,
it would be practical to have a way to go straight to that name, from
anywhere in the buffer. The following patch implements
a [[ref:something]] syntax, or even [[ref:something][text]] to do so.
The problem that I see here is that is breaks a bit syntax for internal
links (protocol:path is usually for external links). Another solution
would be to make them more hermetic: [[!something]].
On the export side, a ref link should be replaced by its description,
if it has any, or by the sequence number of the matching element among
elements of the same type. With the new exporter and the following
buffer:
#+begin_src org
#+name: tab:letters
#+caption: Letters
| a | b |
| c | d |
#+name: tab:numbers
#+caption: Numbers
| 1 |
| 2 |
In tableau [[ref:tab:numbers]] we can see... Yet, in
[[ref:tab:numbers][the same table]], ...
#+end_src
the last sentence, in ascii, becomes:
In tableau 2 we can see... Yet, in the same table, ...
Even if it's not a perfect replacement for \ref{something} commands,
it should be sufficient for all major back-ends to provide an
approximate functionality. And we gain interactivity in the Org buffer.
What do you think?
Regards,
--
Nicolas Goaziou
From f92e12a9482613d4b1d27090fac8d2667b094fdb Mon Sep 17 00:00:00 2001
From: Nicolas Goaziou n.goaz...@gmail.com
Date: Sun, 19 Feb 2012 18:48:41 +0100
Subject: [PATCH] Implement ref internal link type in Org buffers
* lisp/org.el (org-link-search): Handle ref internal link types.
A [[ref:some-name]] link points to a #+name: some-name in the same
buffer.
---
lisp/org.el | 10 ++
1 files changed, 10 insertions(+), 0 deletions(-)
diff --git a/lisp/org.el b/lisp/org.el
index a81f7fc..ea06863 100644
--- a/lisp/org.el
+++ b/lisp/org.el
@@ -9875,6 +9875,16 @@ visibility around point, thus ignoring
;; First check if there are any special search functions
((run-hook-with-args-until-success 'org-execute-file-search-functions s))
;; Now try the builtin stuff
+ ;; Ref internal link.
+ ((and (string-match ^ref:\\(.*\\) s0)
+ (let ((name (org-trim (match-string 1 s0
+ (save-excursion
+ (goto-char (point-min))
+ (and (re-search-forward
+ (format ^[ \t]*#\\+name: %s name) nil t)
+ (setq type 'dedicated pos (match-beginning 0))
+ (goto-char pos))
+ ;; Custom-id
((and (equal (string-to-char s0) ?#)
( (length s0) 1)
(save-excursion
--
1.7.9.1
Re: [O] [dev] Implement ref link types
Hi,
I think it's a great idea, as I've wanted to do it myself :-) , but
I'm glad it's in competent hands instead.
Me, I don't see any problem with a [[ref:something]] syntax. It's the
obvious org-native, cross-backend replacement for \ref. The
[[protocol:something]] syntax already widens the notion of link to
shell: and elisp: links, so I wouldn't worry about breaking
conventions. Using e.g. [[!something]] instead would introduce a brand
new bit of syntax.
Suggestion: On export, how about enabling automatic element
descriptions for references following the type:name convention, so
that e.g. just
: in [[ref:tab:numbers]] we can see...
would expand to
in Table 2 we can see...
If implemented, this should be user-customizable e.g. through an alist
like
((fig . Figure) (tab . Table) (map . Map))
Yours,
Christian
On 2/19/12 7:08 PM, Nicolas Goaziou wrote:
Hello,
I'd like to introduce a new type of internal links, namely ref links.
Since any element can now have a #+name: something affiliated keyword,
it would be practical to have a way to go straight to that name, from
anywhere in the buffer. The following patch implements
a [[ref:something]] syntax, or even [[ref:something][text]] to do so.
The problem that I see here is that is breaks a bit syntax for internal
links (protocol:path is usually for external links). Another solution
would be to make them more hermetic: [[!something]].
On the export side, a ref link should be replaced by its description,
if it has any, or by the sequence number of the matching element among
elements of the same type. With the new exporter and the following
buffer:
#+begin_src org
#+name: tab:letters
#+caption: Letters
| a | b |
| c | d |
#+name: tab:numbers
#+caption: Numbers
| 1 |
| 2 |
In tableau [[ref:tab:numbers]] we can see... Yet, in
[[ref:tab:numbers][the same table]], ...
#+end_src
the last sentence, in ascii, becomes:
In tableau 2 we can see... Yet, in the same table, ...
Even if it's not a perfect replacement for \ref{something} commands,
it should be sufficient for all major back-ends to provide an
approximate functionality. And we gain interactivity in the Org buffer.
What do you think?
Regards,
Re: [O] [dev] Implement ref link types
I think it's a good idea, and would suggest this: * If it is not going to have features added, then [[ref:asdf]] is OK * If it /is/ going to have features added, then I recommend ES/US ES/US is extensible syntax / universal syntax, a specific proposal for an orthogonal and future-proof syntax for new capabilities like this. For example, you might want to put the target anywhere, not just where there are elements. The ID marker idea implements this with ES/US. In this case, we'd simply allow element names in addition with the same source syntax. Of course, you might decide that nobody will ever want to add new syntax to those links, in which case a simple new link type would make sense. Samuel -- The Kafka Pandemic: http://thekafkapandemic.blogspot.com
Re: [O] [dev] Implement ref link types
Hello, Christian Moe m...@christianmoe.com writes: Me, I don't see any problem with a [[ref:something]] syntax. It's the obvious org-native, cross-backend replacement for \ref. The [[protocol:something]] syntax already widens the notion of link to shell: and elisp: links, so I wouldn't worry about breaking conventions. Using e.g. [[!something]] instead would introduce a brand new bit of syntax. Not really brand new, since there already are [[#custom-id]] and [[*headline]]. Though, I'd favour [[ref:name]], too. Suggestion: On export, how about enabling automatic element descriptions for references following the type:name convention, so that e.g. just : in [[ref:tab:numbers]] we can see... would expand to in Table 2 we can see... If implemented, this should be user-customizable e.g. through an alist like ((fig . Figure) (tab . Table) (map . Map)) That's another possibility, but I'd rather follow LaTeX usage. I think it gives user more latitude in the end. Indeed, You don't have to think about a name prefix ; you can also have constructs like Tables [[ref:table1]], [[ref:table2]] and [[ref:table3]] for Tables 1, 2 and 3, etc. Note that the behaviour you suggest can easily be implemented using filters in the new exporter. Regards, -- Nicolas Goaziou
Re: [O] [dev] Implement ref link types
Hello, Samuel Wales samolog...@gmail.com writes: I think it's a good idea, and would suggest this: * If it is not going to have features added, then [[ref:asdf]] is OK * If it /is/ going to have features added, then I recommend ES/US ES/US is extensible syntax / universal syntax, a specific proposal for an orthogonal and future-proof syntax for new capabilities like this. Ok, I found the thread[1] about extensible syntax for links. I don't think that it would be a good idea to use a completely different syntax for just one type of link. Either we change the whole link system into the extensible syntax proposal, or we don't change it at all. I don't mind either way, but that's orthogonal to the problem at hand. For now, I'll assume we keep the classical link syntax. For example, you might want to put the target anywhere, not just where there are elements. Org already has targets for that: anywhere and [[anywhere]]. The [[ref:element]] link is more interesting for its export effect. Moving back and forth between it and targeted element is a bonus. Regards, [1] http://thread.gmane.org/gmane.emacs.orgmode/11896 -- Nicolas Goaziou
Re: [O] [dev] Implement ref link types
On 19.2.2012, at 19:08, Nicolas Goaziou wrote:
Hello,
I'd like to introduce a new type of internal links, namely ref links.
Since any element can now have a #+name: something affiliated keyword,
it would be practical to have a way to go straight to that name, from
anywhere in the buffer. The following patch implements
a [[ref:something]] syntax, or even [[ref:something][text]] to do so.
The problem that I see here is that is breaks a bit syntax for internal
links (protocol:path is usually for external links). Another solution
would be to make them more hermetic: [[!something]].
On the export side, a ref link should be replaced by its description,
if it has any, or by the sequence number of the matching element among
elements of the same type. With the new exporter and the following
buffer:
#+begin_src org
#+name: tab:letters
#+caption: Letters
| a | b |
| c | d |
#+name: tab:numbers
#+caption: Numbers
| 1 |
| 2 |
In tableau [[ref:tab:numbers]] we can see... Yet, in
[[ref:tab:numbers][the same table]], ...
#+end_src
the last sentence, in ascii, becomes:
In tableau 2 we can see... Yet, in the same table, ...
Even if it's not a perfect replacement for \ref{something} commands,
it should be sufficient for all major back-ends to provide an
approximate functionality. And we gain interactivity in the Org buffer.
What do you think?
Love it! Why are you saying it is not a full replacement for \ref{something}?
It is better than that because it will work in more backends
- Carsten
Regards,
--
Nicolas Goaziou
From f92e12a9482613d4b1d27090fac8d2667b094fdb Mon Sep 17 00:00:00 2001
From: Nicolas Goaziou n.goaz...@gmail.com
Date: Sun, 19 Feb 2012 18:48:41 +0100
Subject: [PATCH] Implement ref internal link type in Org buffers
* lisp/org.el (org-link-search): Handle ref internal link types.
A [[ref:some-name]] link points to a #+name: some-name in the same
buffer.
---
lisp/org.el | 10 ++
1 files changed, 10 insertions(+), 0 deletions(-)
diff --git a/lisp/org.el b/lisp/org.el
index a81f7fc..ea06863 100644
--- a/lisp/org.el
+++ b/lisp/org.el
@@ -9875,6 +9875,16 @@ visibility around point, thus ignoring
;; First check if there are any special search functions
((run-hook-with-args-until-success 'org-execute-file-search-functions s))
;; Now try the builtin stuff
+ ;; Ref internal link.
+ ((and (string-match ^ref:\\(.*\\) s0)
+(let ((name (org-trim (match-string 1 s0
+ (save-excursion
+(goto-char (point-min))
+(and (re-search-forward
+ (format ^[ \t]*#\\+name: %s name) nil t)
+ (setq type 'dedicated pos (match-beginning 0))
+ (goto-char pos))
+ ;; Custom-id
((and (equal (string-to-char s0) ?#)
( (length s0) 1)
(save-excursion
--
1.7.9.1
Re: [O] [dev] Implement ref link types
On Sun, Feb 19, 2012 at 08:41:45PM +0100, Nicolas Goaziou wrote:
Suggestion: On export, how about enabling automatic element
descriptions for references following the type:name convention, so
that e.g. just
: in [[ref:tab:numbers]] we can see...
would expand to
in Table 2 we can see...
If implemented, this should be user-customizable e.g. through an alist
like
((fig . Figure) (tab . Table) (map . Map))
That's another possibility, but I'd rather follow LaTeX usage. I think
it gives user more latitude in the end. Indeed, You don't have to think
about a name prefix ; you can also have constructs like Tables
[[ref:table1]], [[ref:table2]] and [[ref:table3]] for Tables 1, 2 and
3, etc.
Note that the behaviour you suggest can easily be implemented using
filters in the new exporter.
Note that for LaTeX export, there's no need to explicitly add names to
references -- LaTeX can figure them out for itself from the label alone,
with a little of help.
There are various CTAN packages implementing this, such as cleveref,
hyperref's \autoref command, varioref's \labelformat command... Cleveref
is arguably the most powerful of these, as you can just chuck references
into a \cref command (which replaces \ref):
\cref{figure1,table1,table3,table2}, and it sorts them all out for you,
to produce Figure~1, and Tables~1 to~3. (Disclaimer: I'm the author of
cleveref.)
Toby
--
Dr T. S. Cubitt
Mathematics and Quantum Information group
Department of Mathematics
Complutense University
Madrid, Spain
email: ts...@cantab.net
web: www.dr-qubit.org
Re: [O] [dev] Implement ref link types
On 2/19/12 8:41 PM, Nicolas Goaziou wrote: That's another possibility, but I'd rather follow LaTeX usage. I think it gives user more latitude in the end. Indeed, You don't have to think about a name prefix ; you can also have constructs like Tables [[ref:table1]], [[ref:table2]] and [[ref:table3]] for Tables 1, 2 and 3, etc. Good points. Note that the behaviour you suggest can easily be implemented using filters in the new exporter. Right. I regret not having had the time to play with the new exporter and give feedback, it sounds very smart. Christian
Re: [O] [dev] Implement ref link types
On 2012-02-19, Nicolas Goaziou n.goaz...@gmail.com wrote: Ok, I found the thread[1] about extensible syntax for links. Again this isn't just for links and if your syntax does all you ever anticipate, then I like it. I am talking about the future and the difficulty of adding ad-hoc syntax fore new features /later/. There are a few other threads (just FYI). I might have them listed someplace. Overview (also FYI): one concern is syntax creep in Org for new features. This affects external parsers and overall complexity and nonorthogonality, and introduces parsing risk, in which there are many gotchas -- such as inability to escape, quote, nest, pretty-print, etc. ES/US solves all of that in a single, simple way. If all you're doing is the one set of features now, then your syntax is great. But I'm talking about the future. I don't think that it would be a good idea to use a completely different syntax for just one type of link. Either we change the whole link system No, it's not for just one type of link. It applies to new features also, not just for ref links but for ID markers (links to anything, even words, using Org ID), very fancy dates that have features that are too difficult to include in existing date syntax, annotation of words or paragraphs or elements, maybe fancy detangling, browser-like link coloring by expiry and cached links, digraphs, undirected graphs including bidirectional links, super-fancy footnotes, any new feature we do not currently anticipate for the ref syntax or any other feature that would create nonorthogonality and complexity in existing syntax, and many new features we haven't thought of. It won't replace existing syntax. It's for new features. One point is that when we address something (such as nestability) for one new feature, it works for all others automatically. into the extensible syntax proposal, or we don't change it at all. I don't mind either way, but that's orthogonal to the problem at hand. Again I think your syntax is great if that is all it is going to do. All I am doing is raising a possible alternative way of doing it. If you don't like it, that's fine. But my point is that if we only look at the problem at hand, we get syntax creep -- because new features are not at hand. Think of how dates now have to deal with deadlines, repeaters, etc. That's OK, but it's going to get harder to add new features to them. I'm not saying to replace dates, but for many new features, we might want to try something more orthogonal and extensible and universal. For example, you might want to put the target anywhere, not just where there are elements. Org already has targets for that: anywhere and [[anywhere]]. The Those do not use the Org ID mechanism, so they are brittle and don't operate across files in the same way Org IDs can (IIRC -- do they?). Again it's an example of how the syntax can add features without making parsing difficult. This all concerns future features, not anything today. Just something to consider. -- The Kafka Pandemic: http://thekafkapandemic.blogspot.com
Re: [O] [dev] Implement ref link types
Hello,
Carsten Dominik carsten.domi...@gmail.com writes:
Why are you saying it is not a full replacement for \ref{something}?
There are still a few limitations. For example, you cannot reference
a precise list item since items do not accept affiliated keywords.
It is better than that because it will work in more backends
Yes, this is a big advantage.
Regards,
--
Nicolas Goaziou
Re: [O] [dev] Implement ref link types
On Feb 20, 2012, at 1:51 AM, Nicolas Goaziou wrote:
Hello,
Carsten Dominik carsten.domi...@gmail.com writes:
Why are you saying it is not a full replacement for \ref{something}?
There are still a few limitations. For example, you cannot reference
a precise list item since items do not accept affiliated keywords.
Ah, yes, this is right.
Regards
- Carsten
It is better than that because it will work in more backends
Yes, this is a big advantage.
Regards,
--
Nicolas Goaziou
- Carsten
