literate-programming-tutorials/how-to/00-convert-latex-template-into-org-mode-template/how-to-migrate-latex-template-into-org-mode.org at master

mirror of https://github.com/vale981/literate-programming-tutorials synced 2025-03-04 17:31:39 -05:00

melioratus a2259db48a Spelling

2019-01-06 10:35:53 -07:00

91 KiB

Raw Permalink Blame History

Summary

This How-To tutorial provides a step by step guide on how to migrate¹ the LaTeX template provided by an academic journal into org-mode syntax.

Instructions

To complete this tutorial successfully, please follow all steps in the order presented of each section listed below:

Requirements
Create New org-mode File
Download LaTeX Template
Migrate LaTeX Template Code into file variables
Migrate LaTeX Template Code into SRC blocks
Customize a SRC block using Literate Programming
Add Content to org-mode File
Export completed org-mode file as PDF

Requirements

Note: All the requirements must be completed successfully before continuing with the steps in this How-To tutorial.

Instructions

Download, Install, and Configure LaTeX Software Unfortunately, this requirement is beyond the scope of this How-To tutorial.
Download, Install, and Configure Emacs Software Unfortunately, this requirement is beyond the scope of this How-To tutorial.
Download, Install, and Configure org-mode Software

Note: The org-mode application is already installed if you are using a recent version of Emacs, i.e. versions 25 or greater.

Unfortunately, this requirement is beyond the scope of this How-To tutorial.
Export an org-mode file as PDF via built-in LaTeX exporter.
TIP: To export an org-mode document to PDF:
1. Open the org-mode file in Emacs.
2. Position the cursor in the buffer of the org-mode document in Emacs.
3. Press the following key chords and keys, C-c C-e l p to initiate the export process.
4. Open the exported PDF file to validate the export process succeeded.
If exporting an org-mode file to PDF succeeded then continue following the steps in this How-To tutorial. Otherwise troubleshoot each step in the requirements section and repeat until exporting an org-mode document to PDF is successful.

Create New org-mode File

Instructions

Create a new org-mode file using Emacs.

For this tutorial, the filename will be journal-template.org
- To create the file in Emacs do the following:
  1. Press the key chords C-x C-f
  2. Type journal-template.org
  3. Press Return or Enter key

Add mode line to top of the file.

  # -*- mode: org; org-confirm-babel-evaluate: nil; org-babel-noweb-wrap-start: "«"; org-babel-noweb-wrap-end: "»"; -*-

TIP: To insert « press key chord C-x 8 < and to insert » press key chord C-x 8 >

Add Template Utility Code Section to end of file.

  * Template Utility Code                                            :noexport:

Add Common Export Settings Section to end of the file.

  * Common Export Settings                                           :noexport:

  #+OPTIONS: ':nil *:t -:t ::t <:nil H:4 \n:nil ^:{} arch:headline
  #+OPTIONS: author:nil broken-links:nil c:nil creator:nil
  #+OPTIONS: d:(not "LOGBOOK") date:nil e:t email:nil f:t inline:t num:nil
  #+OPTIONS: p:nil pri:nil prop:t stat:nil tags:t tasks:nil tex:t
  #+OPTIONS: timestamp:nil title:nil toc:nil todo:nil |:t
  #+SELECT_TAGS: export
  #+EXCLUDE_TAGS: noexport nolatex

  # For Display when file is exported with org-ruby 

  #+EXPORT_SELECT_TAGS: export
  #+EXPORT_EXCLUDE_TAGS: noexport

Save the file in Emacs.
- To save the file in Emacs do the following:
  1. Press the key chords C-x C-s

Self Check - Example 1

After completing the instructions in this section, the contents of journal-template.org should be similar to self-check-example-01.org.

Download LaTeX Template

For this How-To tutorial, the LaTeX template² provided by the European Physical Journal A (EPJ A)³ will be used.

The following 3 files provided by the EPJ A will be needed in this tutorial:

