133 lines
3.8 KiB
Org Mode
133 lines
3.8 KiB
Org Mode
|
|
||
|
|
[[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: =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
|
||
|
|
#+BEGIN_SRC org
|
||
|
|
(
|
||
|
|
: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
|
||
|
|
)
|
||
|
|
#+END_SRC
|