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]