Portable formatting of export?

Portable formatting of export?

[Klaus-Dieter Bauer]

[-- Attachment #1: Type: text/plain, Size: 900 bytes --]

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

[-- Attachment #2: Type: text/html, Size: 1062 bytes --]

Re: Portable formatting of export?

[Eric Schulte]

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

Re: Portable formatting of export?

[Rasmus]

Hi Klaus,

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

> 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).

The authority on fully reproducible exports on this list is 
Thomas S. Dye.   You might be able to find his posts searching 
for "Aloha".  I believe he has a per-project .el file with settings.

You could also have settings in a Babel emacs-lisp block.  I do that
sometimes.  Then use e.g. org-babel-load-file.

> 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).

Customizatoins through org-latex-classes are a lot more comfortable
than adding all those LaTeX headers IMO.

> 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?

Yes.

And you can always check that it works as expected with emacs -q.

–Rasmus

-- 
May the Force be with you

Re: Portable formatting of export?

[Klaus-Dieter Bauer]

[-- Attachment #1: Type: text/plain, Size: 2100 bytes --]

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
>

[-- Attachment #2: Type: text/html, Size: 2956 bytes --]

Re: Portable formatting of export?

[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