#+END_EXPORT
* Source code
** Code blocks with syntax highlighting
Source code blocks support
[[https://orgmode.org/worg/org-contrib/babel/languages/index.html][syntax
highlighting]] (~cpp~),
[[https://orgmode.org/manual/Literal-Examples.html][row numbers]] (~-n~) and highlight
referrals (~ref:~). Code block syntax highlighting in Org mode's HTML export
[[https://stackoverflow.com/questions/24082430/org-mode-no-syntax-highlighting-in-exported-html-page/24087061#24087061][depends
on the =htmlize= library]].
#+begin_src org
#+begin_src cpp -n -r
// Your First C++ "Hello World!" (ref:comment)
#include (ref:preprocessor)
int main() { (ref:main)
std::cout << "Hello World!";
return 0;
}
,#+end_src
Where,
~//~ denotes a comment on line [[(comment)]]
The [[(preprocessor)][~#include~]] is a preprocessor directive used to include files in our program.
~int main() {...}~: A valid C++ program must have the [[(main)][main()]] function.
#+end_src
#+begin_src cpp -n -r
// Your First C++ "Hello World!" (ref:comment)
include (ref:preprocessor)
int main() { (ref:main)
std::cout << "Hello World!";
return 0;
}
#+end_src
Where,
~//~ denotes a comment on line [[(comment)]]
The [[(preprocessor)][~#include~]] is a preprocessor directive used to include files in our program.
~int main() {...}~: A valid C++ program must have the [[(main)][main()]] function.
#+begin_note
*Note:* In above Org code block example I needed to
[[https://orgmode.org/manual/Escape-Character.html][escape]] some elements
with comma (~,#+end_src~) and with
[[https://coolsymbol.com/zero-width-space-joiner-non-joiner-ltr-rtl-lrm-rlm-characters-symbols.html][zero
width spaces]] (~(<200b>ref:comment)~) ensuring those elements were displaying correctly as literal
code and not rendered in html export into something else. See
[[https://pyyhttu.kapsi.fi/debian/org-mode/orgmode.org][=orgmode.org=]]
source file for exact escaped characters and their usage.
#+end_note
** Code blocks without syntax highlighting
Source code blocks without syntax highlighting can be created by omitting the [[https://orgmode.org/worg/org-contrib/babel/languages/index.html][language identifier]]:
#+begin_src org
#+begin_src
This is verbatim fixed width code without syntax highligthing.
,#+end_src
** NEXT Evaluating inline code
If you have done ~$ sudo aptitude install r-base-core~ then you can also evaluate code:
#+BEGIN_SRC R
You can also evaluate code inline as follows: 1 + 1 is src_R{1 + 1}.
#+END_SRC
You can also evaluate code inline as follows: 1 + 1 is src_R{1 + 1}.
*Edit:* Code evaluating does not seem to work in exported results. This has
something to do with this documents header argument: #+PROPERTY: header-args :eval never-export :exports both :results replaced
Google emacs evaluate code and also see:
https://orgmode.org/manual/Exporting-Code-Blocks.html and https://orgmode.org/manual/Literal-Examples.html#FOOT115
Editedit: setup first R language to work https://www.r-bloggers.com/2022/12/using-emacs-for-r/
and then research https://emacs.stackexchange.com/questions/33103/no-org-babel-execute-function-for-calc
Get R first to evaluate anything with c-c c-c
Also see: https://stackoverflow.com/questions/44977043/how-to-execute-inline-source-blocks-in-an-org-mode-table
** Source mode
The following language strings are [[https://orgmode.org/worg/org-contrib/babel/languages.html][currently recognized]]:
ABC, Asymptote, Awk, C, C++, Calc, Clojure, comint, Coq, CSS, D, Ditaa, Dot (Graphviz), ebnf, Emacs Lisp, Forth, Fortran, Gnuplot, Haskell, Io, J, Java, Javascript, LaTeX, Ledger, Lilypond, Lisp, Make, Matlab, Maxima, Mscgen, Objective Caml, Octave, Org, Perl, Picolisp, PlantUML, Processing, Python, R, Ruby, Sass, Scala, Scheme, Screen, Sed, shell, Shen, SQL, SQLite, Stan, Vala, Contributed, Language, Eukleides, Fomus, Groovy, Julia, Mathematica, Mathomatic, OZ, Stata, Tcl, Emacs Package, Language, Axiom, HTML, Neo4j, Elixir, http request, iPython, Kotlin, Lisp Flavored Erlang, MongoDB, Prolog, rec, Standard ML, Google Translate and Typescript.
* Diagrams
Diagrams or flowcharts can be "drawn" in ascii art with Vim addons such as
[[https://www.baeldung.com/linux/vim-drawit-ascii-diagrams][DrawIt]] and
[[https://asciinema.org/a/qeig6TH6N4uteq7J6n4epUGaq][vim-boxdraw]], as well
as utilizing ~:he virtualedit~.
** Ditaa
Export happens calling emacs export via [[https://github.com/stathissideris/ditaa][ditaa]]. Here's a flowchart from [[https://xkcd.com/518/][xkcd]]:
#+BEGIN_SRC ditaa :file diagram.png :exports both
+-------+
| Start |
+---+---+
|
v
+-------------------+
| |
| |
| Do you |Yes +------+Yes
| understand +------------------------------------------>| Good +-------------+
| flow charts? | +------+ |
| {c} | ^ |
| | | v +----------------+
+-------------------+ | +------------+ | |
| No | | | 6 drinks | Hey, I should |
| | | Let's go +---------->| try installing |
| | | drink. | | FreeBSD! |
v | | | | |
+-------------------+ +-------------------+ | +------------+ +----------------+
| | | | | ^
| | | | | |
| Okay. |Yes | ...And you can |Yes | |
| You see the +------------------->+ see the ones +------+ |
| line labeled | | labeled "no"? | +-----+------+
| "yes"? {c} | | {c} | | Screw it. |
| | | | +------------+
+-------------------+ +---------+---------+ ^
| No |No |
| v |
| +-------------------+ |
v | | +------+-------+
+-------------------+ | | | |
| | | But you |Yes | (That wasn't |
| | +-------+ | just followed +--------------->+ a question). |
| But you |Yes | | | them twice! | | |
| see the ones +------>| Wait, | | {c} | +--------------+
| labeled | | What? | | | ^
| "no"? | | | +---------+---------+ |
| {c} | +-------+ |No |
+---------+---------+ +---------------------------------+
|No +--------+
v | |
+---------+ | I hate |
| Listen. |------->| you. |
+---------+ | |
+--------+
#+END_SRC
** Flowchart diagrams
Different kind of diagrams are supported:
#+BEGIN_SRC ditaa :file integration.png :exports both
/-----------+ /---------\
| PLC | | |
| Network +<------>+ PLC +<---=---------+
| cRED | | c707 | |
+-----------/ \----+----/ |
^ |
| |
| +----------------|-----------------+
| | | |
v v v v
+----------+ +----+--+--+ +-------+---+ +-----+-----+ Windows clients
| | | | | | | | +----+ +----+
| Database +<----->+ Shared +<---->+ Executive +<-=-->+ Operator +<---->|cYEL| . . .|cYEL|
| {s} cBLU | | Memory | | {io} cPNK | | Server | | | | |
+--+----+--+ |{d} cGRE | +------+----+ | c707 | +----+ +----+
^ ^ +----------+ ^ +-------+---+
| | |
| +--------=--------------------------+
v
+--------+--------+
| |
| Millwide System | -------- Data ---------
| cBLU | --=----- Signals ---=--
+-----------------+
#+END_SRC
Not all shape selector tags are documented for the diagrams on the ditaa site, document
[[https://plantuml.com/ditaa#189f63f277cd7339][these]] as examples.
#+begin_note
The above =ditaa= (~$ sudo aptitude install ditaa~) diagrams require modifications to =.emacs=
config. Do ({{{kbd(ctrl)}}}-{{{kbd(f)}}} in file =ditaa= to see what those
modifications are and match to your setup accordingly. My setup: WSL2, headless Debian Sid under Windows 11.
#+end_note
Then code block above needs to have =:exports results=: https://orgmode.org/manual/Exporting-Code-Blocks.html
Pay attention also to document header =#+PROPERTIES=, what should they be for
evaluation to pass through silently?
* Math
** Inline math expressions
For *inline math* expressions, use the parentheses notation ~\(...\)~:
#+begin_src org
The formula \(a^2 + b^2 = c^2\) has been discovered by Pythagoras.
Let \(a=\sin(x) + \cos(x)\). Then \(a^2 = 2\sin(x)\cos(x)\) because \(\sin^2x +
\cos^2x = 1\).
#+end_src
The formula \(a^2 + b^2 = c^2\) has been discovered by Pythagoras.
Let \(a=\sin(x) + \cos(x)\). Then \(a^2 = 2\sin(x)\cos(x)\) because \(\sin^2x +
\cos^2x = 1\).
Formulas, like the Pythagoras above, are then displayed after html export either by [[https://www.mathjax.org/][MathJax]] (default) or in images. This can be [[https://orgmode.org/manual/LaTeX-fragments.html][changed]].
MathJax requires Javascript to be enabled in your browser, but offers this handy right-click menu:
[[file:images/mathjax.png]]
** Math expressions in display mode
For mathematical expressions which you want to make *stand out, centered on their
own lines*, use ~\[...\]~:
#+begin_src org
The /Taylor series:/
\[
f(a)+{\frac {f'(a)}{1!}}(x-a)+{\frac {f''(a)}{2!}}(x-a)^{2}+{\frac {f'''(a)}{3!}}(x-a)^{3}+
\]
where /n!/ denotes the factorial of /n/. In the more compact sigma notation, this can be written as
\[ \sum _{n=0}^{\infty }{\frac {f^{(n)}(a)}{n!}}(x-a)^{n} \]
#+end_src
The /Taylor series:/
\[
f(a)+{\frac {f'(a)}{1!}}(x-a)+{\frac {f''(a)}{2!}}(x-a)^{2}+{\frac {f'''(a)}{3!}}(x-a)^{3}+
\]
where /n!/ denotes the factorial of /n/. In the more compact sigma notation, this can be written as
\[ \sum _{n=0}^{\infty }{\frac {f^{(n)}(a)}{n!}}(x-a)^{n} \]
#+begin_note
If your LateX is rusty, you can copy mathematical expressions (e.g. from
wikipedia) using {{{kbd(ctrl)}}}-{{{kbd(c)}}} and paste them into
[[https://latex.codecogs.com/eqneditor/editor.php][online LaTeX editor]] to
get proper code. You can also produce
[[https://ejmastnak.github.io/tutorials/vim-latex/intro.html][real-time
LaTeX]] using Neo(Vim).
#+end_note
** Include Org files
You can include another Org file and skip its title by using the ~:lines~ argument
to ~#+INCLUDE~:
#+begin_src org
,#+INCLUDE: "chapter1.org" :lines "2-"
#+end_src
#+begin_note
File inclusion, through INCLUDE keywords, is an *export-only feature*.
#+end_note
* Footnote
#+begin_src org
It is possible to define named footnotes[fn:myfootnote], or ones with automatic
anchors[fn:2]. Scroll to the bottom to see the footnotes.
#+end_src
#+results:
It is possible to define named footnotes[fn:myfootnote], or ones with automatic
anchors[fn:2]. Scroll to the bottom to see the footnotes.
* Task management
** TODO states and priorities
#+BEGIN_SRC org
,** DONE [#A] H2 Title with closed DONE state, priority and a tag :online:
:LOGBOOK:
- State "TODO" -> "DONE" [2014-01-16 Thu 09:52]
:END:
By default, DONE-actions will be collapsed and drawers (notice ~:LOGBOOK:~
in Org code block?) are not exported to HTML, unless =#+OPTIONS: d:t= is
defined.
[[https://orgmode.org/manual/Priorities.html][Priority]] is displayed if =#+OPTIONS: pri:t= or priority cookie =(org-export-with-priority)= is set.
,*** FOLLOWUP [#B] H3 Title with different TODO state, priority and several tags :computer:write:
,**** NEXT [#C] H4 title with closed TODO state and priority
#+END_SRC
** DONE [#A] H2 Title with closed DONE state, priority and a tag :online:
:LOGBOOK:
- State "TODO" -> "DONE" [2014-01-16 Thu 09:52]
:END:
By default, DONE-actions will be collapsed and drawers (notice ~:LOGBOOK:~
in Org code block?) are not exported to HTML, unless =#+OPTIONS: d:t= is
defined.
[[https://orgmode.org/manual/Priorities.html][Priority]] is displayed if =#+OPTIONS: pri:t= or priority cookie =(org-export-with-priority)= is set.
*** FOLLOWUP [#B] H3 Title with different TODO state, priority and several tags :computer:write:
**** NEXT [#C] H4 title with TODO state and priority
** Timestamps
An inactive timestamp [2014-01-16 Thu] does not cause an agenda entry while active <2014-09-11 Thu> does:
** NEXT Read GTD book
SCHEDULED: <2014-09-11 Thu>
By default, *all* (active) entries will be expanded at page load, so that their
contents is visible.
** NEXT Apply GTD methodoloy
DEADLINE: <2014-12-01 Mon>
,:PROPERTIES:
,:HTML_CONTAINER_CLASS: hsCollapsed
,:END:
This section will be collapsed when loading the page because the entry has the
value ~hsCollapsed~ for the property ~:HTML_CONTAINER_CLASS:~.
* Minimal Working Example of org-special-block-extras
# Is non-nil upon a second export, since no doc:𝒳 encountered yet.
My glossary: show:GLOSSARY
# + [[color:orange][Are you excited to learn some Lisp?]] [[blue:Yes!]]
# + Pop-quiz: How does doc:apply work?
# + link-here:solution
# + Syntactically, ~(apply f '(x0 ... xN)) = (f x0 ... xN)~.
# + [[remark:Musa][Ain't that cool?]]
#
#+begin_spoiler aqua
That is, [[color:magenta][we can ((apply)) a function to a list of arguments!]]
#+end_spoiler
--------------------------------------------------------------------------------
#+begin_documentation Salamun Alayakum :label salam
A form of Arabic greeting. It literally means “peace be upon you”.
#+end_documentation
Sometimes I say doc:salam, other times I say doc:hello, and other times I say
doc:hi.
#+begin_parallel
[[color:orange][Are you excited to learn some Lisp?]] [[blue:Yes!]]
Pop-quiz: How does doc:apply work?
#+end_parallel
#+begin_details Answer
link-here:solution
Syntactically, ~(apply f '(x0 ... xN)) = (f x0 ... xN)~.
[[remark:Musa][Ain't that cool?]]
#+begin_spoiler aqua
That is, [[color:magenta][we can ((apply)) a function to a list of arguments!]]
#+end_spoiler
#+end_details
#+html:
#+begin_box
octoicon:report Note that kbd:C-x_C-e evaluates a Lisp form!
#+end_box
/Allah [[margin:][The God of Abraham; known as Elohim in the Bible]] does not burden a soul
beyond what it can bear./ --- Quran 2:286
#+LATEX_HEADER: \usepackage{multicol}
#+LATEX_HEADER: \usepackage{tcolorbox}
#+latex: In the LaTeX output, we have a glossary.
My glossary: show:GLOSSARY
badge:Thanks|for_reading
tweet:https://github.com/alhassy/org-special-block-extras
badge:|buy_me_a coffee|gray|https://www.buymeacoffee.com/alhassy|buy-me-a-coffee
#+begin_details "SDOF equations are \\(m\\ddot{x}=f(t)\\)"
The above is a differential equation with $\ddot{x}$.
#+end_details
#+begin_calc :hint-format "\\left\\{ %s\\right."
+ x
+ y -- Explanation of why $x \;=\; y$
Actually, let me explain:
* x
* x′ -- hint 1
* y -- hint 2
No words can appear (in the export) *after* a nested calculation, for now.
+ [≤] z
--
Explanation of why $y \;\leq\; z$
-- explain it more, this is ignored from export ;-)
#+end_calc
* NEXT Future direction
- State "NEXT" from "" [2025-02-17 Mon 19:16]
- https://raw.githubusercontent.com/fniessen/refcard-org-mode/master/README.org
- https://github.com/fniessen/org-html-themes/blob/master/src/bigblow_theme/css/bigblow.css
- https://github.com/fniessen/org-macros/blob/master/README.org
- https://github.com/fniessen/orgmk
- http://pirilampo.org/org-mode/syntax/
- https://oskor.netlify.app/post/org_mode_basics_2020-12-03/ (see for spoiler tag).
See also for other similar examples:
- https://sbr.pm/articles/sandbox.html (ditaa) and
- https://github.com/elmarlee/org-mode-template/blob/master/org-mode-template.org
- https://alhassy.github.io/org-special-block-extras/ (see e.g. for hint)
https://anarc.at/blog/2022-06-17-matrix-notes/ (see for glossary syntax and placement)
- https://www.bytedude.com/simple-inline-images-in-org-mode/ (for placing images)
- Find more org-mode related content with [[https://datorss.com/entries/search?q=Org-mode][dato.rss]].
- Check literate code execution from [[https://www.kpassa.me/posts/literate2/][here]] to be added as an example to this document under section Source code. Also check from this block dark css for begin_src section if it can be implemented.
- [[http://blog.lujun9972.win/emacs-document/blog/2018/02/14/emacs-org-mode-examples-and-cookbook/index.html][Org cookbook]]
- [[https://brettviren.github.io/refcard-org-mode/][Org-reference-card]]
- [[https://www.reddit.com/r/orgmode/comments/1icqn8e/best_orgprotocol_capture_from_browser/?rdt=34515][Org-protocol browser capture plugins]].
* Footnotes
[fn:myfootnote] Footnotes are extensively used in large documents.
[fn:2] Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do
eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim
veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea
commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit
esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat
non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.