template.tex The template.tex file is provided as "[a] fill-in-form for a standard article with usage comments"⁴. The objective of this How-To tutorial is migrate LaTeX code from template.tex into the new org-mode file.
svepj.clo The svepj.clo is the LaTeX "[c]lass option file for The European Physical Journal"⁵.
svjour.cls The svjour.cls is the LaTeX "[c]ore document class file for Springer journals"⁶.

Instructions

Download template.tex file into same directory as journal-template.org.
Download svepj.clo file into same directory as journal-template.org.
Download svjour.cls file into same directory as journal-template.org.

Migrate LaTeX Template Code into `file variables`

In this section, the objective is migrate⁷⁸ LaTeX code from LaTeX template into file variables syntax at the bottom of the org-mode file. The file variables will be used when exporting from org-mode back to LaTeX.

The LaTeX code that will be migrated into file variables syntax is located near the top of template.tex file:

%
\begin{filecontents}{leer.eps}
%!PS-Adobe-2.0 EPSF-2.0
%%CreationDate: Mon Jul 13 16:51:17 1992
%%DocumentFonts: (atend)
%%Pages: 0 1
%%BoundingBox: 72 31 601 342
%%EndComments

gsave
72 31 moveto
72 342 lineto
601 342 lineto
601 31 lineto
72 31 lineto
showpage
grestore
%%Trailer
%%DocumentFonts: Helvetica
\end{filecontents}
%
\documentclass[epj]{svjour}

TIP: When migrating the LaTeX code into file variables, you will need to double the backslashes \, e.g. \end will become \\end.

Instructions

Add the following lines of file variables syntax to the end of the journal-template.org file.

# Local Variables:
# eval: (require (quote cl-lib))
# eval: (require (quote ox))
# eval: (require (quote ox-publish))
# org-latex-with-hyperref: nil
# eval: (add-to-list (quote org-latex-classes) (quote ("epj-svjour" "%%%%%%%%%%%%%%%%%%%%%%%% epj-svjour %%%%%%%%%%%%%%%%%%%%%%%%%%
# %
# \\begin{filecontents}{leer.eps}
# %!PS-Adobe-2.0 EPSF-2.0
# %%CreationDate: Mon Jul 13 16:51:17 1992
# %%DocumentFonts: (atend)
# %%Pages: 0 1
# %%BoundingBox: 72 31 601 342
# %%EndComments
# 
# gsave
# 72 31 moveto
# 72 342 lineto
# 601 342 lineto
# 601 31 lineto
# 72 31 lineto
# showpage
# grestore
# %%Trailer
# %%DocumentFonts: Helvetica
# \\end{filecontents}
# %
# \\documentclass[epj]{svjour}
#  [NO-DEFAULT-PACKAGES]
#  [PACKAGES]
#  [EXTRA]" ("\\section{%s}" . "\\section*{%s}") ("\\subsection{%s}" . "\\subsection*{%s}") ("\\subsubsection{%s}" . "\\subsubsection*{%s}") ("\\paragraph{%s}" . "\\paragraph*{%s}") ("\\subparagraph{%s}" . "\\subparagraph*{%s}"))))
# End:

Add the following line under the mode line near the top of the journal-template.org file.
```
  #+LATEX_CLASS: epj-svjour
```

Self Check - Example 2

After completing the instructions in this section, the contents of journal-template.org should be similar to self-check-example-02.org.

Migrate LaTeX Template Code into `SRC` blocks

In this section, the object is to migrate specific snippets of LaTeX code from the LaTeX template into SRC block syntax provided by org-mode. Each SRC block will inject customized LaTeX into the final LaTeX document created by the built-in exporter.

These template specific SRC blocks will be kept under a dedicated section named Template Utility Code which will not be exported.

Instructions

