# org-mode tests

I've often found that specifications in the IT industry have received a negative reputation in our industry. People say things such as, "Code is worth a thousand specifications," or complain that writing specifications is just a waste of time. I concede that when doing exploratory programming, or maybe working on a very small team, specifications may not be necessary; however, on large projects they are absolutely critical. Without a blueprint, or top-level view of the architecture of a system, it can be difficult to understand how things are supposed to be laid out. Worse, it's near impossible to accurately and repeatably dissiminate the architecture of a system without a specification to point at. One-on-one conversations are not a scalable model. I think the reason specification documents receive such a bad reputation stem from the following 3 reasons: 1. It's not code. And programmers wanna write code. 2. Generally speaking, they're hard to do well, and they take too long to create. Hopefully I've shown that they don't have to be difficult to write, and that as quickly as you can jot down ideas, you can create a usable specification. 3. They're seen as wasted effort – something you discard. Hopefully, I've also show how the specification can grow with the code and become a living artifact. So love your specs, and give your team the documentation they deserve. There do exist methodologies that are a joy to use, and this – I feel – is one of them.
#+TITLE: Org mode syntax #+SUBTITLE: Quick reference card #+AUTHOR: Fabrice Niessen #+EMAIL: (concat "fniessen" at-sign "pirilampo.org") #+DESCRIPTION: Org mode syntax example #+KEYWORDS: org-mode, syntax, quick reference, cheat sheet, recommended practices, latex, beamer, html #+LANGUAGE: en #+OPTIONS: H:4 num:nil toc:2 p:t #+HTML_LINK_HOME: http://www.google.com #+HTML_LINK_UP: http://www.bing.com #+SETUPFILE: ~/.dotfiles/org/theme-readtheorg.setup #+PROPERTY: header-args :eval yes :exports both :results replace # #+MACRO: longtext this is a very very long text to include | *Framework* | Org mode 9 | | *Bug tracker* | https://github.com/fniessen/refcard-org-mode/issues | | *Source* | https://github.com/fniessen/refcard-org-mode | # | *Documentation* | http://refcard-org-mode.readthedocs.org/ | * Summary # See https://tutorialtodoapp.readthedocs.org/en/latest/ for nice home page! #+begin_sidebar *You will learn to:* - write your docs in Org mode - create tables - create custom code blocks - and much more! #+end_sidebar #+begin_abstract This is an Org mode document, using the ~.org~ extension (supported by GitHub). *Org mode* is an easy-to-write /plain text/ formatting syntax for authoring notes, articles, LaTeX documents, books, Web pages, Beamer slide decks and much more! This is a cheat sheet for *Org mode 8* (because of some markup syntax changes since Org mode 7), using [[https://github.com/fniessen/org-html-themes][ReadTheOrg CSS]]. Reading through all the [[http://orgmode.org/org.pdf][documentation]] is highly recommended, but for the truly impatient, following are some quick steps to get started. #+end_abstract # #+begin_abstract # This paper talks about... # #+end_abstract # See http://asciidoctor.org/docs/user-manual/#the-big-picture # See http://home.fnal.gov/~neilsen/notebook/orgExamples/org-examples.html. * Reference card #+TOC: headlines 2 * Document header Title and author line: #+begin_src org :eval never-export ,#+TITLE: Org mode syntax examples ,#+AUTHOR: Fabrice Niessen My document provides... #+end_src It's a good practice to also include an email line following the author line. #+begin_src org :eval never-export ,#+EMAIL: [email protected] #+end_src * Document settings ** Document description #+begin_src org :eval never-export #+DESCRIPTION: This document catalogs a set of tips and tricks for composing documents in Org mode. #+KEYWORDS: org-mode, syntax, quick reference, cheat sheet, recommended practices, latex, beamer, html #+LANGUAGE: en #+end_src ** Section numbering #+begin_src org :eval never-export #+OPTIONS: H:4 #+end_src #+begin_src org :eval never-export #+OPTIONS: num:nil #+end_src ** Table of contents Set the ~toc~ attribute to activate an auto-generated table of contents (limited to its 2 first levels) at the top of document. #+begin_src org :eval never-export #+OPTIONS: toc:2 #+end_src #+begin_src org :eval never-export #+OPTIONS: p:t #+end_src #+begin_note The ~ALT_TITLE~ property allows to set an alternate title (shorter, for example) for a given headline in the table of contents and other running heads. #+end_note To locally insert the TOC at some random place, use the ~#+TOC: headlines [n]~ feature; for example: #+begin_src org :eval never-export ,#+TOC: headlines 2 #+end_src ** List of figures ~#+TOC: figures~ is not implemented yet in the HTML backend. ** List of tables ~#+TOC: tables~ is already implemented in the HTML backend. ** List of equations * Section titles (headings) #+begin_src org :eval no ,* Biggest heading (level 1) New chapter. #+end_src #+begin_src org ,** Bigger heading (level 2) New section. ,*** Big heading (level 3) New sub-section. ,**** Heading (level 4) New sub-sub-section. #+end_src ** Numbered headings You can create numbered headings up to a certain level by setting an option: #+begin_src org ,#+OPTIONS: H:4 #+end_src * Paragraphs ** Normal #+begin_src org A single newline has no effect. This line is part of the same paragraph. But an empty line demarcates paragraphs. #+end_src ** Line breaks #+begin_src org By entering two consecutive backslashes, \\ you can force a line break without starting a new paragraph. #+end_src ** Horizontal rules #+begin_src org For an horizontal line, insert at least 5 dashes: this is some text above an horizontal rule ----- and some text below it. #+end_src ** Text width # Premiere Elements, page 111 # # Vous pouvez créer ces objets en cliquant sur le bouton Nouvel| élément de le # fenêtre Média. (Le Chapitre 14 explique comment créer| des titres ; le # Chapitre 15 montre l'utilisation des barres et ton, de la| vidéo noir et de # l'amorce SMPTE.) # # The principles of beautiful Web design, page 6 # # In a figurative sense, the concept of visual balance is similar to that of # physical balance| illustrated by a seesaw. Just as physical objects have # weight, so do the elements of a layout.| If the elements on either side of a # layout are of equal weight, they balance one another.| There are two main forms # of visual balance: symmetrical and asymmetrical. One morning, when Gregor Samsa woke from troubled dreams, he found himself transformed in his bed into a horrible vermin. He lay on his armour-like back, and if he lifted his head a little he could see his brown belly, slightly domed and divided by arches into stiff sections. The bedding was hardly able to cover it and seemed ready to slide off any moment. His many legs, pitifully thin compared with the size of the rest of him, waved about helplessly as he looked. * Formatting text Text effects. ** Bold and italic #+begin_src org /Emphasize/ (italics), *strongly* (bold), and */very strongly/* (bold italics). #+end_src Markup elements can be nested: #+begin_src org This is /italic text which contains _underlined text_ within it/, whereas _this is normal underlined text_. #+end_src Markup can span across multiple lines, by default *no more than 2*: #+begin_src org *This is not bold.* #+end_src Org mode does not interpret a marker surrounded by alphanumeric characters as an emphasis marker. So, you can't (easily) emphasize just part of a word: #+begin_src org Not feas*ible*. #+end_src ** Monospace, superscript and subscript Other elements to use sparingly are: #+begin_src org - monospaced typewriter font for ~inline code~ - monospaced typewriter font for =verbatim text= - +deleted text+ (vs. _inserted text_) - text with super^{script}, such as 2^{10} - text with sub_{script}, such as H_{2}O #+end_src ** Smart punctuation If the XXX option is specified, Org mode will produce typographically correct output, converting straight quotes to curly quotes, ~---~ to em-dashes, ~--~ to en-dashes, and ~...~ to ellipses. * Lists Org markup allows you to create *bulleted* or *numbered* lists. It allows any combination of the two list types. ** Unordered lists Itemized lists are marked with bullets. Create them with a minus or a plus sign. They are convenient to organize data, and make the document prettier, and easier to read. #+begin_src org - Item with some lengthy text wrapping hopefully across several lines. We add a few words to really show the line wrapping. - Bullet. + Bullet. * Bullet. #+end_src ** Checklists #+begin_src org - [X] Checked. - [-] Half-checked. - [ ] Not checked. - Normal list item. #+end_src ** Ordered lists Enumerated lists are marked with numbers or letters: #+begin_src org 1. Arabic (decimal) numbered list item. We add a few words to show the line wrapping. A. Upper case alpha (letter) numbered list item. a. Lower alpha. b. Lower alpha. B. Upper alpha. 2. Number. #+end_src You can have ordered lists with jumping numbers: #+begin_src org 2. [@2] We start with point number 2. 3. Automatically numbered item. #+end_src ** Definition lists :PROPERTIES: :ID: f1a4a242-755b-4c38-9280-ee3f60e2b29a :END: Labeled, multi-line lists. #+begin_src org - First term to define :: Definition of the first term. We add a few words to show the line wrapping, to see what happens when you have long lines. - Second term :: Explication of the second term with *inline markup*. In many paragraphs. #+end_src ** Separating lists Adjacent lists sometimes like to fuse. To force the start of a new list, offset the two lists by an empty line comment: #+begin_src org - apples - oranges - bananas # Comment. - carrots - tomatoes - celery #+end_src * Tables Tables are one of the most refined areas of the Org mode syntax. They are very easy to create and to read. ** Simple table #+begin_src org | Cell in column 1, row 1 | Cell in column 2, row 1 | | Cell in column 1, row 2 | Cell in column 2, row 2 | #+end_src Org tables have cells of at most one line long: there is no such thing as a multi-line table cell in Org. ** Column formatting Columns are automatically aligned: - Number-rich columns to the right, and - String-rich columns to the left. *** Table with aligned cells If you want to override the automatic alignment, use ~~, ~~ or ~~. #+begin_src org ,#+CAPTION: Table with aligned columns | | | | | 1 | 2 | 3 | | Right | Center | Left | | xxxxxxxxxxxx | xxxxxxxxxxxx | xxxxxxxxxxxx | #+end_src *** Table with column size adjusted ** Header row You can create tables with an header row (by using an horizontal line of dashes to separate it from the rest of the table). #+begin_src org #+CAPTION: Table with an header row | Name of column 1 | Name of column 2 | Name of column 3 | |------------------+------------------+------------------| | Top left | Top middle | | | | | Right | | Bottom left | Bottom middle | | #+end_src ** A very long table To test "sticky table headers"... | Name of column 1 | Name of column 2 | Name of column 3 | |------------------+------------------+------------------| | Top left | Top middle | | | 2 | | | | 3 | | | | 4 | | | | 5 | | | | 6 | | | | 7 | | | | 8 | | | | 9 | | | | 10 | | | | 11 | | | | 12 | | | | 13 | | | | 14 | | | | 15 | | Right | | 16 | | | | 17 | | | | 18 | | | | 19 | | | | 20 | | | | 21 | | | | 22 | | | | 23 | | | | 24 | | | | 25 | | | | 26 | | | | 27 | | | | 28 | | | | 29 | | | | Bottom left | Bottom middle | | ** Table placement #+begin_src org #+ATTR_LATEX: :center nil | a | b | | 1 | 2 | #+end_src XXX Different from the following: #+begin_src org | a | b | | 1 | 2 | #+end_src ** Align tables on the page *** Left Here is a table on the left side: #+begin_src org ,#+LATEX: \noindent ,#+ATTR_LATEX: :center nil | a | b | c | |---+---+---| | 1 | 2 | 3 | | 4 | 5 | 6 | ,#+LATEX: \hfill #+end_src The ~noindent~ just gets rid of the indentation of the first line of a paragraph which in this case is the table. The ~hfill~ adds infinite stretch after the table, so it pushes the table to the left. *** Center Here is a centered table: #+begin_src org | a | b | c | |---+---+---| | 1 | 2 | 3 | | 4 | 5 | 6 | #+end_src *** Right And here's a table on the right side: #+begin_src org #+LATEX: \hfill #+ATTR_LATEX: :center nil | a | b | c | |---+---+---| | 1 | 2 | 3 | | 4 | 5 | 6 | #+end_src Here the ~hfill~ adds infinite stretch before the table, so it pushes the table to the right. ** Table size #+begin_src org #+ATTR_HTML: :width 100% | Cell in column 1, row 1 | Cell in column 2, row 1 | | Cell in column 1, row 2 | Cell in column 2, row 2 | #+end_src ** CSV You can fill a table from a CSV file using R commands. * Links :PROPERTIES: :CUSTOM_ID: links :END: #+begin_src org :eval no ,* Links :PROPERTIES: :CUSTOM_ID: links :END: #+end_src This document is available in [[file:README.org][plain text]], [[file:README.html][HTML]] and [[file:README.pdf][PDF]]. The links are delimited by double square brackets. ** External links #+begin_src org See http://www.pirilampo.org (automatic!) and the [[http://orgmode.org/][Org mode Web site]]. #+end_src *** Relative links #+begin_src org [[../README.html][Home]] #+end_src *** Email links #+begin_src org [[mailto:[email protected]][email John Doe]] #+end_src *** Image links To get image links, put a link to a file in the description. #+begin_src org Clicking on the image [[http://orgmode.org/][file:images/org-mode-unicorn.png]] leads to the Org mode home page. #+end_src ** Internal links :PROPERTIES: :ID: 0d2b0cb2-116c-4a61-a076-4c641faf4346 :END: *** Inline anchors Anchors are used to specify hypertext link targets. #+begin_src org > Inline anchors make arbitrary content referenceable. #+end_src *** Internal cross references Links generally point to an headline. #+begin_src org See chapter [[#links][Links]]. #+end_src To add a link to a figure (e.g., "See Figure 1"), just do: #+begin_src org ,#+name: fig ,#+caption: caption [[file:fig.png]] See figure [[fig]]. #+end_src You can also create a hypertext link to a document anchor in the current document /or in another document/. #+begin_src org See: - Location [[anchor][cross reference]]. - Section [[id:0d2b0cb2-116c-4a61-a076-4c641faf4346][Internal links]] #+end_src ** Extensions that define new hyperlinks targets * Images You can insert *image* files of different *formats* to a document: | | HTML | PDF | |------+------------------------------+-----| | gif | yes | | | jpeg | yes | | | png | yes | | | bmp | (depends on browser support) | | ** Inline picture #+begin_src org #+caption: Org mode logo [[file:images/org-mode-unicorn.png]] #+end_src #+begin_src org Click to see the [[file:images/org-mode-unicorn.png][Unicorn picture]]. #+end_src ** 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 #+name: test #+begin_src R :exports results :file-ext pdf :results graphics :width 8 :height 3 plot(runif(100)) #+end_src #+attr_latex: :float t :placement [b] #+results: test [[file:test.pdf]] ** Image attributes and values XXX Available HTML image tags include ... | Attribute | Value(s) | |----------------+-----------------------------| | ~:alt~ | Alternate text | | ~:height~ | | | ~:width~ | User defined size in pixels | | ~:align~ | | | ~:border~ | | | ~:bordercolor~ | | | ~:hspace~ | | | ~:vspace~ | | | ~:title~ | User defined text | #+begin_src org #+ATTR_LaTeX: :width 0.25\linewidth [[file:images/org-mode-unicorn.png]] #+end_src Place images side by side: XXX ** 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: #+begin_src org [[http://www.youtube.com/watch?v=DnSGSiXYuOk][file:../bigblow.png]] #+end_src * 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~ (Most themes style only ~note~ and ~warning~ specially.) ** List of supported admonitions :noexport: | Total | | docutils | rST | RTD | AsciiDoc | DocBook | MoinMoin (Modern) | Bootstrap | DocOnce | Confluence | SuperCollider | |--------+-----------+----------+-----+-----+----------+---------+-------------------+-----------+---------+------------+---------------| | 7 | note | 1 | 1 | 1 | 1 | 1 | 1 | | | 1 | 1 | | 9 | warning | 1 | 1 | 1 | 1 | 1 | 1 | 1 | 1 | 1 | 1 | | 7 | tip | 1 | 1 | 1 | 1 | 1 | 1 | | | 1 | | |--------+-----------+----------+-----+-----+----------+---------+-------------------+-----------+---------+------------+---------------| | 6 | caution | 1 | 1 | 1 | 1 | 1 | 1 | | | | | | 6 | important | 1 | 1 | 1 | 1 | 1 | 1 | | | | | |--------+-----------+----------+-----+-----+----------+---------+-------------------+-----------+---------+------------+---------------| | 3 | attention | 1 | 1 | 1 | | | | | | | | | 3 | hint | 1 | 1 | 1 | | | | | | | | | 3 | error | 1 | 1 | 1 | | | | | | | | | 4 | danger | 1 | 1 | 1 | | | | 1 | | | | |--------+-----------+----------+-----+-----+----------+---------+-------------------+-----------+---------+------------+---------------| | #ERROR | seealso | | | ? | | | | | | | | | #ERROR | todo | | | ? | | | | | | | | |--------+-----------+----------+-----+-----+----------+---------+-------------------+-----------+---------+------------+---------------| | 2 | info | | | | | | | 1 | | 1 | | | 1 | notice | | | | | | | | 1 | | | | 1 | question | | | | | | | | 1 | | | | 1 | summary | | | | | | | | 1 | | | | 1 | success | | | | | | | 1 | | | | #+TBLFM: $1=vsum($3..\$11) ** Base admonitions *** Note A note box is displayed as follows: #+begin_src org ,#+begin_note This is a useful note. ,#+end_note #+end_src # #+attr_html: :options [By the way...] # #+attr_latex: :options Test # #+begin_note # This is a useful note (with a title). # #+end_note *** Warning A warning box is displayed as follows: #+begin_src org ,#+begin_warning Be careful! Check that you have... ,#+end_warning #+end_src *** Tip A tip box is displayed as follows: #+begin_src org ,#+begin_tip Try doing it this way... ,#+end_tip #+end_src *** Caution #+begin_src org ,#+begin_caution Caution ,#+end_caution #+end_src *** Important #+begin_src org ,#+begin_important Important ,#+end_important #+end_src ** Additional admonitions *** Attention #+begin_src org ,#+begin_attention Attention ,#+end_attention #+end_src *** Hint #+begin_src org ,#+begin_hint Hint ,#+end_hint #+end_src *** Error #+begin_src org ,#+begin_error Error ,#+end_error #+end_src *** Danger #+begin_src org ,#+begin_danger Danger ,#+end_danger #+end_src *** SeeAlso (Sphinx additional) #+begin_src org ,#+begin_seealso - [[http://en.wikipedia.org/wiki/Apple][Apples]] :: A kind of [[http://en.wikipedia.org/wiki/Fruit][fruit]]. ,#+end_seealso #+end_src ** Todo admonition # See example at http://docs.ckan.org/en/latest/contributing/python.html # or http://wsgiservice.readthedocs.org/en/latest/todo.html Simple box ("inline task"): #+begin_src org *************** TODO Do this task Description of inline task. *************** END #+end_src *************** TODO Do this task Description of inline task. *************** END or: #+begin_src org *************** WAIT [#B] Do also this other task :phone: *************** END #+end_src #+begin_admonitiontodo Admonitiontodo #+end_admonitiontodo Alternatively to the inline tasks (for creating "TODO" annotations), if you want such notes not to show up in the published version, drawers may also do the job, e.g.: :FIXME: ... :END: You can then control what drawers are exported with ~org-export-with-drawers~ (or per document with d OPTIONS item). * Centered text #+begin_src org ,#+begin_left This text is \\ aligned to the left! ,#+end_left ,#+begin_center This text is \\ centered! ,#+end_center ,#+begin_right This text is \\ aligned to the right! ,#+end_right #+end_src
- Science: \pm \div - Arrows: \to \rarr \larr \harr \rArr \lArr \hArr - Function names: \arccos \cos - Signs and symbols: \bull \star
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. #+begin_sidebar Org mode was first released by Carsten Dominik in 2004 as an outlining and project planning tool. Further development turned it into a general tool that can be used to author professional documents like LaTeX. #+end_sidebar Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Vestibulum tortor quam, feugiat vitae, ultricies eget, tempor sit amet, ante. Donec eu libero sit amet quam egestas semper. Aenean ultricies mi vitae est. Mauris placerat eleifend leo. Quisque sit amet est et sapien ullamcorper pharetra. Vestibulum erat wisi... Phasellus ut libero. Nulla in libero non enim tristique sollicitudin. Ut tempor. Phasellus pellentesque augue eget ante. Mauris malesuada. Donec sit amet diam sit amet dolor placerat blandit. Morbi enim purus, imperdiet in, molestie sit amet, pellentesque eu, mauris. In vel erat vel ipsum bibendum commodo. Curabitur accumsan. Nam sed metus. Etiam tristique bibendum justo.
#+begin_left This text is \\ aligned to the left! #+end_left #+begin_center This text is \\ centered! #+end_center #+begin_right This text is \\ aligned to the right! #+end_right
#+begin_error oops #+end_error
> Inline anchors make arbitrary content referenceable
#+CAPTION: Table with aligned columns | | | | | 1 | 2 | 3 | | Right | Center | Left | | xxxxxxxxxxxx | xxxxxxxxxxxx | xxxxxxxxxxxx |
- apples - oranges - bananas # Comment. - carrots - tomatoes - celery
- First term to define :: Definition of the first term. We add a few words to show the line wrapping, to see what happens when you have long lines. - Second term :: Explication of the second term with *inline markup*. In many paragraphs.
- [X] Checked. - [-] Half-checked. - [ ] Not checked. - Normal list item.
/Emphasize/ (italics), *strongly* (bold), and */very strongly/* (bold italics).
- monospaced typewriter font for ~inline code~ - monospaced typewriter font for =verbatim text= - +deleted text+ (vs. _inserted text_) - text with super^{script}, such as 2^{10} - text with sub_{script}, such as H_{2}O
no sub_script?
- Item with some lengthy text wrapping hopefully across several lines. We add a few words to really show the line wrapping. - Bullet. + Bullet. * Bullet.
#+INCLUDE: "https://lumage.smilebasicsource.com/special/CODING.html" export html