> Inline anchors make arbitrary content referenceable.
*** Internal cross references
See:
- Location [[anchor][cross reference]].
*** Remote references
Linking to a table is done by a
[[https://orgmode.org/org.html#index-remote-references][=#+NAME:=]] line before the table.
Here is a named table.
#+BEGIN_SRC org
#+NAME: my target
| x | y |
| 1 | 2 |
#+END_SRC
#+NAME: my target
| x | y |
| 1 | 2 |
#+BEGIN_SRC org
I can now reference to it with its name. Like this:
[[my target]]
#+END_SRC
I can reference it with its name. Like this:
[[my target]]
** Extensions that define new hyperlinks targets
* Images
** Inline pictures
#+begin_src org
Images are simply shown with: [[file:images/Org-mode-unicorn.svg]]
#+end_src
Images are simply shown with: [[file:images/Org-mode-unicorn.svg]]
#+BEGIN_SRC org
You can also point to an image with text link: [[file:images/Org-mode-unicorn.svg][Unicorn picture]].
#+END_SRC
You can also point to an image with text link: [[file:images/Org-mode-unicorn.svg][Unicorn picture]].
#+BEGIN_SRC org
Images itself can also contain links, HTML-attributes, and a caption, which can be [[https://orgmode.org/manual/Images-in-HTML-export.html][exported]]:
#+caption: Taylor Series
#+ATTR_HTML: :alt Obligatory xkcd comic depicting complexity of Taylor series function :title The Taylor series should have been canceled after the first term.
[[https://m.xkcd.com/2605/][file:images/taylor_series.png]]
#+END_SRC
Images itself can also contain links, HTML-attributes, and a caption, which
can be [[https://orgmode.org/manual/Images-in-HTML-export.html][exported]]:
#+caption: Taylor Series
#+ATTR_HTML: :alt Obligatory xkcd comic depicting complexity of Taylor series function :title The Taylor series should have been canceled after the first term.
[[https://m.xkcd.com/2605/][file:images/taylor_series.png]]
** Image attributes and values
Some of the most used image attributes:
| Attribute | Usage and example |
|----------------+-----------------------------|
| ~:alt~ | Alternative text. ~alt: Obligatory xkcd comic depicting complexity of Taylor series function~ |
| ~:title~ | Visible on mouse hover. ~:title The Taylor series should have been canceled after the first term.~ |
| ~:height~ | Height in percentages. ~:height 35%~ |
| ~:width~ | Width in pixels. ~:width 200~ |
| ~:style float~ | To align images so that text succeeds them. ~:style float:left;margin:20px 20px 20px 0px;~ |
| ~:align~ | To align images so that paragraphs succeed them. ~:align:left;margin:0px 50px 50px 50px;~ |
| ~:border~ | Border. ~:style border:2px solid black;~ |
| ~:bordercolor~ | |
| ~:hspace~ | |
| ~:vspace~ | |
A full list of available HTML image tags linked to at [[https://orgmode.org/worg/org-tutorials/images-and-xhtml-export.html#org3b0fb5d][org-tutorials.]]
#+ATTR_LaTeX: :width 0.25\linewidth
[[file:images/org-mode-unicorn.png]]
Place images side by side: XXX
See also [[https://stackoverflow.com/questions/11670654/how-to-resize-images-in-org-mode][on how to resize image]].
** Image alignment (using positioning)
Books usually align/float images on the right/left of the contents.
*** Image is left aligned
*** Image is right aligned
*** Image is centered
** Figures
To define images that will be *treated as book illustrations* (figures) and
automatically labeled and numbered, use XXX.
* Videos
Videos can't be added directly.
Though, you can add an image with a link to the video like this:
[[http://www.youtube.com/watch?v=DnSGSiXYuOk][file:../bigblow.png]]
* Admonitions
Admonitions (contextual backgrounds) are statements taken out of the content's
flow and labeled with a title.
Common admonitions are:
1. ~note~
2. ~warning~
3. ~tip~
4. ~caution~
5. ~important~
6. ~comment~
(Most themes style only ~note~ and ~warning~ specially.)
** Note
#+begin_src org
,#+begin_note
=/usr/bin/which=: this version of `which' is deprecated; use ~command -v~ in scripts instead.
,#+end_note
#+end_src
#+begin_note
=/usr/bin/which=: this version of `which' is deprecated; use ~command -v~ in scripts instead.
#+end_note
** Warning
#+begin_src org
,#+begin_warning
Do not edit files in =/etc/sudoers.d= directly, but use ~visudo~. Otherwise
you risk locking out all your users!
,#+end_warning
#+end_src
#+begin_warning
Do not edit files in =/etc/sudoers.d= directly, but use ~visudo~. Otherwise
you risk locking out all your users!
#+end_warning
** Comment
Not an admonition per se, but ='#+BEGIN_COMMENT' ... '#+END_COMMENT'= is handy for
metadocumenting larger sections in the .org-document:
#+BEGIN_SRC org
,#+begin_comment
Regions surrounded by ‘#+BEGIN_COMMENT’ … ‘#+END_COMMENT’ are not HTML-exported.
See the actual comment yourself in source org-file, or exact usage in
[[https://orgmode.org/manual/Comment-Lines.html][org-manual]].
,#+end_comment
#+END_SRC
#+begin_comment
Regions surrounded by ‘#+BEGIN_COMMENT’ … ‘#+END_COMMENT’ are not HTML-exported.
See the actual comment yourself in source org-file, or exact usage in [[https://orgmode.org/manual/Comment-Lines.html][org-manual!]]
#+end_comment
* Aligned text
#+begin_src org
,#+begin_left
This text is \\
aligned to the left!
,#+end_left
#+end_src
#+begin_left
This text is \\
aligned to the left!
#+end_left
#+begin_src org
,#+begin_center
This text is \\
centered!
,#+end_center
#+end_src
#+begin_center
This text is \\
centered!
#+end_center
#+begin_src org
,#+begin_right
This text is \\
aligned to the right!
,#+end_right
#+end_src
#+begin_right
This text is \\
aligned to the right!
#+end_right
* Prose excerpts
** Abstract
=#+begin_abstract= works out of the box with LaTeX exports, although HTML with
CSS
[[https://emacs.stackexchange.com/questions/69735/abstract-block-for-html-export/69738][can
support]] it as well:
#+BEGIN_SRC org
,#+begin_abstract
In this Method of Increments, I consider quantities as increased by Increments or
diminished by Decrements, and between the given relations of the Integral [whole]
quantities, I seek the relations between the Increments, and from given relations between
Increments, I seek the Integral quantities themselves in turn. The uses of these methods in
mathematical matters is widely known ; and moreover it is shown to the greatest effect in
these circumstances where all the properties of Fluxions may hence be easily
derived.[...]
,#+end_abstract
#+END_SRC
#+begin_abstract
In this Method of Increments, I consider quantities as increased by Increments or
diminished by Decrements, and between the given relations of the Integral [whole]
quantities, I seek the relations between the Increments, and from given relations between
Increments, I seek the Integral quantities themselves in turn. The uses of these methods in
mathematical matters is widely known ; and moreover it is shown to the greatest effect in
these circumstances where all the properties of Fluxions may hence be easily
derived.[...]
#+end_abstract
** Example blocks
An [[https://alhassy.github.io/org-special-block-extras/#What-is-a-special-block][Org mode block]] is a region of text surrounded by =#+BEGIN_𝒳 … #+END_𝒳=:
#+BEGIN_SRC org
,#+BEGIN_EXAMPLE
You can include literal examples that should not be subjected to markup. Such
examples are typeset in monospace, so this is well suited for source code and
similar examples.
,#+END_EXAMPLE
#+END_SRC
#+BEGIN_EXAMPLE
You can include literal examples that should not be subjected to markup. Such
examples are typeset in monospace, so this is well suited for source code and
similar examples.
#+END_EXAMPLE
#+BEGIN_SRC org
: Short examples can also be created with a colon and a space.
#+END_SRC
: Short examples can also be created with a colon and a space.
** Quote
Use the ~quote~ block for content that *doesn't require the preservation of line
breaks*.
#+begin_src org
,#+begin_quote
Let us change our traditional attitude to the construction of programs:
Instead of imagining that our main task is to instruct a computer what to do,
let us concentrate rather on explaining to human beings what we want a
computer to do.
The practitioner of literate programming can be regarded as an essayist, whose
main concern is with exposition and excellence of style. Such an author, with
thesaurus in hand, chooses the names of variables carefully and explains what
each variable means. He or she strives for a program that is comprehensible
because its concepts have been introduced in an order that is best for human
understanding, using a mixture of formal and informal methods that reinforce
each other.
-- Donald Knuth
,#+end_quote
#+end_src
#+begin_quote
Let us change our traditional attitude to the construction of programs:
Instead of imagining that our main task is to instruct a computer what to do,
let us concentrate rather on explaining to human beings what we want a
computer to do.
The practitioner of literate programming can be regarded as an essayist, whose
main concern is with exposition and excellence of style. Such an author, with
thesaurus in hand, chooses the names of variables carefully and explains what
each variable means. He or she strives for a program that is comprehensible
because its concepts have been introduced in an order that is best for human
understanding, using a mixture of formal and informal methods that reinforce
each other.
-- Donald Knuth
#+end_quote
** Verse
In a verse, there is an *implicit line break at the end of each line*,
and *indentation* is preserved. Here's a 5-7-5 haiku:
#+begin_src org
,#+begin_verse
Fatass Cartman was
Not on the school bus today.
What a big fat turd!
,#+end_verse
#+end_src
#+begin_verse
Fatass Cartman was
Not on the school bus today.
What a big fat turd!
#+end_verse
** Block quotes with their own class attribute
#+begin_highlights
highlights
#+end_highlights
#+begin_pull-quote
[[https://www.htmldog.com/techniques/pullquotes/][pull-quote]]
#+end_pull-quote
#+begin_blockquote
[[https://stackoverflow.com/questions/21876981/differences-between-q-and-blockquote][quote vs. blockquote]]
#+end_blockquote
** NEXT Block quote with optional attribution line
Try with css from https://stackoverflow.com/questions/16712501/org-mode-epigraph
#+begin_epigraph
Three Rings for the Elven-kings under the sky,\\
Seven for the Dwarf-lords in their halls of stone,\\
Nine for the Mortal Men doomed to die,\\
One for the Dark Lord on his dark throne\\
In the Land of Mordor where the Shadows lie.\\
One Ring to rule them all, One Ring to find them,\\
One Ring to bring them all and in the darkness bind the\\
In the Land of Mordor where the Shadows lie.
#+end_epigraph
** Non-breaking space
Insert the Unicode character ~00A0~ to add a non-breaking space.
FIXME Or add/use an Org entity? Or use tilde?
* Substitutions
** NEXT General replacements
#+begin_src org
,#+MACRO: longtext-dish Lopadotemachoselachogaleokranioleipsanodrimhypotrimmatosilphiokarabomelitokatakechymenokichlepikossyphophattoperisteralektryonoptekephalliokigklopeleiolagoiosiraiobaphetraganopterygon
A fictional dish called {{{longtext-dish}}} was mentioned in Aristophanes' 391 B.C. comedy Assemblywomen.
#+end_src
#+MACRO: longtext-dish Lopadotemachoselachogaleokranioleipsanodrimhypotrimmatosilphiokarabomelitokatakechymenokichlepikossyphophattoperisteralektryonoptekephalliokigklopeleiolagoiosiraiobaphetraganopterygon
A fictional dish called {{{longtext-dish}}} was mentioned in Aristophanes' 391 B.C. comedy Assemblywomen.
Emacs comes with [[https://orgmode.org/org.html#Macro-Replacement][these built in macros]], some
more common used are:
#+begin_src org
{{{title}}}\\
{{{author}}}\\
{{{email}}}\\
{{{date}}}\\
{{{date("%Y-%m-%d")}}}\\
{{{time("%H:%M:%S")}}}\\
#+end_src
{{{title}}}\\
{{{author}}}\\
{{{email}}}\\
{{{date}}}\\
{{{date("%Y-%m-%d")}}}\\
{{{time("%H:%M:%S")}}}\\
** Styled references
#+BEGIN_SRC org
,#+MACRO: color @@html:$2@@
{{{color(blue, This text is colored in blue.)}}}
{{{color(red, This other text is in red.)}}}
#+END_SRC
#+MACRO: color @@html:$2@@
{{{color(blue, This text is colored in blue.)}}}
{{{color(red, This other text is in red.)}}}
Other macros from https://github.com/fniessen/org-macros e.g.:
#+BEGIN_SRC org
Keyboard macro:
Pressing {{{kbd(C-x)}}}{{{kbd(f)}}} -- means holding both Control /and/ x, release both, and press f.
#+END_SRC
Keyboard macro:
Pressing {{{kbd(C-x)}}}{{{kbd(f)}}} -- means holding both Control /and/ x, release both, and press f.
Background color macro spans the whole line and can be combined with text alignment:
#+BEGIN_SRC org
,#+begin_center
{{{bgcolor(red, DANGER! MINE FIELD!)}}}
,#+end_center
Common color names are supported by most Org exporters (HTML, LaTeX):
{{{bgcolor(red, red)}}}
{{{bgcolor(orange, orange)}}}
{{{bgcolor(yellow, yellow)}}}
{{{bgcolor(green, green)}}}
{{{bgcolor(blue, blue)}}}
{{{bgcolor(purple, purple)}}}
{{{bgcolor(violet, violet)}}}
You can also use hexadecimal color codes:
{{{bgcolor(#FF0000, #FF0000)}}}
{{{bgcolor(#00FF00, #00FF00)}}}
{{{bgcolor(#0000FF, #0000FF)}}}
#+END_SRC
#+begin_center
{{{bgcolor(red, DANGER! MINE FIELD!)}}}
#+end_center
Common color names are supported by most Org exporters (HTML, LaTeX):
{{{bgcolor(red, red)}}}
{{{bgcolor(orange, orange)}}}
{{{bgcolor(yellow, yellow)}}}
{{{bgcolor(green, green)}}}
{{{bgcolor(blue, blue)}}}
{{{bgcolor(purple, purple)}}}
{{{bgcolor(violet, violet)}}}
You can also use hexadecimal color codes:
{{{bgcolor(#FF0000, #FF0000)}}}
{{{bgcolor(#00FF00, #00FF00)}}}
{{{bgcolor(#0000FF, #0000FF)}}}
Macros can also be applied to foreground text.
Here's Ned Flanders singing
his LP of Dreamcoat:
#+BEGIN_SRC org
,#+BEGIN_VERSE
How I love my coat of many colors.
It was {{{color(red, red)}}} and {{{color(yellow, yellow)}}} and {{{color(green, green)}}} and {{{color(brown, brown)}}},
And {{{color(#ff2d00, scarlet)}}} and {{{color(black, black)}}} and {{{color(#ff8f00, ocher)}}} and {{{color(#fd8340, peach)}}},
And {{{color(#ff003e, ruby)}}} and {{{color(olive, olive)}}} and {{{color(violet, violet)}}} and {{{color(#d18b10, fawn)}}}...
...And {{{color(#d399fa, lilac)}}} and {{{color(gold, gold)}}} and {{{color(chocolate, chocolate)}}} and {{{color(#663f56, mauve)}}},
And {{{color(#eed989, cream)}}} and {{{color(crimson, crimson)}}} and {{{color(silver, silver)}}} and {{{color(#ee89af, rose)}}},
And {{{color(azure, azure)}}} and {{{color(#ebf131, lemon)}}} and {{{color(#954b23, russet)}}} and {{{color(grey, grey)}}}...
...And {{{color(purple, purple)}}} and {{{color(white, white)}}} and {{{color(pink, pink)}}} and {{{color(orange, orange)}}},
And {{{color(red, red)}}} and {{{color(yellow, yellow)}}} and {{{color(green, green)}}} and {{{color(brown, brown)}}},
And {{{color(#ff2d00, scarlet)}}} and {{{color(black, black)}}} and {{{color(#ff8f00, ocher)}}} and {{{color(#fd8340, peach)}}},
,#+END_VERSE
#+END_SRC
#+BEGIN_VERSE center
How I love my coat of many colors.
It was {{{color(red, red)}}} and {{{color(yellow, yellow)}}} and {{{color(green, green)}}} and {{{color(brown, brown)}}},
And {{{color(#ff2d00, scarlet)}}} and {{{color(black, black)}}} and {{{color(#ff8f00, ocher)}}} and {{{color(#fd8340, peach)}}},
And {{{color(#ff003e, ruby)}}} and {{{color(olive, olive)}}} and {{{color(violet, violet)}}} and {{{color(#d18b10, fawn)}}}...
...And {{{color(#d399fa, lilac)}}} and {{{color(gold, gold)}}} and {{{color(chocolate, chocolate)}}} and {{{color(#663f56, mauve)}}},
And {{{color(#eed989, cream)}}} and {{{color(crimson, crimson)}}} and {{{color(silver, silver)}}} and {{{color(#ee89af, rose)}}},
And {{{color(azure, azure)}}} and {{{color(#ebf131, lemon)}}} and {{{color(#954b23, russet)}}} and {{{color(grey, grey)}}}...
...And {{{color(purple, purple)}}} and {{{color(white, white)}}} and {{{color(pink, pink)}}} and {{{color(orange, orange)}}},
And {{{color(red, red)}}} and {{{color(yellow, yellow)}}} and {{{color(green, green)}}} and {{{color(brown, brown)}}},
And {{{color(#ff2d00, scarlet)}}} and {{{color(black, black)}}} and {{{color(#ff8f00, ocher)}}} and {{{color(#fd8340, peach)}}},
#+END_VERSE
Highlight macro spans only the width of the text:
#+BEGIN_SRC org
{{{hl(POLICE LINE DO NOT CROSS)}}}
{{{highlight(red, red)}}}
{{{highlight(orange, orange)}}}
{{{highlight(green, green)}}}
{{{highlight(blue, blue)}}}
{{{highlight(purple, purple)}}}
{{{highlight(violet, violet)}}}
#+END_SRC
{{{hl(POLICE LINE DO NOT CROSS)}}}
{{{highlight(red, red)}}}
{{{highlight(orange, orange)}}}
{{{highlight(green, green)}}}
{{{highlight(blue, blue)}}}
{{{highlight(purple, purple)}}}
{{{highlight(violet, violet)}}}
Lorem Ipsum macro:
#+BEGIN_SRC org
{{{loremipsum}}}
#+END_SRC
{{{loremipsum}}}
** Special symbols
We also use substitutions to include some of the widely used Unicode characters
(like ©, converted from text characters to its typographically correct
entity).
#+begin_src org
- \Agrave \Aacute
- Dash: \ndash \mdash
- Marks: \iexcl \iquest
- Quotations: \laquo \raquo
- Miscellaneous: \para \ordf
- Currency: \cent \EUR \yen \pound
- The Greek letters \alpha, \beta, and \gamma are used to denote angles.
- Science: \pm \div
- Arrows: \to \rarr \larr \harr \rArr \lArr \hArr
- Function names: \arccos \cos
- Signs and symbols: \bull \star
- Smilies: \smiley \sad
- Suits: \clubs \spades
- [...]
#+end_src
- \Agrave \Aacute
- Dash: \ndash \mdash
- Marks: \iexcl \iquest
- Quotations: \laquo \raquo
- Miscellaneous: \para \ordf
- Currency: \cent \EUR \yen \pound
- The Greek letters \alpha, \beta, and \gamma are used to denote angles.
- Science: \pm \div
- Arrows: \to \rarr \larr \harr \rArr \lArr \hArr
- Function names: \arccos \cos
- Signs and symbols: \bull \star
- Smilies: \smiley \sad
- Suits: \clubs \spades
- [...]
See exhaustive list of symbol names supported from
[[https://orgmode.org/worg/org-symbols.html][here]]. For the rest, use
[[https://xkcd.com/2606/][Unicode]].
#+begin_note
Exporting Unicode characters to html should work since the charset is
declared as utf-8. However, do note support between browsers vary.
#+end_note
Org mode also exports HTML entities, decimals and hexadecimals into
[[https://www.w3schools.com/charsets/ref_utf_symbols.asp][literal HTML]] using an export block:
#+BEGIN_SRC org
#+BEGIN_EXPORT html
- Using HTML entity to display ♠
- Using decimal to display ♠
- Using hexadecimal to display ♠
|
#+END_EXPORT
#+END_SRC
#+BEGIN_EXPORT html
- Using HTML entity to display ♠
- Using decimal to display ♠
- Using hexadecimal to display ♠
|
#+END_EXPORT
* Source code
** Code blocks
The 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
** NEXT Inline code
If you have done ~$ sudo aptitude install r-base-core~ then you can evaluate:
#+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~. Export happens calling emacs export via
vim-orgmode and [[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
#+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 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\).
** 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}+\cdots ,
\]
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}+\cdots ,
\]
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.
* Useful extensions
#+BEGIN_SRC org
,** NEXT [#A] H2 Title with TODO state, priority and a tag :online:
,*** FOLLOWUP [#B] H3 Title with different TODO state, priority and several tags :computer:write:
,**** DONE [#C] H4 title with closed TODO state and priority
:LOGBOOK:
- State "TODO" -> "DONE" [2014-01-16 Thu 09:52]
:END:
[[https://orgmode.org/manual/Priorities.html][Priority]] is displayed if =#+OPTIONS: pri:t= or priority cookie
=(org-export-with-priority)= is set.
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.
#+END_SRC
** NEXT [#A] H2 Title with TODO state, priority and a tag :online:
*** FOLLOWUP [#B] H3 Title with different TODO state, priority and several tags :computer:write:
**** DONE [#C] H4 title with closed TODO state and priority
:LOGBOOK:
- State "TODO" -> "DONE" [2014-01-16 Thu 09:52]
:END:
[[https://orgmode.org/manual/Priorities.html][Priority]] is displayed if =#+OPTIONS: pri:t= or priority cookie
=(org-export-with-priority)= is set.
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.
*** Timestamps
#+BEGIN_SRC org
An inactive timestamp does not cause an agenda entry
[2014-01-16 Thu] while active <2014-01-16 Thu> does.
#+END_SRC
An inactive timestamp does not cause an agenda entry
[2014-01-16 Thu] while active <2014-01-16 Thu> does.
*** [#A] TODO 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.
That can be changed by adding such a line (into your Org document):
#+begin_src org
,#+HTML_HEAD:
#+end_src
*** [#B] TODO 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:~.
Powerful, no?
*** Some note :computer:write:
You can add tags to any entry, and hightlight all entries having some specific
tag by clicking on the buttons made accessible to you in the "Dashboard".
*** Weekly review :computer:
Now, you can even make your weekly review in the HTML export... Press the
{{{kbd(r)}}}-key
to start entering the "review mode" where all but one active entry are
collapsed, so that you can really focus on one item at a time!
** Bigblow extension
The string ~fixme~ (in *upper case*) gets replaced by a "Fix Me!" image:
#+begin_src org
FIXME Delete this...
#+end_src
FIXME Delete this...
* Citations
Cross-referenced to bibliography.
* Appendix
Special sections.
** Index
Index (or list of acronyms).
- Write index entries
#+index: Org-mode
Note that multi-entry terms generate separate index entries.
#+index: Definitions!Org-mode
- Place the index at the desired location
- Produce the index by updating ~org-latex-pdf-process~
#+BIND: org-latex-pdf-process ("pdflatex %b" "bibtex %b" "pdflatex %b" "pdflatex %b")
** Bibliography
The bibliography...
- Eric Steven Raymond. The Art of Unix Programming. Addison-Wesley. ISBN
0-13-142901-9.
# http://rmarkdown.rstudio.com/authoring_bibliographies_and_citations.html
** Glossary
- A glossary term ::
The corresponding (indented) definition.
- A second glossary term ::
The corresponding (indented) definition.
* 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
* For additional reading / notes
- 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://www.google.fi/search?q=org+mode+export+examples&uact=5&oq=org+mode+export+examples&sclient=gws-wiz
- 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.
-
* 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.