Info Catalog org: Images and tables org: Markup org: Include files

org: Literal examples

 
 11.3 Literal examples
 =====================
 
 You can include literal examples that should not be subjected to markup.
 Such examples will be typeset in monospace, so this is well suited for
 source code and similar examples.
 
      #+BEGIN_EXAMPLE
      Some example from a text file.
      #+END_EXAMPLE
 
    Note that such blocks may be indented in order to align nicely with
 indented text and in particular with plain list structure (Plain
 lists).  For simplicity when using small examples, you can also start
 the example lines with a colon followed by a space.  There may also be
 additional whitespace before the colon:
 
      Here is an example
         : Some example from a text file.
 
    If the example is source code from a programming language, or any
 other text that can be marked up by font-lock in Emacs, you can ask for
 the example to look like the fontified Emacs buffer(1).  This is done
 with the ‘src’ block, where you also need to specify the name of the
 major mode that should be used to fontify the example(2), see Easy
 Templates for shortcuts to easily insert code blocks.
 
      #+BEGIN_SRC emacs-lisp
        (defun org-xor (a b)
           "Exclusive or."
           (if a (not b) b))
      #+END_SRC
 
    Both in ‘example’ and in ‘src’ snippets, you can add a ‘-n’ switch to
 the end of the ‘BEGIN’ line, to get the lines of the example numbered.
 If you use a ‘+n’ switch, the numbering from the previous numbered
 snippet will be continued in the current one.  In literal examples, Org
 will interpret strings like ‘(ref:name)’ as labels, and use them as
 targets for special hyperlinks like ‘[[(name)]]’ (i.e., 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 ‘-r’ switch which removes the labels from the
 source code(3).  With the ‘-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:
 
      #+BEGIN_SRC emacs-lisp -n -r
      (save-excursion                  (ref:sc)
         (goto-char (point-min)))      (ref:jump)
      #+END_SRC
      In line [[(sc)]] we remember the current position.  [[(jump)][Line (jump)]]
      jumps to point-min.
 
    If the syntax for the label format conflicts with the language
 syntax, use a ‘-l’ switch to change the format, for example ‘#+BEGIN_SRC
 pascal -n -r -l "((%s))"’.  See also the variable
 ‘org-coderef-label-format’.
 
    HTML export also allows examples to be published as text areas (
 Text areas in HTML export).
 
    Because the ‘#+BEGIN_...’ and ‘#+END_...’ patterns need to be added
 so often, shortcuts are provided using the Easy Templates facility
 (Easy Templates).
 
 ‘C-c '’
      Edit the source code example at point in its native mode.  This
      works by switching to a temporary buffer with the source code.  You
      need to exit by pressing ‘C-c '’ again(4).  The edited version will
      then replace the old version in the Org buffer.  Fixed-width
      regions (where each line starts with a colon followed by a space)
      will be edited using ‘artist-mode’(5) to allow creating ASCII
      drawings easily.  Using this command in an empty line will create a
      new fixed-width region.
 ‘C-c l’
      Calling ‘org-store-link’ while editing a source code example in a
      temporary buffer created with ‘C-c '’ will prompt for a label.
      Make sure that it is unique in the current buffer, and insert it
      with the proper formatting like ‘(ref:label)’ at the end of the
      current line.  Then the label is stored as a link ‘(label)’, for
      retrieval with ‘C-c C-l’.
 
    ---------- Footnotes ----------
 
    (1) This works automatically for the HTML back-end (it requires
 version 1.34 of the ‘htmlize.el’ package, which is distributed with
 Org).  Fontified code chunks in LaTeX can be achieved using either the
 listings or the <http://code.google.com/p/minted> package.  Refer to
 ‘org-latex-listings’ documentation for details.
 
    (2) Code in ‘src’ blocks may also be evaluated either interactively
 or on export.  See Working With Source Code for more information
 on evaluating code blocks.
 
    (3) Adding ‘-k’ to ‘-n -r’ will 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.
 
    (4) Upon exit, lines starting with ‘*’, ‘,*’, ‘#+’ and ‘,#+’ will get
 a comma prepended, to keep them from being interpreted by Org as outline
 nodes or special syntax.  These commas will be stripped for editing with
 ‘C-c '’, and also for export.
 
    (5) You may select a different-mode with the variable
 ‘org-edit-fixed-width-region-mode’.
 

Info Catalog org: Images and tables org: Markup org: Include files