Package: scriptorium
ScriptoriumFramework 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.InstallationLinux InstallationInstall external dependencies:gitLaTeXSome distributions don’t includebiber, which should
be installed as wellPythoncmake, which is required to build
MultiMarkdownExecutepip install scriptoriumInstall the MultiMarkdown shared library by executingsudo python-c"import pymmd;pymmd.build_mmd()"Mac InstallationInstall external dependencies:gitMacTeXpipExecutepip install scriptoriumWindows SetupThese 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
requestInstall theGitHub Desktop Client,
and follow the directions to configure it with your GitHub account.InstallMikTexInstallPythonModify the Environment Variables to add Python to thePATHvariable. Based on the helpful instructionshere:Right click on “My Computer” and select PropertiesIn the System Properties window, click on AdvancedClick on the “Environment Variables” buttonSelect thePATHvariable, and add Python. The default values
would beC:\Python27andC:\Python27\Scriptsfor Python
2.7, orC:\Python35andC:\Python35\Scriptsfor 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 thatpython.exeandpipare recognized commands.Executepip install scriptoriumTutorialScriptorium can be invoked directly from the command line using the namescriptorium.Check that all external dependencies are installed and detected
correctly, by veryifying the following command returns nothing:scriptorium doctorYou can check where templates will be installed:scriptorium config TEMPLATE_DIRor change the directory:scriptorium config TEMPLATE_DIR ~/.scriptorium/templatesInstall some exampletemplates:scriptorium template -i https://github.com/jasedit/simple_templates.gitTo list which templates are currently available in scriptorium:scriptorium template -lTo create a new paper in the directoryexample_reportusing 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.mmdThe PDF of the report can be built using:scriptorium build example_reportor, if insideexample_report:scriptorium buildPapers OrganizationSince papers in development are generally not open-source, this
framework pushes papers into standalone folders. Storing these folders
in version control isSTRONGLYencouraged, 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 MetadataIn 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: author@place.com
latex input: template/setup.tex
latex footer: template/footer.exThe 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\chaptercommand in LaTeX, which is often
unused in conference papers. Thelatex authorkey bypasses input
sanitization, allowing LaTeX specific commands in the authors title.myemailis the author’s e-mail address. The input and footer are
used to read the template preamble and footer. Some templates will also
read ametadata.texfile, which provides a direct LaTeX file for
specifying metadata when LaTeX specific commands are necessary.Template OrganizationA 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 thesimple
templatesrepository. A
template is made in a few steps: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.A LaTeX file namedsetup.texinside 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.A LaTeX file namedfooter.texinside this folder, which contains
any LaTeX which should be appended to the end of the file. This often
includes the bibliography commands. The IEEEtranfooter.texfile
is a good example of such a footer.An optionalfrontmatter.mmdand/ormetadata.texfile, 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
thenewcommand.