* Snac: from Org to browsable HTML

[[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,


Full example:

#+BEGIN_SRC org
#+begin_eqlabel
<<tau>>
#+begin_alteqlabels
- KBI V.1.33
#+end_alteqlabels
#+end_eqlabel
\begin{equation}
\tau (\lambda) = \mbox{exp}~ \sum_{n=0}^\infty \frac{i_n}{n!} Q_n (\lambda - \xi)^n
\tag{tau}\label{tau}
\end{equation}
#+END_SRC


** Figures

To include simple figures, simply use a link to the corresponding file. For example,

#+BEGIN_SRC org
  #+begin_eqlabel
  <<fig-your_label>>
  #+end_eqlabel
  #+caption: Your caption.
  #+attr_html: :width 100%
  [[./fig/your_figure.jpg]]
#+END_SRC


** Search box

A search box is included in each output HTML page.
Edit the =searchbox_string= in the =src/split.py= script, making sure you set your site as the =value= of the =sites= input element.



* Styling

The main style file is =css/snac.css=.



* Publishing workflow
- produce the main file's html version: invoke =C-c C-e h h= from the Emacs buffer for your =index.org= source file
- run the =export.sh= script (invoking =./scripts/export.sh= from the base directory)
- navigate to =export/html/index.html= to see the results


* License

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)]].