[[https://en.wikipedia.org/wiki/Org-mode][Org mode]] ([[https://orgmode.org/][orgmode.org]]) is objectively the most flexible, advanced and adaptable authoring markup language available today.
[[https://en.wikipedia.org/wiki/HTML][HTML]] is undoubtedly the most widespread display markup language, with the best perspectives for long-term availability.
Specially tailored for academics looking to easily author electronic versions of books, lecture notes or similar material, *snac* (/snippets of academe/) offers a bridge between Org and HTML: from a single Org source file, it provides split, interlinked and directly publishable web-ready documents.
* Setup
=snac= makes use of python and shell scripts.
** Python virtual environment and requirements
Create a virtual environment (here: named =snac-venv=) and activate it:
#+BEGIN_SRC shell
python -m venv snac-venv
source snac-venv/bin/activate
#+END_SRC
Install the requirements:
#+BEGIN_SRC shell
pip install -r requirements.txt
#+END_SRC
* Authoring a snac
** Source file
The source file is =index.org= in the =src= directory.
** Sections and their labels
Sections are defined through Org mode headlines. Each headline should have a =CUSTOM_ID= whose format is contrained to the form =[id]= for a first-level section, =[id]_[subid]= for second-level, etc.
Plunging into the sections hierarchy, any nth-level section's =CUSTOM_ID=/must/ have the n-1th-level section's =CUSTOM_ID= as prefix (in order for later page splitting and interlinking to work).
** Equations and their labels
Block equations are displayed including a label, permalink and optional alternative labels.
When writing block equations,
- give them a semantic label (which we call eqlabel) in the form of a dedicated link, which must be unique throughout the whole document;
- [optional] include alteqlabels (/i.e./ labels from other sources for the same equation) as a list;
- add LaTeX tag and label with values set to eqlabel,
This codebase is released under the terms of the [[https://www.gnu.org/licenses/agpl.html][GNU Affero General Public License (Version 3, 19 November 2007)]].