110 lines
3.2 KiB
Org Mode
110 lines
3.2 KiB
Org Mode
|
|
* 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)]].
|