The Fregeifier git repo has two branches, one using php for the backend code and filter, and another using server-side (NodeJS) javascript. The former is the 'php' branch and the latter is the 'main' branch. You are viewing the documentation for the php branch. Checkout the main branch if you would prefer the javascript version.
The Fregeifier is a collection of tools for rendering unusual mathematics in documents and webpages, including things such Gottlob Frege’s logical notation or that of Russell and Whitehead’s Principia Mathematica. It is not limited to those, and may be used for any other kind of complex or unusual mathematical symbolism/notation for which LaTeX tools already exist, but are otherwise hard to use outside of LaTeX-produced documents.
Possibly more will come, but currently there are two main tools.
-
A filter for pandoc that allows you to select a subset of LaTeX-coded mathematics in a markdown document, which, when converted to a non-LaTeX format, such as
.docx,.htmlor.epub, will be rendered as (scalable) images created by converting the output of processing the mathematics by means of a full-featured LaTeX engine. Hence, you can leverage existing tools for things like Frege’s notation, and other LaTeX goodies.The filter was originally developed for The Journal for the History of Analytical Philosophy and integrates easily with the Open Guide Typesetting Framework and Open Guide Editor it uses, which I also created, though it may be used independently.
-
A web interface that can be used to create, preview and download (scalable) images stemming from arbitrary LaTeX code, including that which makes use of unusual packages such as the grungesetze or fge packages for Frege’s notation, the principia package for Russell and Whitehead’s, or any other LaTeX packages available in TeXlive.
A live, hopefully working, version of the web interface can be found here: https://russellguide.org/fregeifier.
The Fregeifier has only been tested on linux, but may work on other unix-like environments.
The php branch of Fregeifier requires php, a TeX distribution such as texlive, the mutool program from the MuPDF project, and of course pandoc to use the pandoc filter.
To self-host the php branch web interface, a PHP-enabled web server (apache, nginx, caddy, etc.) must be available.
Clone the php branch of this repository to a directory of your choosing (here /path/to/repos):
cd /path/to/repos
git clone --branch php --depth 1 https://github.com/frabjous/fregeifierIf you want to self-host the web interface, it would be best to clone the repository into a directory to be served by the php-enabled server.
If permissions were not preserved in the cloning, you will need to make the pandoc filter executable:
chmod a+x /path/to/repos/fregeifier/fregeifier_pandoc_filter.php
For background, see pandoc’s documentation on (json) filters.
The filter can be called using the --filter command line option to pandoc. For .html output:
pandoc --filter /path/to/repos/fregeifier/fregeifier_pandoc_filter.php \
mydocument.md -o mydocument.htmlFor .docx (“MS Word”) format:
pandoc --filter /path/to/repos/fregeifier/fregeifier_pandoc_filter.php \
mydocument.md -o mydocument.docxThe output format of the images will either be svg or that specified as the --default-image-extension option passed to pandoc. For png images, one can do:
pandoc --filter /path/to/repos/fregeifier/fregeifier_pandoc_filter.php \
--default-image-extension=png mydocument.md -o mydocument.htmlCurrently only svg and png are supported.
For the filter to have any effect when applied to a markdown input document, parts of the document containing either inline or block/display mathematics must be given the .fregeify css class, e.g.:
Here is some inline math, like [$2 + 2 = 4$]{.fregeify},
with the class applied
Below is some display math with the class applied.
:::{.fregeify}
$$
5 + 7 = 12
$$
:::These math environments will be processed by LaTeX, converted to small images, and inserted into the document at the specified places. Mathematics environments not so marked with the .fregeify class should be unaffected.
Most likely, however, you don’t need to use this on boring math like “5 + 7 = 12” which can easily be rendered as regular text. The main use of the filter is to handle commands from unusual LaTeX packages. The filter will look for pandoc-compliant (yaml) metadata in the document containing code to include additional LaTeX packages in the header, which typically takes the following form:
---
header-includes: |
\usepackage{grundgesetze,fge}
...These packages will be available then not just if the markdown document is processed to PDF by a LaTeX engine, but also when the filter creates the small images.
A small complete document might look like this:
---
header-includes: |
\usepackage{grundgesetze,fge}
...
In Frege’s notation, a conditional is written as so:
:::{.fregeify}
\GGjudge\GGconditional{p}{q}
:::
Here the LaTeX grundgesetze package is used to render Frege’s notation. Again, however, the filter is package-agnostic and may be used with any LaTeX packages, not just those for Frege’s notation.
A custom template can be used to always load certain packages for a local installation. See below.
The recommended.css file is a stylesheet with settings recommended for use with the pandoc filter. This CSS can be added to the output of pandoc with its --css option, or copied into a pandoc template. The additional classes .top and .bottom may be used to aid in the vertical positioning of inline fregeified images when combined with the .fregeify class, as opposed to the default middle alignment, for example.
The LaTeX math code extracted from the environment by pandoc is processed by the filter to create a minimal LaTeX document. That document is then processed by LaTeX into PDF, the PDF is cropped by the pdfcrop utility of TeXlive, and then mutool is used to convert the PDF page to the output format. The images will be placed in an images subdirectory of the active directory. It is usually best to run pandoc from the same directory as your source document.
By default, the minimal LaTeX documents are based on the file default-template.tex. However, the contents of these minimal documents can be modified by using a different template.
Custom templates will be searched for in the following order.
- The path set by environmental variable
FREGEIFIER_TEMPLATEif non-empty. - The current directory using the filename
fregeifier-template.tex. $HOME/.config/fregeifier/fregeifier-template.tex.
If none of these are found, the default is used.
The template may also be used to change the LaTeX engine used. If the template contains (most likely in a comment), xelatex or lualatex, they will be used instead to create the intermediate PDFs; otherwise pdflatex is used.
Templates must also contain comments of the following forms:
% FREGEIFIER:HEADERINCLUDESand
% FREGEIFIER:MATHTEXTWhen processing "fregeified" math, the former will be replaced by any TeX-specific header-includes: content, and the latter by the LaTeX code used in the math.
Templates are fussy. There must be exactly one space between the “%” and the “F”.
The file default-template.tex can be consulted for comparison, and/or directly copied and modified to suit one’s needs (e.g., specify different math fonts, always load certain packages, etc.)
Moreover, if “xelatex” or “lualatex” are found in the code (most likely in another comment), they will be used in place of pdflatex to create the converted images.
If the php branch of this repository is cloned into a directory served by a PHP-enabled web server, the web interface should be accessible through the url for the repository directory, e.g., http(s)://yourdomain.net/fregeifier/.
The interface is hopefully self-explanatory for the visitor for the purposes of creating images similar to those produced by the filter. Additionally, images can be created through the web interface by converting from contemporary notation.
The same tools necessary for the filter must be installed. Files created by the user will be stored in a data directory, either at ../../data/fregeifier relative to the repository directory (if it exists) or $HOME/.cache/fregeifier otherwise. Whenever invoked, files older than a day will be removed.
The interface allows the user to create documents with arbitrary LaTeX code, so security may be a concern. --shell-escape and --write18 are disabled and the number of characters in the LaTeX code is limited, but you may wish to take other measures, especially if the server is exposed to the full internet.
Thanks go to the creators of tools such as the grundgesetze, fge and principia LaTeX packages, including Marcus Rossberg, J. J. Green, and Landon Elkind; the creators of Pandoc, including John MacFarlane, and other contributors to the open source world.
Copyright 2024 © 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.