Re: [RFC] Standardized code block keywords

[Daniel Bausch <DanielBausch@gmx.de>]

[-- Attachment #1: Type: Text/Plain, Size: 4465 bytes --]

Am Sonntag 23 Oktober 2011, 18:09:01 schrieben Sie:
> Daniel Bausch <DanielBausch@gmx.de> writes:
> > Am Freitag, 21. Oktober 2011, 21:10:27 schrieb Thomas S. Dye:
> >> Eric Schulte <schulte.eric@gmail.com> writes:
> >> >>> I'm confused by [3] so I will say nothing for now, except to ask
> >> >>> some questions: are we talking about what a human would use to
> >> >>> label a piece of data for consumption by a block (including perhaps
> >> >>> the future possibilities of lists and paragraphs that Tom brought
> >> >>> up)? what babel would use to label a results block (possibly so
> >> >>> that it could be consumed by another block in a chain)? both? would
> >> >>> that mean that #+tblname would go the way of the dodo and that
> >> >>> tables would be labelled with #+data (or #+object or whatever else
> >> >>> we come up with)?
> >> >> 
> >> >> +1 (Confused, too)
> >> > 
> >> > well, I guess it is good that this discussion has begun if only to
> >> > clear up this lingering uncertainty.
> >> > 
> >> >> I wasn't even aware of #+DATA. Does it do anything TBLNAME and
> >> >> SRCNAME don't?
> >> > 
> >> > from the prospective of code blocks it is exactly synonymous with
> >> > tblname.  Srcname is different in that it labels code blocks.
> >> > 
> >> >> A reason to keep TBLNAME is that it's also used by the spreadsheet
> >> >> remote references. If Babel looked for DATA instead, a table that is
> >> >> both a remote reference for another spreadsheet and a data source for
> >> >> a src block would need both TBLNAME and DATA, which seems redundant.
> >> > 
> >> > agreed, I'm thinking that tblname will at least remain an option no
> >> > matter what decision is made.
> >> > 
> >> >> As for labeling lists and paragraphs, I recall from the list that
> >> >> Nicolas Goaziou is working on a generalized way to set captions,
> >> >> labels and attributes for various kinds of Org block, as is possible
> >> >> now for tables and images. I thought that sounded promising. I don't
> >> >> know if he planned for block names, too (currently we have tblname
> >> >> but no imgname), but that could make sense. In which case it might
> >> >> be a good idea to coordinate.
> >> > 
> >> > Agreed, I was not aware of this work.  Thanks for sharing.  In this
> >> > vein I would like to voice my desire to be able to add captions to
> >> > code blocks, the lack of this feature has bitten me in the past.
> >> 
> >> Hi Eric,
> >> 
> >> For LaTeX export, the listings package has support for code block
> >> captions.
> > 
> > Not in org AFAIK, org only supports these for my use cases not very
> > useful "function name = " exports.  I patched org to produce real
> > captions instead, but my changes are not that well tested and required
> > some changes in the central export logic.  If there is interest I could
> > share what I have so far. The code quality is a mess, as I do not really
> > know elisp.
> > 
> > Daniel
> 
> Yes, source code block captions currently have to be handled outside the
> usual Org-mode mechanism.  If you use org-special-blocks and the
> listings package, then the following template will give you floating
> code block listings with captions in LaTeX export.
> 
>  : #+BEGIN_listing
>  : 
>  :  <source block>
>  : 
>  : #+LATEX: \caption[The short caption]{The long caption.}\ref{fig:src_blk}
>  : #+END_listing
> 
> This doesn't do anything for export to other formats, but it works well
> for LaTeX export.  There is even \listoflistings command to produce a
> list of source code listings in the front matter.
> 
> All the best,
> Tom

Thank you for this hint, but with my patches, I'm able to write 

#+caption: A Code Snippet
#+label: lst:xyz
#+begin_src lang
#+end_src

What I'd like to add, is that the listings implementation in org has a bug, 
which I also fixed.  If you mix #+begin_src and #+begin_example blocks in one 
document, then the #+begin_example blocks are syntax highlighted analog to the 
previous #+begin_src block because the language is selected by \lstset.
In my patches I'm using the 'language' attribute of \begin{lstlisting}, which 
does not affect following blocks that do not have this attribute.

