Re: Portable formatting of export?

[tsd@tsdye.com (Thomas S. Dye)]

Aloha Klaus,

IIUC, you are describing a setup that can also be described as
reproducible research. The idea behind reproducible research is to have
a stand-alone Org file that exactly reproduces the analysis reported in
a scientific paper, then prepares a copy of the document submitted for
publication. The Org file is meant to be distributed and so must be
capable of carrying out these tasks on any Emacs, regardless of the
end-user's setup.

It was possible to do this with Org mode < 8.0, but with version 8.0 and
the new exporter framework, the approach changed and became somewhat
easier to accomplish. The key change was asynchronous export, which
internalized a mechanism for launching a new emacs process (the famous
emacs -q) that is responsible for export. A reproducible research paper
finds a way to configure asynchronous export that can be saved in the
Org file and distributed as part of the reproducible research.

One way to do this is with a babel emacs-lisp source code block that
contains the necessary configuration and that the end-user can tangle to
an initialization file that is read by the asynchronous export process.

My own work is geared to producing pdf files and I haven't worked much
with html, though I imagine the process would be similar.

Below, I've included an init file in progress--one that works for me,
but isn't yet fully reproducible, at least because paths are hard-coded
and I haven't yet spent the time to make them fully portable.  My goal
with this init file is to meet a specification established by the
journal PLOS-One, so I've had to abandon the default packages used by
Org and load the packages specified by the journal.

The noweb parts implement editing conventions that I use, but aren't
strictly necessary for the reproducible research.

