Browse Source

Merge branch 'master' of orgmode.org:worg

David Arroyo Menendez 4 years ago
parent
commit
3cb2fb306d

+ 1 - 0
.gitignore

@@ -1,3 +1,4 @@
 *~
 *.bak
 *.orgx
+patches/

+ 20 - 14
dev/org-syntax.org

@@ -736,31 +736,33 @@ Unless specified otherwise, case is not significant.
    There are 4 major types of links:
 
    #+BEGIN_EXAMPLE
-   RADIO                     ("radio" link)
+   PRE1 RADIO POST1          ("radio" link)
    <PROTOCOL:PATH>           ("angle" link)
-   PRE PROTOCOL:PATH2 POST   ("plain" link)
+   PRE2 PROTOCOL:PATH2 POST2 ("plain" link)
    [[PATH3]DESCRIPTION]      ("regular" link)
    #+END_EXAMPLE
 
-   RADIO is a string matched by some [[#Targets_and_Radio_Targets][radio target]].  It can contain
-   [[#Entities_and_LaTeX_Fragments][entities]], [[#Entities_and_LaTeX_Fragments][latex fragments]], [[#Subscript_and_Superscript][subscript]] and [[#Subscript_and_Superscript][superscript]] only.
+   PRE1 and POST1, when they exist, are non alphanumeric characters.
+
+   RADIO is a string matched by some [[#Targets_and_Radio_Targets][radio target]].  It may contain
+   [[#Entities_and_LaTeX_Fragments][entities]], [[#Entities_and_LaTeX_Fragments][latex fragments]], [[#Subscript_and_Superscript][subscript]] and [[#Subscript_and_Superscript][superscript]].
 
    PROTOCOL is a string among ~org-link-types~.
 
    PATH can contain any character but ~]~, ~<~, ~>~ and ~\n~.
 
-   PRE and POST are non word constituent.  They can be, respectively,
-   the beginning or the end of a line.
+   PRE2 and POST2, when they exist, are non word constituent
+   characters.
 
    PATH2 can contain any non-whitespace character excepted ~(~, ~)~,
    ~<~ and ~>~.  It must end with a word-constituent character, or any
    non-whitespace non-punctuation character followed by ~/~.
 
    DESCRIPTION must be enclosed within square brackets.  It can
-   contain any character but square brackets.  Object-wise, it can
-   contain any object found in a paragraph excepted a [[#Footnote_References][footnote
-   reference]], a [[#Targets_and_Radio_Targets][radio target]] and a [[#Line_Breaks][line break]].  It cannot contain
-   another link either, unless it is a plain link.
+   contain any character but square brackets.  It can contain any
+   object found in a paragraph excepted a [[#Footnote_References][footnote reference]], a [[#Targets_and_Radio_Targets][radio
+   target]] and a [[#Line_Breaks][line break]].  It cannot contain another link either,
+   unless it is a plain link.
 
    DESCRIPTION is optional.
 
@@ -769,6 +771,7 @@ Unless specified otherwise, case is not significant.
    #+BEGIN_EXAMPLE
    FILENAME           ("file" type)
    PROTOCOL:PATH4     ("PROTOCOL" type)
+   PROTOCOL://PATH4   ("PROTOCOL" type)
    id:ID              ("id" type)
    #CUSTOM-ID         ("custom-id" type)
    (CODEREF)          ("coderef" type)
@@ -824,8 +827,9 @@ Unless specified otherwise, case is not significant.
    <<<CONTENTS>>>
    #+END_EXAMPLE
 
-   CONTENTS can be any character besides ~<~, ~>~ and "\n".  As far as
-   objects go, it can contain [[#Entities_and_LaTeX_Fragments][entities]], [[#Entities_and_LaTeX_Fragments][latex fragments]], [[#Subscript_and_Superscript][subscript]] and
+   CONTENTS can be any character besides ~<~, ~>~ and "\n".  It cannot
+   start or end with a whitespace character.  As far as objects go, it
+   can contain [[#Emphasis_Markers][text markup]], [[#Entities_and_LaTeX_Fragments][entities]], [[#Entities_and_LaTeX_Fragments][latex fragments]], [[#Subscript_and_Superscript][subscript]] and
    [[#Subscript_and_Superscript][superscript]] only.
 
    Targets follow the pattern:
@@ -835,7 +839,8 @@ Unless specified otherwise, case is not significant.
    #+END_EXAMPLE
 
    TARGET can contain any character besides ~<~, ~>~ and "\n".  It
-   cannot contain any object.
+   cannot start or end with a whitespace character.  It cannot contain
+   any object.
 
 ** Statistics Cookies
    :PROPERTIES:
@@ -900,7 +905,8 @@ Unless specified otherwise, case is not significant.
    CONTENTS|
    #+END_EXAMPLE
 
-   CONTENTS can contain any character excepted a vertical bar.
+   CONTENTS can contain any character excepted a vertical bar.  The
+   final bar may be omitted.
 
 ** Timestamps
    :PROPERTIES:

+ 552 - 0
exporters/beamer/beamer-dual-format.org

@@ -0,0 +1,552 @@
+#+TITLE:     Using Beamer export to produce slideshows and article-style handouts from the same org source
+#+AUTHOR:    James Harkins
+#+EMAIL:     
+#+DATE:      
+#+LANGUAGE:  en
+#+OPTIONS:   H:3 num:nil toc:t \n:nil ::t |:t ^:t -:t f:t *:t
+#+OPTIONS:   tex:t d:(HIDE) tags:not-in-toc
+#+STARTUP:   fold
+#+CATEGORY:   worg
+
+* Project overview
+
+The project is training material for a one-week intensive workshop in audio 
+synthesis and live-performance control in the SuperCollider programming 
+language. The workshop was commissioned by CHEARS, the China 
+ElectroAcoustic Resource Survey, and will be given first in Shenyang, PRC.
+
+I wanted to have thorough presentation slides available, for some kinds of 
+explanation that are difficult otherwise, and also give a PDF book to 
+workshop attendees for their future reference. During the writing process, 
+the book became more important, as a way to provide copyright-free 
+tutorials for translation into Chinese. The book eventually grew to 237 
+pages (with, admittedly, more white space per page than a standard prose 
+layout), rendered from 10849 lines of LaTeX code, all of which were 
+generated directly by the org Beamer exporter with no manual edits to any 
+of the =tex= files.
+
+Achieving that required some ingenuity in both org mode and LaTeX. This 
+worg page documents the project's design and implementation.
+
+* Requirements
+
+- One org source to produce slideshows and printed material.
+  - Beamer export for both formats.
+    - Normal /beamer/ document class for slides.
+    - Document class /article/ for the book, with
+      =\usepackage{beamerarticle}= in the preamble.
+  - Header files to determine PDF layout.
+  - Additional explanatory text that will be omitted from slideshows.
+    - Use the beamer class option /ignorenonframetext/ for slides.
+    - Put notes under frame-level headings, with the beamer tag
+      =B_ignoreheading=.
+
+- Indexed glossaries of terms, classes and methods, without writing
+  cumbersome LaTeX syntax for the glossaries package.
+  - Keep glossary definitions in org tables.
+  - Convert to LaTeX syntax using emacs-lisp source blocks.
+  - Convert only once in the book combining all chapters, but once per slideshow.
+
+- Extract captioned source blocks into plain-text files for SuperCollider.
+  - =org-element-map= did all the hard work.
+
+* Implementation
+
+** One source: File structure
+The LaTeX preamble controls the output format; so, to have different output 
+from the same org source, the preamble must be separate from the content. 
+Here, we have two headers:
+
+- =slidehead.org=, which specifies the document class /beamer/ with
+  the /presentation/ option.
+- =printhead2.org=, which specifies the /article/ class and adds the
+  /beamerarticle/ package so that the article class can interpret
+  beamer formatting commands.
+
+Other formatting differences are implemented here. For instance, inline 
+code fragments are colored green in the slides, but remain black in the 
+article.
+
+Header files contain nothing specific to any chapter, and content files are 
+strictly content, no formatting definitions. Neither of these are exported 
+directly. The export files provide the title and author fields, and include 
+(=#+INCLUDE:=) the appropriate header and content files. They also include 
+the glossary file; details to follow.
+
+#+name: slidehead
+#+caption: Primary export options for slideshow format.
+#+begin_src org
+  ,#+startup: beamer
+  ,#+LaTeX_CLASS: beamer
+  ,#+LaTeX_CLASS_OPTIONS: [ignorenonframetext,presentation]
+  ,#+BEAMER_THEME: default
+#+end_src
+
+#+name: printhead
+#+caption: Primary export options for article format.
+#+begin_src org
+  ,#+startup: beamer
+  ,#+LaTeX_CLASS: article
+  ,#+LaTeX_CLASS_OPTIONS: [a4paper,twoside,11pt]
+  ,#+BEAMER_THEME: default
+  ,#+LATEX_HEADER: \usepackage{beamerarticle}
+#+end_src
+
+#+name: contents
+#+caption: Beginning of one of the contents files.
+#+begin_src org
+  ,#+startup: beamer
+  
+  ,* Workshop introduction
+  ,** Workshop introduction
+  ,*** Workshop goals
+  ,**** Teach synthesis techniques by experimentation
+       - SC lets us take apart synthesizer components, and put them back together.
+       - SC's /Just-In-Time library/ makes it easy to re-patch components interactively.
+  ,**** Teach techniques for live control and performance
+       - Control by graphic interfaces and external devices.
+       - End goal: A group composition, to perform together.
+  ,**** *Have fun programming!*
+       - Emphasis on /play/ over /correctness/.
+#+end_src
+
+#+name: slideExport
+#+caption: The slideshow document that is actually exported.
+#+begin_src org
+  ,#+startup: beamer
+  
+  ,#+TITLE: SuperCollider Week, Day 1 \\ Introductory SC, Synthesis and Sequencing
+  ,#+DATE: \today
+  ,#+AUTHOR: H. James Harkins
+  
+  ,#+INCLUDE: "../slidehead.org"
+  ,#+include: "../glossary.org"
+  
+  ,#+include: "./01-contents.org" :minlevel 1
+#+end_src
+
+I settled on a project layout like this:
+
+- =shows/= directory
+  - =slidehead.org=: LaTeX preamble for Beamer's presentation style
+  - =printhead2.org=: Preamble for the article document class, with the beamerarticle package
+  - =glossaries.org=: Tables of glossary definitions, and emacs-lisp source blocks for conversion
+  - =01-intro/= directory
+    - =01-contents.org=: Slide contents, no header info at all
+    - =01-slideshow.org=: Defines this chapter's header (title,
+      author, etc.), includes =slidehead.org=, =glossaries.org= and
+      =01-contents.org=
+    - =img/= directory (png and PDF files for Part I)
+  - =02-synth/= directory, structured like =01=
+    Similar directories for chapters 3--6
+  - =full-article/= directory
+    - =full-article.org=: Defines title etc., includes
+      =printhead2.org=, =glossaries.org=, /all/ content files and
+      additional sections at the end for glossaries
+
+To render the slides for day 1, I visit =01-slideshow.org= in Emacs
+and export to Beamer. The print- or tablet-ready book comes from
+=full-article.org=. This should also be exported by the Beamer
+backend, even though the document class is /article/. This makes
+sense, however; the org source uses Beamer-specific markup which the
+normal LaTeX backend will not understand. It's LaTeX itself that
+"converts" the format to article through inclusion of the
+/beamerarticle/ package.
+
+*** Explanatory prose
+Slides minimize the amount of text on one screen, by using shorter, simpler 
+sentences in outline layouts. Some issues call for a narrative discussion 
+in prose. Prose should /not/ be shown in a slide presentation!
+
+Beamer can omit text from a presentation using the document class option 
+/ignorenonframetext/. Text that appears outside of a /frame/ environment 
+will be suppressed. The trick is to get org to export text outside of a 
+frame, without affecting sectioning.
+
+Org creates a frame when it encounters a headline at the level defined by 
+the =H:= export option, and it closes the frame at the next headline at 
+this level or higher. This project uses =H:3=, so normally, the contents 
+under every third-level headline will be enclosed in begin/end frame tags.
+
+If the headline has the Beamer-specific tag =:B_ignoreheading:=, then the 
+heading /and/ the begin/end frame commands are suppressed, but all the 
+content appears.
+
+#+name: prose_source
+#+caption: Org source, including a paragraph that should appear outside of a frame.
+#+begin_src org
+  ,#+OPTIONS: H:3 texht:t
+  ,#+LaTeX_CLASS: beamer
+  ,#+LaTeX_CLASS_OPTIONS: [ignorenonframetext,presentation]
+  
+  ,* Section head
+  ,** Subsection head
+  ,*** Frame title
+  ,**** Block header
+       Text.
+       - Bullet point.
+  ,*** More explanation coming                                 :B_ignoreheading:
+      :PROPERTIES:
+      :BEAMER_env: ignoreheading
+      :END:
+      Here, we explain points from the previous frame in more
+      detail. This text will always appear in the exported LaTeX, but
+      the /ignorenonframetext/ class option will prevent it from being
+      rendered in the presentation.
+#+end_src
+
+#+name: prose_exported
+#+caption: The LaTeX export result. Note the absence of begin/end frame commands around the free-standing paragraph.
+#+begin_src latex
+% Created 2014-05-01 Thu 16:05
+\documentclass[ignorenonframetext,presentation]{beamer}
+\begin{document}
+
+\section{Section head}
+\label{sec-1}
+\subsection{Subsection head}
+\label{sec-1-1}
+\begin{frame}[label=sec-1-1-1]{Frame title}
+\begin{block}{Block header}
+Text.
+\begin{itemize}
+\item Bullet point.
+\end{itemize}
+\end{block}
+\end{frame}
+
+Here, we explain points from the previous frame in more
+detail. This text will always appear in the exported \LaTeX{}, but
+the \emph{ignorenonframetext} class option will prevent it from being
+rendered in the presentation.
+\end{document}
+#+end_src
+
+*** Problem: Position of =\maketitle= command
+
+Because of /ignorenonframetext/, the LaTeX =\maketitle= command must appear 
+in a frame for the slideshows. But, it should /not/ be in a frame for the 
+article. Further, we can't distinguish between presentation and article 
+based on the org export backend, because both are exported by the Beamer 
+backend.
+
+In my environment, I used a hack that assumes Beamer has been added to
+=org-latex-classes= under the exact string "beamer." This is not
+ideal, because a user might have added a custom class under a
+different name. Nicolas Goaziou proposed an alternate approach using
+regular expressions, but I didn't implement it in my environment.
+
+This code snippet should replace the expression following the comment
+=;; 10. Title command= in the function =org-beamer-template=, defined
+in ox-beamer.el.
+
+#+name: maketitlehack
+#+caption: Hack to put the maketitle command in a frame for the beamer class only.
+#+begin_src emacs-lisp
+       ;; 10. Title command.
+       (let ((titlecmd (org-element-normalize-string
+        (cond ((string= "" title) nil)
+              ((not (stringp org-latex-title-command)) nil)
+              ((string-match "\\(?:[^%]\\|^\\)%s"
+                             org-latex-title-command)
+               (format org-latex-title-command title))
+              (t org-latex-title-command)))))
+         (if (string= (plist-get info :latex-class) "beamer")
+             (format "\\begin{frame}%s\\end{frame}" titlecmd)
+           titlecmd))
+#+end_src
+
+*** Problem: Relative links to images
+
+Image files are stored in =img/= directories under the directory for each 
+part. The images must also be accessible from =full-article/=, so simple 
+links of the form =./img/filename= will not work. Instead, this form of 
+link handles both export locations: =../01-intro/img/filename=.
+
+** Glossaries
+The LaTeX /glossaries/ package handled all my requirements: multiple 
+glossaries for different categories of terms and automatic indexing of 
+references to terms in the text. The syntax of the \newglossaryentry 
+command is more verbose than I wanted to manage by hand. Org tables are a 
+useful alternative.
+
+I divided glossary entries into four categories: terms and concepts, unit 
+generators, other classes, and methods. I used two table structures:
+
+- For UGens: Category (not used), name, description, and list of inputs.
+- Others: Term, plural form, description.
+
+The two structures called for two lisp functions; they are essentially the 
+same except for the strings generated and the handling of table rows. The 
+non-UGen function includes arguments for the table and identifiers to embed 
+in the LaTeX syntax, to be supplied in the =#+CALL= lines.
+
+#+name: glossaryTable
+#+caption: Part of a glossary table.
+#+begin_src org
+  ,#+name: gloss
+  | Term  | Plural  | Description                                                                                              |
+  |-------+---------+----------------------------------------------------------------------------------------------------------|
+  | ADSR  |         | An Attack-Decay-Sustain-Release envelope                                                                 |
+  | proxy | proxies | A placeholder that allows you to define connections between modules independent of each module's content |
+#+end_src
+
+#+name: glossaryFunction
+#+caption: Function to convert a normal (non-UGen) glossary table into LaTeX markup.
+#+begin_src org
+  ,#+name: makegloss
+  ,#+begin_src emacs-lisp :var tbl=gloss glosstype='nil :exports none :results value latex
+    (let ((str "")
+          (gltype (if glosstype (format "type=%s," glosstype) "")))
+      (pop tbl)
+      (pop tbl)
+      (while tbl
+        (let ((item (pop tbl)))
+          (setq str
+                (concat str
+                        (format "\\newglossaryentry{%s}{%sname={%s},%sdescription={%s}}\n"
+                                (car item)
+                                gltype
+                                (pop item)
+                                (let ((plural (pop item)))
+                                  (if (string= plural "")
+                                      ""
+                                    (format "plural={%s}," plural)))
+                                (car item))))))
+      str)
+  ,#+end_src
+#+end_src
+
+*** Problem: Redundant glossary export in the full article
+
+The two output styles raise some conflicting requirements:
+
+- *Presentation style:* Because of the /ignorenonframetext/ class
+  option, the =\newglossaryentry= commands must appear within a
+  frame. They cannot go into =slidehead.org=. Each separate contents
+  file must include its own calls to the glossary functions.
+
+- *Article style:* The contents files are included in the same export
+  file -- which would produce redundant copies of the glossary
+  entries.
+
+This calls for /conditional execution/ of the Babel calls. A
+not-quite-obvious feature of Babel properties is that they may be
+Emacs-lisp expressions. That leads to a solution: Use a code block at
+the beginning of the =0*-slideshow.org= and =full-article.org= files
+to set a flag, =hjh-exporting-slides=.
+
+#+name: setflag-slides
+#+caption: Setting the slideshow flag for slideshows.
+#+begin_src org
+  ,#+name: set-slide-flag
+  ,#+begin_src emacs-lisp :exports results :results value latex
+  (setq hjh-exporting-slides 't)
+  ""
+  ,#+end_src
+#+end_src
+
+#+name: setflag-article
+#+caption: Setting the slideshow flag for the article.
+#+begin_src org
+  ,#+name: set-slide-flag
+  ,#+begin_src emacs-lisp :exports results :results value latex
+  (setq hjh-exporting-slides nil)
+  ""
+  ,#+end_src
+#+end_src
+
+Then, the =#+CALL:= lines can use an =(if...)= expression to decide
+whether the =:exports= property should be "results" or "none." If this
+result is "none," then Babel skips that call. So, each glossary
+section evaluates only once per export, no matter how many contents
+files are included.
+
+#+name: call-slides
+#+caption: Calling the glossary function in a slideshow.
+#+begin_src org
+  ,#+call: makegloss :exports (if hjh-exporting-slides "results" "none") :results value latex
+  ,#+results: makegloss
+#+end_src
+
+#+name: call-article
+#+caption: Calling the glossary function in the article.
+#+begin_src org
+  ,#+name: makegloss_art
+  ,#+call: makegloss :exports (if hjh-exporting-slides "none" "results") :results value latex
+  ,#+results: makegloss_art
+#+end_src
+
+*** Output format
+By default, org treats CALL results as example blocks. In LaTeX
+export, example blocks are wrapped in a /verbatim/ environment. These
+functions return LaTeX syntax, to embed into the LaTeX document as
+is. Adding "value latex" to the =:results= property takes care of
+that.
+
+** Extraction of captioned source code blocks
+I also wanted to provide SuperCollider code files containing the
+numbered examples from the text. That means iterating over the source
+code blocks, and collecting the code from every block that has a
+caption. (Code blocks without a caption do not receive a listing
+number.)
+
+The Swiss-army-knife function =org-element-map= handles the iteration
+in a way that is absurdly simple to use: first, use
+=org-element-parse-buffer= to get an object structure for the org
+buffer's contents, and then call =org-element-map= on the parsed tree,
+filtering on ='src-block=.
+
+Each element identified this way is rather complex. Extensive tests
+with Emacs step debugging helped me find several processing steps:
+
+1. The interesting bit of the source-block element is the second item
+   in the list: =(car (cdr element))=.
+
+2. =plist-get= finds the relevant strings in this second item. But
+   this function returns not only the string, but several other
+   properties. The string we need is at the head of the list, but this
+   may be buried within several nested lists. So I wrote a function,
+   =hjh-get-string-from-nested-thing=, that keeps stripping off "car"
+   from the object, until it finds a string.
+
+3. This string itself also includes formatting properties, so I had to
+   use =substring-no-properties= on these items.
+
+To generate the aggregate code file, then, I simply do =M-x
+hjh-src-blocks-to-buffer=, type in the starting listing number for
+this chapter, and in a few seconds, I get a buffer containing
+SuperCollider code separated by comments holding the captions, e.g.:
+
+#+begin_src {SuperCollider} -i
+/**************
+ Listing 6. A very simple synth.
+ **************/
+
+a = { SinOsc.ar(440, 0, 0.1).dup }.play;
+
+// To make it stop:
+a.release;
+#+end_src
+
+#+name: extract
+#+caption: Emacs-lisp functions to find captioned source blocks within a buffer.
+#+begin_src emacs-lisp -i
+(defun hjh-get-string-from-nested-thing (thing)
+  "Peel off 'car's from a nested list until the car is a string."
+  (while (and thing (not (stringp thing)))
+    (setq thing (car thing)))
+  thing
+)
+
+(defun hjh-src-blocks-to-string (counter get-some)
+  "Iterate src blocks from org-element and add them to a string."
+  (interactive "nStarting listing number: \nP")
+  (when (not counter) (setq counter 1))
+  (let ((tree (org-element-parse-buffer))
+	(string "")
+	(get-all (not get-some)))
+    (org-element-map tree 'src-block
+      (lambda (element)
+	(setq element (car (cdr element)))
+	(let ((caption (hjh-get-string-from-nested-thing (plist-get element :caption)))
+	      (source (hjh-get-string-from-nested-thing (plist-get element :value))))
+	  (when caption
+	    (when (or get-all 
+		      (let ((parms
+			     (hjh-get-string-from-nested-thing (plist-get element :parameters))))
+			(and (stringp parms) (string-match-p "extract" parms))))
+	      (setq string (concat string (format "/**************
+ Listing %d. %s
+ **************/
+
+%s\n\n"
+					  counter
+					  (substring-no-properties caption)
+					  (substring-no-properties source)))))
+	    ; always increment if there was a caption
+	    (setq counter (1+ counter))))))
+    string))
+
+(defun hjh-src-blocks-to-buffer (counter get-some)
+  "Put all the captioned source blocks from a buffer into another buffer."
+  (interactive "nStarting listing number: \nP")
+  (let* ((contents (hjh-src-blocks-to-string counter get-some))
+	 (bufpath (buffer-file-name))
+	 (newname (concat (file-name-sans-extension bufpath) ".scd"))
+	 (bufname (file-name-nondirectory newname))
+	 (newbuf (get-buffer-create bufname)))
+    (with-current-buffer newbuf
+      (erase-buffer)
+      (insert contents)
+      (set-visited-file-name newname))
+    (switch-to-buffer-other-window newbuf)))
+#+end_src
+
+# #+begin_comment
+# #+name: 
+# #+caption: 
+# #+begin_src org
+# #+end_src
+# #+end_comment
+
+** Partitioning the article export
+Rather than create a document class to turn top-level headings into =\part= 
+commands, I embedded the LaTeX code for it directly into the full-article 
+template. The trick is closing the environments for the previous sections. 
+This requires a top-level heading, which should not start a new section. I 
+found that =:B_ignoreheading:= did not work for this, but an [[http://stackoverflow.com/questions/10295177/is-there-an-equivalent-of-org-modes-b-ignoreheading-for-non-beamer-documents][export filter]]
+by Suvayu Ali did exactly what I needed.
+
+#+name: articleParts
+#+caption: Part of the full-article export document, with embedded LaTeX \part syntax.
+#+begin_src org
+  ,#+startup: beamer
+  
+  ,#+TITLE: Workshop: Synthesis and Performance in SuperCollider
+  ,#+DATE: \today
+  ,#+AUTHOR: H. James Harkins
+  
+  ,#+INCLUDE: "../printhead2.org"
+  ,#+include: "../glossary.org"
+  ,* Part 1                                                      :ignoreheading:
+  ,#+latex: \clearpage\part{Introductory SC, Synthesis and Sequencing}
+  ,#+include: "../01-intro/01-contents.org" :minlevel 1
+  
+  ,* Part 2                                                      :ignoreheading:
+  ,#+latex: \clearpage\part{Sequencing with Patterns; Synthesis Techniques}
+  ,#+include: "../02-synth/02-contents.org" :minlevel 1
+#+end_src
+
+* Weaknesses
+** Reliance on LaTeX-specific markup
+
+One significant problem, which this project did not attempt to solve,
+is to reconcile the LaTeX's /semantic markup/ with org's ideal of
+backend-independent markup. In LaTeX, it's common to define different
+markup commands for different types of text. This project, for
+instance, uses =\cd{}= for in-line code snippets and =\ci{}= for code
+keywords and identifiers. Both render in the monospace font, in the
+same color; by marking them up differently, I can easily change the
+formatting of one or the other by changing the command's
+definition. (In fact, there is a slight difference: =\ci= identifiers
+are put into an =\mbox=, to suppress hyphenation.)
+
+Org's formatting markup is visual: asterisks for bold, slashes for
+italics and so on.
+
+I think [[http://orgmode.org/manual/Macro-replacement.html#Macro-replacement][export macros]] could support semantic markup that could export
+to LaTeX or HTML equally well, but I didn't investigate that in this
+project. Here, I just embedded LaTeX commands directly into the org
+files: free standing for simple uses, and using export snippets[fn:448d1164] for
+more intricate cases (such as code examples including curly braces,
+which LaTeX export treats specially).
+
+* Footnotes
+
+[fn:448d1164] Export snippets look like this:
+=@@backendname:text...@@=. They will export only to that backend. You
+can write several of them in a row for different backends:
+=@@latex:\emph{italic}@@@@html:<i>italic</i>@@= and each export style
+receives the right snippet.
+

+ 4 - 0
exporters/beamer/index.org

@@ -8,3 +8,7 @@
 - [[file:tutorial.org][Writing Beamer presentations in org-mode]], by Eric S Fraga
 - [[file:presentation.org][Example .org source beamer presentation]], by Eric S Fraga
 - [[file:ox-beamer.org][Using the new exporter]] (in Org's core since 8.0), by Suvayu Ali
+- [[file:beamer-dual-format.org][Writing dual-format presentations using Beamer]], with other tricks, by James Harkins\\
+  "Dual format" here means exporting the same org source to two formats:
+  - Presentation mode (slideshows);
+  - Article mode, using Beamer's /beamerarticle/ package, for handouts.

+ 14 - 0
org-blog-wiki.org

@@ -63,6 +63,20 @@ contribute*!
               org-page posts are in *separate* org-files. Built-in
               support for disqus, google-analytics and RSS.
 
+- [[https://github.com/novoid/lazyblorg][lazyblorg]] :: a static blog-site generator written in Python (HTML5,
+               CSS3). Focus is to have only an absolutely /minimum/ of
+               things to do to write a new blog entry /everywhere/ in
+               your set of Org-mode files. The software is [[https://github.com/novoid/lazyblorg/blob/master/dev/lazyblorg.org][currently
+               in development]]. However, basic functionality is
+               working: persistent pages, temporal pages, tagging,
+               Atom feeds, basic Org-mode syntax, hidden entries, and
+               such. You can take a look at [[http://karl-voit.at/][Karl Voit]]'s personal web
+               page to see an example result. Great features are
+               planned for the future: auto-tags for language or
+               article length, tag description pages, overview pages
+               for navigation, extremely easy integration of image
+               files through [[https://github.com/novoid/Memacs/blob/master/docs/memacs_filenametimestamps.org][a memacs module]], and so forth.
+
 * Wiki tools
 
 - [[http://ikiwiki.info/][ikiwiki]] is a web site compiler written in Perl.  In many ways it is

+ 0 - 823
org-contrib/babel/languages/ob-doc-C-new.org

@@ -1,823 +0,0 @@
-#+OPTIONS:    H:3 num:nil toc:2 \n:nil ::t |:t ^:{} -:t f:t *:t tex:t d:(HIDE) tags:not-in-toc
-#+STARTUP:    align fold nodlcheck hidestars oddeven lognotestate hideblocks
-#+SEQ_TODO:   TODO(t) INPROGRESS(i) WAITING(w@) | DONE(d) CANCELED(c@)
-#+TAGS:       Write(w) Update(u) Fix(f) Check(c) noexport(n)
-#+TITLE:      C, C++, D Source Code Blocks in Org Mode
-#+AUTHOR:     Worg People, Eric Schulte, Thierry Banel, Thomas S. Dye
-#+EMAIL:      schulte.eric at gmail dot com, davison at stats dot ox dot ac dot uk, tbanelwebmin at free dot fr
-#+LANGUAGE:   en
-#+HTML_HEAD:      <style type="text/css">#outline-container-introduction{ clear:both; }</style>
-#+LINK_UP:    ../languages.html
-#+LINK_HOME:  http://orgmode.org/worg/
-#+EXCLUDE_TAGS: noexport
-
-#+name: banner
-#+begin_html
-  <div id="subtitle" style="float: center; text-align: center;">
-  <p>
-  Org Mode support for
-    <br><a href="http://www.gnu.org/software/gcc/">C, C++</a>
-    <br><a href="http://dlang.org/">D</a>
-  </p>
-  <p>
-  <a href="http://www.gnu.org/software/gcc/"><img src="http://www.gnu.org/software/gcc/img/gccegg-65.png"/></a>
-  <a href="http://dlang.org/"><img src="http://dlang.org/images/dlogo.png"/></a>
-  </p>
-  </div>
-#+end_html
-
-* Template Checklist [10/12] 					   :noexport:
-  - [X] Revise #+TITLE:
-  - [X] Indicate #+AUTHOR:
-  - [X] Add #+EMAIL:
-  - [X] Revise banner source block [3/3]
-    - [X] Add link to a useful language web site
-    - [X] Replace "Language" with language name
-    - [X] Find a suitable graphic and use it to link to the language
-      web site
-  - [X] Write an [[Introduction]]
-  - [X] Describe [[Requirements%20and%20Setup][Requirements and Setup]]
-  - [X] Replace "Language" with language name in [[Org%20Mode%20Features%20for%20Language%20Source%20Code%20Blocks][Org Mode Features for Language Source Code Blocks]]
-  - [X] Describe [[Header%20Arguments][Header Arguments]]
-  - [X] Describe support for [[Sessions]]
-  - [ ] Describe [[Result%20Types][Result Types]]
-  - [ ] Describe [[Other]] differences from supported languages
-  - [X] Provide brief [[Examples%20of%20Use][Examples of Use]]
-* Introduction
-
-*Note*: this is a new version of both the software and the documentation.
-It is under evaluation. Hopefully, this version will end up in
-=ob-doc-C.org= and =ob-C.el=, and this file will be removed.
-
-Babel can evaluate C, C++, and D code.
-
-As opposed to interpreted languages, which can be evaluated directly,
-C, C++, and D code is first compiled to an executable which is then
-run.
-
-If a =main= method is not present in a code block then the entire
-block is wrapped in a trivial =main= function call.
-
-Note: there used to be two separate library files, =ob-C.el= and
-=ob-D.el=. They have been merged in a single =ob-C.el= file which
-handle all three languages.
-
-So, for example, the following simple code block can be evaluated and
-the results of evaluation inserted into the buffer.
-
-: #+begin_src C++ :includes <stdio.h>
-:   int a=1;
-:   int b=1;
-:   printf("%d\n", a+b);
-: #+end_src
-: 
-: #+results:
-: : 2
-
-** About C
-C dates back in the 1970.
-It was devised by Kernighan & Ritchie.
-It was used to create the Unix kernel, and many of its utilities.
-Today it is still the base of the Linux & Unix kernel.
-
-** About C++
-C++ was devised by Stroustrup in the 1980.
-The purpose was to enhance C with object programming.
-Among the features introduced by C++, there are:
-  - templates and the Standard Template Library,
-  - object programming, with class definition and inheritance,
-  - functions and operators overloading
-  - exceptions
-
-** About D
-[[http://dlang.org/][D]] is a C++-like language made by [[http://dlang.org/][Digital Mars]].
-It features:
-  - C++ syntax
-  - Built-in garbage collector
-  - Strong type system
-  - Meta-programming
-  - Seamless assembler support
-  - Usable as a scripting language
-  - C binary compatibility
-
-* Requirements and Setup
-
-1- You must have the compilers available on your computer.
-   You may use only one of the three languages:
-   there is no requirement to have all three installed.
-   - C and C++ often come pre-installed.
-     Popular compilers are the GNU ones, called =gcc= and =g++=.
-     But others are usable as well.
-   - For D, look at http://dlang.org/ for downloading and instructions.
-     The compilers are called =dmd= and =rdmd=.
-
-   Eventually, the compilers must be in the =PATH=.
-
-2- Make any or all languages available to Babel.
-   Type:
-   : M-x customize-variable org-babel-load-languages
-   and add the language of your choice.
-
-* Org Mode Features for C, C++, D Source Code Blocks
-** Header Arguments
-
-- =:var VARIABLE=VALUE= ::
-  A global C, C++, or D variable named VARIABLE will be declared
-  and initialized with VALUE
-
-  Possible types for VARIABLE may be:
-    : int,
-    : double,
-    : string or const char*,
-    : type[]    // type = int, double, string, const char*
-    : type[][]  // type = int, double, string, const char*
-
-  The later type, =type[][]=, is used for variables storing Org tables
-
-  The =type[]= is used for lists or vectors declared in the header
-
-- =:cmdline= :: command line arguments to pass to the executable
-     compiled from the code block
-
-- =:flags= :: flags to pass to the compiler
-
-- =:main= :: can be set to "no" to inhibit wrapping of the code block
-     in a =main= function call
-
-- =:includes= (C & CC+ only):: accepts either a single string name, or a list of
-     names of files to =#include= in the execution of the code block
-
-- =:import package= (D only) ::
-  An import statement will be declared in the D source before the source code
-
-- =:defines= (C & C++ only):: just like =:includes= but for =#defines= lines at the
-     top of the code
-
-** Sessions
-   There is no support for sessions
-
-** TODO Result Types
-   - Which result types are supported?
-** TODO Other
-   - Differences from other supported languages
-* Examples of Use
-** Hello World in C & C++
-
-Here is Hello World!
-
-#+name: c-hello
-#+begin_src C :exports results
-  printf ("Hello World!");
-#+end_src
-
-This source code block:
-
-#+begin_example
-#+begin_src C
-  printf ("Hello World!");
-#+end_src
-#+end_example
-
-** Hello World in D
-Here is Hello World!
-
-#+name: d-hello
-#+begin_src D :exports results
-  writefln ("Hello World!");
-#+end_src
-
-This source code block:
-
-#+begin_example
-#+begin_src D
-  writefln ("Hello World!");
-#+end_src
-#+end_example
-
-yields this result:
-
-#+results: d-hello
-Hello World!
-
-Note that:
-- no =main()= is declared, a trivial one is automatically provided,
-- there is no directive like:
-  + =#include "stdio.h"= (in C or C++)
-  + =import std.stdio;= (in D)
-  because those libraries are so common that they are always included.
-
-** Scalar variables
-Variables may be declared outside the script.
-They are automatically inserted at the top of the script.
-Three types are supported, based on the look of the value:
-  - =string= or =const char*=
-  - =int=
-  - =double=
-
-Example in C or C++:
-
-#+begin_example
-#+header: :var mystring="Sunday" :var myint=145 :var mydouble=3.14
-#+BEGIN_SRC C
-  printf ("mystring %s\n", mystring);
-  printf ("myint    %d\n", myint);
-  printf ("mydouble %g\n", mydouble);
-#+END_SRC
-#+end_example
-
-yields this result:
-
-#+RESULTS:
-| mystring | Sunday |
-| myint    |    145 |
-| mydouble |   3.14 |
-
-Example in D:
-
-#+begin_example
-#+header: :var mystring="Sunday" :var myint=145 :var mydouble=3.14
-#+BEGIN_SRC D
-  writefln ("mystring %s", mystring);
-  writefln ("myint    %d", myint);
-  writefln ("mydouble %g", mydouble);
-#+END_SRC
-#+end_example
-
-yields this result:
-
-#+RESULTS:
-| mystring | Sunday |
-| myint    |    145 |
-| mydouble |   3.14 |
-
-** Process an Org Mode Table
-
-*** How to handle a table
-We take an Org mode table as input, process it, and output
-a new Org mode table.
-
-This table will be input in the script, and iterated row by row:
-
-#+tblname: somedata
-| nb    | sqr | noise |
-|-------+-----+-------|
-| zero  |   0 |  0.23 |
-| one   |   1 |  1.31 |
-| two   |   4 |  4.61 |
-| three |   9 |  9.05 |
-| four  |  16 | 16.55 |
-
-The table is converted to a variable in the script:
-  : const char* somedata[5][3] = {...};  // in C & C++
-  : string      somedata[5][3] = [...];  // in D
-
-The header, if any, is available to the script as well:
-  : const char* somedata_header[3] = { "nb", "sqr", "noise" };  // in C & C++
-  : string      somedata_header[3] = { "nb", "sqr", "noise" };  // in D
-
-The dimensions of the table are available:
-  : int somedata_rows = 5;
-  : int somedata_cols = 3;
-
-Additionnally, an accessor function retrives a cell using the column
-name as found in the header:
-  : const char* cell = somedata_h(3,"noise"); // 9.05 in C & C++
-  : string      cell = somedata_h(3,"noise"); // 9.05 in D
-
-Note that table contents are (almost) always strings
-(as opposed to integers or floating point numbers).
-This allows to easily handle heterogeneous tables,
-and tables with missing values.
-To convert a string cell to a numeric value on the fly, use standard convertors:
-  : int    cell = atoi(somedata_h(4,"sqr"));        // integer conversion in C & C++
-  : double cell = atof(somedata_h(4,"noise"));      //  double conversion in C & C++
-  : int    cell = to!int(somedata_h(4,"sqr"));      // integer conversion in D
-  : double cell = to!double(somedata_h(4,"noise")); //  double conversion in D
-
-*** Example in C & C++
-
-#+name: c-table
-#+header: :exports results
-#+begin_src C++ :var somedata=somedata
-  int main()
-  {
-    for (int i=0; i<somedata_rows; i++) {
-      printf ("%2d %7s ", i, somedata_h(i,"nb"));
-      for (int j=1; j<somedata_cols; j++) {
-        const char* cell = somedata[i][j];
-        printf ("%5s %5g ", cell, 1000*atof(cell));
-      }
-      printf("\n");
-    }
-    return 0;
-  }
-#+end_src
-
-This code:
-
-#+begin_example
-#+header: :exports results
-#+begin_src C++ :var somedata=somedata
-  #include "stdlib.h"
-  int main()
-  {
-    for (int i=0; i<somedata_rows; i++) {
-      printf ("%2d ", i);
-      for (int j=0; j<somedata_cols; j++) {
-        const char* cell = somedata[i][j];
-        printf ("%5s %5g ", cell, 1000*atof(cell));
-      }
-      printf("\n");
-    }
-    return 0;
-  }
-#+end_src
-#+end_example
-
-yields this result:
-
-#+RESULTS: c-table
-| 0 | zero  |  0 |     0 |  0.23 |   230 |
-| 1 | one   |  1 |  1000 |  1.31 |  1310 |
-| 2 | two   |  4 |  4000 |  4.61 |  4610 |
-| 3 | three |  9 |  9000 |  9.05 |  9050 |
-| 4 | four  | 16 | 16000 | 16.55 | 16550 |
-
-*** Example in D
-
-#+name: d-table
-#+header: :exports results
-#+begin_src D :var somedata=somedata
-  void main()
-  {
-    foreach (i, row; somedata) {
-      writef ("%2s %7s ", i, somedata_h(i,"nb"));
-      foreach (j, cell; row)
-        if (j) // skip 1st column
-          writef ("%5s %5s ", cell, 1000*to!double(cell));
-      writeln();
-    }
-  }
-#+end_src
-
-#+begin_example
-#+begin_src D :results output :var somedata=somedata :var TT="321" :var QQ=3.14
-  void main()
-  {
-    foreach (i, row; somedata) {
-      writef ("%2s %7s ", i, somedata_h(i,"nb"));
-      foreach (j, cell; row)
-        if (j) // skip 1st column
-          writef ("%5s %5s ", cell, 1000*to!double(cell));
-      writeln();
-    }
-  }
-#+end_src
-#+end_example
-
-yields this result:
-
-#+results: d-table
-| 0 | zero  |  0 |     0 |  0.23 |   230 |
-| 1 | one   |  1 |  1000 |  1.31 |  1310 |
-| 2 | two   |  4 |  4000 |  4.61 |  4610 |
-| 3 | three |  9 |  9000 |  9.05 |  9050 |
-| 4 | four  | 16 | 16000 | 16.55 | 16550 |
-
-
-*** Pure numeric table
-
-This table is a pure numeric table.
-| 3 | 3.3 |
-| 4 | 4.1 |
-| 5 | 5.9 |
-| 6 | 6.5 |
-
-In this special case, it is translated to a numeric table:
-: double MyTable[4][2] = { {3,3.3}, {4,4.1}, {5,5.9}, {6,6.5} };
-
-If there is a blank cell among numeric cells,
-then the whole table falls back to the string case,
-where the blank cell is translated to the empty string "".
-
-** TODO Lists and vectors in the header
-* New version
-
-Here is a new version of =ob-C.el=.
-Compared to the version in the repository, this one adds a few features:
-- non-homogeneous tables
-- table headers support
-- easier table iterating
-- some error handling enhancement
-- new D support for simple lists and vectors
-- temporary block expansion
-
-#+BEGIN_SRC elisp :results none
-;;; ob-C.el --- org-babel functions for C and similar languages
-
-;; Copyright (C) 2010-2014 Free Software Foundation, Inc.
-
-;; Author: Eric Schulte, Thierry Banel
-;; Keywords: literate programming, reproducible research
-;; Homepage: http://orgmode.org
-
-;; This file is part of GNU Emacs.
-
-;; GNU Emacs is free software: you can redistribute it and/or modify
-;; it under the terms of the GNU General Public License as published by
-;; the Free Software Foundation, either version 3 of the License, or
-;; (at your option) any later version.
-
-;; GNU Emacs is distributed in the hope that it will be useful,
-;; but WITHOUT ANY WARRANTY; without even the implied warranty of
-;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-;; GNU General Public License for more details.
-
-;; You should have received a copy of the GNU General Public License
-;; along with GNU Emacs.  If not, see <http://www.gnu.org/licenses/>.
-
-;;; Commentary:
-
-;; Org-Babel support for evaluating C, C++, D code.
-;;
-;; very limited implementation:
-;; - currently only support :results output
-;; - not much in the way of error feedback
-
-;;; Code:
-(require 'ob)
-(require 'cc-mode)
-(eval-when-compile
-  (require 'cl))
-
-(declare-function org-entry-get "org"
-		  (pom property &optional inherit literal-nil))
-(declare-function org-remove-indentation "org" (code &optional n))
-
-(defvar org-babel-tangle-lang-exts)
-(add-to-list 'org-babel-tangle-lang-exts '("C++" . "cpp"))
-(add-to-list 'org-babel-tangle-lang-exts '("D" . "d"))
-
-(defvar org-babel-default-header-args:C '())
-
-(defvar org-babel-C-compiler "gcc"
-  "Command used to compile a C source code file into an
-executable.")
-
-(defvar org-babel-C++-compiler "g++"
-  "Command used to compile a C++ source code file into an
-executable.")
-
-(defvar org-babel-D-compiler "rdmd"
-  "Command used to compile and execute a D source code file.")
-
-(defvar org-babel-c-variant nil
-  "Internal variable used to hold which type of C (e.g. C or C++ or D)
-is currently being evaluated.")
-
-(defun org-babel-execute:cpp (body params)
-  "Execute BODY according to PARAMS.
-This function calls `org-babel-execute:C++'."
-  (org-babel-execute:C++ body params))
-
-(defun org-babel-execute:C++ (body params)
-  "Execute a block of C++ code with org-babel.
-This function is called by `org-babel-execute-src-block'."
-  (let ((org-babel-c-variant 'cpp)) (org-babel-C-execute body params)))
-
-(defun org-babel-execute:D (body params)
-  "Execute a block of D code with org-babel.
-This function is called by `org-babel-execute-src-block'."
-  (let ((org-babel-c-variant 'd)) (org-babel-C-execute body params)))
-
-(defun org-babel-execute:C (body params)
-  "Execute a block of C code with org-babel.
-This function is called by `org-babel-execute-src-block'."
-  (let ((org-babel-c-variant 'c)) (org-babel-C-execute body params)))
-
-(defun org-babel-C-execute (body params)
-  "This function should only be called by `org-babel-execute:C'
-or `org-babel-execute:C++' or `org-babel-execute:D'."
-  (let* ((tmp-src-file (org-babel-temp-file
-			"C-src-"
-			(case org-babel-c-variant
-			 (c   ".c"  )
-			 (cpp ".cpp")
-			 (d   ".d"  ))))
-	 (tmp-bin-file (org-babel-temp-file "C-bin-" org-babel-exeext)) ;; not used for D
-	 (cmdline (cdr (assoc :cmdline params)))
-	 (cmdline (if cmdline (concat " " cmdline) ""))
-	 (flags (cdr (assoc :flags params)))
-	 (flags (mapconcat 'identity
-			   (if (listp flags) flags (list flags)) " "))
-	 (full-body
-	  (case org-babel-c-variant
-	    (c   (org-babel-C-expand-C   body params))
-	    (cpp (org-babel-C-expand-C++ body params))
-	    (d   (org-babel-C-expand-D   body params)))))
-    (with-temp-file tmp-src-file (insert full-body))
-    (case org-babel-c-variant
-      ((c cpp)
-       (org-babel-eval
-	(format "%s -o %s %s %s"
-		(case org-babel-c-variant
-		 (c   org-babel-C-compiler)
-		 (cpp org-babel-C++-compiler))
-		(org-babel-process-file-name tmp-bin-file)
-		flags
-		(org-babel-process-file-name tmp-src-file)) ""))
-      (d nil)) ;; no separate compilation for D
-    (let ((results
-	   (org-babel-eval
-	    (case org-babel-c-variant
-	      ((c cpp)
-	       (concat tmp-bin-file cmdline))
-	      (d
-	       (format "%s %s %s %s"
-		       org-babel-D-compiler
-		       flags
-		       (org-babel-process-file-name tmp-src-file)
-		       cmdline)))
-	    "")))
-      (when results
-	(setq results (org-babel-trim (org-remove-indentation results)))
-	(org-babel-reassemble-table
-	 (org-babel-result-cond (cdr (assoc :result-params params))
-	   (org-babel-read results t)
-	   (let ((tmp-file (org-babel-temp-file "c-")))
-	     (with-temp-file tmp-file (insert results))
-	     (org-babel-import-elisp-from-file tmp-file)))
-	 (org-babel-pick-name
-	  (cdr (assoc :colname-names params)) (cdr (assoc :colnames params)))
-	 (org-babel-pick-name
-	  (cdr (assoc :rowname-names params)) (cdr (assoc :rownames params)))))
-      )))
-
-(defun org-babel-expand-body:C++ (body params)
-  "Expand a block of C++ code with org-babel according to it's
-header arguments."
-  (let ((org-babel-c-variant 'cpp)) (org-babel-C-expand-C++ body params)))
-
-(defun org-babel-expand-body:C (body params)
-  "Expand a block of C code with org-babel according to it's
-header arguments."
-  (let ((org-babel-c-variant 'c)) (org-babel-C-expand-C body params)))
-
-(defun org-babel-expand-body:D (body params)
-  "Expand a block of D code with org-babel according to it's
-header arguments."
-  (let ((org-babel-c-variant 'd)) (org-babel-C-expand-D body params)))
-
-(defun org-babel-C-expand-C++ (body params)
-  "Expand a block of C or C++ code with org-babel according to
-it's header arguments."
-  (org-babel-C-expand-C body params))
-
-(defun org-babel-C-expand-C (body params)
-  "Expand a block of C or C++ code with org-babel according to
-it's header arguments."
-  (let ((vars (mapcar #'cdr (org-babel-get-header params :var)))
-	(colnames (cdar (org-babel-get-header params :colname-names)))
-	(main-p (not (string= (cdr (assoc :main params)) "no")))
-	(includes (or (cdr (assoc :includes params))
-		      (org-babel-read (org-entry-get nil "includes" t))))
-	(defines (org-babel-read
-		  (or (cdr (assoc :defines params))
-		      (org-babel-read (org-entry-get nil "defines" t))))))
-    (unless (listp includes) (setq includes (list includes)))
-    (setq includes (append includes '("<string.h>" "<stdio.h>" "<stdlib.h>")))
-    (mapconcat 'identity
-	       (list
-		;; includes
-		(mapconcat
-		 (lambda (inc) (format "#include %s" inc))
-		 includes "\n")
-		;; defines
-		(mapconcat
-		 (lambda (inc) (format "#define %s" inc))
-		 (if (listp defines) defines (list defines)) "\n")
-		;; variables
-		(mapconcat 'org-babel-C-var-to-C vars "\n")
-		;; table sizes
-		(mapconcat 'org-babel-C-table-sizes-to-C vars "\n")
-		;; tables headers utility
-		(when colnames
-		  (org-babel-C-utility-header-to-C))
-		;; tables headers
-		(mapconcat 'org-babel-C-header-to-C colnames "\n")
-		;; body
-		(if main-p
-		    (org-babel-C-ensure-main-wrap body)
-		  body) "\n") "\n")))
-
-(defun org-babel-C-expand-D (body params)
-  "Expand a block of D code with org-babel according to
-it's header arguments."
-  (let ((vars (mapcar #'cdr (org-babel-get-header params :var)))
-	(colnames (cdar (org-babel-get-header params :colname-names)))
-	(main-p (not (string= (cdr (assoc :main params)) "no")))
-	(imports (or (cdr (assoc :imports params))
-		     (org-babel-read (org-entry-get nil "imports" t)))))
-    (unless (listp imports) (setq imports (list imports)))
-    (setq imports (append imports '("std.stdio" "std.conv")))
-    (mapconcat 'identity
-	       (list
-		"module mmm;"
-		;; imports
-		(mapconcat
-		 (lambda (inc) (format "import %s;" inc))
-		 imports "\n")
-		;; variables
-		(mapconcat 'org-babel-C-var-to-C vars "\n")
-		;; table sizes
-		(mapconcat 'org-babel-C-table-sizes-to-C vars "\n")
-		;; tables headers utility
-		(when colnames
-		  (org-babel-C-utility-header-to-C))
-		;; tables headers
-		(mapconcat 'org-babel-C-header-to-C colnames "\n")
-		;; body
-		(if main-p
-		    (org-babel-C-ensure-main-wrap body)
-		  body) "\n") "\n")))
-
-(defun org-babel-C-ensure-main-wrap (body)
-  "Wrap BODY in a \"main\" function call if none exists."
-  (if (string-match "^[ \t]*[intvod]+[ \t\n\r]*main[ \t]*(.*)" body)
-      body
-    (format "int main() {\n%s\nreturn 0;\n}\n" body)))
-
-(defun org-babel-prep-session:C (session params)
-  "This function does nothing as C is a compiled language with no
-support for sessions"
-  (error "C is a compiled languages -- no support for sessions"))
-
-(defun org-babel-load-session:C (session body params)
-  "This function does nothing as C is a compiled language with no
-support for sessions"
-  (error "C is a compiled languages -- no support for sessions"))
-
-;; helper functions
-
-(defun org-babel-C-format-val (type val)
-  "Handle the FORMAT part of TYPE with the data from VAL."
-  (let ((format-data (cadr type)))
-    (if (stringp format-data)
-	(cons "" (format format-data val))
-      (funcall format-data val))))
-
-(defun org-babel-C-val-to-base-type (val)
-  "Determine the base type of VAL which may be
-'integerp if all base values are integers
-'floatp if all base values are either floating points or integers
-'stringp otherwise."
-  (cond
-   ((integerp val) 'integerp)
-   ((floatp val) 'floatp)
-   ((or (listp val) (vectorp val))
-    (let ((type nil))
-      (mapc (lambda (v)
-	      (case (org-babel-C-val-to-base-type v)
-		(stringp (setq type 'stringp))
-		(floatp
-		 (if (or (not type) (eq type 'integerp))
-		     (setq type 'floatp)))
-		(integerp
-		 (unless type (setq type 'integerp)))))
-	    val)
-      type))
-   (t 'stringp)))
-
-(defun org-babel-C-val-to-C-type (val)
-  "Determine the type of VAL.
-Return a list (TYPE-NAME FORMAT).  TYPE-NAME should be the name of the type.
-FORMAT can be either a format string or a function which is called with VAL."
-  (let* ((basetype (org-babel-C-val-to-base-type val))
-	 (type
-	  (case basetype
-	    (integerp '("int" "%d"))
-	    (floatp '("double" "%f"))
-	    (stringp
-	     (list
-	      (if (equal org-babel-c-variant 'd) "string" "const char*")
-	      "\"%s\""))
-	    (t (error "unknown type %S" type)))))
-    (cond
-     ((integerp val) type) ;; an integer declared in the #+begin_src line
-     ((floatp val) type) ;; a numeric declared in the #+begin_src line
-     ((and (listp val) (listp (car val))) ;; a table
-      `(,(car type)
-	(lambda (val)
-	  (cons
-	   (format "[%d][%d]" (length val) (length (car val)))
-	   (concat
-	    (if (equal org-babel-c-variant 'd) "[\n" "{\n")
-	    (mapconcat
-	     (lambda (v)
-	       (concat
-		(if (equal org-babel-c-variant 'd) " [" " {")
-		(mapconcat (lambda (w) (format ,(cadr type) w)) v ",")
-		(if (equal org-babel-c-variant 'd) "]" "}")))
-	     val
-	     ",\n")
-	    (if (equal org-babel-c-variant 'd) "\n]" "\n}"))))))
-     ((or (listp val) (vectorp val)) ;; a list declared in the #+begin_src line
-      `(,(car type)
-	(lambda (val)
-	  (cons
-	   (format "[%d]" (length val))
-	   (concat
-	    (if (equal org-babel-c-variant 'd) "[" "{")
-	    (mapconcat (lambda (v) (format ,(cadr type) v)) val ",")
-	    (if (equal org-babel-c-variant 'd) "]" "}"))))))
-     (t ;; treat unknown types as string
-      type))))
-
-(defun org-babel-C-var-to-C (pair)
-  "Convert an elisp val into a string of C code specifying a var
-of the same value."
-  ;; TODO list support
-  (let ((var (car pair))
-	(val (cdr pair)))
-    (when (symbolp val)
-      (setq val (symbol-name val))
-      (when (= (length val) 1)
-	(setq val (string-to-char val))))
-    (let* ((type-data (org-babel-C-val-to-C-type val))
-	   (type (car type-data))
-	   (formated (org-babel-C-format-val type-data val))
-	   (suffix (car formated))
-	   (data (cdr formated)))
-      (format "%s %s%s = %s;"
-	      type
-	      var
-	      suffix
-	      data))))
-
-(defun org-babel-C-table-sizes-to-C (pair)
-  "Create constants of table dimensions, if PAIR is a table."
-  (when (listp (cdr pair))
-    (cond
-     ((listp (cadr pair)) ;; a table
-      (concat
-       (format "const int %s_rows = %d;" (car pair) (length (cdr pair)))
-       "\n"
-       (format "const int %s_cols = %d;" (car pair) (length (cadr pair)))))
-     (t ;; a list declared in the #+begin_src line
-      (format "const int %s_cols = %d;" (car pair) (length (cdr pair)))))))
-
-(defun org-babel-C-utility-header-to-C ()
-  "Generate a utility function to convert a column name
-into a column number."
-  (case org-babel-c-variant
-    ((c cpp)
-     "int get_column_num (int nbcols, const char** header, const char* column)
-{
-  int c;
-  for (c=0; c<nbcols; c++)
-    if (strcmp(header[c],column)==0)
-      return c;
-  return -1;
-}
-"
-     )
-    (d
-     "int get_column_num (string[] header, string column)
-{
-  foreach (c, h; header)
-    if (h==column)
-      return to!int(c);
-  return -1;
-}
-"
-     )))
-
-(defun org-babel-C-header-to-C (head)
-  "Convert an elisp list of header table into a C or D vector
-specifying a variable with the name of the table."
-  (let ((table (car head))
-        (headers (cdr head)))
-    (concat
-     (format
-      (case org-babel-c-variant
-	((c cpp) "const char* %s_header[%d] = {%s};")
-	(d       "string %s_header[%d] = [%s];"))
-      table
-      (length headers)
-      (mapconcat (lambda (h) (format "%S" h)) headers ","))
-     "\n"
-     (case org-babel-c-variant
-       ((c cpp)
-	(format
-	 "const char* %s_h (int row, const char* col) { return %s[row][get_column_num(%d,%s_header,col)]; }"
-	 table table (length headers) table))
-       (d
-	(format
-	 "string %s_h (ulong row, string col) { return %s[row][get_column_num(%s_header,col)]; }"
-	 table table table))))))
-
-(provide 'ob-C)
-
-;;; ob-C.el ends here
-
-#+END_SRC

+ 151 - 97
org-contrib/babel/languages/ob-doc-C.org

@@ -45,9 +45,6 @@
   - [X] Provide brief [[Examples%20of%20Use][Examples of Use]]
 * Introduction
 
-*Note*: a new version of both the software and the documentation
-is under evaluation. It is available here: [[ob-doc-C-new.org][ob-doc-C-new]]
-
 Babel can evaluate C, C++, and D code.
 
 As opposed to interpreted languages, which can be evaluated directly,
@@ -61,6 +58,18 @@ Note: there used to be two separate library files, =ob-C.el= and
 =ob-D.el=. They have been merged in a single =ob-C.el= file which
 handle all three languages.
 
+So, for example, the following simple code block can be evaluated and
+the results of evaluation inserted into the buffer.
+
+: #+begin_src C++ :includes <stdio.h>
+:   int a=1;
+:   int b=1;
+:   printf("%d\n", a+b);
+: #+end_src
+: 
+: #+results:
+: : 2
+
 ** About C
 C dates back in the 1970.
 It was devised by Kernighan & Ritchie.
@@ -73,8 +82,8 @@ The purpose was to enhance C with object programming.
 Among the features introduced by C++, there are:
   - templates and the Standard Template Library,
   - object programming, with class definition and inheritance,
-  - functions and operators overloading
-  - exceptions
+  - functions and operators overloading,
+  - exceptions.
 
 ** About D
 [[http://dlang.org/][D]] is a C++-like language made by [[http://dlang.org/][Digital Mars]].
@@ -86,7 +95,6 @@ It features:
   - Seamless assembler support
   - Usable as a scripting language
   - C binary compatibility
-  - and much more.
 
 * Requirements and Setup
 
@@ -104,9 +112,9 @@ It features:
 2- Make any or all languages available to Babel.
    Type:
    : M-x customize-variable org-babel-load-languages
-   and add the language of your choice.
+   and add the C language (capital "C", which gives access to C, C++, D)
 
-* Org Mode Features for D Source Code Blocks
+* Org Mode Features for C, C++, D Source Code Blocks
 ** Header Arguments
 
 - =:var VARIABLE=VALUE= ::
@@ -122,7 +130,7 @@ It features:
 
   The later type, =type[][]=, is used for variables storing Org tables
 
-  The =type[]= is used for lists or vectors declared in the header
+  The =type[]= is used for lists or vectors declared in the header.
 
 - =:cmdline= :: command line arguments to pass to the executable
      compiled from the code block
@@ -132,11 +140,12 @@ It features:
 - =:main= :: can be set to "no" to inhibit wrapping of the code block
      in a =main= function call
 
-- =:includes= (C & CC+ only):: accepts either a single string name, or a list of
+- =:includes= :: (C & CC+ only)
+     accepts either a single string name, or a list of
      names of files to =#include= in the execution of the code block
 
-- =:import package= (D only) ::
-  An import statement will be declared in the D source before the source code
+- =:import package=:: (D only)
+     An import statement will be declared in the D source before the source code
 
 - =:defines= (C & C++ only):: just like =:includes= but for =#defines= lines at the
      top of the code
@@ -144,51 +153,57 @@ It features:
 ** Sessions
    There is no support for sessions
 
+** TODO Result Types
+   - Which result types are supported?
+** TODO Other
+   - Differences from other supported languages
 * Examples of Use
 ** Hello World in C & C++
+
 Here is Hello World!
 
 #+name: c-hello
 #+begin_src C :exports results
-  #include "stdio.h"
   printf ("Hello World!");
 #+end_src
 
 This source code block:
-
 #+begin_example
 #+begin_src C
-  #include "stdio.h"
   printf ("Hello World!");
 #+end_src
 #+end_example
 
-Note that:
-- no =main()= is declared, a trivial one is automatically provided,
+yields this result (type =C-c C-c= in the source block):
+#+results: c-hello
+Hello World!
 
 ** Hello World in D
 Here is Hello World!
 
 #+name: d-hello
 #+begin_src D :exports results
-  import std.stdio;
   writefln ("Hello World!");
 #+end_src
 
 This source code block:
-
 #+begin_example
 #+begin_src D
-  import std.stdio;
   writefln ("Hello World!");
 #+end_src
 #+end_example
 
-yields this result:
-
+yields this result (type =C-c C-c= in the source block):
 #+results: d-hello
 Hello World!
 
+Note that:
+- if no =main()= is declared, a trivial one is automatically provided,
+- there is no directive like:
+  + =#include "stdio.h"= (in C or C++)
+  + =import std.stdio;= (in D)
+  because those libraries are so common that they are always included.
+
 ** Scalar variables
 Variables may be declared outside the script.
 They are automatically inserted at the top of the script.
@@ -198,28 +213,16 @@ Three types are supported, based on the look of the value:
   - =double=
 
 Example in C or C++:
-
-#+header: :var mystring="Sunday" :var myint=145 :var mydouble=3.14
-#+BEGIN_SRC C
-  #include "stdio.h"
-  printf ("mystring %s\n", mystring);
-  printf ("myint    %d\n", myint);
-  printf ("mydouble %g\n", mydouble);
-#+END_SRC
-
-This source code block:
-
 #+begin_example
 #+header: :var mystring="Sunday" :var myint=145 :var mydouble=3.14
 #+BEGIN_SRC C
-  #include "stdio.h"
   printf ("mystring %s\n", mystring);
   printf ("myint    %d\n", myint);
   printf ("mydouble %g\n", mydouble);
 #+END_SRC
 #+end_example
 
-yields this result:
+yields this result (type =C-c C-c=):
 
 #+RESULTS:
 | mystring | Sunday |
@@ -227,66 +230,85 @@ yields this result:
 | mydouble |   3.14 |
 
 Example in D:
-
-#+header: :var mystring="Sunday" :var myint=145 :var mydouble=3.14
-#+BEGIN_SRC D
-  import std.stdio;
-  writefln ("mystring %s", mystring);
-  writefln ("myint    %d", myint);
-  writefln ("mydouble %g", mydouble);
-#+END_SRC
-
 #+begin_example
 #+header: :var mystring="Sunday" :var myint=145 :var mydouble=3.14
 #+BEGIN_SRC D
-  import std.stdio;
   writefln ("mystring %s", mystring);
   writefln ("myint    %d", myint);
   writefln ("mydouble %g", mydouble);
 #+END_SRC
 #+end_example
 
+yields this result (type =C-c C-c=):
+
 #+RESULTS:
 | mystring | Sunday |
 | myint    |    145 |
 | mydouble |   3.14 |
 
+If you want to see the expanded source code, without compiling a running it,
+just type =C-c C-v v=".
+
 ** Process an Org Mode Table
 
 *** How to handle a table
+We take an Org mode table as input, process it, and output
+a new Org mode table.
 
-Example of input table:
+This table will be input in the script, and iterated row by row:
 
 #+tblname: somedata
-| nb    | day       |
-|-------+-----------|
-| zero  | Sunday    |
-| one   | Monday    |
-| two   | Tuesday   |
-| three | Wednesday |
-| four  | Thursday  |
-| five  | Friday    |
-| six   | Saturday  |
+| nb    | sqr | noise |
+|-------+-----+-------|
+| zero  |   0 |  0.23 |
+| one   |   1 |  1.31 |
+| two   |   4 |  4.61 |
+| three |   9 |  9.05 |
+| four  |  16 | 16.55 |
 
 The table is converted to a variable in the script:
-  - =const char* somedata[7][2] = {...};=  // in C & C++
-  - =string      somedata[7][2] = [...];=  // in D
-
-Beware that in the current version, input tables must be homogeneous:
-they must contain only integers, or only doubles, or only strings.
-This constraint will be removed in a future release.
+  : const char* somedata[5][3] = {...};  // in C & C++
+  : string      somedata[5][3] = [...];  // in D
+
+The header, if any, is available to the script as well:
+  : const char* somedata_header[3] = { "nb", "sqr", "noise" };  // in C & C++
+  : string      somedata_header[3] = [ "nb", "sqr", "noise" ];  // in D
+
+The dimensions of the table are available:
+  : int somedata_rows = 5;
+  : int somedata_cols = 3;
+
+Additionnally, an accessor function retrives a cell using the column
+name as found in the header:
+  : const char* cell = somedata_h(3,"noise"); // "9.05" in C & C++
+  : string      cell = somedata_h(3,"noise"); // "9.05" in D
+
+Type =C-c C-v v= to look at the generate code without running it.
+
+Note that table contents are (almost) always strings
+(as opposed to integers or floating point numbers).
+This allows to easily handle heterogeneous tables,
+and tables with missing values.
+To convert a string cell to a numeric value on the fly, use standard convertors:
+  : int    cell = atoi(somedata_h(4,"sqr"));        // integer conversion in C & C++
+  : double cell = atof(somedata_h(4,"noise"));      //  double conversion in C & C++
+  : int    cell = to!int(somedata_h(4,"sqr"));      // integer conversion in D
+  : double cell = to!double(somedata_h(4,"noise")); //  double conversion in D
 
 *** Example in C & C++
 
+#+name: c-table
 #+header: :exports results
 #+begin_src C++ :var somedata=somedata
-  #include "stdio.h"
   int main()
   {
-    for (int i=0; i<7; i++) {
-      for (int j=0; j<2; j++)
-        printf ("%s ", somedata[i][j]);
-      printf("%d\n", i);
+    for (int i=0; i<somedata_rows; i++) {
+      printf ("%2d %7s ", i, somedata_h(i,"nb"));
+      for (int j=1; j<somedata_cols; j++) {
+        const char* cell = somedata[i][j];
+        printf ("%5s %5g ", cell, 1000*atof(cell));
+      }
+      printf("\n");
     }
     return 0;
   }
@@ -297,13 +319,16 @@ This code:
 #+begin_example
 #+header: :exports results
 #+begin_src C++ :var somedata=somedata
-  #include "stdio.h"
+  #include "stdlib.h"
   int main()
   {
-    for (int i=0; i<7; i++) {
-      for (int j=0; j<2; j++)
-        printf ("%s ", somedata[i][j]);
-      printf("%d\n", i);
+    for (int i=0; i<somedata_rows; i++) {
+      printf ("%2d ", i);
+      for (int j=1; j<somedata_cols; j++) {
+        const char* cell = somedata[i][j];
+        printf ("%5s %5g ", cell, 1000*atof(cell));
+      }
+      printf("\n");
     }
     return 0;
   }
@@ -312,42 +337,40 @@ This code:
 
 yields this result:
 
-#+RESULTS:
-| zero  | Sunday    | 0 |
-| one   | Monday    | 1 |
-| two   | Tuesday   | 2 |
-| three | Wednesday | 3 |
-| four  | Thursday  | 4 |
-| five  | Friday    | 5 |
-| six   | Saturday  | 6 |
+#+RESULTS: c-table
+| 0 | zero  |  0 |     0 |  0.23 |   230 |
+| 1 | one   |  1 |  1000 |  1.31 |  1310 |
+| 2 | two   |  4 |  4000 |  4.61 |  4610 |
+| 3 | three |  9 |  9000 |  9.05 |  9050 |
+| 4 | four  | 16 | 16000 | 16.55 | 16550 |
 
 *** Example in D
 
+#+name: d-table
 #+header: :exports results
 #+begin_src D :var somedata=somedata
-  import std.stdio;
   void main()
   {
     foreach (i, row; somedata) {
+      writef ("%2s %7s ", i, somedata_h(i,"nb"));
       foreach (j, cell; row)
-        writef ("%s ", cell);
-      writefln ("%s", i);
+        if (j) // skip 1st column
+          writef ("%5s %5s ", cell, 1000*to!double(cell));
+      writeln();
     }
   }
 #+end_src
 
-This code:
-
 #+begin_example
-#+header: :exports results
-#+begin_src D :var somedata=somedata
-  import std.stdio;
+#+begin_src D :results output :var somedata=somedata :var TT="321" :var QQ=3.14
   void main()
   {
     foreach (i, row; somedata) {
+      writef ("%2s %7s ", i, somedata_h(i,"nb"));
       foreach (j, cell; row)
-        writef ("%s ", cell);
-      writefln ("%s", i);
+        if (j) // skip 1st column
+          writef ("%5s %5s ", cell, 1000*to!double(cell));
+      writeln();
     }
   }
 #+end_src
@@ -355,12 +378,43 @@ This code:
 
 yields this result:
 
-#+RESULTS:
-| zero  | Sunday    | 0 |
-| one   | Monday    | 1 |
-| two   | Tuesday   | 2 |
-| three | Wednesday | 3 |
-| four  | Thursday  | 4 |
-| five  | Friday    | 5 |
-| six   | Saturday  | 6 |
+#+results: d-table
+| 0 | zero  |  0 |     0 |  0.23 |   230 |
+| 1 | one   |  1 |  1000 |  1.31 |  1310 |
+| 2 | two   |  4 |  4000 |  4.61 |  4610 |
+| 3 | three |  9 |  9000 |  9.05 |  9050 |
+| 4 | four  | 16 | 16000 | 16.55 | 16550 |
+
+
+*** Pure numeric table
+
+This table is a pure numeric table.
+| 3 | 3.3 |
+| 4 | 4.1 |
+| 5 | 5.9 |
+| 6 | 6.5 |
+
+In this special case, it is translated to a numeric table:
+: double MyTable[4][2] = { {3,3.3}, {4,4.1}, {5,5.9}, {6,6.5} };
+
+If there is a blank cell among numeric cells,
+then the whole table falls back to the string case,
+where the blank cell is translated to the empty string "".
+
+** TODO Lists and vectors in the header
+
+* Shortcomings and known bugs
+** C++ vs. cpp
+After the =#+begin_src= block header, both =C++= and =cpp= are
+accepted to specify C++ language.
+However only =C++= works for generated code visualization
+through =C-c C-v v=.
+
+** Pure numeric + header  cast error
+A type mismatch between strings  and double cause an error
+when attempting to use the cell accessor with column name
+when the table is pure numeric.
 
+** Compilers customization
+There is no customization of the compilers paths or names
+through the standard Emacs customization facility.

+ 4 - 4
org-contrib/babel/ob-template.el

@@ -97,8 +97,8 @@
 ;; arguments which you feel may be useful -- all header arguments
 ;; specified by the user will be available in the PARAMS variable.
 (defun org-babel-execute:template (body params)
-  "Execute a block of Template code with org-babel.  This function is
-called by `org-babel-execute-src-block'"
+  "Execute a block of Template code with org-babel.
+This function is called by `org-babel-execute-src-block'"
   (message "executing Template source code block")
   (let* ((processed-params (org-babel-process-params params))
          ;; set the session if the session variable is non-nil
@@ -144,8 +144,8 @@ Emacs-lisp table, otherwise return the results as a string."
   )
 
 (defun org-babel-template-initiate-session (&optional session)
-  "If there is not a current inferior-process-buffer in SESSION
-then create.  Return the initialized session."
+  "If there is not a current inferior-process-buffer in SESSION then create.
+Return the initialized session."
   (unless (string= session "none")
     ))
 

+ 187 - 0
org-contrib/org-watchdoc.org

@@ -0,0 +1,187 @@
+# Created 2014-04-10 Do 01:36
+#+TITLE: Org-watchdoc
+#+DATE: <2014-04-09 Mi>
+#+AUTHOR: Thorsten Jolitz
+#+OPTIONS: H:4 num:nil toc:4 \n:nil @:t ::t |:t ^:t -:t f:t *:t TeX:t LaTeX:t skip:nil d:(HIDE) tags:not-in-toc prop:t
+#+STARTUP: align fold nodlcheck oddeven lognotestate
+#+SEQ_TODO: TODO(t) INPROGRESS(i) WAITING(w@) | DONE(d) CANCELED(c@)
+#+TAGS: Write(w) Update(u) Fix(f) Check(c)
+#+LANGUAGE: en
+#+PRIORITIES: A C B
+#+CATEGORY: worg
+
+[[file:index.org][{Back to Worg's index}]]
+
+
+
+* org-watchdoc.el --- Watchdog for exported Org-mode trees
+:PROPERTIES:
+:EXPORT_OPTIONS: prop:nil
+:wdoc_1992rwM: /home/tj/git/org-watchdoc/README.md /home/tj/git/org-watchdoc/export-templates/org-watchdoc-gh.org gfm
+:wdoc_1992G_r: /home/tj/gitclone/worg/org-contrib/org-watchdoc.org /home/tj/git/org-watchdoc/export-templates/org-watchdoc-worg.org org
+:wdoc_1992gas: /home/tj/git/org-watchdoc/targets/org-watchdoc.html /home/tj/git/org-watchdoc/export-templates/org-watchdoc-gh.org html
+:wdoc_1992tky: /home/tj/git/org-watchdoc/targets/org-watchdoc.txt /home/tj/git/org-watchdoc/export-templates/org-watchdoc-gh.org ascii
+:wdoc_1992fuB: /home/tj/git/org-watchdoc/targets/org-watchdoc.tex /home/tj/git/org-watchdoc/export-templates/org-watchdoc-gh.org latex
+:END:
+
+Copyright (C) from 2014 Thorsten Jolitz
+Author: Thorsten Jolitz <tjolitz at gmail dot com>
+Keywords: org-mode, exporter, propagate changes, documentation
+
+** MetaData
+:PROPERTIES:
+:copyright: Thorsten Jolitz
+:copyright-years: 2014+
+:version:  1.0
+:licence:  GPL 3 or later (free software)
+:licence-url: http://www.gnu.org/licenses/
+:part-of-emacs: no
+:git-repo: https://github.com/tj64/org-watchdoc.git
+:git-clone: git://github.com/tj64/org-watchdoc.git
+:author:   Thorsten Jolitz
+:author_email: tjolitz AT gmail DOT com
+:END:
+** Commentary
+
+This library implements functionality for keeping exported files
+associated with Org subtrees up-to-date.
+
+Its principal use case is writing the comment-section of Emacs
+Lisp (or other) source-code files only once (and in full Org-mode
+using outorg.el), export it as README documentation from the
+*outorg-edit-buffer* to html, ascii, latex/pdf,
+markdown-github-flavor or whatever, and keep the exported doc
+files automatically up-to-date when the original comment-section
+of the source-buffer is edited explicitly with outorg (via M-x
+outorg-edit-comments-and-propagate-changes).
+
+org-watchdoc is just a little toolbox that can be used
+independently from outorg too. All its functions are commands, so
+its functionality is available for interactive use too.
+** Installation
+
+Put this line in your init file
+
+#+BEGIN_SRC 'emacs-lisp
+  (require 'org-watchdoc)
+#+END_SRC
+
+and make sure Emacs can find the file org-watchdoc.el.
+
+To take real advantage of org-watchdoc, outshine.el and outorg.el
+(and maybe navi-mode.el) should be installed and source-code
+buffers should be structured with outshine headers (outcommented
+Org-mode headers), taking care that the whole comment-section is
+one single outline tree that is the first headline in the
+source-code file. Use org-watchdoc.el itself as an example for
+this kind of file structuring.
+** Usage
+
+*** Commands
+
+Since org-watchdoc is a toolbox and not a mode, no menu or keymap
+is specified. However, its commands can be used interactively:
+
+| M-x org-watchdoc- | action                                   |
+|-------------------+------------------------------------------|
+| add-target        | add target-combination to watchlist      |
+| remove-target     | remove target-combination from watchlist |
+| propagate-changes | if md5 changed reexport all combinations |
+| set-md5           | set org-watchdoc-md5 to current md5      |
+*** Interactive Use
+
+In interactive use, this would be the typical order of actions:
+
+1. Export first buffer tree to desired doc files (e.g. README-GH.md
+   or README-WORG.html). Optional, since adding non-exiting
+   target-files in step 2 will cause the exporter to write them the
+   when exiting the edit-buffer.
+
+2. Add targets with point on first buffer headline.
+
+   Targets are combinations of files the exporter writes to,
+   export-template files to be inserted before the exporter does
+   its work, and backends the exporter should export to, e.g.
+
+   #+BEGIN_EXAMPLE
+   "/home/me/proj/README-GH.md /home/me/proj/gh-tmpl.org gfm"
+   "/home/me/proj/README-WORG.html /home/me/proj/worg-tmpl.org html"
+   #+END_EXAMPLE
+
+   The three elements of such a combination are prompted from
+   the user.
+
+3. Save and set md5 variable.
+
+4. Edit the (narrowed) first buffer tree and save
+
+5. Propagate changes.
+
+   Since md5 has changed due to the edits, all registered target
+   combinations are automatically re-exported.
+*** Use with Outorg
+
+Assuming outshine and outorg are installed and active, do once:
+
+- Edit as Org
+
+  In the *outorg-edit-buffer* do steps 1 and 2 described above
+  for direct interactive use.
+
+#+BEGIN_EXAMPLE
+M-x outorg-edit-comments-and-propagate-changes
+#+END_EXAMPLE
+
+Then whenever you want to edit the source-buffer's
+comment-section and propagate the changes to the watched doc
+files, do:
+
+#+BEGIN_EXAMPLE
+M-x outorg-edit-comments-and-propagate-changes
+#+END_EXAMPLE
+
+instead of the usual 
+
+#+BEGIN_EXAMPLE
+M-x outorg-edit-comment-as-org
+#+END_EXAMPLE
+
+This will
+
+- Offer the first buffer tree for editing in the
+  *outorg-edit-buffer*
+
+- Reset `org-watchdoc-md5' immediately after edit-buffer setup
+
+- Check if buffer md5 has changed when editing is quitted. If so,
+  propagate the changes to the doc files registered in the subtrees
+  watchlist.
+*** Keybindings in Outshine
+
+Here are the keybindings I added to outshine.el:
+
+#+BEGIN_EXAMPLE
+;; edit comment-section with `outorg' and propagate changes
+
+;; best used with prefix-key 'C-c' 
+(define-key map "`" 'outorg-edit-comments-and-propagate-changes)
+
+;; best used with prefix-key 'M-#'
+(define-key map "\M-+" 'outorg-edit-comments-and-propagate-changes)
+(define-key map "+" 'outorg-edit-comments-and-propagate-changes)
+#+END_EXAMPLE
+
+So just like editing e.g. an Emacs Lisp buffer or subtree (with
+outshine activated) in full Org-mode only involves pressing M-# M-#
+once to start editing, and then M-# to exit the edit-buffer, edting
+the comment-section of such a source-buffer and propagating the
+changes to several export-targets only involves pressing M-# M-+ once
+to start editing, and then M-# to exit the edit buffer (when M-# was
+set as outline-minor-mode prefix). 
+*** ChangeLog
+
+| date            | author(s)       | version |
+|-----------------+-----------------+---------|
+| <2014-04-09 Mi> | Thorsten Jolitz |     0.9 |
+
+# Emacs 24.3.1 (Org mode 8.2.5h)

+ 129 - 120
org-contribute.org

@@ -381,109 +381,115 @@ within GNU Emacs:
 32. David Arroyo Menéndez
 33. David Maus
 34. David O'Toole
-35. Dmitry Antipov
-36. Eric Abrahamsen
-37. Eric S. Fraga
-38. Eric Schulte
-39. Erik Iverson
-40. Ethan Ligon
-41. Feng Shu
-42. Francesco Pizzolante
-43. Gary Oberbrunner
-44. Georg Lehner
-45. George Kettleborough
-46. Giovanni Ridolfi
-47. Grégoire Jadi (aka Daimrod)
-48. Henning Dietmar Weiss
-49. Ian Barton
-50. Ilya Shlyakhter
-51. Ippei Furuhashi
-52. James TD Smith
-53. Jan Böcker
-54. Jarmo Hurri
-55. Jason Riedy
-56. Jay Kerns
-57. Jeffrey Ryan Horn
-58. Joel Boehland
-59. John Wiegley
-60. Jonas Bernoulli
-61. Jonathan Leech-Pepin
-62. Juan Pechiar
-63. Julian Gehring
-64. Julien Barnier
-65. Julien Danjou
-66. Justin Gordon
-67. Justus Piater
-68. Kodi Arfer
-69. Konstantin Antipin
-70. Lawrence Mitchell
-71. Le Wang
-72. Lennart Borgman
-73. Luis Anaya
-74. Lukasz Stelmach
-75. Madan Ramakrishnan
-76. Magnus Henoch
-77. Manuel Giraud
-78. Martin Pohlack
-79. Martyn Jago
-80. Matt Lundin
-81. Max Mikhanosha
-82. Michael Albinus
-83. Michael Brand
-84. Michael Gauland
-85. Michael Sperber
-86. Miguel A. Figueroa-Villanueva
-87. Mikael Fornius
-88. Moritz Ulrich
-89. Nathan Neff
-90. Nicholas Dokos
-91. Nicolas Goaziou
-92. Nicolas Richard
-93. Niels Giessen
-94. Noorul Islam K M
-95. Oleh Krehel
-96. Paul Sexton
-97. Pedro Alexandre Marcelino Costa da Silva
-98. Peter Jones
-99. Phil Jackson
-100. Philip Rooke
-101. Pieter Praet
-102. Piotr Zielinski
-103. Puneeth Chaganti
-104. Rasmus Pank Roulund
-105. Richard Klinda
-106. Richard Riley
-107. Rick Frankel
-108. Russel Adams
-109. Ryo Takaishi
-110. Rüdiger Sonderfeld
-111. Sacha Chua
-112. Samuel Loury
-113. Sebastian Rose
-114. Sebastien Vauban
-115. Sergey Litvinov
-116. Seweryn Kokot
-117. Stephen Eglen
-118. Suvayu Ali
-119. T.F. Torrey
-120. Tassilo Horn
-121. Thierry Banel
-122. Thomas Baumann
-123. Thomas Holst
-124. Thomas S. Dye
-125. Thorsten Jolitz
-126. Tim Burt
-127. Toby Cubitt
-128. Tokuya Kameshima
-129. Tom Breton
-130. Tomas Hlavaty
-131. Tony Day
-132. Ulf Stegemann
-133. Vitalie Spinu
-134. Yann Hodique
-135. Yasushi Shoji
-136. Yoshinari Nomura
-137. Zhang Weize
+35. Dieter Schoen
+36. Dmitry Antipov
+37. Eric Abrahamsen
+38. Eric S. Fraga
+39. Eric Schulte
+40. Erik Iverson
+41. Ethan Ligon
+42. Feng Shu
+43. Francesco Pizzolante
+44. Gary Oberbrunner
+45. Georg Lehner
+46. George Kettleborough
+47. Giovanni Ridolfi
+48. Grégoire Jadi (aka Daimrod)
+49. Henning Dietmar Weiss
+50. Ian Barton
+51. Ian Kelling
+52. Ilya Shlyakhter
+53. Ippei Furuhashi
+54. James TD Smith
+55. Jan Böcker
+56. Jarmo Hurri
+57. Jason Riedy
+58. Jay Kerns
+59. Jeffrey Ryan Horn
+60. Joel Boehland
+61. John Kitchin
+62. John Wiegley
+63. Jonas Bernoulli
+64. Jonathan Leech-Pepin
+65. Juan Pechiar
+66. Julian Gehring
+67. Julien Barnier
+68. Julien Danjou
+69. Justin Gordon
+70. Justus Piater
+71. Kodi Arfer
+72. Konstantin Antipin
+73. Lawrence Mitchell
+74. Le Wang
+75. Lennart Borgman
+76. Leonard Avery Randall
+77. Luis Anaya
+78. Lukasz Stelmach
+79. Madan Ramakrishnan
+80. Magnus Henoch
+81. Manuel Giraud
+82. Martin Pohlack
+83. Martyn Jago
+84. Matt Lundin
+85. Max Mikhanosha
+86. Michael Albinus
+87. Michael Brand
+88. Michael Gauland
+89. Michael Sperber
+90. Miguel A. Figueroa-Villanueva
+91. Mikael Fornius
+92. Moritz Ulrich
+93. Nathan Neff
+94. Nicholas Dokos
+95. Nicolas Goaziou
+96. Nicolas Richard
+97. Niels Giessen
+98. Noorul Islam K M
+99. Oleh Krehel
+100. Paul Sexton
+101. Pedro Alexandre Marcelino Costa da Silva
+102. Peter Jones
+103. Phil Jackson
+104. Philip Rooke
+105. Pieter Praet
+106. Piotr Zielinski
+107. Puneeth Chaganti
+108. Rainer M Krug
+109. Rasmus Pank Roulund
+110. Richard Klinda
+111. Richard Riley
+112. Rick Frankel
+113. Russel Adams
+114. Ryo Takaishi
+115. Rüdiger Sonderfeld
+116. Sacha Chua
+117. Samuel Loury
+118. Sebastian Rose
+119. Sebastien Vauban
+120. Sergey Litvinov
+121. Seweryn Kokot
+122. Stephen Eglen
+123. Suvayu Ali
+124. T.F. Torrey
+125. Tassilo Horn
+126. Thierry Banel
+127. Thomas Baumann
+128. Thomas Holst
+129. Thomas S. Dye
+130. Thorsten Jolitz
+131. Tim Burt
+132. Toby Cubitt
+133. Tokuya Kameshima
+134. Tom Breton
+135. Tomas Hlavaty
+136. Tony Day
+137. Ulf Stegemann
+138. Vitalie Spinu
+139. Yann Hodique
+140. Yasushi Shoji
+141. Yoshinari Nomura
+142. Zhang Weize
+143. Zhuo Qingliang (Killy Draw)
 
 ** Processing
 
@@ -506,23 +512,26 @@ change lines.  Details are given in [[http://www.gnu.org/prep/maintain/maintain.
 2. Aurélien Aptel
 3. Brice Waegenire
 4. Craig Tanis
-5. Gustav Wikström
-6. Ivan Vilata i Balaguer
-7. Joe Hirn
-8. John Foerch
-9. Jonas Hörsch
-10. Joost Diepenmaat
-11. Kodi Arfer
-12. Miro Bezjak
-13. Muchenxuan Tong
-14. Myles English
-15. Rafael Laboissiere
-16. Richard Lawrence
-17. Robert P. Goldman
-18. Sylvain Chouleur
-19. Trevor Murphy
-20. Viktor Rosenfeld
-21. Vladimir Lomov
+5. Greg Tucker-Kellogg
+6. Gustav Wikström
+7. Ivan Vilata i Balaguer
+8. Joe Hirn
+9. John Foerch
+10. Jonas Hörsch
+11. Joost Diepenmaat
+12. Kodi Arfer
+13. Michael Weylandt
+14. Miro Bezjak
+15. Muchenxuan Tong
+16. Myles English
+17. Rafael Laboissiere
+18. Richard Lawrence
+19. Robert P. Goldman
+20. Sylvain Chouleur
+21. Trevor Murphy
+22. Viktor Rosenfeld
+23. Vladimir Lomov
+24. York Zhao
 
 (This list may be incomplete - please help completing it.)
 

+ 89 - 0
org-faq.org

@@ -3458,6 +3458,87 @@ Yes.  Vagn Johansen wrote [[http://ozymandias.dk/emacs/org-import-calendar.el][o
   :PROPERTIES:
   :CUSTOM_ID: Export
   :END:
+** How do I ignore a headline?
+   :PROPERTIES:
+   :CUSTOM_ID: ignoreheadline
+   :END:
+
+   This is one of the most common FAQs on the Org mailing list.  The
+   following export filter will allow headlines tagged =ignore= to be
+   ignored during export, while their contents and children headlines
+   are retained and children headlines are promoted to the level of
+   the original headline.  Alternately, a more in depth discussion
+   with a variety of alternate solutions is available in org-hacks
+   [[file:org-hacks.org::#ignoreheadline][here]].
+
+   #+begin_src emacs-lisp
+     ;; During export headlines which have the "ignore" tag are removed
+     ;; from the parse tree.  Their contents are retained (leading to a
+     ;; possibly invalid parse tree, which nevertheless appears to function
+     ;; correctly with most export backends) all children headlines are
+     ;; retained and are promoted to the level of the ignored parent
+     ;; headline.
+     ;;
+     ;; This makes it possible to add structure to the original Org-mode
+     ;; document which does not effect the exported version, such as in the
+     ;; following examples.
+     ;;
+     ;; Wrapping an abstract in a headline
+     ;;
+     ;;     * Abstract                        :ignore:
+     ;;     #+LaTeX: \begin{abstract}
+     ;;     #+HTML: <div id="abstract">
+     ;;
+     ;;     ...
+     ;;
+     ;;     #+HTML: </div>
+     ;;     #+LaTeX: \end{abstract}
+     ;;
+     ;; Placing References under a headline (using ox-bibtex in contrib)
+     ;;
+     ;;     * References                     :ignore:
+     ;;     #+BIBLIOGRAPHY: dissertation plain
+     ;;
+     ;; Inserting an appendix for LaTeX using the appendix package.
+     ;;
+     ;;     * Appendix                       :ignore:
+     ;;     #+LaTeX: \begin{appendices}
+     ;;     ** Reproduction
+     ;;     ...
+     ;;     ** Definitions
+     ;;     #+LaTeX: \end{appendices}
+     ;;
+     (defun org-export-ignore-headlines (data backend info)
+       "Remove headlines tagged \"ignore\" retaining contents and promoting children.
+     Each headline tagged \"ignore\" will be removed retaining its
+     contents and promoting any children headlines to the level of the
+     parent."
+       (org-element-map data 'headline
+         (lambda (object)
+           (when (member "ignore" (org-element-property :tags object))
+             (let ((level-top (org-element-property :level object))
+                   level-diff)
+               (mapc (lambda (el)
+                       ;; recursively promote all nested headlines
+                       (org-element-map el 'headline
+                         (lambda (el)
+                           (when (equal 'headline (org-element-type el))
+                             (unless level-diff
+                               (setq level-diff (- (org-element-property :level el)
+                                                   level-top)))
+                             (org-element-put-property el
+                               :level (- (org-element-property :level el)
+                                         level-diff)))))
+                       ;; insert back into parse tree
+                       (org-element-insert-before el object))
+                     (org-element-contents object)))
+             (org-element-extract-element object)))
+         info nil)
+       data)
+
+     (add-hook 'org-export-filter-parse-tree-functions 'org-export-ignore-headlines)
+   #+end_src
+
 ** My old beamer presentations does not look the same with =ox-beamer.el=
    :PROPERTIES:
    :CUSTOM_ID: beamer-backwards-incompatibility
@@ -4537,6 +4618,14 @@ please submit a bug report so that it can be fixed properly.
 See the "rather crude solution" posted in [[http://robert-adesam.blogspot.com/2011/07/orgmode-capture-to-insert-mairix-link.html][this blog entry]] by Robert
 Adesam.
 
+** Can I prevent ispell from checking source blocks?
+
+Yes, use this:
+
+#+BEGIN_SRC emacs-lisp
+(add-to-list 'ispell-skip-region-alist '("#\\+begin_src". "#\\+end_src"))
+#+END_SRC
+
 * Google Summer of Code (GSoC)
   :PROPERTIES:
   :CUSTOM_ID: GSoC

+ 165 - 117
org-hacks.org

@@ -2190,6 +2190,58 @@ security risk associated with completely disabling the prompting
 before you proceed.
 
 ** Exporting org files
+*** Ignoring headlines during export
+    :PROPERTIES:
+    :CUSTOM_ID: ignoreheadline
+    :END:
+#+index: Export!ignore headlines
+Sometimes users want to ignore the headline text during export like in
+the Beamer exporter (=ox-beamer=).  In the [[http://orgmode.org/manual/Beamer-export.html#Beamer-export][Beamer exporter]] one can use
+the tag =ignoreheading= to disable the export of a certain headline,
+whilst still retaining the content of the headline.  We can imitate
+this feature in other export backends.  Note that this is not a
+particularly easy problem, as the Org exporter creates a static
+representation of section numbers, table of contents etc.
+
+Consider the following document:
+#+BEGIN_SRC org
+  ,* head 1                    :noexport:
+  ,* head 2                    :ignoreheading:
+  ,* head 3
+  ,* =head 4=                  :ignoreheading:
+
+#+END_SRC
+We want to remove heading 2 and 4.
+
+There are different strategies to accomplish this:
+1. The best option is to remove headings tagged with =ignoreheading=
+   before export starts.  This can be accomplished with the hook
+   =org-export-before-parsing-hook= that runs before the buffer has
+   been parsed.  In the example above, however, =head 2= would not be
+   exported as it becomes part of =head 1= which is not exporter.  To
+   overcome this move perhaps =head 1= can be moved to the end of the
+   buffer.  An example of a hook that removes headings is before
+   parsing is available [[https://lists.gnu.org/archive/html/emacs-orgmode/2014-03/msg01459.html][here]].  Note, this solution is compatible with
+   /all/ export formats!
+2. The problem is simple when exporting to LaTeX, as the LaTeX
+   compiler determines numbers.  We can thus use
+   =org-export-filter-headline-functions= to remove the offending
+   headlines.  One regexp-based solution that looks for the word
+   =ignoreheading= is available on [[https://stackoverflow.com/questions/10295177/is-there-an-equivalent-of-org-modes-b-ignoreheading-for-non-beamer-documents][StackOverflow]] for both the legacy
+   exporter Org v7 exporter and the current Org v8 exporter.  Note,
+   however, that this filter will only work with LaTeX (numbering and
+   the table of content may break in other exporters).  In the example
+   above, this filer will work flawlessly in LaTeX, it will not work
+   at all in HTML and it will fail to update section numbers, TOC and
+   leave some auxiliary lines behind when exporting to plain text.
+3. Another solution that tries to recover the Org element
+   representation is available [[https://lists.gnu.org/archive/html/emacs-orgmode/2014-03/msg01480.html][here]].  In the example above this filter
+   will not remove =head 4= exporting to any backend, since verbatim
+   strings do not retain the Org element representation.  It will
+   remove the extra heading line when exporting to plain text, but
+   will also fail to update section numbers.  It should be fairly
+   simple to also make it work with HTML.
+
 *** Export Org to Org and handle includes.
 #+index: Export!handle includes
 Nick Dokos came up with this useful function:
@@ -3060,8 +3112,8 @@ See the relevant discussion [[http://thread.gmane.org/gmane.emacs.orgmode/58715/
 
 ** poporg.el: edit comments in org-mode
 
-[[https://github.com/pinard/PopOrg/blob/master/poporg.el][poporg.el]] is a library by François Pinard which lets you edit comments
-from your code using a separate org-mode buffer.
+[[https://github.com/QBobWatson/poporg/blob/master/poporg.el][poporg.el]] is a library by François Pinard which lets you edit comments
+and strings from your code using a separate org-mode buffer.
 
 ** Convert a .csv file to an Org-mode table
 
@@ -3430,7 +3482,7 @@ Using hooks and on the fly
   leading stars for headings.
 
 To change the file format just add or remove the keyword in the
-=#+STARTUP:= line in the Org buffer and save.
+~#+STARTUP:~ line in the Org buffer and save.
 
 Now you can also change to Fundamental mode to see how the file looks
 like on the level of the file, can go back to Org mode, reenter Org
@@ -3446,12 +3498,12 @@ whenever necessary.
 This is like "a cleaner outline view":
 http://orgmode.org/manual/Clean-view.html
 
-Example of the _file content_ first with leading stars as usual and
-below without leading stars through =#+STARTUP: odd hidestars
-hidestarsfile=:
+Example of the *file content* first with leading stars as usual and
+below without leading stars through ~#+STARTUP: odd hidestars
+hidestarsfile~:
 
-#+BEGIN_EXAMPLE
-  #+STARTUP: odd hidestars
+#+BEGIN_SRC org
+  ,#+STARTUP: odd hidestars
   [...]
   ***** TODO section
   ******* subsection
@@ -3460,10 +3512,10 @@ hidestarsfile=:
   ***** section
         - bla bla
   ******* subsection
-#+END_EXAMPLE
+#+END_SRC
 
-#+BEGIN_EXAMPLE
-  #+STARTUP: odd hidestars hidestarsfile
+#+BEGIN_SRC org
+  ,#+STARTUP: odd hidestars hidestarsfile
   [...]
       * TODO section
         * subsection
@@ -3472,21 +3524,21 @@ hidestarsfile=:
       * section
         - bla bla
         * subsection
-#+END_EXAMPLE
+#+END_SRC
 
 The latter is convenient for better human readability when an Org file,
 additionally to Emacs, is read with a file viewer or, for smaller edits,
 with an editor not capable of the Org file format.
 
-=hidestarsfile= is a hack and can not become part of the Org core:
-- An Org file with =hidestarsfile= can not contain list items with a
+~hidestarsfile~ is a hack and can not become part of the Org core:
+- An Org file with ~hidestarsfile~ can not contain list items with a
   star as bullet due to the syntax conflict at read time. Mark
   E. Shoulson suggested to use the non-breaking space which is now
-  implemented in fileconversion as =nbspstarsfile= as an alternative
-  for =hidestarsfile=. Although I don't recommend it because an editor
+  implemented in fileconversion as ~nbspstarsfile~ as an alternative
+  for ~hidestarsfile~. Although I don't recommend it because an editor
   like typically e. g. Emacs may render the non-breaking space
-  differently from the space =0x20=.
-- An Org file with =hidestarsfile= can almost not be edited with an
+  differently from the space ~0x20~.
+- An Org file with ~hidestarsfile~ can almost not be edited with an
   Org mode without added functionality of hidestarsfile as long as the
   file is not converted back.
 
@@ -3496,15 +3548,15 @@ with an editor not capable of the Org file format.
     :END:
 #+index: Conversion!fileconversion markdownstarsfile
 
-Together with =oddeven= you can use =markdownstarsfile= to be readable
+Together with ~oddeven~ you can use ~markdownstarsfile~ to be readable
 or even basically editable with Markdown (does not make much sense
-with =odd=, see =org-convert-to-odd-levels= and
-=org-convert-to-oddeven-levels= for how to convert).
+with ~odd~, see ~org-convert-to-odd-levels~ and
+~org-convert-to-oddeven-levels~ for how to convert).
 
-Example of the _file content_:
+Example of the *file content*:
 
-#+BEGIN_EXAMPLE
-  #+STARTUP: oddeven markdownstarsfile
+#+BEGIN_SRC org
+  ,#+STARTUP: oddeven markdownstarsfile
   # section level 1
     1. first item of numbered list (same format in Org and Markdown)
   ## section level 2
@@ -3514,10 +3566,10 @@ Example of the _file content_:
   #### section level 4
        * first item of unordered list (same format in Org and Markdown)
        * avoid this item type to be compatible with Org hidestarsfile
-#+END_EXAMPLE
+#+END_SRC
 
-An Org file with =markdownstarsfile= can not contain code comment
-lines prefixed with =#=, even not when within source blocks.
+An Org file with ~markdownstarsfile~ can not contain code comment
+lines prefixed with ~#~, even not when within source blocks.
 
 *** emacs-lisp code
     :PROPERTIES:
@@ -3526,177 +3578,174 @@ lines prefixed with =#=, even not when within source blocks.
 #+index: Conversion!fileconversion emacs-lisp code
 
 #+BEGIN_SRC emacs-lisp
-  ;; - fileconversion version 0.8
-  ;; - DISCLAIMER: Make a backup of your Org files before using
-  ;;   f-org-fileconv-*.
-  ;; - supported #+STARTUP: formats: hidestarsfile, nbspstarsfile,
-  ;;   markdownstarsfile
-
-  ;; design summary: fileconversion is a round robin of two states
-  ;; linked by two actions:
-  ;; - state v-org-fileconv-level-org-p is nil: the level is “file”
-  ;;   (encoded)
-  ;; - action f-org-fileconv-decode: replace file char with “*”
-  ;; - state v-org-fileconv-level-org-p is t: the level is “Org”
-  ;;   (decoded)
-  ;; - action f-org-fileconv-encode: replace “*” with file char
-  ;; naming convention of prefix:
-  ;; - f-[...]: “my function”, instead of the unspecific prefix “my-”
-  ;; - v-[...]: “my variable”, instead of the unspecific prefix “my-”
+  ;; - fileconversion version 0.10
+  ;; - DISCLAIMER: Make a backup of your Org files before trying
+  ;;   `f-org-fileconv-*'. It is recommended to use a version control
+  ;;   system like git and to review and commit the changes in the Org
+  ;;   files regularly.
+  ;; - Supported "#+STARTUP:" formats: "hidestarsfile",
+  ;;   "nbspstarsfile", "markdownstarsfile".
+
+  ;; Design summary: fileconversion is a round robin of two states linked by
+  ;; two actions:
+  ;; - State `v-org-fileconv-level-org-p' is nil: The level is "file"
+  ;;   (encoded).
+  ;; - Action `f-org-fileconv-decode': Replace file char with "*".
+  ;; - State `v-org-fileconv-level-org-p' is non-nil: The level is "Org"
+  ;;   (decoded).
+  ;; - Action `f-org-fileconv-encode': Replace "*" with file char.
+  ;;
+  ;; Naming convention of prefix:
+  ;; - f-[...]: "my function", instead of the unspecific prefix `my-*'.
+  ;; - v-[...]: "my variable", instead of the unspecific prefix `my-*'.
 
   (defvar v-org-fileconv-level-org-p nil
     "Whether level of buffer is Org or only file.
-  nil means the level is file (encoded), non-nil means the level is
-  Org (decoded).")
+  nil: level is file (encoded), non-nil: level is Org (decoded).")
   (make-variable-buffer-local 'v-org-fileconv-level-org-p)
-  ;; survive a change of major mode that does kill-all-local-variables,
-  ;; e. g. when reentering Org mode through “C-c C-c” on a STARTUP line
+  ;; Survive a change of major mode that does `kill-all-local-variables', e.
+  ;; g. when reentering Org mode through "C-c C-c" on a #+STARTUP: line.
   (put 'v-org-fileconv-level-org-p 'permanent-local t)
 
-  (defadvice org-mode (before advice-org-mode-before)
+  ;; * Callback `f-org-fileconv-org-mode-beg' before `org-mode'
+  (defadvice org-mode (before org-mode-advice-before-fileconv)
     (f-org-fileconv-org-mode-beg))
   (ad-activate 'org-mode)
   (defun f-org-fileconv-org-mode-beg ()
-    (interactive)
-    ;; only when converting really from/to an Org _file_, not e. g. for
-    ;; a temp Org buffer unrelated to a file
-    (when (buffer-file-name)
-      (message "INF: buffer %s: f-org-fileconv-org-mode-beg"
-               (buffer-name))
-      ;; f-org-fileconv-decode in org-mode-hook would be too late for
-      ;; performance reasons, see
-      ;; http://lists.gnu.org/archive/html/emacs-orgmode/2013-11/msg00920.html
-      (f-org-fileconv-decode)))
-
+    ;; - Reason to test `buffer-file-name': Only when converting really
+    ;;   from/to an Org _file_, not e. g. for a temp Org buffer unrelated to a
+    ;;   file.
+    ;; - No `message' to not wipe a possible "File mode specification error:".
+    ;; - `f-org-fileconv-decode' in org-mode-hook would be too late for
+    ;;   performance reasons, see
+    ;;   http://lists.gnu.org/archive/html/emacs-orgmode/2013-11/msg00920.html
+    (when (buffer-file-name) (f-org-fileconv-decode)))
+
+  ;; * Callback `f-org-fileconv-org-mode-end' after `org-mode'
   (add-hook 'org-mode-hook 'f-org-fileconv-org-mode-end
-            nil   ; _prepend_ to hook to have it first
-            nil)  ; hook addition globally
+            nil   ; _Prepend_ to hook to have it first.
+            nil)  ; Hook addition global.
   (defun f-org-fileconv-org-mode-end ()
-    (interactive)
-    ;; only when converting really from/to an Org _file_, not e. g. for
-    ;; a temp Org buffer unrelated to a file
+    ;; - Reason to test `buffer-file-name': only when converting really
+    ;;   from/to an Org _file_, not e. g. for a temp Org buffer unrelated to a
+    ;;   file.
+    ;; - No `message' to not wipe a possible "File mode specification error:".
     (when (buffer-file-name)
-      (message "INF: buffer %s: f-org-fileconv-org-mode-end"
-               (buffer-name))
-      ;; - the hooks are not permanent-local, this way and as needed
-      ;;   they will disappear when the major mode of the buffer changes
-      ;; - adding to change-major-mode-hook in "defadvice before" would
-      ;;   be too early and already trigger during find-file
-      ;; - t at the end: hook addition limited to buffer locally
+      ;; - Adding this to `change-major-mode-hook' or "defadvice before" of
+      ;;   org-mode would be too early and already trigger during find-file.
+      ;; - Argument 4: t to limit hook addition to buffer locally, this way
+      ;;   and as required the hook addition will disappear when the major
+      ;;   mode of the buffer changes.
       (add-hook 'change-major-mode-hook 'f-org-fileconv-encode nil t)
       (add-hook 'before-save-hook       'f-org-fileconv-encode nil t)
       (add-hook 'after-save-hook        'f-org-fileconv-decode nil t)))
 
   (defun f-org-fileconv-re ()
-    "Check whether there is a STARTUP line for fileconversion.
+    "Check whether there is a #+STARTUP: line for fileconversion.
   If found then return the expressions required for the conversion."
     (save-excursion
-      (goto-char (point-min))  ; beginning-of-buffer not allowed
+      (goto-char (point-min))  ; `beginning-of-buffer' is not allowed.
       (let (re-list (count 0))
-        (while (re-search-forward "^#\\+STARTUP:" nil t)
+        (while (re-search-forward "^[ \t]*#\\+STARTUP:" nil t)
           ;; #+STARTUP: hidestarsfile
-          (when (string-match-p "\\bhidestarsfile\\b"
-                                (thing-at-point 'line))
-            ;; exclude e. g.:
-            ;; - line starting with star for bold emphasis
-            ;; - line of stars to underline section title in loosely
-            ;;   quoted ASCII style (star at end of line)
+          (when (string-match-p "\\bhidestarsfile\\b" (thing-at-point 'line))
+            ;; Exclude e. g.:
+            ;; - Line starting with star for bold emphasis.
+            ;; - Line of stars to underline section title in loosely quoted
+            ;;   ASCII style (star at end of line).
             (setq re-list '("\\(\\* \\)"  ; common-re
                             ?\ ))         ; file-char
             (setq count (1+ count)))
           ;; #+STARTUP: nbspstarsfile
-          (when (string-match-p "\\bnbspstarsfile\\b"
-                                (thing-at-point 'line))
+          (when (string-match-p "\\bnbspstarsfile\\b" (thing-at-point 'line))
             (setq re-list '("\\(\\* \\)"  ; common-re
                             ?\xa0))       ; file-char non-breaking space
             (setq count (1+ count)))
           ;; #+STARTUP: markdownstarsfile
           (when (string-match-p "\\bmarkdownstarsfile\\b"
                                 (thing-at-point 'line))
-            ;; exclude e. g.:
-            ;; - #STARTUP:
+            ;; Exclude e. g. "#STARTUP:".
             (setq re-list '("\\( \\)"  ; common-re
                             ?#))       ; file-char
             (setq count (1+ count))))
-        (when (> count 1)
-          (error "More than one fileconversion found"))
+        (when (> count 1) (error "More than one fileconversion found."))
         re-list)))
 
   (defun f-org-fileconv-decode ()
     "In headings replace file char with '*'."
     (let ((re-list (f-org-fileconv-re)))
       (when (and re-list (not v-org-fileconv-level-org-p))
-        ;; no `save-excursion' to be able to keep point in case of error
+        ;; No `save-excursion' to be able to keep point in case of error.
         (let* ((common-re (nth 0 re-list))
                (file-char (nth 1 re-list))
                (file-re   (concat "^" (string file-char) "+" common-re))
                (org-re    (concat "^\\*+" common-re))
                len
                (p         (point)))
-          (goto-char (point-min))  ; beginning-of-buffer not allowed
-          ;; syntax check
+