I have attached my patch.  I suspect that there might be a bug in it, that 
disables that tables that have #+attr_latex can be used by babel using 
#+tblname, because I observed such a behavior recently.  It is possible that 
this second defect might origin from somewhere else, too.

Daniel

[-- Attachment #2: org-exp_caption.patch --]
[-- Type: text/x-patch, Size: 6950 bytes --]

diff --git a/lisp/org-exp.el b/lisp/org-exp.el
index 2aad322..8255021 100644
--- a/lisp/org-exp.el
+++ b/lisp/org-exp.el
@@ -1171,7 +1171,15 @@ on this string to produce the exported version."
       ;; Export code blocks
       (org-export-blocks-preprocess)
 
+      ;; Select and protect backend specific stuff, throw away stuff
+      ;; that is specific for other backends
+      (run-hooks 'org-export-preprocess-before-selecting-backend-code-hook)
+      (org-export-select-backend-specific-text)
+
+      ;; Attach captions to the correct object
+      (setq target-alist (org-export-attach-captions-and-attributes target-alist))
       ;; Mark lists with properties
+
       (org-export-mark-list-properties)
 
       ;; Handle source code snippets
@@ -1213,11 +1221,6 @@ on this string to produce the exported version."
       ;; but mark them as targets that should be invisible
       (setq target-alist (org-export-handle-invisible-targets target-alist))
 
-      ;; Select and protect backend specific stuff, throw away stuff
-      ;; that is specific for other backends
-      (run-hooks 'org-export-preprocess-before-selecting-backend-code-hook)
-      (org-export-select-backend-specific-text)
-
       ;; Protect quoted subtrees
       (org-export-protect-quoted-subtrees)
 
@@ -1235,9 +1238,6 @@ on this string to produce the exported version."
       (unless (plist-get parameters :timestamps)
 	(org-export-remove-timestamps))
 
-      ;; Attach captions to the correct object
-      (setq target-alist (org-export-attach-captions-and-attributes target-alist))
-
       ;; Find matches for radio targets and turn them into internal links
       (org-export-mark-radio-links)
       (run-hooks 'org-export-preprocess-after-radio-targets-hook)
@@ -1894,7 +1894,11 @@ table line.  If it is a link, add it to the line containing the link."
 		    "\\|"
 		    "^[ \t]*\\(|[^-]\\)"
 		    "\\|"
-		    "^[ \t]*\\[\\[.*\\]\\][ \t]*$"))
+		    "^[ \t]*\\[\\[.*\\]\\][ \t]*$"
+		    "\\|"
+		    "^[ \t]*#\\+begin_src.*$"
+		    "\\|"
+		    "^[ \t]*#\\+begin_example.*$"))
 	cap shortn attr label end)
     (while (re-search-forward re nil t)
       (cond
@@ -2468,7 +2472,7 @@ in the list) and remove property and value from the list in LISTVAR."
   "Replace source code segments with special code for export."
   (setq org-export-last-code-line-counter-value 0)
   (let ((case-fold-search t)
-	lang code trans opts indent caption)
+	lang code trans opts indent caption label attr)
     (goto-char (point-min))
     (while (re-search-forward
 	    "\\(^\\([ \t]*\\)#\\+BEGIN_SRC:?\\([ \t]+\\([^ \t\n]+\\)\\)?\\(.*\\)\n\\([^\000]+?\n\\)[ \t]*#\\+END_SRC.*\n?\\)\\|\\(^\\([ \t]*\\)#\\+BEGIN_EXAMPLE:?\\(?:[ \t]+\\(.*\\)\\)?\n\\([^\000]+?\n\\)[ \t]*#\\+END_EXAMPLE.*\n?\\)"
@@ -2489,15 +2493,19 @@ in the list) and remove property and value from the list in LISTVAR."
 		  opts (match-string 5)
 		  code (match-string 6)
 		  indent (length (match-string 2))
-		  caption (get-text-property 0 'org-caption (match-string 0))))
+		  caption (get-text-property 0 'org-caption (match-string 0))
+		  label (get-text-property 0 'org-label (match-string 0))
+		  attr (get-text-property 0 'org-attributes (match-string 0))))
 	(setq lang nil
 	      opts (match-string 9)
 	      code (match-string 10)
 	      indent (length (match-string 8))
-              caption (get-text-property 0 'org-caption (match-string 0))))
+              caption (get-text-property 0 'org-caption (match-string 0))
+	      label (get-text-property 0 'org-label (match-string 0))
+	      attr (get-text-property 0 'org-attributes (match-string 0))))
 
       (setq trans (org-export-format-source-code-or-example
-		   lang code opts indent caption))
+		   lang code opts indent caption label attr))
       (replace-match trans t t))))
 
 (defvar org-export-latex-verbatim-wrap) ;; defined in org-latex.el
@@ -2519,7 +2527,7 @@ in the list) and remove property and value from the list in LISTVAR."
       (forward-char 1))))
 
 (defun org-export-format-source-code-or-example
-  (lang code &optional opts indent caption)
+  (lang code &optional opts indent caption label attr)
   "Format CODE from language LANG and return it formatted for export.
 The CODE is marked up in `org-export-current-backend' format.
 
@@ -2664,13 +2672,13 @@ INDENT was the original indentation of the block."
 	     ((eq org-export-current-backend 'latex)
 	      (setq rtn (org-export-number-lines rtn 0 0 num cont rpllbl fmt))
 	      (cond
-	       ((and lang org-export-latex-listings)
+	       (org-export-latex-listings
 		(flet ((make-option-string
 			(pair)
 			(concat (first pair)
 				(if (> (length (second pair)) 0)
 				    (concat "=" (second pair))))))
-		  (let* ((lang-sym (intern lang))
+		  (let* ((lang-sym (cond (lang (intern lang)) (t nil)))
 			 (minted-p (eq org-export-latex-listings 'minted))
 			 (listings-p (not minted-p))
 			 (backend-lang
@@ -2687,13 +2695,6 @@ INDENT was the original indentation of the block."
 			    lang-sym
 			    org-export-latex-custom-lang-environments))))
 		    (concat
-		     (when (and listings-p (not custom-environment))
-		       (format
-			"\\lstset{%s}\n"
-			(mapconcat
-			 #'make-option-string
-			 (append org-export-latex-listings-options
-				 `(("language" ,backend-lang))) ",")))
 		     (when (and caption org-export-latex-listings-w-names)
 		       (format
 			"\n%s $\\equiv$ \n"
@@ -2703,8 +2704,26 @@ INDENT was the original indentation of the block."
 		       (format "\\begin{%s}\n%s\\end{%s}\n"
 			       custom-environment rtn custom-environment))
 		      (listings-p
-		       (format "\\begin{%s}\n%s\\end{%s}"
-			       "lstlisting" rtn "lstlisting"))
+		       (concat
+			"\\begin{lstlisting}"
+			(when (or (and caption (not org-export-latex-listings-w-names)) attr label backend-lang org-export-latex-listings-options) "[")
+			(when org-export-latex-listings-options
+			  (mapconcat
+			   #'make-option-string
+			   org-export-latex-listings-options ","))
+			(when (and org-export-latex-listings-options (or (and caption (not org-export-latex-listings-w-names)) attr label backend-lang)) ",")
+			(when backend-lang (concat "language=" backend-lang))
+			(when (and backend-lang (or (and caption (not org-export-latex-listings-w-names)) attr label)) ",")
+			(when (and caption (not org-export-latex-listings-w-names))
+			  (format "caption={%s}" (replace-regexp-in-string "_" "\\\\_" caption)))
+			(when (and caption (not org-export-latex-listings-w-names) label) ",")
+			(when label (format "label=%s" label))
+			(when (and (or (and caption (not org-export-latex-listings-w-names)) label) attr) ",")
+			attr
+			(when (or (and caption (not org-export-latex-listings-w-names)) attr label backend-lang org-export-latex-listings-options) "]")
+			"\n"
+			rtn 
+			"\\end{lstlisting}\n"))
 		      (minted-p
 		       (format
 			"\\begin{minted}[%s]{%s}\n%s\\end{minted}"