snac/readme.org

• Setup
  • Python virtual environment and requirements
• Authoring a snac
  • Source file
  • Sections and their labels
  • Equations and their labels
  • Figures
  • Search box
• Styling
• Publishing workflow
• Org export customization
  • HTML export

Org mode (orgmode.org) is objectively the most flexible, advanced and adaptable authoring markup language available today.

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:

  python -m venv snac-venv
  source snac-venv/bin/activate

Install the requirements:

  pip install -r requirements.txt

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_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

Figures

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

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

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: C-c C-e h h
• run the export.sh script
• navigate to export/html/index.html to see the results

Org export customization

HTML export

In emacs customize, define an `org-publish-project-alist` entry for this project as

  (
  :base-directory "~/work/writing/sci-p-org/src/"
  :base_extension "org"
  :recursive t
  :exclude "index_head\.org"
  :html-head "
  <link href=\"https://cdn.jsdelivr.net/npm/bootstrap@5.1.3/dist/css/bootstrap.min.css\" rel=\"stylesheet\" integrity=\"sha384-1BmE4kWBq78iYhFldvKuhfTAU6auU8tT94WrHftjDbrCEXSU1oBoqyl2QvZ6jIW3\" crossorigin=\"anonymous\">
  <script src=\"https://cdn.jsdelivr.net/npm/bootstrap@5.1.3/dist/js/bootstrap.bundle.min.js\" integrity=\"sha384-ka7Sk0Gln4gmtz2MlQnikT1wXgYsOg+OMhuP+IlRH9sENBO0LRn5q+8nbTov4+1p\" crossorigin=\"anonymous\"></script>
  "
  :html-head-include-default-style nil
  :publishing-directory "~/work/writing/sci-p-org/export/html/"
  :publishing-function org-html-publish-to-html
  :auto-sitemap t
  :makeindex t
  )