In practice, the user tangles the initialization file in preparation for
asynchronous export. For convenience, in a no-export section at the top
of the file, I have:

  #+call: tangle-init-file()

  ** Export setup  :noexport:

  #+name: tangle-init-file
  #+header: :results silent
  #+begin_src emacs-lisp
  (org-babel-tangle)
  #+end_src

  #+name: export-setup-plos-one
  #+header: :noweb yes
  #+header: :results silent
  #+header: :tangle init-plos.el
  #+begin_src emacs-lisp
      (setq load-path (cons "~/.emacs.d/src/org-mode/lisp" load-path))
      (require 'ox-latex)
      (org-babel-lob-ingest "~/org/td-lob.org")
      (setq org-confirm-babel-evaluate nil)
      (org-babel-do-load-languages
       'org-babel-load-languages
       '((R . t)
         (dot . t)
         (emacs-lisp . t)
         (latex . t)
         (org . t)
         (sh . t)))
      <<user-entities>>
      (setq org-latex-packages-alist nil)
      (add-to-list 'org-latex-packages-alist '("" "setspace"))
      (add-to-list 'org-latex-packages-alist '("" "amsmath"))
      (add-to-list 'org-latex-packages-alist '("" "amssymb"))
      (add-to-list 'org-latex-packages-alist '("" "graphicx"))
      (add-to-list 'org-latex-packages-alist '("" "cite"))
      (add-to-list 'org-latex-packages-alist '("" "color"))
      (add-to-list 'org-latex-packages-alist '("" "setspace"))
      (add-to-list 'org-latex-packages-alist '("labelfont=bf,labelsep=period,justification=raggedright" "caption"))
      (setq org-latex-pdf-process '("latexmk -pdf %f"))
      (setq org-latex-tables-booktabs nil)
      (setq org-latex-title-command nil)
      (setq org-latex-remove-logfiles nil)
      (setq org-latex-toc-command "\\tableofcontents\n\n")
      (setq org-latex-classes nil)
      (add-to-list 'org-latex-classes
                   '("plos-article"
                     "\\documentclass[10pt]{article}
    [NO-DEFAULT-PACKAGES]
    [PACKAGES]
    [EXTRA]
    \\doublespacing
    % Text layout
    \\topmargin 0.0cm
    \\oddsidemargin 0.5cm
    \\evensidemargin 0.5cm
    \\textwidth 16cm 
    \\textheight 21cm
    \\bibliographystyle{plos2009}
    \\makeatletter
    \\renewcommand{\\@biblabel}[1]{\\quad#1.}
    \\makeatother
    \\pagestyle{myheadings}
    %% ** EDIT HERE **


    %% ** EDIT HERE **
    %% PLEASE INCLUDE ALL MACROS BELOW
    \\newcommand{\\texttwosuperior}{$^{2}$}
    \\newcommand{\\textpm}{$\\pm$}
    \\newcommand{\\rc}{$^{14}C$}
    %% END MACROS SECTION"
                     ("\\section{%s}" . "\\section*{%s}")
                     ("\\subsection{%s}" . "\\subsection*{%s}")
                     ("\\subsubsection{%s}" . "\\subsubsection*{%s}")
                     ("\\paragraph{%s}" . "\\paragraph*{%s}")
                     ("\\subparagraph{%s}" . "\\subparagraph*{%s}")))
      <<ngz-nbsp>>
      <<tsd-textpm>>
      <<define-cite-link>>
  #+end_src

It is also necessary to set up the end-user's Emacs instance somewhat,
although this is intrusive and leaves the user with a different Emacs
instance, and one that might not be wanted.  I want this part to be as
minimal as possible, so eventually will work to move as much of this as
possible to file-local variables along the lines suggested by Eric
Schulte earlier in this thread.

The one I'm working with at the moment looks like this:

  ** Editing setup   :noexport:
  #+name: editing-setup
  #+header: :noweb yes
  #+header: :results silent
  #+begin_src emacs-lisp
    (require 'ox-latex)
    (setq org-export-in-background t)
    (setq org-export-async-debug t)
    (setq org-export-async-init-file (expand-file-name "init-plos.el"))
    (setq org-fontify-quote-and-verse-blocks t)
    <<user-entities>>
    <<define-cite-link>>
  #+end_src

The user executes this emacs-lisp source block before exporting. I like
to have a line like this in a no-export section near the top of the
file:

  #+call: editing-setup()

In theory, the export then happens like magic.  At this stage, it works
locally :)

When I have this one fully worked out, and PLOS-One has accepted my
paper for review (which will prove the setup works to specification), I
intend to package up a PLOS-One template so Org mode users can write for
the journal without worrying about configuration.

hth,
Tom

Klaus-Dieter Bauer <bauer.klaus.dieter@gmail.com>
writes:

> There are several problems with this approach:
>
> 1. In order to force default behaviour, I'd have to set ALL customization
> variables of org explicitly (can be avoided by using an "emacs -q" session
> for compiling).
> 2. Even setting just a single setting can be very verbose (e.g. when
> defining a new document class).
> 3. The variables are not flagged as safe for use as file-local variables,
> requiring extra user-interaction whenever the file is visited.
>
> Sure, those are all mere convenience issues, but they add up to enough
> potential inconvenience for cooperative authoring (i.e. the file being
> edited in different emacs configurations by different people) to make
> direct latex editing rather attractive.
>
> Is that scenario simply outside the scope of org-mode?
>
> - Klaus-Dieter Bauer
>
>
>
> 2013/10/21 Eric Schulte <schulte.eric@gmail.com>
>
>> This can be done with file local variables.  See the following page of
>> the Emacs manual.
>>
>>   (info "(emacs)Specifying File Variables")
>>
>> Klaus-Dieter Bauer <bauer.klaus.dieter@gmail.com> writes:
>>
>> > Hello!
>> >
>> > I have customized org export to both html and latex extensively since I
>> > disliked many of the defaults (e.g. the use of article vs scrartcl, red
>> > borders around pdf hyperlinks).
>> >
>> > This left me wondering however, if it is possible to create org files
>> that
>> > will produce the same output on every machine, regardless of the local
>> > emacs customizations (of course assuming that no hacks of the export
>> engine
>> > are part of the configuration).
>> >
>> > In order to make the files more portable I have been trying to make
>> changes
>> > affecting export with things like #+LATEX_HEADER: but e.g. changing the
>> > documentclass to scrartcl seems to be possible only by changing a
>> > customization variable (org-latex-classes).
>> >
>> > Is it possible to make the export engine assume defaults for all
>> > customization variables for a file (preferably through an in-file
>> setting)
>> > and to specify those customization inside the file?
>> >
>> > - Klaus
>>
>> --
>> Eric Schulte
>> https://cs.unm.edu/~eschulte
>> PGP: 0x614CA05D
>>
> There are several problems with this approach:
>
> 1. In order to force default behaviour, I'd have to set ALL
> customization variables of org explicitly (can be avoided by using an
> "emacs -q" session for compiling). 
> 2. Even setting just a single setting can be very verbose (e.g. when
> defining a new document class). 
> 3. The variables are not flagged as safe for use as file-local
> variables, requiring extra user-interaction whenever the file is
> visited.
>
> Sure, those are all mere convenience issues, but they add up to enough
> potential inconvenience for cooperative authoring (i.e. the file being
> edited in different emacs configurations by different people) to make
> direct latex editing rather attractive. 
>
> Is that scenario simply outside the scope of org-mode?
>
> - Klaus-Dieter Bauer 
>
> 2013/10/21 Eric Schulte <schulte.eric@gmail.com>
>
>     This can be done with file local variables. See the following page
>     of
>     the Emacs manual.
>     
>     (info "(emacs)Specifying File Variables")
>     
>     
>     
>     Klaus-Dieter Bauer <bauer.klaus.dieter@gmail.com> writes:
>     
>     > Hello!
>     >
>     > I have customized org export to both html and latex extensively
>     since I
>     > disliked many of the defaults (e.g. the use of article vs
>     scrartcl, red
>     > borders around pdf hyperlinks).
>     >
>     > This left me wondering however, if it is possible to create org
>     files that
>     > will produce the same output on every machine, regardless of the
>     local
>     > emacs customizations (of course assuming that no hacks of the
>     export engine
>     > are part of the configuration).
>     >
>     > In order to make the files more portable I have been trying to
>     make changes
>     > affecting export with things like #+LATEX_HEADER: but e.g.
>     changing the
>     > documentclass to scrartcl seems to be possible only by changing
>     a
>     > customization variable (org-latex-classes).
>     >
>     > Is it possible to make the export engine assume defaults for all
>     > customization variables for a file (preferably through an
>     in-file setting)
>     > and to specify those customization inside the file?
>     >
>     > - Klaus
>     
>     
>     --
>     Eric Schulte
>     https://cs.unm.edu/~eschulte
>     PGP: 0x614CA05D
>
>

-- 
Thomas S. Dye
http://www.tsdye.com