scriptorium

|Latest Version| |Downloads| |License| |Code Health|

Scriptorium

Framework for easily using MultiMarkdown and LaTeX based system to write academic papers, especially those with shared templates for organization. This system is designed with several important design guidelines and observations:

• Many academic publications are collaborative, continuously evolving works.
• Many academic publications provide LaTeX templates to meet the formatting guidelines for submission.
• Research groups often use common templates for documents, such as submitting to a particular conference repeatedly over the years, or thesis/dissertation requirements at a particular university.
• LaTeX can have a high learning curve for people unfamiliar with its syntax and style. Simpler markup langauges can sacrifice control for ease of use or readability. Ideally, a system would provide tools that cover the continuum between simplicity and control.
• Academic publications can have a mix of visibility/availability between groups. Some papers may be private to an individual, a group, some mix of groups, or publicly available. The tools for building papers may not share this variability of privacy.

In light of these observations, this framework aims to provide:

• Version control for documents, allowing concurrent collaboration, full history tracking, branching for edits, etc.
• User friendly in syntax and operation, minimizing the requirement to learn gory internal details.
• Provide the ability to selectively access lower level commands for power users to fine tune results.
• A base for groups to use to distribute/share a common working base, with flexibility for individuals to choose documents which are present on their system.
• Fine grained privacy controls for controlling access to documents and intellectual property.
• Plain text as the basis for documents, ensuring that a wide variety of workflows and tools can be used to edit documents.

Installation

Linux Installation

• Install external dependencies:

  • git <https://git-scm.com/>__

  • LaTeX <http://www.latex-project.org/>__

    • Some distributions don't include biber <http://biblatex-biber.sourceforge.net>__, which should be installed as well

  • Python <http://python.org/>__

  • cmake <https://cmake.org/>__, which is required to build MultiMarkdown

• Execute pip install scriptorium

• Install the MultiMarkdown shared library by executing sudo python -c "import pymmd; pymmd.build_mmd()"

Mac Installation

• Install external dependencies:

  • git <https://git-scm.com/>__
  • MacTeX <https://www.tug.org/mactex/>__
  • pip <https://pip.pypa.io/en/latest/installing/#install-or-upgrade-pip>__

• Execute pip install scriptorium

Windows Setup

These instructions provide a method to configure Scriptorium to work on Windows with a minimum of fuss. There are many other ways to configure this system, and cleaner instructions would be appreciated in a pull request

• Install the GitHub Desktop Client <https://desktop.github.com/>__, and follow the directions to configure it with your GitHub account.

• Install MikTex <http://miktex.org/>__

• Install Python <https://www.python.org/downloads/>__

• Modify the Environment Variables to add Python to the PATH variable. Based on the helpful instructions here <http://stackoverflow.com/questions/23400030/windows-7-add-path>__:

  • Right click on "My Computer" and select Properties
  • In the System Properties window, click on Advanced
  • Click on the "Environment Variables" button
  • Select the PATH variable, and add Python. The default values would be C:\Python27 and C:\Python27\Scripts for Python 2.7, or C:\Python35 and C:\Python35\Scripts for Python 3.5, although this would changed if the installation directories were changed in previous steps.

• Open the "Git Shell" installed by GitHub, and verify that python.exe and pip are recognized commands.

• Execute pip install scriptorium

Tutorial

Scriptorium can be invoked directly from the command line using the name scriptorium.

Check that all external dependencies are installed and detected correctly, by veryifying the following command returns nothing:

::

scriptorium doctor

You can check where templates will be installed:

::

scriptorium config TEMPLATE_DIR

or change the directory:

::

scriptorium config TEMPLATE_DIR ~/.scriptorium/templates

Install some example templates <https://github.com/jasedit/simple_templates>__:

::

scriptorium template -i https://github.com/jasedit/simple_templates.git

To list which templates are currently available in scriptorium:

::

scriptorium template -l

To create a new paper in the directory example_report using the report template previously installed:

::

scriptorium new example_report -t report -c author "John Doe" -c title "My Example Report"

Adding example content using the command:

::

echo "

# Introduction

This is an introductory section." >> example_report/paper.mmd

The PDF of the report can be built using:

::

scriptorium build example_report

or, if inside example_report:

::

scriptorium build

Papers Organization

Since papers in development are generally not open-source, this framework pushes papers into standalone folders. Storing these folders in version control is STRONGLY encouraged, though not strictly required by the system. Generally, version control repositories don't handle binary files (e.g. images) particularly well, so it is recommended to break up papers into more repositories to require less overhead storing history, as well as providing finer granularity in sharing papers.

Paper Metadata

In order to integrate the template system, the MultiMarkdown metadata
header requires a few important statements. Consider an example header,
as shown below.

::

    Base Header Level: 3
    latex author: Author
    Title: Paper Title
    myemail: [e-mail]
    latex input: template/setup.tex
    latex footer: template/footer.ex

The Base Header Level is important for configuring MultiMarkdown to
avoid section levels which may not be supported by the template being
used. Level 1 is the ``\chapter`` command in LaTeX, which is often
unused in conference papers. The ``latex author`` key bypasses input
sanitization, allowing LaTeX specific commands in the authors title.
``myemail`` is the author's e-mail address. The input and footer are
used to read the template preamble and footer. Some templates will also
read a ``metadata.tex`` file, which provides a direct LaTeX file for
specifying metadata when LaTeX specific commands are necessary.

Template Organization
---------------------

A template defines the latex setup defining how a paper is going to be
laid out, which packages it will use, etc. For reference, consider
templates in the `simple
templates <https://github.com/jasedit/simple_templates>`__ repository. A
template is made in a few steps:

1. A folder inside the templates directory. The name of this folder is
   what is used to reference the template in a MultiMarkdown paper, by
   LaTeX's recursive subdirectory search.
2. A LaTeX file named ``setup.tex`` inside this folder, which contains
   the template preamble. The preamble should include everything at the
   start of the document before the content, through the
   ``\begin{document}`` statement. More may be included in this
   preamble, such as seen in the IEEEtran example in the simple
   templates.
3. A LaTeX file named ``footer.tex`` inside this folder, which contains
   any LaTeX which should be appended to the end of the file. This often
   includes the bibliography commands. The IEEEtran ``footer.tex`` file
   is a good example of such a footer.
4. An optional ``frontmatter.mmd`` and/or ``metadata.tex`` file, which
   contains a default values, minus the input and footer values. Any
   field can have a value starting with a dollar sign, and capital
   alphanumeric and ``_``, ``.``, or ``-``, which are replaceable during
   the ``new`` command.

.. |Latest Version| image:: https://img.shields.io/pypi/v/scriptorium.svg
   :target: https://pypi.python.org/pypi/scriptorium
.. |Downloads| image:: https://img.shields.io/pypi/dm/scriptorium.svg
   :target: https://pypi.python.org/pypi/scriptorium
.. |License| image:: https://img.shields.io/pypi/l/scriptorium.svg
   :target: https://pypi.python.org/pypi/scriptorium
.. |Code Health| image:: https://landscape.io/github/jasedit/scriptorium/master/landscape.svg?style=flat
   :target: https://landscape.io/github/jasedit/scriptorium/master