Skip to content

Manual.md

Latest commit

 

History

History
192 lines (116 loc) · 3.86 KB

Manual.md

File metadata and controls

192 lines (116 loc) · 3.86 KB

PaperShell Manual

This file contains the complete documentation.

For a quick introduction, see README.md.

Project structure

PaperShell generates the files

  • gen/preamble.inc.tex
  • gen/midamble.inc.tex
  • gen/postamble.inc.tex

automatically during compilation. Your main document contains:

\input{gen/preamble.inc.tex}  
\input{gen/midamble.inc.tex}  

... paper content ...

\input{gen/postamble.inc.tex}

Switching publisher

Change the publisher in Source/settings.tex and compile once with LuaLaTeX.

Generated files

The generated files contain the class declaration, title block, bibliography configuration, and style-specific fixes.

Exporting final sources

If your paper is accepted, you may need to send a clean bundle of sources to the editor.

Run

php export.php

This will

  • inline all \input files
  • include the bibliography
  • copy required files
  • create a standalone directory

The exported version compiles with pdfLaTeX.

Option:

php export.php --flatten

Theme manager

PaperShell comes with a small theme manager called psmod.lua.

A theme is a small ZIP archive containing additional style files and templates, along with a manifest.lua file describing the package. Themes are downloaded from the PaperShell theme repository and unpacked directly into the project. This makes it possible to install support for additional publisher styles without manually copying files into the PaperShell tree.

Usage

Run the theme manager with texlua:

texlua psmod.lua <action> [theme]

Available actions are:

  • list — list the themes currently installed
  • install — download and install a theme

You can also display the help message with:

texlua psmod.lua -h

Listing installed themes

To list all themes currently installed in the project:

texlua psmod.lua list

Installing a theme

To install a theme named foo:

texlua psmod.lua install foo

This downloads the archive https://sylvainhalle.github.io/PaperShell/themes/foo.zip and extracts its contents into the PaperShell source tree.

Theme layout

A theme is a ZIP archive with a simple structure. It should contain:

  • template files under tpl/<theme>/
  • style files under sty/<theme>/
  • a manifest.lua file under tpl/<theme>/

The manifest is a Lua file returning a table with metadata such as:

  • id
  • name
  • version
  • innerversion

Notes

  • The theme manager currently supports install and list.
  • Themes are downloaded from the official PaperShell theme repository.
  • Installing a theme copies files into the local PaperShell project.

BibTeX helper scripts

Cleaning:

php clean-bibtex.php

Importing citations:

php import-citations.php file.bib

Diffing bibliographies:

php bib-diff.php file1.bib file2.bib

Other helper scripts

Diff versions:

./diff-versions.sh old new target

Archive source:

./archive-source.sh

Dependencies

Required:

  • LaTeX distribution (such as TeXLive or MikTeX
  • latexmk
  • LuaLaTeX (generally included in the LaTeX distribution)

Optional:

Notes about publisher styles

PaperShell fixes various issues in publisher styles, including problems with fonts, bibliography titles, package incompatibilities, and class bugs.

Design philosophy

PaperShell follows these rules:

  • Write once
  • Switch style easily
  • Keep sources plain LaTeX
  • Produce editor-friendly bundles
  • Work in Overleaf
  • Avoid complex build tools