-- back-up-by-copying t --

How To Read an OrgMode File

An OrgMode file is an ordinary text file with special syntax, called "markup" to render it as an HTML file. The markup is chosen to be as inobtrusive as possible, so the ordinary text is easily read as an alternative to the formatted version.

The HTML copy of this file is composed with the push of a button in the emacs text editor for a file with the .org suffix. The PDF is produced in a web browser, while viewing the HTML by the { menu >> print >> save as pdf } sequence.

An OrgMode file is a text file, whose source contains all the text of both HTML and PDF documents. For example, if reading this in the HTML verion, here is the source text for this document.

Rendering differences

When viewed as a text, in a non-emacs editor, such as an email, a few renderings are not displayed. These are a few:

• italic – text between a pair of slashes is rendered in italics.
• bold – text between a pair of asterisks is rendered as bold
• sections automatically create a line-break; paragraphs are separated with a blank line.

Header differences

• sections of the document are delimited with leading asterisks, one for top level, two for second, …

• a section whose first word is COMMENT is not placed in the published document. In this way, It's possible to keep sections in an outline and selectively exclude them. In this file, the final section, commands is hidden in the exported HTML, but is visible in this source.

• in my copy, the headers are rendered in blue.

Other differences

• images appear in the output HTML and PDF copies. the syntax of the OrgMode text file produces the HTML version which includes the image

• the #+ notation suggests what it does, in this case,

  • the TITLE of the document
  • INCLUDE a local file which has some formatting information, in this case, it sets the output font and page

• a hypertext link is enclosed in nested braces: [[ URL ] [ display text ]]

submitted

This paper is part of the Yellow, Literature Tools chapter in my commonplace book.