Literate DevOps: My OS X Development System

Setting up a development system is a non-trivial investment.

This document captures the steps required and automates as much as possible. The project has other formats, too.

The Style Guide is a must read for the operator.

Org-Mode converted this manual, tedious, and error prone task to a semi-automated, nearly reproducible, and error-less process, for me. This document has never been beta tested; I am it’s only user.

org-scraps Notes 30D36486-3578-4C0D-B16F-CE89A283358A

  • catch the file name during export
    • Code block specific header arguments are evaluated before execution of the source block. The arguments seem to be symbols, strings, or Emacs-Lisp SEXPs.
    • Here is an example of an inline source block that gets the name of this file and returns it: "/Users/gcr/tmp/scratch.org"
    • Using Emacs-Lisp in header arguments introduces great flexibility.
  • export of inline code blocks which are silent
    • Configure a document so that results are included in the document if it is being exported. This is a dynamic decision. It probably relies on org-export-current-backend now. Another example of Elisp configuring a header arg.
  • mentions of file names in file contents
    • Literate example using table defintions, sh, find, and dot.
    • An example that demonstrates a lot with a little.
  • inline code block
    • Develop a philosophy of what to evaluate and when.
    • They are as easy as 6 .
  • recutils
    • Great example of using output to a file and a file as input via header args.
    • Demonstrate usage of Recutils.
  • SQL — example reading org-mode table into sql
    • Show how Org-Mode Table data is converted to SQL data.
    • This is the essence of how data is brokered in the “BabelVM”.

org-scraps Notes 6CBD47FB-80AD-41DC-9E0C-482FE1C230E6

  • About
    • org-scraps is a collection of Org-Mode demonstrations published by Eric Schulte. All of my experience with Org-Mode Literate Programming is working on my Emacs configuration for Literate Programming. Wanting to address my limited experience I am working through each example in org-scraps. Org-Scraps is weaved to HTML files published here.
  • Approach
    • Evaluate each example.
    • Verify identical result.
    • Update notes on approach.
    • After every reconfiguration re-evaluate DONE examples to verify identical result.
    • Scraps are under-documented. Important ideas are explored often without explicit mention. Sometimes it is obvious; other times not.
  • simple short R block
    • “value table org replace” is probably the best :results configuration for source blocks. Replace table with scalar for in-line source blocks.
  • two blocks and a table
    • Programmatically create tables with org-sbe and #+TBLFM.
  • a table with tags
    • Special blocks like TBLNAME are taggable, for example with :noexport:.
  • shell script output not in table
    • Evaluating a sh SB generates a table with the captured output from echo, with 1 row for each call.
    • Scalar output demands replaceable formatting.
  • space around exported code blocks
    • org-babel-remove-result works no matter where the RESULT block is located. It doesn’t have to immediately follow the Source-Block.
  • scheme sessions
    • ob-scheme allows two sessions with the same name when they were started with different interpreters.

Org2Blog DITAA Test

+--------+   +-------+    +-------+
|        | --+ ditaa +--> |       |
|  Text  |   +-------+    |diagram|
|Document|   |!magic!|    |       |
|     {d}|   |       |    |       |
+---+----+   +-------+    +-------+
    :                         ^
    |       Lots of work      |
    +-------------------------+

0AE23A91-0184-4D16-93F8-8A7D73A6B3E2.png

The test succeeded by turning off thumbnail images.

Migrating to Org2Blog

WordPress is a powerful and satisfying writing and publishing platform. After learning Org-Mode, I wanted to use Org-Mode for writing and WordPress for publishing. Org2Blog makes that easy.

WordPress easily exports your posts to XML. Org2Blog-Importers converts them to Org-Mode via Pandoc. Tonight I converted them here. Any future modifications belong in these documents with publishing to WordPress.

I tested both publishing new posts and modifying and re-publishing old posts and both worked correctly.

How to reintegrate changes for Word back into Org-Mode

Via:

From:   Ken Mankoff
Subject:  Re: [O] Organizing and taming hectic Academia work (faculty   viewpoint)? Tips or a good guides sought after :)
Date:   Fri, 12 Jun 2015 10:02:50 -0400
Hi Julian,
On 2015-06-10 at 10:16, Julian Burgos <address@hidden> wrote:
> a) I first write in org-mode. Export to Word, either exporting first
> to ODT and then to Word, or to LaTex and then use pandoc to convert
> LaTex to Word. My coauthor can edit the document as he wishes, using
> the "Track changes" option. Then, I transcribe their edits back into
> the org-mode document. Advantage of this approach: your coauthor
> receives a clean word file, that could include figures, references,
> etc., and he/she uses the tools she likes to edit the file.
> Disadvantage: you have to manually incorporate the changes to the
> org-mode file each time there are edits.
>
> b) I write the manuscript in org-mode. Then I send the org-mode file
> to my coauthor. Because the org-mode file is just a text file, my
> coauthor can use Word to edit it. I ask him/her *not* to use "track
> changes" and to save the edited version also as a text file. Then,
> when I receive it I use ediff in emacs to compare both documents and
> incorporate the edits I want. Advantage of this approach: the merging
> of the documents is easy using ediff. Disadvantage: your coauthor has
> to edit a weird-looking document, with markup, code blocks, etc.
It seems like with a bit of extra (scriptable?) work you could remove both
disadvantages.
Why can't you use method (a) above, and then DOCX -> Org via pandoc (with
--accept-all option)?
I know pandoc introduce some of its own changes to the Org syntax but not the
document itself. You can get around this. You can remove the pandoc-generated
changes automagically so that only co-author changes appear in Org format,
which you can then use with your (b) above and emacs ediff.
Original: Your Org source
A: Org -> DOCX for co-authors (using pandoc)
B: Org -> DOCX -> Org (using pandoc).
C: A -> Org (using pandoc and --accept-all-changes)
D: B-Original
The difference between B and Original are pandoc-introduced changes that you do
not want. Ignore/remove these changes from C, call it D and then the difference
between D and the Original are your co-author comments. Now your authors can
edit DOCX with Track Changes and you can work on those edits with Emacs ediff.
  -k.