Coderefs: Documentation in the manual

This patch adds documentation about code references and line numbering
to the manual, and also adds an example to Changes.org.

ORGWEBPAGE/Changes.org

@@ -14,6 +14,58 @@
 
 ** Details
 
+*** Line numbers and references in literal examples
+
+Literal examples introduced with =#+BEGIN_EXAMPLE= or =#+BEGIN_SRC=
+do now allow optional line numbering in the example.
+Furthermore, links to specific code lines are supported, greatly
+increasing Org-mode utility for writing tutorials and other
+similar documents.
+
+Code references use special labels embedded directly into the
+source code.  Such labels look like "((name))" and must be unique
+within a document.  Org-mode links with the coderef cookie in the
+link part will be correctly interpreted, both while working with
+an Org file (internal links), and while exporting to the
+different backends.  Line numbering and code references are
+supported for all three major backends, HTML, LaTeX, and ASCII.
+In the HTML backend, hovering the mouse over a link to a source
+line will remote-highlight the referenced code line.
+
+The options for the BEGIN lines are:
+
+ - -n :: Number the lines in the example
+ - +n :: Like -n, but continue numbering from where the previous
+         example left off.
+ - -r :: Remove the coderef cookies from the example, and replace
+         links to this reference with line numbers.  This option
+         takes only effect if either -n or +n are given as well.
+         If -r is not given, coderefs simply use the label name.
+	 
+Here is an example:
+
+#+begin_example -k
+#+begin_src emacs-lisp -n -r
+(defmacro org-unmodified (&rest body)                   ((def))
+  "Execute body without changing `buffer-modified-p'."
+  `(set-buffer-modified-p                               ((back))
+    (prog1 (buffer-modified-p) ,@body)))
+#+end_src
+[[((def))][Line ((def))]] contains the macro name.  Later at line [[((back))]],
+backquoting is used.
+#+end_example
+
+When exported, this is translated to:
+#+begin_src emacs-lisp -n -r
+(defmacro org-unmodified (&rest body)                   ((def))
+  "Execute body without changing `buffer-modified-p'."
+  `(set-buffer-modified-p                               ((back))
+    (prog1 (buffer-modified-p) ,@body)))
+#+end_src
+[[((def))][Line ((def))]] contains the macro name.  Later at line [[((back))]],
+backquoting is used.
+
+
 *** Capture column view into a different file.
 
     The :id parameter for the dynamic block capturing column view
@@ -676,8 +728,9 @@ Schulte.
 
     After this, a link like this will work
 
-    : [[att:some-attached-file.txt]]
-
+#+BEGIN_EXAMPLE
+     [[att:some-attached-file.txt]]
+#+END_EXAMPLE
     This was a proposal by Lindsay Todd.
 
 *** Completed repeated tasks listed briefly in agenda

doc/org.texi

@@ -7257,6 +7257,7 @@ but not any simpler -- Albert Einstein
 @node Literal examples, Include files, Paragraphs, Markup rules
 @subheading Literal examples
 @cindex literal examples, markup rules
+@cindex code line refenences, markup rules
 
 You can include literal examples that should not be subjected to
 markup.  Such examples will be typeset in monospace, so this is well suited
@@ -7297,18 +7298,25 @@ example:
 Both in @code{example} and in @code{src} snippets, you can add a @code{-n}
 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.  When Org finds a
-cookie like @samp{((name))} is a numbered example, it will remove it, and
-replace links like
+numbered snippet will be continued in the current one.  In literal examples,
+Org will interpret strings like @samp{((name))} as labels, and use them as
+targets for hyperlinks like @code{[[((name))]]}.  In HTML, hoovering 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 an example, you can use the @code{-k} switch to make
+sure they are not touched.} with line numbers from the code listing.  Here is
+an exmmple:
 
 @example
-In line [[((name))]] ...
+#+BEGIN_SRC emacs-lisp -n -r
+(save-excursion
+   (goto-char (point-min))       ((jump))
+#+END SRC
+In [[((jump))][line ((jump))]] we go to .....
 @end example
 
-with the line number.  In HTML export, if you hoover over the link with the
-mouse, the corresponding code line will be highlighted according to the CSS
-class @code{code-highlighted}.
-
 @table @kbd
 @kindex C-c '
 @item C-c '
@@ -7324,9 +7332,15 @@ edited using @code{artist-mode}@footnote{You may select a different-mode with
 the variable @code{org-edit-fixed-width-region-mode}.} to allow creating
 ASCII drawings easily.  Using this command in an empty line will create a new
 fixed-width region.
+@kindex C-c l
+@item C-c l
+Calling @code{org-store-link} while editing a source code example in a
+temporary buffer created with @kbd{C-c '} will prompt for a label, make sure
+that it is unique in the current buffer, and insert it as @samp{((label))} at
+the end of the current line.  Then the label is stored as a link, for
+retrieval with @kbd{C-c C-l}.
 @end table
 
-
 @node Include files, Tables exported, Literal examples, Markup rules
 @subheading Include files
 @cindex include files, markup rules
@@ -7825,16 +7839,20 @@ and you could use @code{http} addresses just as well.
 @cindex CSS, for HTML export
 @cindex HTML export, CSS
 
-You can also give style information for the exported file.  The HTML
-exporter assigns the following CSS classes to appropriate parts of the
-document - your style specifications may change these:
-@example
-.todo           @r{TODO keywords}
-.done           @r{the DONE keyword}
-.timestamp      @r{time stamp}
-.timestamp-kwd  @r{keyword associated with a time stamp, like SCHEDULED}
-.tag            @r{tag in a headline}
-.target         @r{target for links}
+You can also give style information for the exported file.  The HTML exporter
+assigns the following special CSS classes to appropriate parts of the
+document - your style specifications may change these, in addition to any of
+the standard classes like for headlines, tables etc.
+@example
+.todo              @r{TODO keywords}
+.done              @r{the DONE keyword}
+.timestamp         @r{time stamp}
+.timestamp-kwd     @r{keyword associated with a time stamp, like SCHEDULED}
+.tag               @r{tag in a headline}
+.target            @r{target for links}
+div.figure         @r{how to format an inlined image}
+.linenr            @r{the line number in a code example}
+.code-highlighted  @r{for highlighting referenced code lines}
 @end example
 
 Each exported files contains a compact default style that defines these