Stay Focused on Content with an Automation
Workflow for Professional Publication
Lonnie VanZandt
lonniev@gmail.com
Predictable Response Consulting
Abstract—Modern desktop word processors have evolved into
personal graphics design studios. Although their capabilities are
impressive, they impede an author who has the primary responsibility
of crafting a compelling story with sound argumentation for their
claims. The use of simple editing environment that offers only
Markdown notation along with an automation workflow for the
production of stylized, page-laid-out presentation files empowers an
author to stay focused on their content.
Keywords—Workflow; Markdown; Focus
III. STAY FOCUSED ON CONTENT WITH AN AUTOMATION
WORKFLOW FOR PROFESSIONAL PUBLICATION
Doing defensible science and crafting prose that
effectively communicates that research is difficult. Preparing
that content for acceptance in professional academic or
industry journals is likewise onerous. When an author attempts
to contemporaneously conceive new content and perform page
layout, their goal of getting published in prestigious journals
can by stymied as the details of LaTex, CSS, HTML, RTF,
and PDF programming consume their minds and pollute their
documents. They spend too much time tweaking layout syntax
for proper appearance and too little time in the more important
tasks of thinking, argumentation, and writing.
Time is precious; learn how to use an automation workflow
to perform presentation layout and to use a “markdown” editor
free of presentation features to stay focused on content
creation.
A. Academic Journals and Traditional Tactics
Graphic design editors for academic and industry journals
format the articles they publish with a consistent and
characteristic style. This they do both for brand reinforcement
and to enable their readers to become habituated to the
journal’s content. Consider for example the illustrious design
of “The Gray Lady”, the New York Times. [1]
Like the recognizable layout of The Gray Lady, IEEE
journals have a distinctive style well known to scholars.
Compact yet readable, offering a consistent pattern of
organization despite accomodating manifold fields of study,
the IEEE Journal page layout style is suprisingly complex,
including within its dominion: type face, type weights, font
size, kerning, line spacing, margins, indentations, columns,
gaps, captions, header systems, footnote markers, footnote
positioning, citation markers, citation list formats, citation
style.
FIG. 1. AN IMAGE OF THE FIRST PAGE OF A SAMPLE ARTICLE FORMATTED
WITH THE IEEETRAN.CLS LATEX TEMPLATE FOR IEEE COMPUTER
Academic authors, especially in the scientific fields, have
since 1984 used Leslie Lamport’s version of Donald Knuth’s
Tex typesetting system, LaTex [2], for the page layout of their
articles for publications in the numerous scholarly societies
and conferences.
While LaTex promotes an authoring philosophy of keeping
presentation separate from content, in practice authors using
LaTex mingle their LaTex presentative directives with their
content as they emit that content. Although writing LaTex
into content avoids the focus on the appearance of content
that a WYSIWYG page layout editor demands, the conceptual
content of a work is nonetheless inextricably mired in
presentation statements that are suitable for only one layout
style and for only one body of content.
The following text comes from the IEEEtran.cls LaTex
file. The text is a fragment of LaTex script to configure the
height of the first letter of the first word of a paragraph.
several presentation formats such as for an IEEE Journal, a
web site, a blog post, a slide presentation, a newspaper article,
or others.
% calculate the desired height of the big letter
% it extends from the top of
\@IEEEPARstartHEIGHTTEXT in the current font
% down to \@IEEEPARstartDROPDEPTH below the
current baseline
\settoheight{\@IEEEtrantmpdimenA}{
\@IEEEPARstartHEIGHTTEXT}%
\addtolength{\@IEEEtrantmpdimenA}{
\@IEEEPARstartDROPDEPTH}%
% extract the name of the current font in bold
% and place it in \@IEEEPARstartFONTNAME
\def\@IEEEPARstartGETFIRSTWORD##1 ##2\
relax{##1}%
{\@IEEEPARstartFONTSTYLE{
\selectfont\edef\@IEEEPARstartFONTNAMESPACE{
\fontname\font\space}%
\xdef\@IEEEPARstartFONTNAME{
\expandafter\@IEEEPARstartGETFIRSTWORD
\@IEEEPARstartFONTNAMESPACE\relax}}}%
C. Apple Mac and Useful Usability
The concepts and tactics presented in the workflow
described in this article can be implemented on the
predominant desktop operating systems for the major
hardware platforms. However, the workflow described herein
is especially tailored for the Apple Mac OSX operating system
on Mac systems.
When an author is attempting to concentrate on a mental
task such as how to analyze algorithms, balance chemical
reactions, or compose poetic couplets, most likely they do not
want to have to become fluent in such LaTex scripting in order
to prepare their paper submissions.
This Mac environment is recommended—or at least
encouraged—because out of the three major platforms Linux,
Mac OSX, and Windows, informal studies indicate that the
“user experience”, the application integration, and the scalable
multi-processing of Mac OSX outperforms the other two
admirable contenders.
D. One Workflow but There’s More than One Way to do This
The capabilities, operational use, components, and files
of an automation workflow for the production of
publication-quality articles from Markdown-annotated content
are described.
D.1. Capabilities
Capabilities of system or service are its behaviors.
An automation workflow for authoring and publication
should offer these capabilities:
• Provide a Markdown Editor
B. Markdown and its Plain Purpose
Like LaTex, Markdown is a notation for annotating
otherwise plain sentential text for presentation purposes.
However, unlike LaTex, Markdown is more primitive and
lacks programmatic extension.
• Store Bibliographic Records in a standard Format
To gain the same presentation capabilities of LaTex or
of a WYSIWYG layout editor, markdown authors rely on
conventions and on document post-processors that translate
the simpler Markdown-annotated text to HTML. Then, in
concert with a Cascading Style Sheet (CSS), a web
browser—or another HTML rendering program—transforms
the HTML and CSS into one—of the potentially
many—presentation output files.
• Automate the Generation of Lists of Cited and
Referenced Works in Presentation Documents
Writing content mixed with Markdown rather than content
mixed with LaTex enables the author to increase the separation
between the pure content and the presentation directives. Here
follows a fragment of plain text with Markdown directives.
# A Level 1 Heading
## A Level 2 Heading
This is normal *bold body* text.
When the content is kept separate from the presentation
directives, the author can use unchanged the same content for
• Query Bibliographic Records for related Works
• Export keys to Bibliographic Records in standard
Formats
• Automate the Generation of Cross-Referential
hyperlinks between Citation and Reference Keys in
the plain Content with the entries of the Generated
Cited and Referenced Works
• Automate the Generation of Footnotes
• Automate the linking of Footnotes to usage in the
plain Content
• Automate the Style and Position Layout of plain
Content for a variety of particular Presentation
outputs
Note that today many existing systems and services are
available to authors which either readily or with effort exhibit
these capabilities. This article presents only one particular
integrated workflow.
D.2. Operational Use
The components and files of the workflow are described
after a brief story of how an author might use the workflow.
Beginning the story, as the author diligently researches
existing prior art, they add to Zotero new bibliographic records
for those works that prove or may prove to be related to their
field of study. This author uses Zotero.app on their desktop
or Zed Lite on their smartphone to update their Zotero.org
repository.
When starting to compose their article, this author begins
thinking about what they hope to communicate and writes into
Ulysses their plain content using markdown to sketch their
outline.
As this author conceives and types more content, they
enter citation keys into their text using a hotkey to bring up
the ZotQuery service to find, copy, and paste citations into the
content.
Having drafted their article, this author may preview the
approximate appearance of that article to review the sequence
of their argumentation by using the markdown editor’s
preview capability.
Once this author is ready to review or publish a PDF
version of the properly styled and laid out, they export an
instance of the content from the markdown editor to the file
system. Then they find the exported file in Finder.
Right-clicking the file, this author selects the Markdown to
IEEE Paper workflow Service and choose a new file name and
location for the final PDF publication.
At this point in the story, this author can return to research
and to authoring content. The Finder Automation Service calls
the file transformation components in the proper ordering with
the author’s bibliographic repository, the appropriate style
sheets and layout templates, and the intermediate files. The
submission-ready PDF file is written out into the chosen
folder.
In practice, an author may repeat the process of writing
content and generating presentation outputs several times to
review how their content looks in the form of the chosen
publication. (The important distinction between this practice
and that of using editors that present a WYSIWYG editing
environment is that an author is not continually confronted
with the appearance of their content and is at liberty to focus
on the argumentation in their content.)
D.3. Components
This figure illustrates the collection of components and
files that have been integrated and exploited to implement the
workflow.
FIG. 2. AN ILLUSTRATION OF THE SOFTWARE APPLICATIONS AND
INTERMEDIATE DOCUMENT ARTIFACTS THAT SHOWS THE AUTOMATED FLOW
OF WORK THROUGH THE COLLECTION AND THE APPROXIMATE SEQUENCE OF
PROCESSING STEPS.
Here environments for execution are shown as large boxes
containing components; software applications are shown as
small rectangles with two interface boxes on the left; and files
are shown in simple rectangles or as tearsheet boxes. Directed
arrows show the flow of control and of information through
the integrated components.
In this automation workflow for the production of IEEE
Journal papers from pure content, the components are:
1) Ulysess III
Provides a distraction-free Markdown editor
2) Zotero.app
Provides the desktop access to the author’s Bibliographic
repository
3) ZotQuery
Provides an Alfred workflow for keyboard access to querying,
updating, and exporting citations within the Zotero repository
into the content in the Markdown editor
4) Zotero.org
Provides an Internet cloud-based collaboration site for the
author’s bibliographic records as well as those of the author’s
chosen colleagues
5) Zed Lite
Provides an application for Android smartphones that enables
the author to access and update their bibliographic records
repository while out in the modern world away from their
desktop
6) Apple Automator
Provides a Mac OSX Finder service that transforms a given
Markdown file into an IEEE Journal PDF by executing the
remaining steps of the workflow
7) Pandoc
A multi-purpose file composition and format transformation
service that, here, transforms input markdown to output
HTML
8) citeproc
Plugs into Pandoc as a filtering stage that transforms citation
keys in the markdown content into enumerated hyperlinks
to generated lists of cited and referenced works using
bibliographic records from the Zotero repository
9) Stylizer
Provides an editor for the creation and modification of CSS
directives to customize or tune the CSS used for any particular
presentation format
10) Prince XML
Another multi-purpose service for the transformation of files
between formats. Here used to transform Pandoc’s output
HTML to final PDF without the use of a LaTex service
(Pandoc can transform from HTML to PDF but depends on
MacTex or a similar LaTex engine for PDF production.)
D.4. Input Files of the Workflow
The aforementioned components of the workflow both
operate on and yield these files:
1) index.md
The author’s markdown-decorated content crafted in Ulysses
III
2) ZotOutput.bib
The author’s Bibliographic Records repository exported from
Zotero
3) ieee-pub-pandoc
An HTML template with Pandoc template variables that serves
to compost intermediate content into the order with the proper
CSS style annotations suitable for production of the sought
presentation output
4) ieee-with-url.cls
A Zotero Citation Style Sheet for IEEE publications that is
slightly modified to include a hyperlink from the use of a
citation to its entry in the list of references.
5) pub.css
A CSS file that informs the HTML rendering engine of how
contents with particular CSS styles or in particular locations in
the document structure are to rendered for presentation
D.5. Build Your Own
Each of the components of the illustrated workflow are
available from Internet sites. This section states where to
obtain each one and how to integrate it into the workflow.
D.5.a. Where to Obtain Each
Listed here are the locations for obtaining each of the
components.
• Ulysses III Mac OSX app
Available from the Apple iTunes Mac OS Store [3]
• Zotero.app
Available from the Apple iTunes Mac OS Store [4]
• Better BibTex Zotero plugin [5]
• Zotero.org
Allocated to the author during configuration of the
Zotero.app [4]
• Zed Lite
Available from the Google Play Android Store [6]
• ZotQuery
Available from the Alfred Workflow repository [7]
• Pandoc
Available using Mac homebrew “brew install
pandoc” [8]
• citeproc
Available using Mac homebrew “brew install
pandoc-citeproc” [9]
• Automater.app
Included with Mac OSX
• Markdown to IEEE PDF Automator Workflow
Available at github:lonniev/ieeeWorkflow [10]
• ieee-with-url.csl
Available at github:lonniev/ieeeWorkflow [10]
• ieee-pub-pandoc.html
Available at github:lonniev/ieeeWorkflow [10]
• pub.css
Available at github:lonniev/ieeeWorkflow [10]
D.5.b. How to Integrate Each
Described next are the configuration tasks for each of the
individual components of the overall workflow.
(b.1) Ulysses III Configuration
This Markdown editor needs to emit a plaintext markdown
file that includes a YAML metadata header and to pass without
transformation the Citation key phrases.
Within Ulysses III, perform these steps:
• Go to File:Preferences:Markup
• Select New Markup… from the list of Markdown
styles
• Name the new Markup Style as “Pandoc Markdown
<- XL”
• Choose Markdown XL as the base Template from
which to derive the new style
• Change the Unordered List tag from a dash “-“ to an
asterisk “*”
• Change the Link tags from “[…]” to “[!…!]”
• Exit the Preferences to save the changes.
These small edits allow YAML strings and Citation keys
to pass out of Ulysses when the content is exported without
getting translated to list paragraphs.
(b.6) Pandoc Configuration
At the start of each Markdown file that you want to
transform to an IEEE publication in PDF, add a YAML block
at the start, like this one:
After installing Pandoc with Homebrew, create a .pandoc
folder in the user home directory. This folder stores the
additional CSS and HTML style and template sheets and the
citeproc filter for Pandoc.
——
Copy the pub.css here and the ieee-pub-pandoc.html file to
~/.pandoc/templates.
title: Enabling Rational Decision Making with
Provenance-annotated OSLC Relationships
author:
- name: First Last
affiliation: Company
email: userid@company.com
bibliography: /Users/userid/.pandoc/
ZotOutput.bib
css: /Users/userid/.pandoc/pub
template: ieee-pub-pandoc
keywords: tag1; tag2; tag3
abstract: lorem ipsum
——
(b.2) Zotero.app Configuration
Obtain the Better BibTex extension for Zotero [???] and
install it into Zotero.app
This allows the output format for citations to be
customized.
(b.7) Pandoc citeproc Configuration
No configuration of citeproc is necessary. Simply let
homebrew install it.
(b.8) ieee-pub-pandoc.html
Place this file into the ~/.pandoc/templates folder.
This file provides structured HTML that informs Pandoc
where to place the values of variables from the YAML block
and where to place the abstract, body content, and references
in relation to each other.
(b.9) ieee-with-url.csl
Place this file into the ~/.csl folder.
This file provides stylesheet directives on how to generate
citation keys and on how to generate the list of citations.
(b.3) Zotero.org Configuration
(b.10) pub.css
Create an account with Zotero.org during the installation
of the Zotero.app.
This site serves as the synchronization hub between
Zotero.app on the desktop and Zed Light on a mobile device. It
also provides a community site for the author to share citations
with team members.
(b.4) Zed Lite Configuration
Login into the Zotero.org site when installing Zed Lite on
to a mobile device.
(b.5) ZotQuery Configuration
Place this file into the ~/.pandoc folder.
This file provides CSS styling directives for the generated
HTML.
(b.11) Automator.app Workflow Configuration
Obtain the Markdown to IEEE Workflow script, run
Automator.app on the Mac, and import the workflow into
Automator.app.
This Automator Workflow gathers input files, executes
the shell script to perform the transformations, and writes the
output file.
The key part of the workflow is its script:
Use the Alfred Workflow Finder hotkey to find the 8.5
version of ZotQuery from Packal. The later 10.0 version is not
functional.
Once ZotQuery is installed in Alfred, run its configuration
process with the hotkey “z:config”. Connect ZotQuery to the
Zotero.app internal files.
/usr/local/bin/pandoc "$2" -s --filter /usr/local/
bin/pandoc-citeproc --template ieee-pub-pandoc -t
html --csl ieee-with-url.csl -o - | /usr/local/bin/
prince - -o "$3"/"$1"
Within an Automator workflow, complete paths to
executable files must be provided. However, the references to
the template file and the citation style sheet are specified here
without complete pathnames because Pandoc will look in the
~/.pandoc and in the ~/.csl folders for those files.
(b.12) Prince XML Configuration
No configuration of Prince XML is necessary. Simply
install it.
D.6. As you Like It
This Markdown to IEEE Paper workflow is configured for
the automated generation of PDF files in the layout format and
font style of IEEE Journal articles. However, the workflow is
easily tailored for alternative output formats.
To evolve the workflow for additional styles of the IEEE
Journal template or to produce publications with layouts and
themes distinct from the IEEE Journal form, modify one or
more these components:
• ieee-pub-pandoc.html
Alter the arrangement of content within the final
publication by tailoring this Pandoc template
• pub.css
Evolve this CSS file to alter the appearance of
content such as Headers, Captions, Font face and
size, Mathematical equations, and more
• ieee-with-url.csl
Change this XSLT Stylesheet to modify how Pandoc
transforms and hyperlinks citation usages.
E. Summary of Usage
Having stated the capabilities the workflow should exhibit,
having described the operational scenario, having enumerated
all of the components of the workflow, and having explained
how to integrate each of the components with its peers, this
section simply summarizes how to use the workflow after it
has been established on an author’s Mac.
The steps are:
• Reseach a topic with typical due diligence
• Record new citations into Zotero with either Zed
Lite or with Zotero.app
• Open Ulysses III and create a new Sheet
• Add a YAML header block to identify the title,
authors, the abstract, and keywords
• Lay out in Ulysses III an outline for the content
• Begin writing content appropriate for the sections of
the content
• While writing, use ZotQuery to look up appropriate
citations and to paste citation keys into the content
• Export from Ulysses III an index.md file into the
author’s Finder folders
• Right-click the index.md file in Finder and select the
Markdown to IEEE PDF Service
• Provide Finder folder and then a file name for the
generated PDF
• Open Finder and double-click the generated PDF
file
• Review the “camera ready” IEEE journal article
PDF in Preview.
If only a quick preview is needed, use Ulysses III’s builtin
presentation viewer to see how approximately the content will
look in a choice of formats such as HTML, RTF, Plaintext, or
PDF.
IV. REFERENCES
[1] Gray Lady Wikipedia contributors, “The new york times,”
Wikipedia, the free encyclopedia. Wikipedia, The Free
Encyclopedia, 03-Jun-2015 [Online]. Available:
http://en.wikipedia.org/w/
index.php?title=The_New_York_Times\&oldid=665385739.
[Accessed: 06-Jun-2015]
[2] LaTex Wikipedia contributors, “LaTeX,” Wikipedia, the
free encyclopedia. 05-Jun-2015 [Online]. Available:
http://en.wikipedia.org/w/
index.php?title=LaTeX\&oldid=665562592. [Accessed:
06-Jun-2015]
[3] Soulmen, “Ulysses mac app. Mac app store,”
12-Jun-2015. [Online]. Available: https://itunes.apple.com/us/
app/id623795237?mt=12. [Accessed: 12-Jun-2015]
[4] Zotero, “Zotero,” 07-Jun-2015. [Online]. Available:
https://www.zotero.org/. [Accessed: 08-Jun-2015]
[5] Better BibTex, “Zotero better BibTeX. The better BibTex
plugin for zotero,” 12-Jun-2015. [Online]. Available:
https://zotplus.github.io/better-bibtex/. [Accessed:
12-Jun-2015]
[6] D. Favand, Zed lite. Daniel P Favand LLC, 2015 [Online].
Available: https://play.google.com/store/apps/
details?id=net.favand.zedlite\&hl=en. [Accessed:
08-Jun-2015]
[7] ZotQuery, “ZotQuery,” 07-Jun-2015. [Online]. Available:
http://www.packal.org/workflow/zotquery. [Accessed:
08-Jun-2015]
[8] Pandoc, “Pandoc - about pandoc. About pandoc,”
12-Jun-2015. [Online]. Available: http://pandoc.org/.
[Accessed: 12-Jun-2015]
[9] J. MacFarlane, “Pandoc-citeproc. GitHub
pandoc-citeproc,” 12-Jun-2015. [Online]. Available:
https://github.com/jgm/pandoc-citeproc. [Accessed:
12-Jun-2015]
[10] L. VanZandt, “Lonniev/ieeeWorkflow. GitHub,”
12-Jun-2015. [Online]. Available: https://github.com/lonniev/
ieeeWorkflow. [Accessed: 13-Jun-2015]