Add the following lines after the * Template Utitily Code section in the journal-template.org document.

  ** export-epj-latex-block

   #+NAME: export-epj-latex-block
   #+BEGIN_SRC latex :noweb yes
     %
     \title{«get-title-text()»}
     \subtitle{«get-subtitle-text()»}
     \author{«epj-authors-latex()»% etc
     % \thanks is optional - remove next line if not needed
     \thanks{\emph{Present address:} Insert the address here if needed}%
     }                     % Do not remove
     %
     \offprints{}          % Insert a name or remove this line
     %
     \institute{«epj-institutions-latex()»}
     %
     \date{Received: date / Revised version: date}
     % The correct dates will be entered by Springer
     %
     \abstract{
     «get-abstract-text()»
     %
     \PACS{
     «epj-pacs-codes-latex()»
          } % end of PACS codes
     } %end of abstract
     %
     \maketitle
   #+END_SRC

  *** get-title-text

   #+NAME: get-title-text
   #+BEGIN_SRC elisp 
     (format "%s" (car (plist-get (org-export-get-environment) ':title)))
   #+END_SRC

   #+RESULTS: get-title-text
   : Title Goes Here

  *** get-subtitle-text

   #+NAME: get-subtitle-text
   #+BEGIN_SRC elisp  :results replace :var keyword="subtitle" :var delimiter=" "
    (mapconcat 'car (org-element-map
         (org-element-parse-buffer)
         '(keyword)
       (lambda (x) (if (string= (upcase keyword) (org-element-property :key x))
                    (list (org-element-property :value x)) )
         )
       ) delimiter)
   #+END_SRC

   #+RESULTS: get-subtitle-text
   : Subtitle Goes Here

  *** get-abstract-text

   #+NAME: get-abstract-text
   #+BEGIN_SRC elisp :results replace :var keyword="abstract"
     (org-element-map (org-element-map
                          (org-element-parse-buffer)
                          '(headline)
                        (lambda (hl) (if (string= (upcase keyword) (upcase (org-element-property :raw-value hl)))
                                        hl)
                          ) 
                        nil t)
         '(paragraph)
       (lambda (p) 
         (format "%s" (replace-regexp-in-string (rx (or (: bos (* (any " \t\n")))
                                                        (: (* (any " \t\n")) eos)))
                                                ""
                                   (buffer-substring-no-properties (org-element-property :contents-begin p) (org-element-property :contents-end p))))
         )
       nil t)
   #+END_SRC

   #+RESULTS: get-abstract-text
   : The abstract goes here.

  *** epj-pacs-codes-latex 

   #+NAME: epj-pacs-codes-latex
   #+BEGIN_SRC elisp  :var pacs_codes=pacs-codes-table :results latex replace :var join_delim="   \\and\n"
     (mapconcat 'identity (mapcar (lambda (x) (format "      {%s}{%s}" (car x) (nth 1 x))) pacs_codes) join_delim)
   #+END_SRC

   #+RESULTS: epj-pacs-codes-latex
   #+BEGIN_EXPORT latex
         {PACS-key01}{Text Describing PACS-key01}   \and
         {PACS-key02}{Text Describing PACS-key02}
   #+END_EXPORT

  *** epj-authors-latex 

   #+NAME: epj-authors-latex
   #+BEGIN_SRC elisp  :var authors=authors-table :results latex replace :var join_delim=" \\and "
     (mapconcat 'identity (mapcar (lambda (x) (format "%s\\inst{%s}" (car x) (nth 2 x))) authors) join_delim)
   #+END_SRC

   #+RESULTS: epj-authors-latex
   #+BEGIN_EXPORT latex
   Mai Deah\inst{1} \and Arthur Secondus\inst{1} \and E. Tal\inst{2}
   #+END_EXPORT

  *** epj-institutions-latex 

   #+NAME: epj-institutions-latex
   #+BEGIN_SRC elisp  :var institutions=institutions-table :results latex replace :var join_delim=" \\and "
     (mapconcat 'identity (mapcar (lambda (x) (format "%s" (nth 1 x))) institutions) join_delim)
   #+END_SRC

   #+RESULTS: epj-institutions-latex
   #+BEGIN_EXPORT latex
   New Discoveries Lab, Department of Something-or-Ruther, University of Some-Sort, Some-Sort, Some-Sort-of-Country \and Golden Opportunities Lab, Department of Obscure Studies, Ancient College, Olde-Locale, Stodgy-Land
   #+END_EXPORT

Add the following lines before the * Template Utitily Code section in the journal-template.org document.

  #+TITLE: Title Goes Here

  #+SUBTITLE: Subtitle Goes Here

  #+CALL: export-epj-latex-block()

  * Authors                                                          :nolatex:

  #+NAME: authors-table
  | Author          | Email                | Institution-ID |
  |-----------------+----------------------+----------------|
  | Mai Deah        | mai.deah@example.edu |              1 |
  | Arthur Secondus |                      |              1 |
  | E. Tal          |                      |              2 |

  * Institutions                                                     :nolatex:

  #+NAME: institutions-table
  | Institution-ID | Institution                                                                                                      |
  |----------------+------------------------------------------------------------------------------------------------------------------|
  |              1 | New Discoveries Lab, Department of Something-or-Ruther, University of Some-Sort, Some-Sort, Some-Sort-of-Country |
  |              2 | Golden Opportunities Lab, Department of Obscure Studies, Ancient College, Olde-Locale, Stodgy-Land               |

  * PACS                                                             :nolatex:

  #+NAME: pacs-codes-table
  | PACS-KEY   | PACS-KEY-Description-Text  |
  |------------+----------------------------|
  | PACS-key01 | Text Describing PACS-key01 |
  | PACS-key02 | Text Describing PACS-key02 |

  * Abstract                                                         :nolatex:

  # The abstract goes here.

Self Check - Example 3

After completing the instructions in this section, the contents of journal-template.org should be similar to self-check-example-03.org.

Add Content to `org-mode` File

In this section, several new placeholder sections will added. The content of each section will be Lorem Ipsum

Instructions

Add content to journal-template.org.

The migration to journal-template.org is complete. Adding real content will be left as an exercise for the reader.

Self Check - Example 4 - Part I

After completing the instructions in this section, the contents of journal-template.org should be similar to self-check-example-04.org.

Export completed `org-mode` file as `PDF`

In this section, the objective is to export the org-mode template to LaTeX and create a PDF.

Instructions

Export an org-mode file as PDF via built-in LaTeX exporter.

To export an org-mode document to PDF:
1. Open the org-mode file in Emacs.
2. Position the cursor in the buffer of the org-mode document in Emacs.
3. Press the following key chords and keys, C-c C-e l p to initiate the export process.
4. Open the exported PDF file to validate the export process succeeded.

Self Check - Example 4 - Part II

After completing the instructions in this section, the contents of journal-template.org should be similar to self-check-example-04.pdf.

Note: The LaTeX file created during the export should be similar to self-check-example-04.tex.

Footnotes

https://emacs.stackexchange.com/q/46017/388

https://mc.manuscriptcentral.com/societyimages/epja/EPJA_templ.zip

https://epja.epj.org/

⁴

Description text for template.tex provided by EPJ A in read.me instructions.

⁵

Description text for svepj.clo provided by EPJ A in read.me instructions.

⁶

Description text for svjour.cls provided by EPJ A in read.me instructions.

⁷

https://github.com/jkitchin/scimax/commit/65467038c65695eb710c7203e7a99d33c4784928

⁸

https://emacs.stackexchange.com/questions/46017/is-there-a-way-to-export-latex-template-to-scimax-template/46051#46051

91 KiB Raw Permalink Blame History

Summary

Instructions

Requirements

Instructions

Create New org-mode File

Instructions

Self Check - Example 1

Download LaTeX Template

Instructions

Migrate LaTeX Template Code into file variables

Instructions

Self Check - Example 2

Migrate LaTeX Template Code into SRC blocks

Instructions

Self Check - Example 3

Add Content to org-mode File

Instructions

Self Check - Example 4 - Part I

Export completed org-mode file as PDF

Instructions

Self Check - Example 4 - Part II

Footnotes

91 KiB

Raw Permalink Blame History

Migrate LaTeX Template Code into `file variables`

Migrate LaTeX Template Code into `SRC` blocks

Add Content to `org-mode` File

Export completed `org-mode` file as `PDF`