Enhance export options for code source examples.

Allow whitespace in code references.  Allow the -r switch to remove the
references in the source code even when the lines are not numbered: the
labels can be explicit enough.  Note that "-r -k" is the same than no
switch - as expected.

Thanks to Ulf Stegemann for bring this up.

doc/ChangeLog

@@ -1,3 +1,8 @@
+2009-07-23  Bastien Guerry  <bzg@altern.org>
+
+	* org.texi (Literal examples): Update to reflect the new behavior
+	of the -n -r -k switches when exporting source code examples.
+
 2009-07-21  Dan Davison <davison@stats.ox.ac.uk>  (tiny change)
 
 	* org.texi (Structure editing): Add information about `C-c *',

doc/org.texi

@@ -8197,15 +8197,18 @@ switch to the end of the @code{BEGIN} line, to get the lines of the example
 numbered.  If you use a @code{+n} switch, the numbering from the previous
 numbered snippet will be continued in the current one.  In literal examples,
 Org will interpret strings like @samp{(ref:name)} as labels, and use them as
-targets for special hyperlinks like @code{[[(name)]]} (@ie the reference
-name enclosed in single parenthesis).  In HTML, hovering the mouse over such
-a link will remote-highlight the corresponding code line, which is kind of
-cool.  If the example/src snippet is numbered, you can also add a @code{-r}
-switch.  Then labels will be @i{removed} from the source code and the links
-will be @i{replaced}@footnote{If you want to explain the use of such labels
-themelves in org-mode example code, you can use the @code{-k} switch to make
-sure they are not touched.} with line numbers from the code listing.  Here is
-an example:
+targets for special hyperlinks like @code{[[(name)]]} (@ie the reference name
+enclosed in single parenthesis).  In HTML, hovering the mouse over such a
+link will remote-highlight the corresponding code line, which is kind of
+cool.
+
+You can also add a @code{-r} switch which @i{removes} the labels from the
+source code@footnote{Adding @code{-k} to @code{-n -r} will @i{keep} the
+labels in the source code while using line numbers for the links, which might
+be useful to explain those in an org-mode example code.}.  With the @code{-n}
+switch, links to these references will be labeled by the line numbers from
+the code listing, otherwise links will use the labels with no parentheses.
+Here is an example:
 
 @example
 #+BEGIN_SRC emacs-lisp -n -r

lisp/ChangeLog

@@ -1,5 +1,10 @@
 2009-07-23  Bastien Guerry  <bzg@altern.org>
 
+	* org-exp.el (org-export-number-lines): Allow whitespace in code
+	references.  Allow the -r switch to remove the references in the
+	source code even when the lines are not numbered: the labels can
+	be explicit enough.
+
 	* org.el (org-fontify-whole-heading-line): New option.
 	(org-set-font-lock-defaults): Use the new option.
 

lisp/org-exp.el

@@ -2293,8 +2293,6 @@ INDENT was the original indentation of the block."
 (defun org-export-number-lines (text backend
 				     &optional skip1 skip2 number cont
 				     replace-labels label-format)
-  (if (and (not number) (not (eq replace-labels 'keep)))
-      (setq replace-labels nil)) ;; must use names if no numbers
   (setq skip1 (or skip1 0) skip2 (or skip2 0))
   (if (not cont) (setq org-export-last-code-line-counter-value 0))
   (with-temp-buffer
@@ -2326,7 +2324,7 @@ INDENT was the original indentation of the block."
 	    (concat
 	     ".*?\\S-.*?\\([ \t]*\\("
 	     (regexp-quote label-pre)
-	     "\\([-a-zA-Z0-9_]+\\)"
+	     "\\([-a-zA-Z0-9_ ]+\\)"
 	     (regexp-quote label-post)
 	     "\\)\\)"))
 	   ref)
@@ -2336,17 +2334,28 @@ INDENT was the original indentation of the block."
 	(if number
 	    (insert (format fm (incf n)))
 	  (forward-char 1))
-	(when (and (not (eq replace-labels 'keep))
-		   (looking-at lbl-re))
+	(when (looking-at lbl-re) 
 	  (setq ref (match-string 3))
-	  (if replace-labels
-	      (progn
-		(delete-region (match-beginning 1) (match-end 1))
-		(push (cons ref n) org-export-code-refs))
-	    (goto-char (match-beginning 2))
-	    (delete-region (match-beginning 2) (match-end 2))
-	    (insert "(" ref ")")
-	    (push (cons ref (concat "(" ref ")")) org-export-code-refs))
+	  (cond ((numberp replace-labels)
+		 ;; remove labels; use numbers for references when lines
+		 ;; are numbered, use labels otherwise
+		 (delete-region (match-beginning 1) (match-end 1))
+		 (push (cons ref (if (> n 0) n ref)) org-export-code-refs))
+		((eq replace-labels 'keep)
+		 ;; don't remove labels; use numbers for references when
+		 ;; lines are numbered, use labels otherwise
+		 (goto-char (match-beginning 2))
+		 (delete-region (match-beginning 2) (match-end 2))
+		 (insert "(" ref ")")
+		 (push (cons ref (if (> n 0) n (concat "(" ref ")"))) 
+		       org-export-code-refs))
+		(t 
+		 ;; don't remove labels and don't use numbers for
+		 ;; references
+		 (goto-char (match-beginning 2))
+		 (delete-region (match-beginning 2) (match-end 2))
+		 (insert "(" ref ")")
+		 (push (cons ref (concat "(" ref ")")) org-export-code-refs)))
 	  (when (eq backend 'html)
 	    (save-excursion
 	      (beginning-of-line 1)

lisp/org-src.el

@@ -57,7 +57,7 @@ there are kept outside the narrowed region."
 (defcustom org-coderef-label-format "(ref:%s)"
   "The default coderef format.
 This format string will be used to search for coderef labels in literal
-examples (EXAMPLE and SRC blocks).  The format can be overwritten
+examples (EXAMPLE and SRC blocks).  The format can be overwritten in
 an individual literal example with the -f option, like
 
 #+BEGIN_SRC pascal +n -r -l \"((%s))\"