snac/readme.org

* 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, offering

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
<<E_vcd>>
#+begin_alteqlabels
- Gr4(2.8)
- W3(??)
#+end_alteqlabels
#+end_eqlabel
#+attr_html: :class main
#+begin_div

\begin{equation}
{\bf E} ({\bf r}) = \frac{1}{4\pi\varepsilon_0} \int_{\cal V} d\tau' \rho({\bf r}') \frac{{\bf r} - {\bf r}'}{|{\bf r} - {\bf r}'|^3}
\tag{E_vcd}\label{E_vcd}
\end{equation}

#+end_div
#+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 `GNU Affero General
Public License (Version 3, 19 November 2007) <https://www.gnu.org/licenses/agpl.html>`_.