Journal Tools

The JHAP Typesetting framework

This code provides a web-based framework for typesetting academic journal articles and book reviews using LaTeX. Editors can log in, create projects, convert other file formats to LaTeX, edit LaTeX files, and natbib-based bibliographies, create page proofs and leave comments on them, share proofs with authors, allow authors to leave comments and answer queries on these proofs, and create web-optimized PDFs for online publication.

The framework was designed for The Journal for the History of Analytical Philosophy but may be adapted for use by other journals, or others in general.

Requirements and Installation

You will need:

  • A PHP-enabled web-server; I recommend running it on a Linux/Unix based system (but haven't tested other operating systems)
  • Other helper libraries created by me: KCKlib; KCK Icons and K(ev)E(dit); these are expected be installed in immediate subfolders of the web server root directory kcklib/, icons/ and ke/; as well as CodeMirror in a ke/codemirror/ subfolder. These can be optionally installed through the initial_setup.php script.
  • A number of other programs used either by K(ev)E(dit) or Journal Tools for performing conversions, typesetting, optimization, etc. These include TeXlive (or another TeX distribution, for processing LaTeX files), rubber (for processing LaTeX errors), LibreOffice (for convering Word Processor files to markup files), pandoc (for converting markup formats to LaTeX), ghostscript (for optimizing and shriking output PDF files), the mupdf project’s mutool (for converting PDF pages to images that can be displayed in a browser), flite and lame (for K(ev)E(dit)'s text-to-speech features). The executables for these programs should be found in the $PATH for the webserver user.

For installation and setup:

  • Clone this repository into your webserver document root; rename the output folder if you wish.
  • From within the subfolder created, from the command line execute the initial_setup.php script with php.
  • The two steps above, for example might be (from a terminal):
cd /home/web/public_html # or whatever the webserver root folder is
git clone
mv journal-tools myjournal
cd myjournal
php initial_setup.php
  • The set up script will ask for the name of the journal, contact information, etc., and in the process will create the first user of the framework and provide a password.
  • The script may also be used to install KCKlib, KCK Icons and K(ev)E(dit)/Codemirror if not installed already. This functionality requires that git and npm are installed on the server.
  • Login to the framework (e.g. through your browser to ensure that the created user and password work as expected. That user can create others users (who will be sent invitations via email).


Here is a rough summary of usage. Fuller instructions for how the system is used for JHAP can be found with the JHAP Typesetting Guide:

  1. After logging in, the user will see a list of projects. There is a field to create a new one.
  2. Each project is given a unique document number; this is meant to match the number given in an OJS or similar system (and future versions of this project may allow for automatic integration with OJS).
  3. This will bring up a page to enter metadata, and choose between articles and review. Fill in a click save.
  4. Back at the project listing, there is now a box for the new project, and a link to upload a file for conversion; all file formats which can be imported into LibreOffice and/or Pandoc are allowed, including Word, etc.
  5. The next step is to edit the bibliography by clicking the "edit bibliography" link; when the bibliography is finalized, you can move to the next step.
  6. Click the "create LaTeX file" link to convert the uploaded file to LaTeX format; you will be automatically redirected to a page where the LaTeX file can be edited. This uses K(ev)E(dit); see its documentation for more information. Use the "play button" icon to create a PDF at least once.
  7. When the LaTeX file is in good shape, return to the main page for the framework (by clicking back in your browser, or renavigating to its page). Create a set of proofs with "create new proof set".
  8. This will bring up the editor's version of viewing the proofs; queries can be added by drawing boxes on the page, and the toolbar at the top can be used for navigating between pages.
  9. Click back to return the menu, and there are two links for the proof set, an editor link and author link. The author link should be provided to the author, who can use it to add comments, corrections and respond to queries. This link provides further instructions when first visited.
  10. When author corrections are submitted, the journal contact is emailed. Changes may be made to the LaTeX file with "edit LaTeX file", and additional proof sets created as needed.
  11. When all corrections are made, the "create optimized PDF" link will create a smaller, and web-optimized PDF, which should be the published (e.g. as "galleys" in OJS).


A different document class other than jhap.cls can be chosen at setup when running the initial_setup.php script, or changed by directly editing the file jtsettings.json created by that script.

A different bibliography style can be used by creating a javascript file called custombibstyle.js which defines a function:

function bblEntryFor(bibkey, bibdata, elem) {
    // ...

This function takes three arguments: a citation key, used, e.g., in LaTeX \cite commands, bibliographical data, as an object, and the form element on the page where such data is entered. This function should output a string used as the LaTeX thebibliography listing item for the entry. For more details, it would be best to compare to the bblEntryFor function defined in the file editbib.php, which is the version of the function used by JHAP. The output should be natbib-compatible.

Note that this script is used instead of BibTeX, which is not used at all, though BibTeX files may be imported.


© 2018–2019 Kevin C. Klement. This is free software, which can be redistributed and/or modified under the terms of the GNU General Public License (GPL), version 3.